IBM Security Access Manager for Web
Version 7.0
Command Reference
SC23-6512-02
IBM Security Access Manager for Web
Version 7.0
Command Reference
SC23-6512-02
Note
Before 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 (product
number 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 Contract
with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . vii
About this publication . . . . . . . . ix
Intended audience . . .
Access to publications and
Related publications .
Accessibility . . . . .
Technical training . . .
Support information . .
. . . . .
terminology .
. . . . .
. . . . .
. . . . .
. . . . .
Chapter 1. pdadmin commands
.
.
. ix
. ix
. . . . xii
. . . . xiii
. . . . xiv
. . . . xiv
.
.
. . . . 1
How to read syntax statements . . . . .
Syntax for pdadmin commands . . . . .
Command modes. . . . . . . . . .
Single command mode . . . . . . .
Interactive command mode . . . . .
Multiple command mode . . . . . .
Non-English locales . . . . . . . . .
Error handling . . . . . . . . . . .
Return codes for a single command. . .
Return codes for an interactive command.
Return codes for multiple commands . .
Local or other domain . . . . . . . .
Command option processing . . . . . .
Commands by category. . . . . . . .
Access control list commands . . . .
Action commands . . . . . . . .
Authorization rule commands . . . .
Configuration commands . . . . . .
Context commands . . . . . . . .
Domain commands . . . . . . . .
Group commands . . . . . . . .
Login and logout commands . . . .
Object commands . . . . . . . .
Object space commands . . . . . .
Policy commands . . . . . . . .
Protected object policy commands . . .
Resource and resource group commands
Server commands . . . . . . . .
Session Management Server commands .
User commands . . . . . . . . .
WebSEAL commands . . . . . . .
acl attach . . . . . . . . . . . .
acl create . . . . . . . . . . . .
acl delete . . . . . . . . . . . .
acl detach . . . . . . . . . . . .
acl find . . . . . . . . . . . . .
acl list . . . . . . . . . . . . .
acl modify . . . . . . . . . . . .
acl show . . . . . . . . . . . .
action create . . . . . . . . . . .
action delete . . . . . . . . . . .
action group create . . . . . . . . .
action group delete . . . . . . . . .
action group list . . . . . . . . . .
© Copyright IBM Corp. 2001, 2012
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 1
. 1
. 3
. 4
. 4
. 5
. 6
. 6
. 7
. 7
. 7
. 8
. 9
. 9
. 10
. 10
. 11
. 11
. 12
. 12
. 12
. 13
. 13
. 14
. 14
. 15
. 15
. 16
. 17
. 18
. 19
. 21
. 22
. 23
. 24
. 25
. 26
. 26
. 30
. 31
. 33
. 34
. 34
. 35
action list . . . .
admin show conf .
authzrule attach . .
authzrule create . .
authzrule delete . .
authzrule detach. .
authzrule find . .
authzrule list . . .
authzrule modify .
authzrule show . .
config modify . .
config show . . .
context show . . .
domain create . .
domain delete . .
domain list . . .
domain modify . .
domain show . . .
errtext . . . . .
exit or quit . . .
group create . . .
group delete . . .
group import . . .
group list . . . .
group modify. . .
group show . . .
help . . . . . .
login . . . . .
logout . . . . .
object access . . .
object create . . .
object delete . . .
object exists . . .
object list . . . .
object listandshow .
object modify . . .
object show . . .
objectspace create .
objectspace delete .
objectspace list . .
policy get . . . .
policy set . . . .
pop attach . . . .
pop create . . . .
pop delete . . . .
pop detach . . .
pop find . . . .
pop list . . . . .
pop modify . . .
pop show . . . .
rsrc create . . . .
rsrc delete . . .
rsrc list . . . .
rsrc show. . . .
rsrccred create . .
rsrccred delete . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 35
. 36
. 37
. 38
. 39
. 40
. 40
. 41
. 42
. 43
. 44
. 46
. 48
. 49
. 51
. 52
. 53
. 54
. 54
. 55
. 56
. 57
. 58
. 59
. 61
. 62
. 63
. 65
. 67
. 68
. 69
. 71
. 72
. 73
. 74
. 75
. 77
. 81
. 82
. 83
. 83
. 86
. 90
. 91
. 92
. 92
. 93
. 94
. 95
. 98
. 99
. 100
. 101
. 102
. 102
. 104
iii
rsrccred list user . . . . . . . . . .
rsrccred modify . . . . . . . . . .
rsrccred show . . . . . . . . . . .
rsrcgroup create . . . . . . . . . .
rsrcgroup delete . . . . . . . . . .
rsrcgroup list . . . . . . . . . . .
rsrcgroup modify . . . . . . . . . .
rsrcgroup show. . . . . . . . . . .
server list. . . . . . . . . . . . .
server listtasks . . . . . . . . . . .
server replicate . . . . . . . . . . .
server show . . . . . . . . . . . .
server task add . . . . . . . . . . .
server task cache flush all . . . . . . .
server task create . . . . . . . . . .
server task delete . . . . . . . . . .
server task dynurl update . . . . . . .
server task help . . . . . . . . . .
server task jmt . . . . . . . . . . .
server task list . . . . . . . . . . .
server task offline . . . . . . . . . .
server task online . . . . . . . . . .
server task refresh all_sessions . . . . .
server task reload . . . . . . . . . .
server task remove . . . . . . . . .
server task show . . . . . . . . . .
server task sms key change. . . . . . .
server task sms key show . . . . . . .
server task sms realm list . . . . . . .
server task sms realm show . . . . . .
server task sms session refresh all_sessions .
server task sms session refresh session . . .
server task sms replica set list . . . . . .
server task sms replica set show . . . . .
server task sms session list . . . . . . .
server task sms session terminate all_sessions
server task sms session terminate session . .
server task sms trace get . . . . . . .
server task sms trace set . . . . . . . .
server task stats . . . . . . . . . .
server task terminate all_sessions . . . . .
server task terminate session . . . . . .
server task throttle . . . . . . . . .
server task trace . . . . . . . . . .
server task virtualhost add . . . . . . .
server task virtualhost create . . . . . .
server task virtualhost delete . . . . . .
server task virtualhost list . . . . . . .
server task virtualhost offline . . . . . .
server task virtualhost online . . . . . .
server task virtualhost remove. . . . . .
server task virtualhost show . . . . . .
server task virtualhost throttle . . . . . .
server task server restart . . . . . . .
server task server sync . . . . . . . .
server task jdb export . . . . . . . .
server task jdb import . . . . . . . .
server task cfgdb export . . . . . . . .
server task cfgdb import. . . . . . . .
server task file cat . . . . . . . . . .
user create . . . . . . . . . . . .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
105
106
107
108
109
110
110
112
112
113
115
116
117
120
121
128
130
131
133
134
135
137
139
140
141
143
144
145
146
147
148
150
151
152
153
154
156
157
158
159
162
163
164
166
168
171
177
179
180
182
184
186
188
190
191
192
193
194
195
196
197
user
user
user
user
user
delete .
import .
list . .
modify .
show .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
199
200
201
203
205
Chapter 2. Security Access Manager
utilities . . . . . . . . . . . . . . 209
Installation and configuration utilities . . . .
Migration utilities . . . . . . . . . . .
WebSEAL utilities . . . . . . . . . . .
Session management server utilities . . . . .
Security Access Manager plug-in for web servers
utilities . . . . . . . . . . . . . .
Serviceability and problem determination utilities
adschema_update . . . . . . . . . . .
amauditcfg . . . . . . . . . . . . .
amwebcfg . . . . . . . . . . . . .
amwpmcfg . . . . . . . . . . . . .
bassslcfg . . . . . . . . . . . . . .
cdsso_key_gen . . . . . . . . . . . .
ivacld_setup . . . . . . . . . . . . .
ivacld_uninst . . . . . . . . . . . .
ivbase_setup. . . . . . . . . . . . .
ivbase_uninst . . . . . . . . . . . .
ivmgrd_setup . . . . . . . . . . . .
ivmgrd_uninst . . . . . . . . . . . .
ivrgy_tool . . . . . . . . . . . . .
mgrsslcfg . . . . . . . . . . . . . .
PDAcld_config . . . . . . . . . . . .
PDAcld_unconfig . . . . . . . . . . .
pdadmin_host . . . . . . . . . . . .
pd_start . . . . . . . . . . . . . .
pdbackup . . . . . . . . . . . . .
pdconf . . . . . . . . . . . . . .
pdconfig . . . . . . . . . . . . . .
pdjrtecfg . . . . . . . . . . . . . .
pdjservicelevel . . . . . . . . . . . .
PDMgr_config . . . . . . . . . . . .
PDMgr_unconfig . . . . . . . . . . .
pdproxycfg . . . . . . . . . . . . .
PDRTE_config . . . . . . . . . . . .
PDRTE_unconfig . . . . . . . . . . .
pdservicelevel . . . . . . . . . . . .
pdsmsclicfg . . . . . . . . . . . . .
pdversion . . . . . . . . . . . . .
pdweb. . . . . . . . . . . . . . .
pdwebpi . . . . . . . . . . . . . .
pdwebpi_start . . . . . . . . . . . .
pdwpi-version . . . . . . . . . . . .
pdwpicfg . . . . . . . . . . . . . .
query_contents . . . . . . . . . . . .
smsbackup . . . . . . . . . . . . .
smscfg. . . . . . . . . . . . . . .
smsservicelevel . . . . . . . . . . . .
svrsslcfg . . . . . . . . . . . . . .
.
.
.
.
209
210
211
211
. 211
212
. 212
. 213
. 217
. 221
. 226
. 229
. 230
. 231
. 233
. 236
. 237
. 240
. 242
. 245
. 247
. 250
. 251
. 252
. 254
. 258
. 260
. 261
. 266
. 267
. 270
. 272
. 275
. 278
. 278
. 279
. 282
. 284
. 285
. 286
. 287
. 288
. 290
. 291
. 293
. 300
. 301
Appendix A. Password limitations and
characters allowed in object names. . 307
General password policies .
IBM Security Access Manager for Web Version 7.0: Command Reference
.
.
.
.
.
.
.
. 307
Character limitations for passwords and user
names . . . . . . . . . . . . . . . .
Characters allowed for secure domain names. . .
Characters disallowed for user and group name
Characters disallowed for distinguished names . .
Characters disallowed for Microsoft Active
Directory distinguished names . . . . . .
Characters disallowed for GSO names . . . . .
Characters disallowed for authorization rule names
308
308
309
310
310
311
311
Characters disallowed for ACL policy names .
Characters disallowed for POP names . . .
Appendix B. Using response files
.
.
. 312
. 313
. . 315
Notices . . . . . . . . . . . . . . 317
Index . . . . . . . . . . . . . . . 321
Contents
v
vi
IBM Security Access Manager for Web Version 7.0: Command Reference
Tables
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Access control list (ACL) commands . .
Action commands . . . . . . . .
Authorization rule commands . . . .
Config commands . . . . . . . .
Context commands . . . . . . . .
Domain commands . . . . . . . .
Group commands . . . . . . . .
Logon commands . . . . . . . .
Object commands . . . . . . . .
Objectspace commands . . . . . .
Policy commands . . . . . . . .
Protected object policy (POP) commands
Resource commands . . . . . . .
© Copyright IBM Corp. 2001, 2012
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10
10
11
12
12
12
13
13
13
14
14
15
. 15
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
Server commands . . . . . . . . .
Server task commands . . . . . . . .
User commands . . . . . . . . . .
WebSEAL server task commands . . . .
Security Access Manager installation and
configuration utilities . . . . . . . .
Security Access Manager migration utilities
WebSEAL utilities . . . . . . . . .
Session management server utilities . . .
Security Access Manager for web servers
utilities. . . . . . . . . . . . .
Serviceability and problem determination
utilities . . . . . . . . . . . .
.
.
.
.
16
17
18
19
. 209
210
. 211
. 211
. 211
. 212
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 Manager
for e-business, is a user authentication, authorization, and web single sign-on
solution for enforcing security policies over a wide range of web and application
resources.
The IBM Security Access Manager for Web Command Reference provides a
comprehensive set of procedures and reference information for managing Security
Access Manager servers and resources. This guide also provides you with valuable
background and conceptual information for the wide range of Security Access
Manager functions.
Intended audience
This guide is for system administrators responsible for the deployment and
administration of base Security Access Manager software.
Readers must be familiar with the following systems and concepts:
v Microsoft Windows, AIX®, Linux, and Solaris operating systems
v Database architecture and concepts
v
v
v
v
v
Security management
Internet protocols, including HTTP and TCP/IP
Lightweight Directory Access Protocol (LDAP) and directory services
Authentication and authorization
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 terminology
This 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 initial
configuration of the WebSEAL Hardware Appliance, SC22-5434-00
v IBM Security Web Gateway Appliance Quick Start Guide – Virtual Offering
Guides users through the process of connecting and completing the initial
configuration of the WebSEAL Virtual Appliance.
© Copyright IBM Corp. 2001, 2012
ix
v IBM Security Access Manager for Web Installation Guide, GC23-6502-02
Explains how to install and configure Security Access Manager.
v IBM Security Access Manager for Web Upgrade Guide, SC23-6503-02
Provides information for users to upgrade from version 6.0, or 6.1.x to version
7.0.
v IBM Security Access Manager for Web Administration Guide, SC23-6504-02
Describes the concepts and procedures for using Security Access Manager.
Provides instructions for performing tasks from the Web Portal Manager
interface and by using the pdadmin utility.
v IBM Security Access Manager for Web WebSEAL Administration Guide, SC23-6505-02
Provides background material, administrative procedures, and reference
information for using WebSEAL to manage the resources of your secure Web
domain.
v IBM Security Access Manager for Web Plug-in for Web Servers Administration Guide,
SC23-6507-02
Provides procedures and reference information for securing your Web domain
by using a Web server plug-in.
v IBM Security Access Manager for Web Shared Session Management Administration
Guide, SC23-6509-02
Provides administrative considerations and operational instructions for the
session management server.
v IBM Security Access Manager for Web Shared Session Management Deployment Guide,
SC22-5431-00
Provides deployment considerations for the session management server.
v IBM Security Web Gateway Appliance Administration Guide, SC22-5432-00
Provides administrative procedures and technical reference information for the
WebSEAL Appliance.
v IBM Security Web Gateway Appliance Configuration Guide for Web Reverse Proxy,
SC22-5433-00
Provides configuration procedures and technical reference information for the
WebSEAL Appliance.
v IBM Security Web Gateway Appliance Web Reverse Proxy Stanza Reference,
SC27-4442-00
Provides a complete stanza reference for the IBM® Security Web Gateway
Appliance Web Reverse Proxy.
v IBM Security Access Manager for Web WebSEAL Configuration Stanza Reference,
SC27-4443-00
Provides a complete stanza reference for WebSEAL.
v IBM Global Security Kit: CapiCmd Users Guide, SC22-5459-00
Provides instructions on creating key databases, public-private key pairs, and
certificate requests.
v IBM Security Access Manager for Web Auditing Guide, SC23-6511-02
Provides information about configuring and managing audit events by using the
native Security Access Manager approach and the Common Auditing and
Reporting Service. You can also find information about installing and
configuring the Common Auditing and Reporting Service. Use this service for
generating 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 that
are provided with Security Access Manager.
v IBM Security Access Manager for Web Administration C API Developer Reference,
SC23-6513-02
Provides reference information about using the C language implementation of
the administration API to enable an application to perform Security Access
Manager administration tasks.
v IBM Security Access Manager for Web Administration Java Classes Developer
Reference, SC23-6514-02
Provides reference information about using the Java™ language implementation
of the administration API to enable an application to perform Security Access
Manager administration tasks.
v IBM Security Access Manager for Web Authorization C API Developer Reference,
SC23-6515-02
Provides reference information about using the C language implementation of
the authorization API to enable an application to use Security Access Manager
security.
v IBM Security Access Manager for Web Authorization Java Classes Developer Reference,
SC23-6516-02
Provides reference information about using the Java language implementation of
the authorization API to enable an application to use Security Access Manager
security.
v IBM Security Access Manager for Web Web Security Developer Reference,
SC23-6517-02
Provides programming and reference information for developing authentication
modules.
v IBM Security Access Manager for Web Error Message Reference, GI11-8157-02
Provides explanations and corrective actions for the messages and return code.
v IBM Security Access Manager for Web Troubleshooting Guide, GC27-2717-01
Provides problem determination information.
v IBM Security Access Manager for Web Performance Tuning Guide, SC23-6518-02
Provides performance tuning information for an environment that consists of
Security Access Manager with the IBM Tivoli Directory Server as the user
registry.
Online publications
IBM posts product publications when the product is released and when the
publications are updated at the following locations:
IBM Security Access Manager for Web Information Center
The http://pic.dhe.ibm.com/infocenter/tivihelp/v2r1/topic/
com.ibm.isam.doc_70/welcome.html site displays the information center
welcome page for this product.
IBM Publications Center
The http://www-05.ibm.com/e-business/linkweb/publications/servlet/
pbi.wss site offers customized search functions to help you find all the IBM
publications that you need.
About this publication
xi
IBM Terminology website
The IBM Terminology website consolidates terminology for product libraries in one
location. You can access the Terminology website at http://www.ibm.com/
software/globalization/terminology.
Related publications
This section lists the IBM products that are related to and included with the
Security Access Manager solution.
Note: The following middleware products are not packaged with IBM Security
Web 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 Web
Version 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 a
pure Java application with no dependency on the native GSKit runtime. Do not
move or remove the bundled java/jre/lib/gskikm.jar library.
The IBM Developer Kit and Runtime Environment, Java Technology Edition, Version 6
and 7, iKeyman User's Guide for version 8.0 is available on the Security Access
Manager 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 of
Transport 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 compatible
with earlier versions of GSKit. Any component that communicates with Security
Access 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 included
on the IBM Security Access Manager for Web Version 7.0 product image or DVD for
your 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
IBM Tivoli Directory Integrator
IBM Tivoli Directory Integrator version 7.1.1 is included on the IBM Tivoli Directory
Integrator Identity Edition V 7.1.1 for Multiplatform product image or DVD for your
particular 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 provided
on the IBM Security Access Manager for Web Version 7.0 product image or DVD for
your particular platform. You can install DB2® with the Tivoli Directory Server
software, or as a stand-alone product. DB2 is required when you use Tivoli
Directory Server or z/OS® LDAP servers as the user registry for Security Access
Manager. 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 with
Security Access Manager version 7.0. WebSphere eXtreme Scale is required only
when 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/
Accessibility
Accessibility features help users with a physical disability, such as restricted
mobility or limited vision, to use software products successfully. With this product,
you can use assistive technologies to hear and navigate the interface. You can also
use the keyboard instead of the mouse to operate all features of the graphical user
interface.
Visit the IBM Accessibility Center for more information about IBM's commitment
to accessibility.
About this publication
xiii
Technical training
For technical training information, see the following IBM Education website at
http://www.ibm.com/software/tivoli/education.
Support information
IBM Support provides assistance with code-related problems and routine, short
duration installation or usage questions. You can directly access the IBM Software
Support site at http://www.ibm.com/software/support/probsub.html.
The IBM Security Access Manager for Web Troubleshooting Guide provides details
about:
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 can
provide more support resources.
xiv
IBM Security Access Manager for Web Version 7.0: Command Reference
Chapter 1. pdadmin commands
The pdadmin command-line utility is installed as part of the IBM Security Access
Manager runtime package.
Use this interface to manage access control lists, groups, servers, users, objects, and
other resources in your secure domain. You can also automate certain management
functions by writing scripts that use pdadmin commands.
Use the Web Portal Manager interface, as discussed in the IBM Security Access
Manager for Web Administration Guide, to complete remotely similar administrative
tasks. When you use Web Portal Manager, no special network configuration is
needed 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 statements
Syntax diagrams pictorially display the order and parameters for the command
utility.
The reference documentation uses the following special characters to define syntax:
[]
Identifies optional options. Options that are not enclosed in brackets are
required.
...
Indicates that you can specify multiple values for the previous option.
|
Indicates mutually exclusive information. You can use the option to the left
of the separator or the option to the right of the separator. You cannot use
both options in a single use of the command.
{}
Delimits a set of mutually exclusive options when one of the options is
required. If the options are optional, they are enclosed in brackets ([ ]).
\
Indicates that the command line wraps to the next line. It is a continuation
character.
The options for each command are listed alphabetically in the Options section. The
options for each utility are listed alphabetically in the Parameters section. When
the order of the options or parameters must be used in a specific order, this order
is shown in the syntax statements.
Syntax for pdadmin commands
The 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:
command
Specifies the single pdadmin command to run. The command is run one
time. The pdadmin utility does not enter interactive mode. The command
option is mutually exclusive with the file option.
file
Specifies the fully qualified name of the file that contains a list of
commands to run. These commands are run one time. The pdadmin utility
does not enter interactive mode. The file option is mutually exclusive
with the command option.
Note: For Windows operating systems, file names cannot contain the
backward slash (\), colon (:), question mark (?), or double quotation mark
characters.
–a admin_id
Logs you in as the user admin_id. This administrator must exist in the
domain. If you do not specify this option on the command line, you are
considered unauthenticated, and your access to other commands is limited.
If you specify this option without specify the –p option, you are prompted
for the password.
The –a option is mutually exclusive with the –l option. If you do not
specify 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 domain
Specifies the Security Access Manager secure domain to log in. Log in to
this domain requires authentication. The admin_id user that is specified
must exist in this domain. The –d option is mutually exclusive with the –m
option. If neither options are specified, the target domain is the local
domain that is configured for the system.
–I configuration-instance-name
Specifies the pd.conf file instance that the pdadmin command should use.
The configuration-instance-name value is the hostname that is provided to
the pdadmin_host command that generated the configuration file. This
option allows pdadmin to communicate with multiple policy servers.
–l
2
Specifies a local login operation. When modifications are made to local
configuration files by using the pdadmin config commands, a local login is
required before you can run commands.
IBM Security Access Manager for Web Version 7.0: Command Reference
The –l option is mutually exclusive with the –a option. If you do not
specify 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-linelen
Currently, the –linelen option is ignored.
–m
Specifies that the login operation must be directed to the management
domain. Log in to this domain requires authentication. The admin_id user
that is specified must exist in this domain. The –m option is mutually
exclusive with the –d option. If neither options are specified, the target
domain is the local domain that is configured for the system.
–p password
Specifies the password for the user admin_id. Using this option might show
your password to others because the password is visible on the screen and
also in the process table. If you do not specify this option on the command
line, you are prompted for a password. This option cannot be used unless
the –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 this
option:
Security Access Manager Administrative Tool v7.0.0.0 (Build 111215)
Copyright (C) IBM Corporation 2012. All Rights Reserved.
–histsize
Specifies the command history size. The default command history size is
64. The minimum size of the command history is 1 and the maximum size
is 1024. The command history option is available only in the interactive
mode 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 this
method might show your password to others. For example, one user is using
pdadmin with this command. Another user lists the processes that are running.
Then, the full command that includes the password, might be visible to the
second user.
2. Users can run the pdadmin context show command to view their authentication
information.
Command modes
You 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 4
v “Interactive command mode” on page 4
v “Multiple command mode” on page 5
For details about the command options that are displayed in the following
sections, see “Syntax for pdadmin commands” on page 1.
Chapter 1. pdadmin commands
3
Single command mode
In single command mode, the CLI runs only the specified command, and ends
after 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” on
page 1.
Interactive command mode
Interactive command mode uses an interactive command-line session where, after
the 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, where
your access to other pdadmin commands is limited for unauthenticated users, such
as 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 can
use other pdadmin commands. You can be prompted for both the administrator ID
and the password:
c:\> pdadmin
pdadmin> login
Enter User ID:sec_master
Enter Password: secmstrpw
pdadmin sec_master> pdadmin_command
Or, you can be prompted for just the administrator password:
c:\> pdadmin
pdadmin> login -a sec_master
Enter Password: secmstrpw
pdadmin sec_master> pdadmin_command
Or, you can bypass being prompted, which is less secure because your password is
visible:
c:\> pdadmin
pdadmin> login -a sec_master -p secmstrpw
pdadmin sec_master> pdadmin_command
4
IBM Security Access Manager for Web Version 7.0: Command Reference
To start pdadmin in interactive mode with a login for issuing local configuration
commands, use the local login (pdadmin login –l) command. You can use the
config 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 associated
options. The pdadmin prompt changes, depending on the type of login. See “Login
and logout commands” on page 13 for more information about the login
command and prompt changes.
Note: In this release, the length of a command line that is used in pdadmin
interactive mode is limited to 1023 characters.
Multiple command mode
With multiple command mode, you can create a file that contains multiple pdadmin
commands, 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 and
remote login, as needed. Login commands can be included in a command file to
switch 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 pdadmin
login –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 following
sections, see “Syntax for pdadmin commands” on page 1.
Chapter 1. pdadmin commands
5
Non-English locales
For Security Access Manager software, you can specify localized behavior by
setting 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 and
globalization. However, be aware of the following issues when you are running the
pdadmin 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's
local (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 the
Nls/CodePage/ACP key in the Windows registry. Files that are created by
standard Windows editing tools (such as Notepad or WordPad) are encoded in
this way.
On AIX, Linux, and Solaris operating systems, you must run the pdadmin
command in the same locale that was used to create the command file.
v On Windows operating systems, you can enter commands to pdadmin by
redirecting a command file. The command file must be encoded in a Microsoft
Original Equipment Manufacturer (OEM) code page. The OEM code page
corresponds to the active code page in the command window in which the
pdadmin 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 the
pdadmin command window.
Alternatively, you can redirect a file that is encoded in the local code page of the
system. However, you must change the active code page of the command
window to correspond to the encoding of the file. Change the active code page
of the window by using the chcp command. For example, entering the command
chcp 1252 changes the active code page to the ANSI code page for Western
Europe and the United States.
On AIX, Linux, and Solaris operating systems, you must run the pdadmin
command in the same locale that was used to create the redirected command
file.
v Security Access Manager data that is created in one locale might not display
correctly on a system that is configured to another locale. Whether data displays
correctly depends on the configuration of the second system. For example,
correct display depends on what the current locale is, and whether the necessary
code pages and fonts are installed.
Error handling
After a command finishes processing, a return code is displayed or logged to
provide the success or failure of the command.
The pdadmin command has the following return code values:
0
6
The command that completed successfully.
IBM Security Access Manager for Web Version 7.0: Command Reference
1
The command failed. When a command fails, the pdadmin command
displays a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
For information about how to use the message number that is associated with a
message to display only the descriptive text, see “errtext” on page 54.
Return codes for a single command
A single command is normally typed from a command prompt such as a DOS
command prompt, Korn shell prompt, and C shell prompt. Single command mode
does not automatically display the 0 or 1 return code values; the operating system
must be queried for the return code value.
For command failures, the hexadecimal error code status with its associated error
message 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 text
file. When a single command fails, you see an error message that is like the one
displayed:
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 errorlevel
command:
v For AIX, Linux, and Solaris operating systems:
# pdadmin_command
# echo $?
v For Windows operating systems:
C:>pdadmin_command
C:>echo %errorlevel%
Return codes for an interactive command
Interactive command mode does not automatically display the 0 or 1 return code
values. Also, you cannot follow an interactive command with the AIX, Linux, and
Solaris echo or the Windows errorlevel command.
For a command failure, you see a message that is like:
pdadmin sec_master> user show oogle
Could not perform the administration request.
Error: HPDMG0754WThe entry was not found. If ...
(status 0x14c012f2)
Only the hexadecimal exit status code is displayed.
Return codes for multiple commands
You can use a text file containing pdadmin commands to run those commands in a
single pdadmin invocation.
Chapter 1. pdadmin commands
7
Consider that an error occurs for a command while the commands run in multiple
command mode. Then, an error message for the failed command is provided.
Processing of the remaining commands in the file continues after an error. At the
end of multiple command processing, a final status is provided. The final status
code at the termination of multiple command processing is only for the last
command 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 cwright
user 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: cwright
LDAP DN: cn=Claude Wright,ou=Dallas,o=Tivoli,c=us
LDAP CN: Claude Wright
LDAP SN: Wright
Description:
Is SecUser: yes
Is GSO user: no
Account valid: yes
Password valid: yes
Authorization mechanism: Default:LDAP
cmd:> user show oogle
Could not perform the administration request.
Error: HPDMG0754WThe entry was not found. If ...
(status 0x14c012f2)
Local or other domain
Use the pdadmin command to authenticate your user ID and password. You must
authenticate before you log in to the local domain or to a domain other than the
local 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 your
own local domain.
To authenticate and log in to a domain with a name that is different from the local
domain, 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 is
the domain_name to which you are logging on, in interactive mode.
8
IBM Security Access Manager for Web Version 7.0: Command Reference
Command option processing
Some pdadmin command options use specific symbols or characters.
Some pdadmin command options begin with a hyphen (-). For example, the
following 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 a
command 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 an
argument rather than as a command option. For example, you might want to name
the 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 name
would 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 optional
arguments, 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 order
so that all tokens that begin with a hyphen, which are not command options,
follow the single hyphen character.
Commands by category
The pdadmin commands are listed here by major category.
This section lists the pdadmin commands by the following categories:
v
v
v
v
v
v
v
“Access control list commands” on page 10
“Action commands” on page 10
“Authorization rule commands” on page 11
“Configuration commands” on page 11
“Context commands” on page 12
“Domain commands” on page 12
“Group commands” on page 12
v
v
v
v
v
v
v
v
“Login and logout commands” on page 13
“Object commands” on page 13
“Object space commands” on page 14
“Policy commands” on page 14
“Protected object policy commands” on page 15
“Resource and resource group commands” on page 15
“Server commands” on page 16
“Session Management Server commands” on page 17
Chapter 1. pdadmin commands
9
v “User commands” on page 18
v “WebSEAL commands” on page 19
Access control list commands
Use acl commands to manage access control list (ACL) policies and extended
attributes.
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. If
the protected object already has an ACL
attached, 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. This “acl create” on
command does not create ACL entries.
page 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 a
protected object. This command does not delete
the ACL policy from the ACL database.
“acl detach”
on page 24
“acl find” on page 25
Finds and lists all protected objects that have a
specific ACL policy attached.
“acl find” on
page 25
“acl list” on page 26
Lists the names of all defined ACLs. Also lists
the extended attribute keys that are associated
with a specific ACL.
“acl list” on
page 26
“acl modify” on page 26 Modifies ACLs, their extended attributes, and
associated values.
“acl modify”
on page 26
“acl show” on page 30
“acl show” on
page 30
Lists the complete set of entries for a specific
ACL policy. Also lists the values of a specific
extended attribute that is associated with an
ACL policy.
Action commands
The action commands define more authorization actions (permissions) and action
groups.
Table 2 lists action commands.
Table 2. Action commands
Command
10
Description
Page
“action create” on page
31
Creates and adds an action to an action group.
“action create”
on page 31
“action delete” on page
33
Deletes an action from an action group.
“action delete”
on page 33
“action group create” on Creates an action group.
page 34
“action group
create” on
page 34
“action group delete”
on page 34
“action group
delete” on
page 34
Deletes an action group.
IBM Security Access Manager for Web Version 7.0: Command Reference
Table 2. Action commands (continued)
Command
Description
Page
“action group list” on
page 35
Lists all action groups.
“action group
list” on page
35
“action list” on page 35
Lists all defined actions in an action group.
“action list”
on page 35
Authorization rule commands
The authzrule commands manage authorization rules.
Table 3 lists authzrule commands.
Table 3. Authorization rule commands
Command
Description
Page
“authzrule attach” on
page 37
Attaches an authorization rule to the specified
protected object.
“authzrule
attach” on
page 37
“authzrule create” on
page 38
Creates an authorization rule.
“authzrule
create” on
page 38
“authzrule delete” on
page 39
Deletes an authorization rule.
“authzrule
delete” on
page 39
“authzrule detach” on
page 40
Detaches an authorization rule from the
specified protected object.
“authzrule
detach” on
page 40
“authzrule find” on
page 40
Finds and lists all the protected objects that have “authzrule
the specified authorization rule attached.
find” on page
40
“authzrule list” on page Lists all the registered authorization rules.
41
“authzrule
list” on page
41
“authzrule modify” on
page 42
Modifies an authorization rule.
“authzrule
modify” on
page 42
“authzrule show” on
page 43
Shows all the attributes of an authorization rule,
including description, rule text, and fail reason
code.
“authzrule
show” on
page 43
Configuration commands
Configuration commands modify the local configuration files.
Table 5 on page 12 lists config commands that are configuration database
commands.
Chapter 1. pdadmin commands
11
Table 4. Config commands
Command
Description
Page
“config modify” on
page 44
Modifies a stanza entry in a configuration file or “config
sets the password for the server user account.
modify” on
page 44
“config show” on page
46
Shows the value that is associated with specified “config show”
stanzas or keys in Security Access Manager
on page 46
server configuration files or in customized server
configuration files.
Context commands
Context commands display the context (authentication) information for the user
who is running the pdadmin utility.
Table 5 lists context commands.
Table 5. Context commands
Command
Description
“context show” on page Displays the user ID and domain ID used to
48
establish the current context.
Page
“context
show” on
page 48
Domain commands
Domain commands manage Security Access Manager secure domains.
Table 6 lists domain commands.
Table 6. Domain commands
Command
Description
Page
“domain create” on
page 49
Creates a Security Access Manager secure
domain.
“domain
create” on
page 49
“domain delete” on
page 51
Deletes the specified Security Access Manager
secure domain, and optionally deletes the
information about the domain from the user
registry.
“domain
delete” on
page 51
“domain list” on page
52
Lists all the domains except for the management “domain list”
domain.
on page 52
“domain modify” on
page 53
Modifies the description of the specified domain. “domain
modify” on
page 53
“domain show” on page Displays the specified attributes of the domain,
54
including name and description.
“domain
show” on
page 54
Group commands
Group commands manage Security Access Manager groups.
A group is a set of Security Access Manager user accounts that have similar
attributes. By using groups, you can use a group name in an access control list
12
IBM Security Access Manager for Web Version 7.0: Command Reference
(ACL) instead of listing all users individually. When an LDAP-based user registry
is used, group names are not case-sensitive.
Table 7 lists group commands.
Table 7. Group commands
Command
Description
Page
“group create” on page
56
Creates a group.
“group create”
on page 56
“group delete” on page
57
Deletes the specified Security Access Manager
group and optionally deletes the information
about the group from the user registry. ACL
entries that are associated with the group are
also deleted.
“group delete”
on page 57
“group import” on page Imports the information about an existing
58
registry group to create a Security Access
Manager group.
“group
import” on
page 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” on
page 61
Changes an existing group by adding a
description, or adding or removing a list of
members.
“group
modify” on
page 61
“group show” on page
62
Displays details about a specified group.
“group show”
on page 62
Login and logout commands
Login and logout commands are used to log in to, and log out of, a Security
Access Manager secure domain.
Table 8 lists login and logout commands.
Table 8. Logon commands
Command
Description
Page
“login” on page 65
Authenticates the user to the Security Access
Manager policy server as a given administrative
identity in a domain.
“login” on
page 65
“logout” on page 67
Discards any authentication credentials that are
in effect.
“logout” on
page 67
Object commands
Object commands can protect objects by attaching ACLs or protected object policy
(POP).
Table 9 lists objects commands.
Table 9. Object commands
Command
Description
Page
“object access” on page
68
Confirms whether a specified access is permitted “object access”
on the named protected object.
on page 68
“object create” on page
69
Creates a protected object.
“object create”
on page 69
Chapter 1. pdadmin commands
13
Table 9. Object commands (continued)
Command
Description
Page
“object delete” on page
71
Deletes a protected object.
“object delete”
on page 71
“object exists” on page
72
Confirms whether a protected object is in either
the policy database or in an object space that is
managed by an administration service plug-in.
“object exists”
on page 72
“object list” on page 73
Lists any objects that are grouped under the
specified protected object. Also lists all the
extended attributes that are associated with the
specified protected object.
“object list”
on page 73
“object listandshow” on
page 74
Lists any child objects that are grouped under
the specified protected object and shows all
values that are associated with each of those
objects.
“object
listandshow”
on page 74
“object modify” on page Modifies an existing object.
75
“object
modify” on
page 75
“object show” on page
77
“object show”
on page 77
Shows all values that are associated with a
protected object.
Object space commands
Object space commands allow the creation of more object spaces that contain
protected objects that are used by third-party applications.
Table 10 lists objectspace commands.
Table 10. Objectspace commands
Command
Description
Page
“objectspace create” on
page 81
Creates a protected object space under which
protected objects can be placed.
“objectspace
create” on
page 81
“objectspace delete” on
page 82
Deletes an existing protected object space and all “objectspace
associated protected objects.
delete” on
page 82
“objectspace list” on
page 83
Lists all the existing protected object spaces in
the policy server.
“objectspace
list” on page
83
Policy commands
Policy commands manage user password and account policies.
Table 11 lists policy commands.
Table 11. Policy commands
Command
“policy get” on page 83
14
Description
Displays the policy for user passwords, account
rules, and conditions. Requires authentication
(administrator ID and password) to use this
command.
IBM Security Access Manager for Web Version 7.0: Command Reference
Page
“policy get”
on page 83
Table 11. Policy commands (continued)
Command
“policy set” on page 86
Description
Page
Sets the policy for user passwords, account rules, “policy set”
and conditions. Requires authentication
on page 86
(administrator ID and password) to use this
command.
Protected object policy commands
Protected 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
Command
Description
Page
“pop attach” on page 90
Attaches a protected object policy to a
specified 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 the
specified protected object.
“pop detach”
on page 92
“pop find” on page 93
Finds and lists all protected objects with
protected object policies attached.
“pop find”
on page 93
“pop list” on page 94
Lists all created protected object policies.
“pop list” on
page 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 object
policy.
“pop show”
on page 98
Resource and resource group commands
Resource and resource group commands manage resource-related information.
Table 13 lists rsrc, rsrccred, and rsrcgroup commands.
Table 13. Resource commands
Command
Description
Page
“rsrc create” on page 99 Creates and names a server as a resource.
“rsrc create”
on page 99
“rsrc delete” on page
100
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 resource
names.
“rsrc list” on
page 101
“rsrc show” on page 102 Displays the resource information for the named “rsrc show”
resource.
on page 102
Chapter 1. pdadmin commands
15
Table 13. Resource commands (continued)
Command
Description
Page
“rsrccred create” on
page 102
Creates and names a resource credential.
“rsrccred
create” on
page 102
“rsrccred delete” on
page 104
Deletes only the resource credential information
for an existing user.
“rsrccred
delete” on
page 104
“rsrccred list user” on
page 105
Displays the names of all defined resource
credentials and their type for the specified user.
“rsrccred list
user” on page
105
“rsrccred modify” on
page 106
Changes the user ID and password resource
credential information for the named resource.
“rsrccred
modify” on
page 106
“rsrccred show” on
page 107
Displays the resource credential information for
a specified user.
“rsrccred
show” on
page 107
“rsrcgroup create” on
page 108
Creates and names a resource group.
“rsrcgroup
create” on
page 108
“rsrcgroup delete” on
page 109
Deletes the named resource group, including any “rsrcgroup
description information.
delete” on
page 109
“rsrcgroup list” on page Displays the names of all resource groups that
110
are defined in the user registry.
“rsrcgroup
list” on page
110
“rsrcgroup modify” on
page 110
Adds or removes a single sign-on resource to or
from a single sign-on resource group.
“rsrcgroup
modify” on
page 110
“rsrcgroup show” on
page 112
Displays the resource group information for the
specified resource group.
“rsrcgroup
show” on
page 112
Server commands
Server commands perform management tasks on Security Access Manager servers.
Table 14 lists server and server task commands, and the admin show config
command.
Table 14. Server commands
Command
16
Description
Page
“admin show conf” on
page 36
Displays current policy server configuration
information.
“admin show
conf” on page
36
“server list” on page 112
Lists all registered servers.
“server list”
on page 112
“server listtasks” on page
113
Retrieves the list of tasks (commands)
available for this server.
“server
listtasks” on
page 113
IBM Security Access Manager for Web Version 7.0: Command Reference
Table 14. Server commands (continued)
Command
Description
Page
“server replicate” on page
115
Notifies authorization servers to receive
database updates.
“server
replicate” on
page 115
“server show” on page 116
Displays the specified properties of the server. “server
show” on
page 116
“server task help” on page
131
Lists detailed help information about a
specific server task command.
“server task
help” on
page 131
“server task stats” on page
159
Manages the gathering and reporting of
statistics for Security Access Manager servers
and server instances.
“server task
stats” on
page 159
“server task trace” on page
166
Enables the gathering of trace information for
components of installed Security Access
Manager servers or server instances that
support debug event tracing.
“server task
trace” on
page 166
Session Management Server commands
Session Management Server commands perform session management tasks. These
commands are available only when a Web security server and Session Management
Server are installed.
Table 15 lists server task commands.
Table 15. Server task commands
Command
“server task sms key
change” on page 144
Description
Forces the creation of a new session
management key.
Page
“server task
sms key
change” on
page 144
“server task sms key show” Lists detailed information about the current
on page 145
session management key.
“server task
sms key
show” on
page 145
“server task sms realm list” Lists all session management server realms in
on page 146
the domain.
“server task
sms realm
list” on page
146
“server task sms realm
show” on page 147
Lists all session management server realms
within the specified realm.
“server task
sms realm
show” on
page 147
“server task sms session
refresh all_sessions” on
page 148
Refreshes the credential for all sessions for a
specified user.
“server task
sms session
refresh
all_sessions”
on page 148
Chapter 1. pdadmin commands
17
Table 15. Server task commands (continued)
Command
Description
Page
“server task sms session
refresh session” on page
150
Refreshes the credential for a session.
“server task
sms session
refresh
session” on
page 150
“server task sms replica set
list” on page 151
Lists all session management replica sets in
the domain.
“server task
sms replica
set list” on
page 151
“server task sms replica set
show” on page 152
Lists all session management replica sets in
the domain with the time and date each
joined the realm.
“server task
sms replica
set show” on
page 152
“server task sms session
list” on page 153
Lists all session management sessions.
“server task
sms session
list” on page
153
“server task sms session
terminate all_sessions” on
page 154
Terminates all user sessions for a specific user. “server task
sms session
terminate
all_sessions”
on page 154
“server task sms session
terminate session” on page
156
Terminates a specific session.
“server task
sms session
terminate
session” on
page 156
“server task sms trace get”
on page 157
Displays the trace level for the session
management server.
“server task
sms trace
get” on page
157
“server task sms trace set”
on page 158
Sets the trace level for the session
management server.
“server task
sms trace set”
on page 158
User commands
User commands manage Security Access Manager users.
Table 16 lists user commands.
Table 16. User commands
Command
18
Description
Page
“user create” on page 197
Creates a Security Access Manager user
account.
“user create”
on page 197
“user delete” on page 199
Deletes a Security Access Manager user and
optionally deletes the user information from
the user registry. ACL entries that are
associated with the user are also deleted.
“user delete”
on page 199
“user import” on page 200
Imports the information about an existing
registry user to create a Security Access
Manager user.
“user import”
on page 200
IBM Security Access Manager for Web Version 7.0: Command Reference
Table 16. User commands (continued)
Command
Description
Page
“user list” on page 201
Generates a list of all users whose names
“user list” on
match the specified pattern, which is listed by page 201
user names.
“user modify” on page 203
Modifies various user account parameters.
“user
modify” on
page 203
“user show” on page 205
Displays details about a specified user.
“user show”
on page 205
WebSEAL commands
WebSEAL commands perform management tasks on WebSEAL servers and
instances. These commands are available only when WebSEAL is installed.
Table 17 lists server task commands.
Table 17. WebSEAL server task commands
Command
“server task add” on page
117
Description
Adds an application server to an existing
WebSEAL junction.
Page
“server task
add” on page
117
“server task cache flush all” Flushes the HTML document cache.
on page 120
“server task
cache flush
all” on page
120
“server task create” on
page 121
Creates a WebSEAL junction point.
“server task
create” on
page 121
“server task delete” on
page 128
Deletes a WebSEAL junction point.
“server task
delete” on
page 128
“server task dynurl
update” on page 130
Reloads the dynamic URL configuration file.
“server task
dynurl
update” on
page 130
“server task help” on page
131
Lists detailed help information about a
specific server task command.
“server task
help” on
page 131
“server task jmt” on page
133
Clears or loads the junction mapping table
data.
“server task
jmt” on page
133
“server task list” on page
134
Lists all junction points on a WebSEAL server
or server instance.
“server task
list” on page
134
“server task offline” on
page 135
Places the server that is at this junction in an
offline operational state.
“server task
offline” on
page 135
“server task online” on
page 137
Places the server that is at this junction in an
online operational state.
“server task
online” on
page 137
Chapter 1. pdadmin commands
19
Table 17. WebSEAL server task commands (continued)
Command
Description
“server task refresh
all_sessions” on page 139
Refreshes the credential for all sessions for a
specified user.
“server task
refresh
all_sessions”
on page 139
“server task reload” on
page 140
Reloads the junction mapping table from the
database.
“server task
reload” on
page 140
“server task remove” on
page 141
Removes the specified installed WebSEAL
server or server instance from a WebSEAL
junction point.
“server task
remove” on
page 141
“server task show” on page Displays detailed information about the
143
specified WebSEAL junction.
20
Page
“server task
show” on
page 143
“server task terminate
all_sessions” on page 162
Terminates all user sessions for a specific user. “server task
terminate
all_sessions”
on page 162
“server task terminate
session” on page 163
Terminates a user session by using a session
ID.
“server task
terminate
session” on
page 163
“server task throttle” on
page 164
Places the server that is at this junction in a
throttled operational state.
“server task
throttle” on
page 164
“server task virtualhost
add” on page 168
Adds an additional installed WebSEAL server
or server instance to an existing virtual host
junction.
“server task
virtualhost
add” on page
168
“server task virtualhost
create” on page 171
Creates a virtual host junction.
“server task
virtualhost
create” on
page 171
“server task virtualhost
delete” on page 177
Deletes a virtual host junction.
“server task
virtualhost
delete” on
page 177
“server task virtualhost
list” on page 179
Lists all configured virtual host junctions by
label name.
“server task
virtualhost
list” on page
179
“server task virtualhost
offline” on page 180
Places the server that is at this virtual host
junction in an offline operational state.
“server task
virtualhost
offline” on
page 180
“server task virtualhost
online” on page 182
Places the server that is at this virtual host
junction in an online operational state.
“server task
virtualhost
online” on
page 182
“server task virtualhost
remove” on page 184
Removes the specified server from a virtual
host junction.
“server task
virtualhost
remove” on
page 184
IBM Security Access Manager for Web Version 7.0: Command Reference
Table 17. WebSEAL server task commands (continued)
Command
Description
Page
“server task virtualhost
show” on page 186
Displays information about the specified
virtual host junction.
“server task
virtualhost
show” on
page 186
“server task virtualhost
throttle” on page 188
Places the server that is at this virtual host
junction in a throttled operational state.
“server task
virtualhost
throttle” on
page 188
“server task server restart”
on page 190
Restarts the WebSEAL instance.
“server task
server
restart” on
page 190
“server task server sync”
on page 191
Synchronizes the configuration of the supplied “server task
WebSEAL authorization server to the current server sync”
WebSEAL server.
on page 191
“server task jdb export” on
page 192
Exports the current junction database into a
single file.
“server task jdb import” on Imports the current junction database from a
page 193
single file.
“server task
jdb export”
on page 192
“server task
jdb import”
on page 193
“server task cfgdb export”
on page 194
Exports the current configuration into a single “server task
file. The export is based on a configured set of cfgdb export”
exclude and include rules. It also exports the on page 194
configured list of data files.
“server task cfgdb import”
on page 195
Imports the configuration from the specified
exported file into the current WebSEAL
configuration file. The import is based on a
configured set of exclude and include rules. It
also imports the configured list of data files.
“server task file cat” on
page 196
Obtains the string content of the specified file. “server task
A flag controls whether the contents of the file file cat” on
are base64 encoded or not encoded. A
page 196
WebSEAL configuration item defines the
maximum allowable size of the file.
“server task
cfgdb
import” on
page 195
acl attach
Attaches an ACL policy to a protected object. If the protected object already has an
ACL 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 can
be attached to multiple protected objects. Ensure that you are familiar with ACL
management before you use this function.
Chapter 1. pdadmin commands
21
Options
acl_name
Specifies the ACL policy that is applied to the named object. The ACL
policy must exist, or an error is displayed.
Examples of the ACL names are default-root, test, default-management,
and pubs_acl3.
object_name
Specifies the object to which to apply the named ACL policy. The object
name 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 command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access 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 create
Creates an ACL policy in the ACL database. This command does not create ACL
entries.
Requires authentication (administrator ID and password) to use this command.
Syntax
acl create acl_name
Options
acl_name
Specifies the name of the ACL policy that is being created. 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. The following characters cannot be used in the
name of the ACL policy:
22
IBM Security Access Manager for Web Version 7.0: Command Reference
! " # & ( ) * + , ; : < > = @ / \ | .
Examples: default-root, test, default-management, and pubs_acl3
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 delete
Deletes an ACL policy from the ACL database.
Requires authentication (administrator ID and password) to use this command.
Syntax
acl delete acl_name
Options
acl_name
Specifies the name of the ACL policy that is being deleted from the ACL
database. The ACL policy must exist, or an error is displayed.
Examples: default-root, test, default-management, and pubs_acl3.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example deletes the ACL policy that is named pubs_acl3:
pdadmin sec_master> acl delete pubs_acl3
Chapter 1. pdadmin commands
23
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 detach
Detaches the current ACL policy from a protected object. This command does not
delete the ACL policy from the ACL database.
Requires authentication (administrator ID and password) to use this command.
Syntax
acl detach object_name
Description
Only one access control list at a time can be attached to an object. Therefore, the
currently attached access control list is detached. If the object does not have an
attached ACL policy, an error is displayed.
Options
object_name
Specifies 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.
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 command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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
24
IBM Security Access Manager for Web Version 7.0: Command Reference
acl find
Returns a list of protected objects, which have the specified ACL attached.
Requires authentication (administrator ID and password) to use this command.
Syntax
acl find acl_name
Description
A user must have the browse (b) and view (v) permissions for the object to be
listed when the pdadmin object show command is issued. Otherwise, an error is
returned:
The user is not authorized to view one or more protected objects where the
requested acl is attached.
Options
acl_name
Specifies the name of the ACL policy that you want to find. The ACL
policy must exist, or an error is displayed.
Examples: default-root, test, default-management, and pubs_acl3
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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-defined
ACL, _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
Chapter 1. pdadmin commands
25
acl list
Lists the names of all defined access control lists. Alternatively, lists the extended
attribute keys that are associated with a specific ACL.
Requires authentication (administrator ID and password) to use this command.
Syntax
acl list
acl list [acl_name attribute]
acl list [pattern max-return]
Options
acl_name attribute
Specifies the ACL policy for which to list the attributes. The ACL policy
must exist, or an error is displayed. (Optional)
Examples: default-root, test, default-management and pubs_acl3.
pattern max-return
Specifies the pattern and the maximum number of access control lists to be
returned. (Optional)
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example lists ACL policies:
pdadmin sec_master> acl list
The output is like:
default-webseal
default-root
test
default-replica
default-management
See also
“acl find” on page 25
“acl show” on page 30
acl modify
Modifies access control list (ACL) policies.
Requires authentication (administrator ID and password) to use this command.
26
IBM Security Access Manager for Web Version 7.0: Command Reference
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_name
Specifies the ACL policy that you want to be modified. The ACL policy
must exist, or an error is displayed.
Examples: default-root, test, default-management, and pubs_acl3
delete attribute attribute_name [attribute_value]
Deletes the specified extended attribute name and value from the specified
ACL. The attribute must exist, or an error is displayed.
The attribute_value deletes the specified value from the specified
extended attribute key in the specified ACL. (Optional)
Examples of extended attribute names and values:
Dept_No 445
Employee_Name "Diana Lucas"
description description
Sets or modifies the description for the specified ACL. This option is
equivalent to the acl modify set description command. Use the acl
modify description command instead of the acl modify set description
command.
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 code
set. Spaces are allowed.
If the description contains a space, ensure that you enclose the description
in double quotation marks. You can specify an empty string ("") to clear an
existing description.
Example of description: "Department number of employee"
Chapter 1. pdadmin commands
27
permissions
Security Access Manager uses a set of default actions (known as primary
action tasks and permissions) that cover a wide range of operations. You
can also create your own action tasks and permissions. Primary
permissions and procedures for entering custom permissions into ACL
entries are described in the IBM Security Access Manager for Web
Administration Guide.
A complete list of primary action tasks and their associated permissions
includes:
TTraverseBase
cControlBase
gDelegationBase
mModifyGeneric
dDeleteGeneric
bBrowseBase
sServer AdminGeneric
vViewGeneric
aAttachBase
BBypass POPBase
tTraceBase
rReadWebSEAL
xExecuteWebSEAL
lList DirectoryWebSEAL
NCreateBase
WPasswordBase
AAddBase
RBypass AuthzRuleBase
remove any-other
Removes the ACL entry for the any-other user category from the specified
ACL.
remove group group_name
Removes 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 unauthenticated
Removes the ACL entry for the unauthenticated user category from the
specified ACL.
remove user user_name
Removes the ACL entry for the specified user from the specified ACL. The
user 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 ASCII
characters (a-z, A-Z).
set attribute attribute_name attribute_value
Sets the extended attribute value for the specified extended attribute key in
the specified ACL. The attribute must exist, or an error is displayed. If the
attribute exists, the attribute value is added as an additional value if the
same value does not exist for this attribute. If the same value exists for this
attribute, 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 specified
extended attribute key in the specified ACL.
28
IBM Security Access Manager for Web Version 7.0: Command Reference
Examples of extended attribute names and values:
Dept_No 445
Employee_name "Diana Lucas"
set description description
Sets or modifies the description for the specified ACL. This option is
equivalent to the acl modify description command. Use the acl modify
description command instead of the acl modify set description
command.
set group group_name [permissions]
Sets or modifies the ACL entry for the specified group in the specified
ACL. The group must exist, or an error is displayed.
Examples of group names are Credit, Sales, and Test-group.
Security Access Manager uses a set of default actions that cover a wide
range of operations. Valid actions, or permissions, are represented by single
alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for
the list of possible permissions.
set unauthenticated [permissions]
Sets or modifies the ACL entry for the unauthenticated user category in
the specified ACL.
Security Access Manager uses a set of default actions that cover a wide
range of operations. Valid actions, or permissions, are represented by single
alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for
examples of permissions.
set user user_name [permissions]
Sets permissions that the user is permitted to perform. The user must exist
or an error is displayed.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Security Access Manager uses a set of default actions that cover a wide
range of operations. Valid actions, or permissions, are represented by single
alphabetic ASCII characters (a-z, A-Z). See set any-other [permissions] for
examples of permissions.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 the
Tr 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 to
have the r permission, which is the Read (WebSEAL) permission:
Chapter 1. pdadmin commands
29
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 Tr
permissions, 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 Tbr
permissions, which are the Traverse (Base), Browse (Base) and Read (WebSEAL)
permissions. It also sets custom permissions PS for the existing test-group action
group. 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: test
Description:
Entries:
User sec_master TcmdbsvaBl
Group ivmgrd-servers Tl
Any-other r
User kathy Tbr[test-group]PS
v The following example sets the kathy user entry in the test ACL to have Tbr
permissions, 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: test
Description:
Entries:
User sec_master TcmdbsvaBl
Group ivmgrd-servers Tl
Any-other r
User kathy Tbr
See also
“acl attach” on page 21
“acl create” on page 22
acl show
Lists 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 with
an ACL policy.
Requires authentication (administrator ID and password) to use this command.
Syntax
acl show acl_name [attribute attribute_name]
Options
acl_name
Specifies the name of the ACL policy for which the extended attribute
values are displayed. The ACL policy must exist, or an error is displayed.
Examples of ACL names are default-root, test, default-management, and
pubs_acl3.
30
IBM Security Access Manager for Web Version 7.0: Command Reference
attribute attribute_name
Specifies 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
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example shows details about ACL test-acl:
pdadmin sec_master> acl show test-acl
ACL Name: test-acl
Description:
Entries:
User sec_master Tcmdbva
Group ivmgrd-servers Tl
Any other r
See also
“acl find” on page 25
“acl list” on page 26
action create
Creates and adds an action (permission) to an action group.
Requires authentication (administrator ID and password) to use this command.
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 are
case-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 add
custom codes to the primary group.
Options
action_group_name
Specifies the name of the action group to which the action code is to be
added. If no action group is specified, the action is added to the primary
Chapter 1. pdadmin commands
31
action group. Supports a maximum of 32 action groups. Examples of action
group names are primary and test-group. (Optional)
action_label
Specifies the label or description for the action. Each default permission is
displayed with a label that describes the operation that it governs. In
addition, the ACLs are grouped in one of the following ways, according to
their 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 code
set. Spaces are not allowed.
Examples of action labels: time, Generic, Base, and WebSEAL
action_name
Specifies the new single-character permission that is being created, which
can be specified by using any case.
Security Access Manager uses a set of default actions that cover a wide
range of operations. Valid actions, or permissions, are represented by single
alphabetic ASCII characters (a-z, A-Z).
For example, k is the action name in the following example:
k time Ext-Authzn
action_type
Specifies the organizational category for this action within a specified
action group. The action type can be a description of the action, such as
what application the action is specific to. The action type is
application-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 code
set. Spaces are not allowed.
For example, Ext-Authzn is the action type in the following example:
k time Ext-Authzn
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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:
32
IBM Security Access Manager for Web Version 7.0: Command Reference
pdadmin sec_master> action create k time Ext-Authzn
v The following example creates a customized action named P and an action label
of Test-Action with an action type of Special within the test-group action
group:
pdadmin sec_master> action create P Test-Action Special test-group
See also
“action delete”
action delete
Deletes an action (permission) from an action group.
Requires authentication (administrator ID and password) to use this command.
Syntax
action delete action_name [action_group_name]
Options
action_group_name
Specifies the name of the action group from which the specified action
must be deleted. Examples of action group names are primary and
test-group. (Optional)
action_name
Specifies 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 wide
range of operations. Valid actions, or permissions, are represented by single
alphabetic ASCII characters (a-z, A-Z). For example, k is the action name in
the following example:
k time Ext-Authzn
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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
Chapter 1. pdadmin commands
33
action group create
Creates an action group.
Requires authentication (administrator ID and password) to use this command.
Syntax
action group create action_group_name
Options
action_group_name
Specifies the name of the action group to create. Supports a maximum of
32 action groups. The action group must not exist, or an error is displayed.
A valid action group 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.
Examples of action group names are primary and test-group.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example creates the test action group:
pdadmin sec_master> action group create test
action group delete
Deletes an action group.
Requires authentication (administrator ID and password) to use this command.
Syntax
action group delete action_group_name
Options
action_group_name
Specifies the name of the action group to delete. All the actions that belong
to the specified group are also deleted. The action group must exist, or an
error is displayed. Examples of action group names are primary and
test-group.
Return codes
34
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
IBM Security Access Manager for Web Version 7.0: Command Reference
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access 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 list
Lists all action groups.
Requires authentication (administrator ID and password) to use this command.
Syntax
action group list
Description
The action group list command lists all the defined names of action groups
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example lists the names of all defined action groups:
pdadmin sec_master> action group list
primary
test-group
action list
Lists all actions (permissions) in an action group.
Requires authentication (administrator ID and password) to use this command.
Syntax
action list [action_group_name]
Chapter 1. pdadmin commands
35
Options
action_group_name
Specifies 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 action
group 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
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example displays all existing actions in the primary action group:
pdadmin sec_master> action list
TTraverseBase
cControlBase
gDelegationBase
mModifyGeneric
dDeleteGeneric
bBrowseBase
sServer AdminGeneric
vViewGeneric
aAttachBase
BBypass POPBase
tTraceBase
rReadWebSEAL
xExecuteWebSEAL
lList DirectoryWebSEAL
NCreateBase
WPasswordBase
AAddBase
RBypass AuthzRuleBase
admin show conf
Displays the current policy server configuration information, such as the type of
registry or whether global sign-on is enabled.
Requires authentication (administrator ID and password) to use this command.
Syntax
admin show conf
Options
None.
Return codes
0
36
The command completed successfully.
IBM Security Access Manager for Web Version 7.0: Command Reference
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example displays the current server configuration information:
pdadmin sec_master> admin show conf
LDAP: yes
secAuthority
GSO: yes
authzrule attach
Attaches an authorization rule to the specified protected object.
Requires authentication (administrator ID and password) to use this command.
Syntax
authzrule attach protobjid ruleid
Description
At most, one rule can be attached to a given protected object. If the object already
has a rule that is attached to it, the specified rule replaces the existing one. The
same rule can be attached to multiple protected objects. Ensure that the protected
object exists in the protected object space before you attach a rule.
Options
protobjid
Specifies the fully qualified name of the protected object to which the
authorization rule is attached. The object must exist, or an error is
displayed.
ruleid Specifies the name of the authorization rule to attach. The rule must exist,
or an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example attaches the r1 rule to the /Test-Space/folder1 protected
object named:
pdadmin sec_master> authzrule attach /Test-Space/folder1 r1
Chapter 1. pdadmin commands
37
See also
“authzrule create”
“authzrule detach” on page 40
authzrule create
Creates an authorization rule.
Requires authentication (administrator ID and password) to use this command.
Syntax
authzrule create rule_id –rulefile file_name [–desc description] [–failreason
fail_reason]
authzrule create rule_id rule_text [–desc description] [–failreason
fail_reason]
Description
You can attach an authorization rule to a protected object. To authorize access to
the protected object, the user credential and application context attributes are
compared against the rule.
Note: Quotation marks within an authorization rule must be escaped by using the
backward slash (\) character when the rule is entered without using the –rulefile
option.
Options
–desc description
Specifies 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 code
set. If the description contains a space, ensure that you enclose the
description in double quotation marks. You can specify an empty string ("")
to clear an existing description.
Example of description: "time-of-day rule for engineering object
space"
–failreason fail_reason
Specifies the message that is returned if the rule denies access to a
protected object. Consider that the authorization is denied as a result of the
evaluation of this rule. However, other authorization checks succeed. In
this case, the reason code is returned to the application that makes the
authorization check. (Optional)
–rulefile file_name
Specifies the file from which to read the XSL rule text. The rule file must
exist, or an error is displayed.
rule_id
Specifies the name of the authorization rule to create.
A valid authorization rule is an alphanumeric string that is not
case-sensitive. String values are expected to be characters that are part of
38
IBM Security Access Manager for Web Version 7.0: Command Reference
the local code set. Spaces are not allowed. The following characters cannot
be used in the name of an authorization rule:
! " # & ( ) * + , ; : < > = @ / \ | .
rule_text
Specifies the rule policy that is used to evaluate the rule in XSL format.
The rule must be enclosed in double quotation mark (") character. If the
rule specifies a double quotation mark as part of the rule text, precede the
double quotation mark with a backward slash (\) character. Doing so
instructs the system to ignore the double quotation mark.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example creates the r1 rule with the r1.xsl rule file that implements
the 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 delete
Deletes an authorization rule.
Requires authentication (administrator ID and password) to use this command.
Syntax
authzrule delete rule_id
Options
rule_id
Specifies the name of the authorization rule to delete. The authorization
rule must exist, or an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Chapter 1. pdadmin commands
39
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 detach
Detaches an authorization rule from the specified protected object.
Requires authentication (administrator ID and password) to use this command.
Syntax
authzrule detach protobjid
Options
protobjid
Specifies the name of the protected object from which the authorization
rule is detached. The object must exist and have an authorization rule that
is attached, or an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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 find
Finds and lists all protected objects that have the specified authorization rule
attached.
Requires authentication (administrator ID and password) to use this command.
40
IBM Security Access Manager for Web Version 7.0: Command Reference
Syntax
authzrule find rule_id
Description
A user must have the browse (b) and view (v) permissions for the object to be
listed when the pdadmin object show command is issued. Otherwise, an error is
returned:
The user is not authorized to view one or more protected objects where the
requested authzrule is attached.
Options
rule_id
Specifies the name of the authorization rule to find. The authorization rule
must exist, or an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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 list
Lists all the authorization rules.
Requires authentication (administrator ID and password) to use this command.
Syntax
authzrule list
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
Chapter 1. pdadmin commands
41
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example lists authorization rules:
pdadmin sec_master> authzrule list
r1
r2
r3
r4
See also
“authzrule find” on page 40
authzrule modify
Changes an authorization rule.
Requires authentication (administrator ID and password) to use this command.
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 description
Specifies 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 code
set. Spaces are allowed. If the description contains a space, ensure that you
enclose the description in double quotation marks. You can specify an
empty string ("") to clear an existing description.
Example of description: "time-of-day access"
failreason fail_reason
Specifies the fail reason code. Consider that authorization is denied as a
result of the evaluation of this rule. However, other authorization checks
succeed. In this case, the reason code is returned to the application that
makes the authorization check. You can specify an empty string ("") to
clear an existing fail reason.
rule_id
Specifies the name of the authorization rule to change. The authorization
rule must exist, or an error is displayed.
42
IBM Security Access Manager for Web Version 7.0: Command Reference
–rulefile file_name
Specifies the file from which to read the XSL rule text. The –rulefile
option 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. String
values are expected to be characters that are part of the local code set.
ruletext rule_text
Specifies the new rule text in XSL format. Do not use the –rulefile option
when you specify rule text directly.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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 show
Shows all the attributes of an authorization rule, including description, rule text,
and fail reason code.
Requires authentication (administrator ID and password) to use this command.
Syntax
authzrule show rule_id
Options
rule_id
Specifies the name of the authorization rule to show. The rule must exist,
or an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Chapter 1. pdadmin commands
43
Example
The following example shows attributes for a rule named r2:
pdadmin sec_master> authzrule show r2
The output is like:
Authorization Rule Name: r2
Description: time-of-day access
Rule 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 modify
Modifies a stanza entry in a configuration file or sets the password for the server
user 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 file
or sets the password for the application server user account. Depending on which
configuration operation you want, you must either perform a local login or a
remote 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.
44
IBM Security Access Manager for Web Version 7.0: Command Reference
– 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 the
keyvalue option, perform a local login. Use the login command with the –l
option.
Note: If you attempt to run one of the configuration operations that requires a
local login, an error is displayed.
Error: HPDMS4061ELocal authentication (local login) is required to perform
this 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 system
permissions to read and modify the configuration file.
For key values that are not obfuscated, use the config show command to display
modified values.
For information and guidelines about the stanzas and stanza entries in
configuration files, see the IBM Security Access Manager for Web Stanza Reference.
Options
–obfuscate
Indicates that the stanza entry must be written to or removed from the
obfuscated (.obf file) version of the configuration file, which is specified
by config_file. (Optional)
config_file
Specifies the fully qualified name of the configuration file, unless the
configuration file is in the current directory. When used with the
–obfuscate option, do not specify the .obf extension as part of the
configuration file name.
key
Specifies the key portion of the stanza entry.
keyvalue append
Adds a value to a stanza entry in the configuration file stanza. If you
attempt to append a duplicate value to a key, the duplicate value is
ignored.
keyvalue remove
Removes a value from a stanza entry in the configuration file stanza. If
you do not specify the value option, the key is removed from the
configuration file.
keyvalue set
Defines a stanza entry (key value pair) or changes the value of a key in the
configuration file stanza.
password
Specifies the password for the application server account.
stanza Specifies the name of stanza that contains the stanza entry.
Chapter 1. pdadmin commands
45
svrpassword
Sets the password for the application server account. This password is
updated in the registry and in the obfuscated version of the local
configuration file.
value
Specifies the configuration value for the key.
Authorization
No authentication is required, except for the svrpassword option. The svrpassword
option requires authentication (administrator ID and password).
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Examples
v 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 example
sets 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 file
does not have the .obf file extension.
See also
“config show”
“login” on page 65
config show
Shows the value that is associated with the specified stanza and key in the Security
Access Manager server configuration files or in customized server configuration
files. The stanza and key must exist, or an error is displayed.
Requires a local login to use this command. No authentication is required.
46
IBM Security Access Manager for Web Version 7.0: Command Reference
Syntax
config show config_file stanza key
Options
config_file
Specifies the Security Access Manager or custom configuration file to use.
Unless the configuration file is in the current directory, the configuration
file name must be a fully qualified path name. The necessary operating
system permissions are required to read and update the configuration file.
The default names for the configuration files are documented in the
Security Access Manager administration guides.
key
Specifies the configuration value to associate with the key in the specified
configuration file stanza. Valid key-value pairs are documented in the
Security Access Manager administration guides.
stanza Specifies the name of a Security Access Manager or custom stanza that
contains the input key. A valid stanza 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. Valid stanzas are documented in the Security
Access Manager administration guides.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web: Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 changes
to show that the login is local:
pdadmin> login -l
pdadmin local> config show "c:\Program Files\Tivoli\Policy
Directory\etc\activedir.conf" meta-info version
Provides output like:
1296
v The following example provides a local login and requests the value of the
enabled key for the [ldap] stanza. The output provides a key value of yes. The
prompt 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
Chapter 1. pdadmin commands
47
See also
“config modify” on page 44
“login” on page 65
context show
Displays the user ID and domain ID used to establish the current authentication
context. Also, specifies whether the domain is the management domain or a
domain other than the management domain.
This command does not require a login or authentication to use.
Syntax
context show
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 show
command is issued:
c:\> pdadmin -l
pdadmin 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
48
IBM Security Access Manager for Web Version 7.0: Command Reference
v The following example shows authentication context information for a user who
is 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_master
Domain: Default
The user is logged into the management domain
v The following example shows authentication context information for the
testdomain_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_admin
Domain: testdomain
The 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 create
Creates a domain, including an administrator ID and password to log in to the
specified domain. You must log in to the management domain as an administrator
to perform this command.
Requires authentication (administrator ID and password) to use this command.
This command applies to LDAP registries only.
Syntax
domain create domain domain_admin_id domain_admin_password [–desc
description]
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 Access
Manager enforces security policies for authentication, authorization, and access
control. You must log in to the management domain to create more policy
domains.
When you create a domain, you must specify an administrative ID and password
for the domain. The administrator of the management domain later assigns the
new ID and password. The new credentials are assigned to the administrator
Chapter 1. pdadmin commands
49
responsible for handling policy management tasks for the specific domain. The
administrator of the domain is responsible for updating the security policy for that
particular domain if:
v Users change.
v Groups change.
v Resources change.
This domain administrator can also delegate administration tasks to others within
that specific domain. For more information about managing domains, see the IBM
Security Access Manager for Web: Administration Guide.
Options
–desc description
Specifies an optional description for the domain. 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 code set. If the description contains
a 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 name
are:
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. Some
registries are not case-sensitive.
domain_admin_id
Specifies an administrator ID, which is created in the specified domain.
domain_admin_password
Specifies the password for the domain_admin_id user.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 domain
administrator ID Admin2, a password, and a domain description:
pdadmin sec_master> domain create Finance Admin2 password
-desc "accounting area"
50
IBM Security Access Manager for Web Version 7.0: Command Reference
See also
“domain
“domain
“domain
“domain
delete”
list” on page 52
modify” on page 53
show” on page 54
domain delete
Deletes a domain, excluding the management domain. Optionally deletes the user
and group information of the domain, from the user registry. To perform this
command, you must log in to the management domain as an administrator.
Requires authentication (administrator ID and password) to use this command.
This command applies to LDAP registries only.
Syntax
domain delete domain [–registry]
Description
A domain can be deleted within the management domain only by an administrator
with the appropriate privileges.
Options
–registry
Specifies that the information of the domain, including user and group
data, be deleted from the user registry. (Optional) If this option is not
selected, 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, or
an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 user
and group information in the user registry:
pdadmin sec_master> domain delete Finance -registry
Chapter 1. pdadmin commands
51
See also
“domain
“domain
“domain
“domain
create” on page 49
list”
modify” on page 53
show” on page 54
domain list
Lists all domains, excluding the management domain. You must log in to the
management domain as an administrator to perform this command.
Requires authentication (administrator ID and password) to use this command.
This command applies to LDAP registries only.
Syntax
domain list
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example lists existing domains other than the management domain
(Default):
pdadmin sec_master> domain list
The output is like:
Marketing
Finance
Advertising
Receiving
See also
“domain
“domain
“domain
“domain
52
create” on page 49
delete” on page 51
modify” on page 53
show” on page 54
IBM Security Access Manager for Web Version 7.0: Command Reference
domain modify
Changes the description of a domain. You must log in to the management domain
as an administrator to perform this command.
Requires authentication (administrator ID and password) to use this command.
This command applies to LDAP registries only.
Syntax
domain modify domain description description
Options
description description
Specifies a new description for the domain.
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 code
set. Spaces are allowed. If the description contains a space, ensure that you
enclose the description in double quotation marks. You can specify an
empty string ("") to clear an existing description.
Example of description: "marketing and advertising areas"
domain Specifies the name of the domain to modify.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example changes the description that is specified for the Marketing
domain:
pdadmin sec_master> domain modify Marketing description "marketing and
advertising areas"
See also
“domain
“domain
“domain
“domain
create” on page 49
delete” on page 51
list” on page 52
show” on page 54
Chapter 1. pdadmin commands
53
domain show
Displays the properties of a domain. You must log in to the management domain
as an administrator to perform this command.
Requires authentication (administrator ID and password) to use this command.
This command applies to LDAP registries only.
Syntax
domain show domain
Options
domain Specifies the name of the domain for which to display properties. The
domain must exist, or an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example displays properties for the Marketing domain:
pdadmin sec_master> domain show Marketing
The output is like:
Domain Name: Marketing
Description: marketing and advertising areas
See also
“domain
“domain
“domain
“domain
create” on page 49
delete” on page 51
list” on page 52
modify” on page 53
errtext
Displays the error message of a specific error number.
For detailed information about messages, see the IBM Security Access Manager for
Web Error Message Reference.
This command does not require a login or authentication to use.
Syntax
errtext error_number
54
IBM Security Access Manager for Web Version 7.0: Command Reference
Description
The message ID is also displayed (for example, HPDMS4047E) The message ID
consists of 10 alphanumeric characters that uniquely identify the message. The
message 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 identifier
v A four-digit message number
v A one-character type code indicates the severity of the message (I for
informational, W for warning, and E for error)
Options
error_number
Specifies the number, in either decimal or hexadecimal, of the error for
which to generate the error text.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 perform
this operation (status 0x14c52fcf)
v The following example displays the error message that is associated with a
specific decimal number:
pdadmin> errtext 268808652
The output is like:
HPDAC0460E The protected object space specified already exists in the
authorization policy database (status 0x1005b1cc)
exit or quit
Exits from the pdadmin utility interactive command-line mode.
This command does not require a login or authentication to use.
Syntax
exit
quit
Chapter 1. pdadmin commands
55
Options
None.
Examples
v 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 create
Creates 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 (AD
LDS) user registry must be created in the same AD LDS partition where the Access
Manager 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 being
created. For example, cwright.
dn
Specifies the registry identifier that is assigned to the group that is being
created.
The format for a distinguished name is like:
cn=credit,ou=Austin,o=Tivoli,c=US
group_container
Specifies the group container object that is assigned to the group that is
being created. If this option is not specified, the group by default is placed
in the object space under /Management/Groups. (Optional)
Examples of group containers are Credit and Sales_Teams.
group_name
Specifies the name of the group that is being created. This name must be
unique 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 code
set. Spaces are not allowed.
Examples of group names are Credit, Sales, and Test-group.
56
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 name
of 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 delete
Deletes the specified Security Access Manager group. Optionally deletes the
information of the group, from the user registry. ACL entries that are associated
with the group are also deleted.
Requires authentication (administrator ID and password) to use this command.
Syntax
group delete [–registry] group_name
Options
–registry
Deletes the entire group object from the user registry. (Optional)
group_name
Specifies the name of the Security Access Manager group to be deleted.
The group must exist, or an error is displayed.
Examples of group names are Credit, Sales, and Test-group.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Chapter 1. pdadmin commands
57
Examples
v 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 also
deletes the existing Test-group group:
pdadmin sec_master> group delete -registry Test-group
See also
“group create” on page 56
“group import”
group import
Creates a Security Access Manager group by importing group data that exists in
the 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) is
the 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 Manager
management domain information is stored.
Requires authentication (administrator ID and password) to use this command.
Syntax
group import group_name dn [group_container]
Options
dn
Specifies the registry identifier of the group to import. The distinguished
name must exist, or an error is displayed. The format for a distinguished
name is like "cn=engineering,ou=Austin,o=Tivoli,c=us"
group_container
Specifies the group container object that is assigned to the group that is
being created. By default, the group is placed in the object space under
/Management/Groups. If the container object does not currently exist, it is
automatically created. (Optional)
group_name
Specifies the name of the group to create. 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 code set. Spaces are not allowed.
Examples of group names are Credit, Sales, and Test-group.
Return codes
58
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
IBM Security Access Manager for Web Version 7.0: Command Reference
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 an
Active 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 uses
multiple Active Directory domains, enter the following command to
create 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 list
Generates a list of all groups, by group names, whose names match the specified
pattern.
Requires authentication (administrator ID and password) to use this command.
Syntax
group list pattern max_return
group list-dn pattern max_return
Chapter 1. pdadmin commands
59
Options
list pattern max_return
Specifies the pattern for the group name for which to be searched. The
pattern can include a mixture of wildcard and string constants, and is not
case-sensitive (for example, *austin*).
The max_return option specifies the limit of how many entries must be
returned for a single request; for example, 2. The number that is returned
is also governed by the server configuration. The configuration specifies
the maximum number of results that can be returned as part of a search
operation. The actual maximum returned entries is the minimum of
max_return and the configured value on the server.
list-dn pattern max_return
Lists user registry identifiers whose user registry common name attribute
matches the pattern specified. The returned list contains groups, which are
defined in the user registry. The groups might not necessarily be Security
Access Manager groups. You can import groups that are not Security
Access Manager groups into Security Access Manager by using the group
import command.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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:
Sales
Marketing
Alex
v The following example lists 2 groups that match the specified pattern of a
distinguished 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 Sales
cn=marketing,ou=Boston,o=Austin Sale,c=US Marketing
See also
“group show” on page 62
60
IBM Security Access Manager for Web Version 7.0: Command Reference
group modify
Changes an existing group by adding or changing a group description, adding
members to the group, or removing members from the group.
Requires authentication (administrator ID and password) to use this command.
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 not
include the user name in parentheses. For multiple users, the format of the
user list is a parenthesized list of user names, which are separated by
spaces.
The following list shows examples of user names:
v dlucas
v "Bob Smith"
v (dlucas "Mary Jones" mlucaser)
description description
Changes the description for the specified group. 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 code set. Spaces are allowed. If the
description contains a space, ensure that you enclose the description in
double quotation marks. You can specify an empty string ("") to clear an
existing description. For example, you can specify "Credit, Dept HCUS" as
the description.
group_name
Specifies the name of the group. The group must exist, or an error is
displayed.
Examples of group names are Credit, Sales, and Test-group.
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 not
include the user name in parentheses. For multiple users, the format of the
user list is a parenthesized list of user names, which are separated by
spaces. The following list shows examples of user names:
v dlucas
v "Bob Smith"
v (dlucas "Mary Jones" mlucaser)
Return codes
0
The command completed successfully.
Chapter 1. pdadmin commands
61
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web: Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 show
Shows the properties of the specified group.
Requires authentication (administrator ID and password) to use this command.
Syntax
group show group_name
group show-dn dn
group show-members group_name
Options
show group_name
Shows the properties of the group that is specified by group_name. The
group must exist, or an error is displayed.
Examples of group names are Credit, Sales, and Test-group.
show-dn dn
Shows the group that is specified by the group identifier in the user
registry. The returned group is defined in the user registry, but it is not
necessarily a Security Access Manager group. Groups that are not Security
Access Manager groups can be imported into Security Access Manager by
use of the group import command. For example, the format for a
distinguished name is like "cn=engineering,ou=Austin,o=Tivoli,c=us".
show-members group_name
Lists the user names of the members of the specified group. The group
must exist, or an error is displayed.
Examples of group names are Credit, Sales, and Test-group.
62
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web: Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Examples
v The following example displays properties of the credit group:
pdadmin sec_master> group show credit
The output is like:
Group ID: credit
LDAP dn: cn=credit,ou=Austin,o=Tivoli,c=US
Description: Credit, Dept HCUS
LDAP cn: credit
Is SecGroup: yes
v The following example displays properties that are specified by the identifier of
the 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: credit
LDAP dn: cn=credit,ou=Austin,o=Tivoli,c=US
Description: Credit, Dept HCUS
LDAP cn: credit
Is 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:
dlucas
mlucaser
See also
“group list” on page 59
help
Obtains system help for pdadmin commands and options.
This command does not require a login or authentication to use.
Syntax
help {topic | command}
Options
command
Specifies the miscellaneous command for which help is needed.
topic
Specifies the help command topic for which help is needed.
Chapter 1. pdadmin commands
63
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web: Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example lists help topics and commands:
pdadmin> help
The output is like:
Type ’help <topic>’ or ’help <command> for more information
Topics:
acl
action
admin
authzrule
config
context
domain
errtext
exit
group
help
login
logout
object
objectspace
policy
pop
quit
rsrc
rsrccred
rsrcgroup
server
user
Miscellaneous Commands:
exit
help
quit
v The following example lists the options and descriptions that are available
whether you specify the topic action or action create:
pdadmin> help action
Or:
pdadmin> help action create
The output is like:
action create
Creates a new
action create
Creates a new
...
64
<action-name> <action-label> <action-type>
ACL action definition
<action-name> <action-label> <action-type> <action-group-name>
ACL action definition in a group
IBM Security Access Manager for Web Version 7.0: Command Reference
login
Establishes authentication credentials that are used for communication with the
Security Access Manager policy server. These credentials are used to determine
access privileges for the user to policy server data. Most commands cannot be
performed unless an explicit login is done.
This command does not require a login or authentication to use.
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, and
the local configuration commands, a user ID, and a password are needed for
authentication.
Credentials are not accumulated or stacked. A login command completely replaces
any existing credentials.
In interactive mode, the pdadmin prompt changes, depending on how the user logs
in:
v Not interactive mode. This command starts the pdadmin utility. In interactive
mode, the login commands are entered from the pdadmin> prompt.
c:\> pdadmin
pdadmin>
v A user local login that is performed for local configuration. No authentication is
required.
pdadmin> login -l
pdadmin local>
v An administrator login that is performed to the local domain. In some cases, the
local domain might be the management domain, which is named Default.
Authentication is required.
pdadmin> login -a sec_master -p secmstrpw
pdadmin sec_master>
v A user login that is performed to the local domain. Authentication is required.
pdadmin> login -a dlucas -p lucaspw
pdadmin 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_a
pdadmin dlucas@domain_a>
v A user login that is performed to the management domain. Authentication is
required.
pdadmin> login -a dlucas -p lucaspw -m
pdadmin dlucas@Default>
Chapter 1. pdadmin commands
65
Options
–a admin_id
Specifies an administrator ID.
–d domain
Specifies the Security Access Manager secure domain for the login. The
admin_id user must exist in this domain.
–m
Specifies that the login operation must be directed to the management
domain. The admin_id user must exist in this domain.
Note: Only one of the following domain options can be specified: –d
domain or –m. If neither option is specified, the target domain is the local
domain that is configured for the system. The admin_id user must exist in
the target domain, whether it is explicitly specified.
–p password
Specifies the password for the admin_id user. If this option is not specified,
the user is prompted for the password. The password cannot be specified
if the admin_id is not specified.
–l
Specifies a local login operation. When modifications are made to local
configuration files by using the config commands, a local login is required
before you can run commands. The user can run the context show
command to view more authentication information.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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_master
Domain: Default
The user is logged in to the management domain.
v The following example logs in a user to the domain1 domain and then displays
the authentication context for the user:
pdadmin> login -a domain1_admin -p d0main1pwd -d domain1
pdadmin domain1_admin@domain1> context show
User: domain1_admin
Domain: domain1
The user is not logged in to the management domain
v The following example interactively logs in the user to their local domain that is
configured for the system. The domain name is testdomain. The example then
displays the authentication context of the user:
66
IBM Security Access Manager for Web Version 7.0: Command Reference
pdadmin> login
Enter User ID: testdomain_admin
Enter password: adminpwd
pdadmin testdomain_admin> context show
User: testdomain_admin
Domain: testdomain
The 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>
logout
Discards any authentication credentials that are in effect.
This command does not require a login or authentication to use.
Syntax
logout
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example first shows a local login and then demonstrates how the
prompt changes:
pdadmin login -l
pdadmin 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 show
User: domain1_admin
Domain: domain1
The user is not logged in to the management domain.
Chapter 1. pdadmin commands
67
The following example shows a logout command, and then displays context
information after the logout command was issued:
pdadmin domain1_admin@domain1> logout
The user has been logged out and credentials have been discarded.
pdadmin>context show
No login information.
See also
“exit or quit” on page 55
“login” on page 65
“context show” on page 48
object access
Confirms whether the specified access is permitted on the specified object. The
access is determined based on the permissions of this user.
Requires authentication (administrator ID and password) to use this command.
Syntax
object access object_name permissions
Options
object_name
Specifies the protected object, which is the fully qualified name of the
object, including the object space within which it is located.
Examples of object names are:
v /Management/Groups/Travel
v /WebSEAL
v /Management
permissions
Specifies the permission or permissions to check. Security Access Manager
uses a set of default actions that cover a wide range of operations. Actions
are represented by single alphabetic ASCII characters (a-z, A-Z).
For example, a list of primary action tasks and associated permissions for
the user sec_master, with WebSEAL as the web server, might include:
TTraverseBase
cControlBase
gDelegationBase
mModifyGeneric
dDeleteGeneric
bBrowseBase
sServer AdminGeneric
vViewGeneric
aAttachBase
BBypass POPBase
tTraceBase
rReadWebSEAL
xExecuteWebSEAL
lList DirectoryWebSEAL
68
IBM Security Access Manager for Web Version 7.0: Command Reference
NCreateBase
WPasswordBase
AAddBase
RBypass AuthzRuleBase
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 has
action 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 create
Creates 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_description
Specifies any text string that describes the object that is being created.
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 code
set. If the description contains a space, ensure that you enclose the
description in double quotation marks. You can specify an empty string ("")
to clear an existing description.
An example of a description is "Travel Groups".
Chapter 1. pdadmin commands
69
ispolicyattachable {yes|no}
Specifies whether an ACL, a protected object policy, or an authorization
rule can be attached to this object. Valid values are yes or no.
object_name
Specifies the name for the protected object that is being created. This name
is the fully qualified name of the object, including the object space within
which 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 code
set.
Examples of object names are:
v /Management/Groups/Travel
v /WebSEAL
v /Management
type
Specifies the type of object to be created. Types range from 0 to 17. For
example, types 10 or 16 are appropriate for container objects. Object types
are described in the IBM Security Access Manager for Web: Administration
Guide.
You can assign any of the following types:
0
Unknown
1
Secure domain
2
File
3
Executable program
4
Directory
5
Junction
6
WebSEAL server
7
Unused
8
Unused
9
HTTP server
10
Nonexistent object
11
Container object
12
Leaf object
13
Port
14
Application container object
15
Application leaf object
16
Management object
17
Unused
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example creates the object named /Management/test-object that
has a description of Test Object and is an application container object (14). An
ACL or a protected object policy can be attached to this object:
70
IBM Security Access Manager for Web Version 7.0: Command Reference
pdadmin sec_master> object create /Management/test-object "Test Object" 14
ispolicyattachable yes
v The following example creates the object named /Management/Groups/Travel that
has a description of Travel Container Object and is an application container
object (14). An ACL or a protected object policy cannot be attached to this object:
pdadmin sec_master> object create /Management/Groups/Travel "Travel
Container Object" 14 ispolicyattachable no
See also
“object exists” on page 72
“object delete”
object delete
Deletes a protected object.
Requires authentication (administrator ID and password) to use this command.
Syntax
object delete object_name
Options
object_name
Specifies the protected object to be deleted, which is the fully qualified
name of the object, including the object space in which it is located. The
object 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 command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web: Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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
Chapter 1. pdadmin commands
71
object exists
Indicates whether a protected object exists.
The protected object might be located either in:
v The policy database, or in
v An object space that is managed by an administration service plug-in.
The administration service plug-in might be registered by an authorization
application, such as WebSEAL. Use this command to determine whether the
specified object was created.
Authentication (administrator ID and password) is required to use this command.
Syntax
object exists object_name
Options
object_name
Specifies the protected object, which is the fully qualified name of the
object, including the object space within which it is located.
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 command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web: Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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
72
IBM Security Access Manager for Web Version 7.0: Command Reference
See also
“object listandshow” on page 74
“object show” on page 77
object list
Lists any objects that are grouped under the specified protected object.
Alternatively, lists all the extended attributes that are associated with the specified
protected object.
Requires authentication (administrator ID and password) to use this command.
Syntax
object list
object list object_name
object list object_name attribute
Options
object list
Lists all protected objects. The output is the same as if you issued the
objectspace list command.
object list object_name
Lists all objects that are grouped under the specified protected object. The
specified object is the fully qualified name of the object, including the
object space within which it is located.
object list object_name attribute
Lists all extended attributes that are associated with the specified protected
object. The object must exist, or an error is displayed.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Examples
v 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
Chapter 1. pdadmin commands
73
v The following example lists all the protected objects under the protected object
named /Management. In this example, both /Management and /Management/ACL are
object 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 listandshow
Lists any child objects that are grouped under the specified protected object and
displays all values that are associated with each object. Shows all values that are
associated with the protected object, including the attached ACLs, POPs, and
authorization rules. Also shows any policies that are inherited from protected
objects higher in the hierarchy.
Requires authentication (administrator ID and password) to use this command.
Syntax
object listandshow object_name
Options
object_name
Specifies the protected object for which the child objects and associated
values are to be displayed. The specified protected object is the fully
qualified name of the object, including the object space within which it is
located.
Examples of object names are:
v /Management/Groups/Travel
v /WebSEAL
v /Management
Return codes
74
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
IBM Security Access Manager for Web Version 7.0: Command Reference
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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/Travel
Description : Travel Container Object
Type : <Application Container Object> : 14
Is Policy Attachable : no
Extended Attributes :
test1
1111
v The following example displays the object named /Management/test-object and
lists any attached policies (myrule) and effective policies (myacl and mypop):
pdadmin sec_master> object listandshow /Management/test-object
Displays information like:
Name : /Management/test-object
Description : Test Object
Type : <Application Container Object> : 14
Is Policy Attachable : yes
Attached ACL :
Attached Policy :
Attached AuthzRule : myrule
Effective ACL : myacl
Effective Policy : mypop
Effective AuthzRule : myrule
See also
“object list” on page 73
“object show” on page 77
object modify
Modifies an existing object.
Requires authentication (administrator ID and password) to use this command.
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
Chapter 1. pdadmin commands
75
Options
delete attribute attribute_name [attribute_value]
Deletes the specified extended attribute (name and value) from the
specified protected object. The attribute must exist, or an error is displayed.
When you delete the last value for an attribute, it also deletes the attribute
from the specified protected object. The optional attribute_value deletes
the specified value from the specified extended attribute key in the
specified protected object. Examples of attribute names and values:
test11111
Dept_No445
Employee_name"Diana Lucas"
object_name
Specifies the protected object to be modified. The specified protected object
is the fully qualified name of the object, including the object space within
which it is located. The object must exist, or an error is displayed.
Examples of object names are:
v /Management/Groups/Travel
v /WebSEAL
v /Management
set attribute attribute_name attribute_value
Creates an extended attribute, with the specified name and value, and
adds it to the specified protected object. If the attribute exists, the attribute
value is added as an additional value if the same value does not exist for
this attribute. If the same value exists for this attribute, 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 specified
extended attribute key in the specified protected object. The attribute value
must exist, or an error is displayed.
Examples of extended attribute names and values:
attr1valueA
attr1valueB
attr2valueC
set description description
Sets the description field of the specified protected object.
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 code
set. Spaces are allowed. If the description contains a space, ensure that you
enclose the description in double quotation marks. You can specify an
empty string ("") to clear an existing description.
Example of description: "Travel Group aaa"
set ispolicyattachable {yes|no}
Sets whether the protected object can have an ACL, a POP, or an
authorization rule attached or not. Valid values are yes or no.
set type type
Specifies the type of the object space to be created. Types range from 0 to
17. For example, types 10 or 16 are appropriate for objects.
You can assign any of the following types:
0
Unknown
1
Secure domain
2
File
76
IBM Security Access Manager for Web Version 7.0: Command Reference
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Executable program
Directory
Junction
WebSEAL server
Unused
Unused
HTTP server
Nonexistent object
Container object
Leaf object
Port
Application container object
Application leaf object
Management object
Unused
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example sets the ispolicyattachable option for the
/Management/Groups/Travel object:
pdadmin sec_master> object modify /Management/Groups/Travel set
ispolicyattachable yes
v The following example sets the attributes for the /Management/test-object
object:
pdadmin sec_master> object modify /Management/test-object set attribute
test1 1111
See also
“object create” on page 69
object show
Shows values for the protected object.
If the protected object name specified does not exist, default values are shown. To
determine whether a protected object exists, use the object show command.
Requires authentication (administrator ID and password) to use this command.
Syntax
object show object_name [attribute attribute_name]
Chapter 1. pdadmin commands
77
Description
The object show command shows values that are associated with the protected
object.
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 from
protected objects in the hierarchy of this object.
When the attribute option is specified, the attribute_name value or values are
shown if the attribute is attached to the protected object specified.
This command limits the output for POPs, ACLs, and authorization rules, which
are based on the permissions of the user. A user must have the view (v) permission
on the object to show it.
Options
object_name
Specifies the protected object. The specified protected object is the fully
qualified name of the object, including the object space within which it is
located.
Examples of object names are:
v /Management/Groups/Travel
v /WebSEAL
v /Management
attribute attribute_name
Specifies the name of the extended attribute whose values are to be
displayed. (Optional) The extended attribute must exist for the object name
that is specified, or an error is displayed. In the example that is listed for
the /object-text object in “Examples,” the following extended attributes
are shown:
v test1
v test2
v abc
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example displays the /object-test object and lists all attached
and effective ACLs, POPs, authzrules, and extended attributes:
78
IBM Security Access Manager for Web Version 7.0: Command Reference
pdadmin sec_master> object show /object-test
Displays information like:
Name: /object-test
Description: Test object
Type: 12 <Leaf Object>
Is Policy Attachable : Yes
Extended Attributes:
Name:test1
Value(s): 1111
Name:test2
Value(s): abc
2222
second
Attached ACL:
Attached POP:
Attached AuthzRule:
Effective Extended Attributes:
Protected Object Location: /object-test
Name:test1
Value(s): 1111
Name:test2
Value(s): abc
2222
second
Effective ACL: default-root
Effective POP:
Effective AuthzRule:
v The following example displays the /object-test/child1 object and lists all
attached and effective ACLs, POPs, AuthzRules, and extended attributes:
pdadmin sec_master> object show /object-test/child1
Displays information like:
Name: /object-test/child1
Description: Child 1
Type: 12 <Leaf Object)>
Is Policy Attachable : Yes
Extended Attributes:
Attached ACL:
Attached POP:
Attached AuthzRule:
Effective Extended Attributes:
Protected Object Location: /object-test
Name:test1
Value(s): 1111
Name:test2
Value(s): abc
2222
second
Effective ACL: default-root
Effective POP:
Effective AuthzRule:
v The following example displays information about the test1 attribute that is
listed 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:
Chapter 1. pdadmin commands
79
Could not perform the administration request
Error: HPDAC0463E There are no extended attributes associated with the
specified protected object or authorization policy object. (status
0x1005b1cf)
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:
test1
1111
v The following example displays the /Management/test-object object, which lists
any 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 object
Type: 14 <Application Container Object>
Is Policy Attachable: Yes
Extended Attributes:
Attached ACL: myacl
Attached Policy: mypop
Attached AuthzRule: myrule
Effective
Effective
Effective
Effective
Extended Attributes:
ACL: myacl
Policy: mypop
AuthzRule: myrule
v The following example creates a protected object and then performs an object
show of that protected object. An object show is then performed for an object
that has not been created. Then the object exist command is issued for both of
these objects.
pdadmin sec_master> object create /Management/new_object1" "0ispoly
pdadmin sec_master> object show /Management/new_object1
Name: /Management/new_object1
Description:
Type: 0 (Unknown)
Is Policy Attachable: Yes
Extended Attributes:
Attached ACL:
Attached POP:
Attached AuthzRule:
Effective
Effective
Effective
Effective
Extended Attributes:
ACL: default-management
POP:
AuthzRule:
pdadmin sec_master> object show /Management/not_there_object
Name: /Management/not_there_object
Description:
Type: 0 (Unknown)
Is Policy Attachable: Yes
Extended Attributes:
Attached ACL:
Attached POP:
Attached AuthzRule:
Effective Extended Attributes:
80
IBM Security Access Manager for Web Version 7.0: Command Reference
Effective ACL: default-management
Effective POP:
Effective AuthzRule:
pdadmin
Exists:
pdadmin
Exists:
sec_master> object exist /Management/new_object1
Yes
sec_master> object exist /Management/not_there_object
No
See also
“object list” on page 73
“object list” on page 73
“object listandshow” on page 74
objectspace create
Creates a protected object space under which protected objects can be placed.
Requires authentication (administrator ID and password) to use this command.
Syntax
objectspace create objectspace_name description type
Description
The root of the new protected object space automatically has the
ispolicyattachable option that is set to true.
Options
description
Specifies the description of the new object space.
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 code
set. If the description contains a space, ensure that you enclose the
description in double quotation marks. You can specify an empty string ("")
to clear an existing description.
An example description is "Accounting".
objectspace_name
Specifies the name of the object space to be created.
A valid object space 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.
Examples of object space names are /Management and /WebSEAL.
type
Specifies the type of the object space to be created. Types range from 0 to
17. For example, types 10 or 16 are appropriate for objects and object
spaces.
You can assign any of the following types:
0
Unknown
1
Secure domain
2
File
3
Executable program
Chapter 1. pdadmin commands
81
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Directory
Junction
WebSEAL server
Unused
Unused
HTTP server
Nonexistent object
Container object
Leaf object
Port
Application container object
Application leaf object
Management object
Unused
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 a
management object (type 16):
pdadmin sec_master> objectspace create /Dept4D4 "Department 4D4" 16
See also
“objectspace delete”
objectspace delete
Deletes the specified protected object space.
Requires authentication (administrator ID and password) to use this command.
Syntax
objectspace delete objectspace_name
Options
objectspace_name
Specifies the name of the object space to be deleted. The object space must
exist or an error is displayed.
Examples of object space names are /Management and /WebSEAL.
Return codes
0
82
The command completed successfully.
IBM Security Access Manager for Web Version 7.0: Command Reference
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
1
Examples
v 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 list
Lists all the existing protected object spaces in the policy server.
Requires authentication (administrator ID and password) to use this command.
Syntax
objectspace list
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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 get
Displays the policy for user passwords, account rules, and conditions. Requires
authentication (administrator ID and password) to use this command.
Chapter 1. pdadmin commands
83
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_name
Specifies the user whose policy information is to be displayed. If this
option is not specified, the general policy is displayed. For any specified
policy, if a user has a specific policy that is applied, this specific policy
takes precedence over any general policy that might also be defined. The
precedence applies regardless of whether the specific policy is more or less
restrictive than the general policy. Examples of user names are dlucas,
sec_master, and "Mary Jones". (Optional)
account-expiry-date
Displays the account expiration date.
disable-time-interval
Displays the time, in seconds, to disable user accounts when the maximum
number of login failures is exceeded.
max-concurrent-web-sessions
Displays the maximum number of concurrent web sessions. The value is a
number equal to or greater than 1 or one of the following values:
displace
All existing web sessions end when the user starts a new web
session.
unlimited
The 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 user
session that is maintained by a web security solution, such as WebSEAL or
the plug-in for web servers. See component administration guides to
determine whether this setting is applicable and whether specific
configuration options are required to enforce this policy.
84
IBM Security Access Manager for Web Version 7.0: Command Reference
max-login-failures
Displays the maximum number of login failures. To enforce maximum
login failures, the disable-time-interval parameter must be set. For more
information, see the disable time interval section.
max-password-age
Displays the maximum time that a password is valid. The time is indicated
in 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 the
password was changed.
max-password-repeated-chars
Displays the maximum number of repeated characters that are allowed in a
password.
min-password-alphas
Displays the minimum number of alphabetic characters that are required in
a password.
min-password-length
Displays the minimum password length.
min-password-non-alphas
Displays the minimum number of non-alphabetic characters that are
required in a password.
password-spaces
Displays whether spaces are allowed in passwords.
tod-access
Displays the time of day access policy.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example returns the account expiration date of unlimited for the
specified user dlucas:
pdadmin sec_master> policy get account-expiry-date -user dlucas
Account expiry date: unlimited
v The following example returns the maximum time of 0 days, where zero
indicates 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
Chapter 1. pdadmin commands
85
policy set
Sets the policy for user passwords, account rules, and conditions. Requires
authentication (administrator ID and password) to use this command.
Syntax
policy set account-expiry-date {unlimited|absolute_time|unset} [–user
user_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 reasonable
number for the task that you want to complete. For example, a minimum
password length must be long enough to protect your system. In addition, the
password must not be so short as to make it easy for someone to determine your
password by trying different combinations.
When you define the password policy, ensure that this definition complies with the
password 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 in
the following format:
YYYY-MM-DD-hh:mm:ss
The hours must be entered by using a 24-hour clock (for example, 09 for 9
a.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 not
use the –user user_name option. By default, the sec_master user account
86
IBM Security Access Manager for Web Version 7.0: Command Reference
has a per-user account expiration date of unlimited. If you set the account
expiration 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 maximum
number of login failures is exceeded. Security Access Manager does not
impose an upper limit for the maximum number allowed. Use a range
from 0 (unlimited) to a number that represents the value that is most
logical for the parameter you are trying to set. The default value is 180
seconds.
max-concurrent-web-sessions {number|displace|unlimited|unset}
Sets the maximum number of concurrent web sessions. This policy applies
only to certain components. A web session is a user session that is
maintained by a web security solution, such as WebSEAL or the plug-in for
web Servers. See component administration guides to determine whether
this setting is applicable and whether specific configuration options are
required to enforce this policy.
This option supports the following values:
number
Specifies the maximum number of concurrent web sessions that
can be established. This value is a number that is equal to or
greater than one.
displace
Specifies that if a user starts a new web session, any existing web
session ends.
unlimited
Allows 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 Access
Manager does not impose an upper limit for the maximum number
allowed. Instead, use a range from zero to a number that represents the
value that is most logical for the parameter you are trying to set. If the
number is too large, it might render the login policy ineffective. The
default value is 10.
To enforce maximum login failures, the disable-time-interval parameter
must be set. See disable-time-interval for more information about
disable-time-interval.
max-password-age {unset|relative_time}
Sets the maximum time, in days, that a password is valid. This policy is a
global password policy as opposed to the individual user policy. The
individual 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.
Chapter 1. pdadmin commands
87
The relative_time option is relative to the number of days since the last
password change occurred. The relative_time format is specified in the
following 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 default
value 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 are
allowed in a password. Security Access Manager does not impose an upper
limit on the maximum number allowed. Instead, use a range from 0 to a
number that represents the most logical value for the parameter you are
trying to set. If the number is too large, it might render the password
policy ineffective. The default value is 2.
Example: If max-password-repeated-chars is set to 2, then password and
pspassword are both valid values. However, passsword is not valid because
the character s occurs three times consecutively.
min-password-alphas {unset|number}
Sets the minimum number of alphabetic characters that are required in a
password. Security Access Manager does not impose an upper limit for the
minimum number allowed. Instead, use a number that represents the value
that is most logical for the parameter you are trying to set. If the number is
too small, it might render the password policy ineffective. The default
value is 4.
min-password-length {unset|number}
Sets the minimum password length. Security Access Manager does not
impose an upper limit for the minimum number allowed. Instead, use a
number that represents the value that is most logical for the parameter you
are trying to set. If the number is too large, the password policy might be
difficult 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 in
a password. Security Access Manager does not impose an upper limit for
the minimum number allowed. Instead, use a number that represents the
value that is most logical for the parameter you are trying to set. If the
number 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 default
value 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 which
is represented by a three-character value (for example, mon,wed,fri). The
day_list specifies which days of the week you can log in to the account. If
you want to list every day of the week, specify anyday; if you do not want
to include the weekend days, specify weekday.
The time_spec format is specified in the following format:
hhmm
88
IBM Security Access Manager for Web Version 7.0: Command Reference
The format is expressed by using a 24-hour clock. For example, 0900 for 9
a.m. or 1430 for 2:30 p.m. The default value is unset, and the optional time
zone is local by default. The time_spec value and time zone specify the
time 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, start
time, and end time. The start time and end time apply to each day on
the 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_name
Specifies the user whose policy information is to be set. If this option is not
specified, the general policy is set. For any specified policy, if a user has a
specific policy that is applied, this specific policy takes precedence over
any general policy that might also be defined. The precedence applies
regardless of whether the specific policy is more or less restrictive than the
general 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 code
set.
Examples of user names are dlucas, sec_master, and "Mary Jones".
(Optional)
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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, 30
minutes, 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
Chapter 1. pdadmin commands
89
pop attach
Attaches a protected object policy (POP) to the specified protected object. The POP
must be created before it can be attached.
Requires authentication (administrator ID and password) to use this command.
Syntax
pop attach object_name pop_name
Description
At most, one POP can be attached to a given protected object. If the object already
has a POP attached to it, the specified POP replaces the existing one. The same
POP can be attached to multiple protected objects. Ensure that the protected object
exists in the protected object space before you attempt to attach a POP.
Options
object_name
Specifies the name of the protected object to which the protected object
policy is attached. The object must exist, or an error is displayed.
Examples of object names are:
v /Management/Groups/Travel
v /WebSEAL
v /Management
pop_name
Specifies the name of the protected object policy to be attached. The POP
must exist, or an error is displayed.
Examples of POP names are poptest and pop1.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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
90
IBM Security Access Manager for Web Version 7.0: Command Reference
pop create
Creates a protected object policy (POP).
Requires authentication (administrator ID and password) to use this command.
Syntax
pop create pop_name
Options
pop_name
Specifies the name of the POP to be created. A valid protected object 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. Avoid the following characters in the POP name:
! " # & ( ) * + , ; : < > = @ / \ | .
Note: Although a POP name can contain 1 or more of these characters, the
results of using such a POP are undefined.
Examples of POP names are poptest and pop1.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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:test
Description:
Warning:no
Audit Level:none
Quality of protection: none
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime: local
IP Endpoint Authentication Method Policy
Any Other Network 0
See also
“pop attach” on page 90
“pop delete” on page 92
Chapter 1. pdadmin commands
91
pop delete
Deletes the specified protected object policy (POP).
Requires authentication (administrator ID and password) to use this command.
Syntax
pop delete pop_name
Options
pop_name
Specifies the name of the POP to be deleted. The POP must exist, or an
error is displayed. Examples of POP names are poptest and pop1.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 detach
Detaches a protected object policy (POP) from the specified protected object.
Requires authentication (administrator ID and password) to use this command.
Syntax
pop detach object_name
Options
object_name
Specifies the protected object from which the POP is to be detached. The
object must exist and have a POP attached, or an error is displayed.
Examples of object names are:
v /Management/Groups/Travel
v /WebSEAL
v /Management
92
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 find
Finds and lists all protected objects that have a protected object policy (POP)
attached.
Requires authentication (administrator ID and password) to use this command.
Syntax
pop find pop_name
Description
A user must have the browse (b) and view (v) permissions for the object to be
listed 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 the
requested acl is attached.
Options
pop_name
Specifies the name of the POP for which to search. The POP must exist, or
an error is displayed. Examples of POP names are poptest and pop1.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Chapter 1. pdadmin commands
93
Examples
v 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 list
Lists all protected object policies that are created. Alternatively, lists all extended
attributes that are associated with a protected object policy.
Requires authentication (administrator ID and password) to use this command.
Syntax
pop list [pop_name attribute]
Options
pop_name attribute
Specifies the POP for which to list the attributes. The POP must exist, or an
error is displayed. (Optional)
Examples of POP names are poptest and pop1.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example shows how to list all POPs:
pdadmin sec_master> pop list
test
pop1
poptest
v The following example shows how to list all the attributes for the POP named
pop1:
pdadmin sec_master> pop list pop1 attribute
attr1
94
IBM Security Access Manager for Web Version 7.0: Command Reference
See also
“pop find” on page 93
pop modify
Modifies protected object policies.
Requires authentication (administrator ID and password) to use this command.
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 use
the 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 IP
addresses 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 IP
version.
Note: When you use IPv6 notation, do not use prefix notation when you specify IP
addresses.
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.
Chapter 1. pdadmin commands
95
v For Java methods, IPv4 clients can provide addresses in IPv4 or IPv6 format to
IPv6 servers.
For an IPv6 address to be accepted (commands, C APIs, and Java methods), the
server must be IPv6. You cannot provide an IPv6 address to an IPv4 server.
The operating system functions that are provided to Security Access Manager have
certain limitations. Regardless of C or Java clients, IPv4 addresses must be in IPv4
format 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 the
specified POP. The attribute must exist, or an error is displayed.
The optional attribute_value deletes the specified value from the specified
extended attribute key in the specified POP.
Examples of extended attribute names and values:
Dept_No445
Employee_Name"Diana Lucas"
pop_name
Specifies the name of the protected object policy to be modified. The POP
must exist, or an error is displayed.
set attribute attribute_name attribute_value
Sets or modifies the specified value from the specified extended attribute
key in the specified POP. If the attribute exists, the attribute value is added
as an additional value if the same value does not exist for this attribute. If
the 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 extended
attribute 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 an
audit_level_list is a comma-separated list that contains one or more of
these audit levels: permit,deny,error,admin.
set description description
Sets the description of the specified POP.
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 code
set. If the description contains a space, ensure that you enclose the
description in double quotation marks. You can specify an empty string ("")
to clear an existing description.
Example of description: "Policies of Jenson Corp."
set ipauth add network netmask level
Sets the IP endpoint authentication settings in 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) or version 6
(IPv6) addresses. Both the network and netmask options must be specified
in the same IP version.
The following values are supported for level:
96
IBM Security Access Manager for Web Version 7.0: Command Reference
forbidden
A value that prohibits object access.
integer_values
Application-specific integer values that define the step-up
authentication levels. All integer values, except 1000, are
supported. For more information about step-up authentication, the
IBM Security Access Manager for Web: Administration Guide.
set ipauth anyothernw level
Sets the anyothernw (any other network setting) for the IP authentication
level in the specified POP. If you are controlling access by IP address is not
important, use the anyothernw option to set the authentication level for:
v All IP addresses, and
v IP address ranges not listed explicitly in the POP.
The following values are supported for level:
forbidden
A value that prohibits object access.
integer_values
Application-specific integer values that define the step-up
authentication levels. All integer values, except 1000, are
supported. For more information about step-up authentication, the
IBM Security Access Manager for Web: Administration Guide.
set ipauth remove network netmask
Removes 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) or
version 6 (IPv6) notation. Both the network and netmask options must be
specified in the same IP version.
set qop {none|integrity|privacy}
Sets the quality of protection level for the specified POP. The following
string values are supported:
v none
v integrity
v privacy
set tod-access {anyday|weekday|day_list}:{anytime|time_spectime_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 which
is represented by a three-character value (for example, mon,wed,fri). The
day_list specifies which days of the week the object can be accessed. If
you want to list every day of the week, specify anyday; if you do not want
to include the weekend days, specify weekday.
The time_spec format is specified as hhmm and is expressed by using a
24-hour clock (for example, 0900 for 9 a.m. or 1430 for 2:30 p.m.). The
default value is not defined, and the optional time zone is local by
default. The time_spec value and time zone specify the time of day the
object can be accessed.
Note: utc=GMT
Chapter 1. pdadmin commands
97
set warning {yes|no}
Sets the warning mode for the specified protected object policy. Valid
values are yes or no.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 a
protected 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 valueA
for 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 show
Shows details about the protected object policy (POP). Alternatively, displays the
values for the specified extended attribute from the specified protected object
policy.
Requires authentication (administrator ID and password) to use this command.
Syntax
pop show pop_name [attribute attribute_name]
Options
attribute attribute_name
Specifies the name of the extended attribute whose values you want to
display. The attribute must exist, or an error is displayed. Examples of
attribute names are Dept_No and Employee_Name. (Optional)
pop_name
Specifies the POP to display. The POP must exist, or an error is displayed.
Examples of POP names are poptest and pop1.
98
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v
The following example shows how to show POP information, including the
description:
pdadmin sec_master> pop show test
Protected object policy:test
Description:Test POP
Warning:no
Audit level:none
Quaility of protection:none
Time of day access: sun, mon, tue, wed, thu, fri, sat:
anytime: local
IP Endpoint Authentication Method Policy
Any Other Network 0
v The following example shows attribute attr1 information for the POP named
pop1:
pdadmin sec_master> pop show pop1 attribute attr
attr1
valueA
See also
“pop find” on page 93
“pop list” on page 94
rsrc create
Creates and names a web server single sign-on resource.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrc create resource_name [–desc description]
Description
A web resource is a web server that serves as the back-end of a WebSEAL
GSO-enabled junction. The web resource name must be specified with the –T
option when the GSO-enabled WebSEAL junction is created.
Options
–desc description
Specifies a description for the resource. Descriptions containing a space
must be enclosed in double quotation marks. (Optional)
Chapter 1. pdadmin commands
99
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 code
set. If the description contains a space, ensure that you enclose the
description in double quotation marks.
Examples of descriptions are “Engineering Web server – Room 4807” and
“Printer in room 345, Bldg 2”.
resource_name
Specifies 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 these
characters.
Examples of resource names are engwebs01 and JonesData.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 Web
server – Room 4807"
v The following example is entered as one line. This example creates and names a
printer resource "Mary Jones Printer" with an associated description "Printer
in room 345, Bldg 2":
pdadmin sec_master> rsrc create "Mary Jones Printer" –desc "Printer in
room 345, Bldg 2"
See also
“rsrc delete”
rsrc delete
Deletes the specified single sign-on resource.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrc delete resource_name
Options
resource_name
Specifies the name of the resource to be deleted. The resource must exist,
or an error is displayed.
100
IBM Security Access Manager for Web Version 7.0: Command Reference
Examples of resource names are engwebs01 and JonesData.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 list
Returns a list of all the single sign-on resource names.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrc list
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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:
engwebs01
Mary Jones Printer
Chapter 1. pdadmin commands
101
See also
“rsrc create” on page 99
rsrc show
Displays the resource information for the named resource.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrc show resource_name
Options
resource_name
Specifies the name of the resource for which information is shown. The
resource must exist, or an error is displayed.
Examples of resource names are engwebs01 and JonesData.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example returns information for the specified resource engwebs01:
pdadmin sec_master> rsrc show engwebs01
The output is like:
Web Resource Name: engwebs01
Description: Engineering Web server - Room 4807
v The following example returns information for the specified resource "Mary
Jones Printer":
pdadmin sec_master> rsrc show "Mary Jones Printer"
Output is like:
Web Resource Name: Mary Jones Printer
Description: Printer in room 345, Bldg 2
See also
“rsrc list” on page 101
rsrccred create
Creates a single sign-on credential.
Requires authentication (administrator ID and password) to use this command.
102
IBM Security Access Manager for Web Version 7.0: Command Reference
Syntax
rsrccred create resource_name rsrcuser resource_userid rsrcpwd
resource_password rsrctype {web|group} user user_name
Description
A resource credential is a credential that is used to identify the authentication
information of a user. WebSEAL uses the authentication information when it
accesses a back-end web resource or resource group through a GSO-enabled
junction. WebSEAL accesses these resources on behalf of that user.
For example, a user dlucas might require the authentication identity 4807ws01 and
password pwd4lucas when accessing the engwebs01 web resource that is junctioned
through WebSEAL.
A resource credential can be created with this authentication information. Then,
WebSEAL automatically uses this information to access the engwebs01 server
whenever the user dlucas accesses that resource.
Options
resource_name
Specifies the name that is given to the resource or resource group when the
resource or resource group was created. The resource or resource group
must exist to create the resource credential. If the resource or resource
group does not exist or is not specified, an error message is displayed.
Examples of resource names are engwebs01 and "Mary Jones Printer".
rsrcpwd resource_password
Specifies 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_userid
Specifies the unique user identification (user ID) for the user at the web
server.
Examples of user identifications are 4807ws01 and userD4D.
user user_name
Specifies the name of the user for whom the resource credential
information applies. If the user does not exist or is not specified, an error
message is displayed.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Chapter 1. pdadmin commands
103
Examples
v 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 4807ws01
rsrcpwd pwd4lucas rsrctype web user dlucas
v The following example creates the group resource credential named
printerusers for the resource user ID userD4D and password pwd4mjones given
to user "Mary Jones":
pdadmin sec_master> rsrccred create printerusers rsrcuser userD4D rsrcpwd
pwd4mjones rsrctype group user "Mary Jones"
See also
“rsrccred delete”
“rsrccred modify” on page 106
rsrccred delete
Deletes a single sign-on credential.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrccred delete resource_name rsrctype {web|group} user user_name
Options
resource_name
Specifies the name that is given to the resource or resource group when the
resource was created. The resource or resource group must exist, or an
error is displayed.
Examples of resource names are engwebs01 and "Mary Jones Printer".
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 the
credential. The type of resource must match the resource type that is
assigned when the resource or resource group was first created.
user user_name
Specifies the name of the user for whom the resource credential
information applies. The user must exist, or an error is displayed.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Return codes
104
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
IBM Security Access Manager for Web Version 7.0: Command Reference
Examples
v 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 the
resource printerusers, resource type group, and user name "Mary Jones":
pdadmin sec_master> rsrccred delete printerusers rsrctype group
user "Mary Jones"
See also
“rsrccred create” on page 102
rsrccred list user
Returns the list of single sign-on credentials for the specified user. The user must
exist, or an error is displayed.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrccred list user user_name
Options
user_name
Specifies the name of the user for whom the resource credential
information applies. The user must exist, or an error is displayed.
Examples of user names are dlucas, sec_master and "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example returns the list of single sign-on credentials for the
specified user dlucas:
pdadmin sec_master> rsrccred list user dlucas
The output is like:
Resource Name: engwebs01
Resource Type: web
See also
“rsrccred show” on page 107
Chapter 1. pdadmin commands
105
rsrccred modify
Changes a single sign-on credential.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrccred modify resource_name rsrctype {web|group} set [–rsrcuser
new_resource_userid [–rsrcpwd new_resource_password]] user user_name
Options
–rsrcpwd new_resource_password
Specifies the new password for a user at the web server. To change or reset
the password information, this optional command must be preceded by a
dash (-). Specifying this option without specifying the –rsrcpwd option
clears both the resource user ID and the resource password from the
resource credential. To set the resource password, you must specify both
the resource user ID and the resource password. (Optional)
–rsrcuser new_resource_userid
Specifies the new unique user identification (user ID) for the user at the
web server. To change or reset the resource user ID of the user, this
optional command must be preceded by a dash (-). (Optional)
A valid new resource user ID 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.
Examples of user identifications are 4807ws01 and userD4D.
resource_name
Specifies the name that is given to the resource or resource group when the
resource was created. The resource or resource group must exist, or an
error is displayed.
Examples of resource names are engwebs01 and "Mary Jones Printer".
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 the
credential. The type of resource must match the resource type that is
assigned when the resource or resource group credential was first created.
user user_name
Specifies the name of the user for whom the resource credential
information applies. The user must exist, or an error is displayed.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Return codes
106
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
IBM Security Access Manager for Web Version 7.0: Command Reference
Examples
v 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 ID
to 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 show
Displays the attributes of a single sign-on credential. The credential identifier is
composed of a resource name, a resource type, and a user name.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrccred show resource_name rsrctype {web|group} user user_name
Options
resource_name
Specifies the name of the single sign-on resource or resource group that is
associated 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 the
credential. The type of resource must match the resource type that is
assigned when the resource or resource group was first created.
user user_name
Specifies the name of the user that is associated with this credential. The
user must exist, or an error is displayed.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Chapter 1. pdadmin commands
107
Examples
v 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: engwebs01
Resource Type: web
Resource 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: printerusers
Resource Type: group
Resource User Id: Mary Jones
See also
“rsrccred list user” on page 105
rsrcgroup create
Creates and names a resource group.
Requires authentication (administrator ID and password) to use this command.
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-on
credential for the set of web servers is the same. In this case, web servers are
considered resources.
For example, if the user dlucas has the same identity for web servers engwebs01
and 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 group
for dlucas. Then, that single sign-on credential can be used to access all the web
servers in the webs4807 group.
Options
–desc description
Specifies the description to identify this resource group. This parameter is
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 code set. If the description contains a space, ensure that you
enclose the description in double quotation marks. (Optional)
Examples of descriptions are "Engineering Web server – Room 4807" and
"Printer in room 345, Bldg 2".
108
IBM Security Access Manager for Web Version 7.0: Command Reference
resource_group_name
Specifies the name of the resource group. A valid resource group 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 these characters.
Examples of resource group names are webs4807, engwebs01, and
IBMprinters.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 named
webs4807 and provides a description ("Web servers, Room 4807") for that
resource:
pdadmin sec_master> rsrcgroup create webs4807 –desc "Web servers, Room 4807"
See also
“rsrcgroup delete”
rsrcgroup delete
Deletes a single sign-on resource group.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrcgroup delete resource_group_name
Options
resource_group_name
Specifies the name of the resource group. The resource must exist, or an
error is displayed.
Examples of resource group names are webs4807, engwebs01, and
IBMprinters.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Chapter 1. pdadmin commands
109
Example
The following example deletes the named resource group and its associated
description information:
pdadmin sec_master> rsrcgroup delete webs4807
See also
“rsrcgroup create” on page 108
rsrcgroup list
Displays the names of all resource groups that are defined in the user registry.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrcgroup list
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal 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:
webs4807
websbld3
See also
“rsrcgroup show” on page 112
rsrcgroup modify
Adds or removes a single sign-on resource to or from a single sign-on resource
group.
Requires authentication (administrator ID and password) to use this command.
110
IBM Security Access Manager for Web Version 7.0: Command Reference
Syntax
rsrcgroup modify resource_group_name add rsrcname resource_name
rsrcgroup modify resource_group_name remove rsrcname resource_name
Options
add rsrcname resource_name
Adds a single sign-on resource to the specified single sign-on resource
group.
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 these
characters.
Examples of resource names are engwebs01 and "Mary Jones Printer".
remove rsrcname resource_name
Removes a single sign-on resource from the specified single sign-on
resource group.
Examples of resource names are engwebs01 and "Mary Jones Printer".
Note: Depending on the LDAP server in your environment, any attempt to
remove a non-existing resource from a group, might generate an error.
resource_group_name
Specifies the name of the resource group to be modified. The resource
group must exist, or an error is displayed.
Examples of resource group names are webs4807, engwebs01, and
IBMprinters.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 existing
web resource group webs4807:
pdadmin sec_master> rsrcgroup modify webs4807 remove rsrcname engwebs02
See also
“rsrcgroup create” on page 108
Chapter 1. pdadmin commands
111
rsrcgroup show
Displays the resource group information for the specified resource group.
Requires authentication (administrator ID and password) to use this command.
Syntax
rsrcgroup show resource_group_name
Description
The resource group name, the resource group description, and a list of all resource
group members names are displayed. The resource group members are the
individual web resources (servers).
Options
resource_group_name
Specifies the name of the resource group.
Examples of resource group names are webs4807, engwebs01, and
IBMprinters.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example returns the specified single sign-on resource group named
webs4807:
pdadmin sec_master> rsrcgroup show webs4807
The output is like:
Resource Group Name: webs4807
Description: Web servers, Room 4807
Resource Members:
engwebs01
engwebs02
engwebs03
See also
“rsrcgroup list” on page 110
server list
Lists all registered Security Access Manager servers.
Requires authentication (administrator ID and password) to use this command.
112
IBM Security Access Manager for Web Version 7.0: Command Reference
Syntax
server list
Description
Lists all registered Security Access Manager servers. The name of the server for all
server commands must be entered in the exact format as it is displayed in the
output of this command. The server list command does not have such a
requirement.
Options
None.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example lists registered servers:
pdadmin> server list
The output is as follows:
ivmgrd-master
ivacld-server1
ivacld-server2
where ivmgrd-master represents the Policy server; ivacld-server2 and
ivacld-server1 represent Authorization server instances.
server listtasks
Retrieves the list of tasks (commands) available for the specified installed Security
Access Manager server or server instance.
Requires authentication (administrator ID and password) to use this command.
Syntax
server listtasks server_name-host_name
Options
server_name-host_name
Specifies the name of the installed Security Access Manager server or
server instance. You must specify the server_name in the exact format as
displayed in the output of the server list command.
Chapter 1. pdadmin commands
113
For example, if the configured name of a single WebSEAL server is
default, the server_name is default-webseald followed by -host_name. The
full server name–host name is default-webseald-cruz.dallas.ibm.com.
For multiple server instances on the same computer, if the configured
name of a WebSEAL server instance is webseal2-webseald, the
instance_name is followed by -host_name. The full server instance
name–host name is webseal2-webseald-cruz.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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 list
stats 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 the
list of tasks available from the Policy server. The output is similar to the output
listed for the authorization server.
v The following example displays the list of tasks available from the WebSEAL
server default-webseald-cruz:
pdadmin sec_master server listtasks default-webseald-cruz
The output is like:
dynurl update
jmt load
jmt clear
cache flush all
create
add
remove
delete <junction point>
list
show <junction point>
reload
terminate all_sessions <user_id>
terminate session <user_session_id>
refresh all_sessions <user_id>
help command
trace set component level [file path=file|
114
IBM Security Access Manager for Web Version 7.0: Command Reference
other-log-agent-config]
trace show [component]
trace list [component]
stats show [component]
stats list
stats 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 replicate
Notifies the installed Security Access Manager authorization server or server
instance to receive database updates.
Requires authentication (administrator ID and password) to use this command.
Syntax
server replicate [–server server_name-host_name]
Options
–server server_name-host_name
Specifies the name of the installed Security Access Manager server or
server instance. You must specify the server_name in the exact format as
displayed in the output of the server list command. (Optional)
For example, if the configured name of a single WebSEAL server is
default, the server_name is default-webseald followed by -host_name. The
full server name–host name is default-webseald-cruz.dallas.ibm.com.
For multiple server instances on the same computer, if the configured
name of a WebSEAL server instance is webseal2-webseald, the
instance_name is followed by -host_name. The full server instance
name–host name is webseal2-webseald-cruz.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
Here is an example of this command when the server name is specified:
pdadmin sec_master> server replicate -server ivacld-topserver
Chapter 1. pdadmin commands
115
See also
“server list” on page 112
“server show”
server show
Displays the properties for the specified installed Security Access Manager server
or server instance. The server must exist, or an error is displayed.
Requires authentication (administrator ID and password) to use this command.
Syntax
server show server_name-host_name
Options
server_name-host_name
Specifies the name of the installed Security Access Manager server or
server instance. You must specify the server_name in the exact format as
displayed in the output of the server list command.
For example, if the configured name of a single WebSEAL server is
default, the server_name is default-webseald followed by -host_name. The
full server name–host name is default-webseald-cruz.dallas.ibm.com.
For multiple server instances on the same computer, if the configured
name of a WebSEAL server instance is webseal2-webseald, the
instance_name is followed by -host_name. The full server instance
name–host name is webseal2-webseald-cruz.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v 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-mogman
Description: ivacld/mogman
Hostname: mogman
Principal: ivacld/mogman
Administration Request Port: 7137
Listening for authorization database update notifications: yes
AZN Administration Services:
AZN_ADMIN_SVC_TRACE
v The following example displays the properties of the WebSEAL server
default-webseald-cruz:
pdadmin sec_master> server show default-webseald-cruz
116
IBM Security Access Manager for Web Version 7.0: Command Reference
The output is like:
default-webseald-cruz
Description: default-webseald-cruz
Hostname: cruz.dallas.ibm.com
Principal: default-webseald/cruz
Administration Request Port: 7234
Listening for authorization database update notifications: yes
AZN Administration Services:
webseal-admin-svc
azn_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-master
Description: ivmgrd-master
Hostname: localhost
Principal:
Administration Request Port: 7135
Listening for authorization database update notifications: no
AZN Administration Services:
azn_admin_svc_trace
Note: The Administration Request Port, 7135 in the output, is the same port that
is set for the policy server during policy server configuration.
See also
“server list” on page 112
“server task show” on page 143
server task add
Adds an application server to an existing WebSEAL junction.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name add –h host_name [options]
junction_point
Options
–h host_name
Specifies 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_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
Chapter 1. pdadmin commands
117
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
options
Specifies 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. This
value, matched with the actual certificate DN, enhances
authentication and provides mutual authentication over SSL. For
example, the certificate for www.example.com might have the
following 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 the
type of ssl or sslproxy.
–H host_name
Specifies the DNS host name or IP address of the proxy server.
Valid values for host_name include any valid IP host name. For
example:
www.example.com
This option is used for junctions that were created with the type of
tcpproxy or sslproxy.
–i
Indicates that the WebSEAL server does not treat URLs as
case-sensitive. This option is used for junctions that were created
with the type of tcp or ssl.
–p port
Specifies the TCP port of the server. The default value is 80 for
TCP junctions and 443 for SSL junctions. This option is used for
junctions that were created with the type of tcp or ssl.
–P port
Specifies the TCP port of the HTTP proxy server. The default value
is 7138. Use this option for junctions that were created with the
type of tcpproxy or sslproxy.
For port, use any valid port number. A valid port number is any
positive number that is allowed by TCP/IP and that is not
currently being used by another application. Use the default port
number value, or use a port number that is greater than 1000 that
is not being used.
This option is also valid for mutual junctions to specify the HTTPS
port of the back-end third-party server.
–q url Specifies the relative path for the query_contents script. By default,
118
IBM Security Access Manager for Web Version 7.0: Command Reference
Security Access Manager looks for this script in the /cgi_bin
subdirectory. If this directory is different or the query_contents file
is renamed, use this option to indicate to WebSEAL the new URL
to the file. Required for Windows servers.
This option is used for junctions that were created with the type of
tcp or ssl.
–u uuid
Specifies the UUID of this server when connected to WebSEAL
over a stateful junction that was using the –s option. This option is
used for junctions that were created with the type of tcp or ssl.
–v virtual_hostname
Specifies the virtual host name that is represented on the server.
This option supports a virtual host setup on the server. Use this
option 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 know
that the server has multiple names and multiple virtual servers.
You must configure WebSEAL to supply that extra header
information in requests that are destined for a server that is set up
as a virtual host.
This option is used for junctions that were created with the type of
tcp or ssl.
–V virtual_hostname
Specifies the virtual host name that is represented on the back-end
server. 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 host
name header and you are junctioning to one virtual instance of
that server. The default HTTPS header request from the browser
does not know that the back-end server has multiple names and
multiple virtual servers. You must configure WebSEAL to supply
that extra header information. This header information applies to
requests destined for a back-end server that is set up as a virtual
host.
–w
Indicates Microsoft Windows 32 bit (Win32) file system support.
This option is used for junctions that were created with the type of
tcp or ssl.
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_nameinstance_name/junction_point object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
Chapter 1. pdadmin commands
119
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete the command, and returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
For more information about how to add servers to existing junctions, see the IBM
Security Access Manager for Web WebSEAL Administration Guide.
Example
The following example creates a junction for the WebSEAL server named WS1 to the
server named APP1. The example adds another server named APP2 to the same
junction 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
“server
“server
“server
task
task
task
task
create” on page 121
delete” on page 128
remove” on page 141
show” on page 143
server task cache flush all
Flushes the HTML document cache.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name cache flush all
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-webseald-abc.ibm.com.
120
IBM Security Access Manager for Web Version 7.0: Command Reference
If an additional WebSEAL server instance is configured and named web2,
the full WebSEAL server name is web2-webseald-abc.ibm.com.
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user is given
this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
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 create
Creates a WebSEAL junction point.
Requires authentication (administrator ID and password) to use this command.
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 –h
host_name [options] junction_point
Options
–d dir Specifies the local directory to the junction. This option is required if the
junction type is local.
Chapter 1. pdadmin commands
121
This option is valid only with junctions that were created with the type of
local.
–h host_name
Specifies the DNS host name or IP address of the target server. This option
is valid only for non-local junctions; local junctions do not need a host
name. Valid values for host_name include any valid IP host name. For
example:
www.example.com
–T {resource | resource_group}
Specifies the name of the resource or resource group. This option is
required only when the –b gso option is used. This option is valid for all
junctions except for the type of local.
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
machine where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host machine name where the WebSEAL server is installed is
abc.ibm.com. Then, the full WebSEAL server name is default-websealdabc.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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
options
Specifies the options that you can use with the server task create
command. (Optional) These options include:
–a address
Specifies the local IP address that WebSEAL uses to communicate
with the target back-end server. If this option is not provided,
WebSEAL uses the default address as determined by the operating
system.
If an address is supplied for a particular junction, WebSEAL is
modified to bind to this local address for all communication with
the junctioned server.
–A
Enables or disables lightweight third-party authentication
mechanism (LTPA) junctions. This option requires the –F and –Z
options. 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
122
You can use this option with the –A option to specify that LTPA
version 2 cookies (LtpaToken2) are used. The –A option without the
–2 option specifies that LTPA version 1 cookies (LtpaToken) are
used.
IBM Security Access Manager for Web Version 7.0: Command Reference
–b BA_value
Defines how the WebSEAL server passes the HTTP BA
authentication information to the server, which is one of the
following values:
v filter (default)
v ignore
v supply
v gso
This option is valid for all junctions except for the type of local.
–B
Indicates that WebSEAL uses the BA header information to
authenticate to the server and to provide mutual authentication
over SSL. This option requires the –U and –W options.
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–c header_type
Inserts the Security Access Manager client identity in HTTP
headers across the junction. The header_type argument can include
any combination of the Security Access Manager HTTP header
types:
v {iv_user|iv_user-l}
v iv_groups
v iv_creds
v all
The header types must be comma-separated, and cannot have a
space between the types. For example: -c iv_user,iv_groups
Specifying –c all is the same as specifying –c
iv_user,iv_groups,iv_creds.
This option is valid for all junctions except for the type of local.
–C
Indicates single sign-on from a front-end WebSEAL server to a
back-end WebSEAL server. The –C option is not mutual
authentication.
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–D "dn"
Specifies the distinguished name of the server certificate. This
value, matched with the actual certificate DN, enhances
authentication and provides mutual authentication over SSL. For
example, 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"
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–e encoding_type
Specifies the encoding to use when HTTP headers are generated
for junctions. This encoding applies to headers that are generated
with both the –c junction option and tag-value. The following
values for encoding are supported:
utf8_bin
WebSEAL sends the headers in UTF-8.
Chapter 1. pdadmin commands
123
utf8_uri
WebSEAL sends the headers in UTF-8 but URI also
encodes them. This behavior is the default behavior.
lcp_bin
WebSEAL sends the headers in the local code page of the
WebSEAL server.
lcp_uri
WebSEAL sends the headers in the local code page of the
WebSEAL server, but URI also encodes them.
This option is valid for all junctions except for the type of local.
–f
Forces the replacement of an existing junction.
This option is used for junctions that were created with any
junction type.
–F keyfile
Specifies the location of the key file that is used to encrypt LTPA
cookie data.
The –F option requires –A and –Z options. The –A, –F, and –Z
options all must be used together.
This option is valid for all junctions except for the type of local.
–H host_name
Specifies the DNS host name or IP address of the proxy server. The
–P option also supports proxy server junctions. Valid values for
host_name include any valid IP host name. For example,
proxy.www.example.com
This option is valid only with junctions that were created with the
type of tcpproxy or sslproxy.
–i
Indicates that the WebSEAL junction does not treat URLs as
case-sensitive. To correctly authorize requests for junctions that are
not case-sensitive, WebSEAL does the authorization check on a
lowercase version of the URL. For example, a Web server that is
running on a Windows operating system treats requests for
INDEX.HTM and index.htm as requests for the same file.
Junctions to such a Web server must be created with the –i or –w
option. ACLs or POPs that are attached to objects beneath the
junction point must use the lowercase object name. An ACL
attached to /junction/index.htm applies to all the following
requests 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; all
other platforms are case-sensitive.
–I
Ensures a unique Set-Cookie header name attribute when the –j
option is used to modify server-relative URLs in requests.
This option is valid for all junctions except for the type of local.
124
IBM Security Access Manager for Web Version 7.0: Command Reference
–j
Supplies junction identification in a cookie to handle
script-generated server-relative URLs.
This option is valid for all junctions except for the type of local.
–J trailer,inhead,onfocus,xhtml10
Controls the junction cookie Java™Script block.
Use –J trailer to append the junction cookie JavaScript to HTML
page 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 JavaScript
to ensure that the correct junction cookie is used in a
multiple-junction/multiple-browser-window scenario.
Use –J xhtml10 to insert a JavaScript block that is HTML 4.01 and
XHTML 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.
This option is valid for all junctions except for the type of local.
–K "key_label"
Specifies the key label of the client personal certificate that
WebSEAL must present to the server. Use of this option allows the
junction server to authenticate the WebSEAL server by using client
certificates.
This option is valid only with junctions that were created with the
type of ssl and sslproxy.
–l percent
Defines the soft limit for consumption of worker threads.
This option is valid for all junctions except for the type of local.
–L percent
Defines the hard limit for consumption of worker threads.
This option is valid for all junctions except for the type of local.
–n
Indicates that no modifications of the names of non-domain
cookies are to be made. Use when client side scripts depend on the
names of cookies.
WebSEAL modifies the names of non-domain cookies that are
returned from the junction to prefix with AMWEBJCT!junction_point.
WebSEAL does this action by default, if a junction is listed in the
JMT or if the –j junction option is used.
This option is valid for all junctions except for the type of local.
–p port
Specifies the TCP port of the back end third-party server. The
default value is 80 for TCP junctions and 443 for SSL junctions.
This option is valid for all junctions except for the type of local.
–P port
For proxy junctions that were created with the type of tcpproxy or
sslproxy this option specifies the TCP port number for the HTTP
proxy server. The –P option is required when the –H option is used.
Chapter 1. pdadmin commands
125
This option is also valid for mutual junctions to specify the HTTPS
port of the back-end third-party server.
–q path
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 the
query_contents file name is renamed, this option indicates to
WebSEAL the new URL to the file. Required for back end Windows
servers.
This option is valid for all junctions except for the type of local.
–r
Inserts the incoming IP address into the HTTP header across the
junction. This option is valid for all junctions except for the type of
local.
–R
Allows the request to proceed but provides the rule failure reason
to the junction in an HTTP header. If the –R option is not used and
a rule failure occurs, WebSEAL does not allow the request to
proceed. This option is valid for all junctions except for the type of
local.
–s
Indicates that the junction support stateful applications. By default,
junctions are not stateful. This option is valid for all junctions
except for the type of local.
–S path
Specifies the location of the forms single sign-on configuration file.
This option is valid for all junctions except for the type of local.
–t type
Specifies the type of junction; must be one of the following types:
v tcp
v tcpproxy
v ssl
v sslproxy
v local
–u uuid
Specifies the Universally Unique Identifier (UUID) of a server that
is 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 to
authenticate to the server and to provide mutual authentication
over SSL. This option is valid only with junctions that were created
with the type of ssl or sslproxy.
–v virtual_hostname[:HTTP-port]
Specifies the virtual host name for the server. This option supports
multiple virtual hosts that are served from the same Web server.
Use –v when the junction server expects a host name header
different from the DNS name of the server. This option is valid for
all junctions except for the type of local. For mutual junctions, this
value corresponds to the virtual host that is used for HTTP
requests.
126
IBM Security Access Manager for Web Version 7.0: Command Reference
–V virtual_hostname[:HTTPS-port]
Specifies the virtual host name for the back-end server. This option
supports multiple virtual hosts that are served from the same Web
server. Use –V when the back-end junction server expects a host
name header that is different from the DNS name of the server.
This option is used only for mutual junctions and corresponds to
the 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 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 to
authenticate to the server and to provide mutual authentication
over SSL. This option is valid only with junctions that were created
with the type of ssl or sslproxy.
–x
Creates a path junction that is not apparent.
This option is valid for all junctions except for the type of local.
–Y
Enables Tivoli® Federated Identity Manager single sign-on (SSO)
for the junction.
Indicates that Kerberos SSO is enabled for the junction. Before you
use this command, configure the WebSEAL configuration file to
support Kerberos single-signon over junctions.
–Z keyfile_pwd
Specifies the password of the key file that is used to encrypt LTPA
cookie data. This option requires the –A and –F options. The –A, –F,
and –Z options all must be used together. This option is valid for
all junctions except for the type of local.
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/junction_point object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete the command. The WebSEAL server returns an error message.
1
The command failed. See the IBM Security Access Manager for Web Error
Chapter 1. pdadmin commands
127
Message Reference. This reference provides a list of the Security Access
Manager 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.
Examples
v The following example creates a basic WebSEAL junction /pubs on the
default-webseald-cruz WebSEAL server. The junction type is TCP, and the host
name 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 current
junction point. The –f option is required to force a new junction that overwrites
an 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 basis
with 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
“server
“server
“server
task
task
task
task
add” on page 117
delete”
remove” on page 141
show” on page 143
server task delete
Deletes a WebSEAL junction point.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name delete junction_point
128
IBM Security Access Manager for Web Version 7.0: Command Reference
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
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_nameinstance_name/junction_point object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete 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 Access
Manager 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 server
default-webseald-abc.ibm.com:
pdadmin> server task default-webseald-abc.ibm.com delete /pubs
Chapter 1. pdadmin commands
129
See also
“server
“server
“server
“server
task
task
task
task
add” on page 117
create” on page 121
remove” on page 141
show” on page 143
server task dynurl update
Reloads the dynamic URL configuration file.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name dynurl update
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user is given
this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
130
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
IBM Security Access Manager for Web Version 7.0: Command Reference
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
For more information about how WebSEAL handles dynamic URLs, see the IBM
Security 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 help
Lists detailed help information about a specific server task command.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name help task
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
task
Lists detailed help for the specified task, such as the command syntax, the
description, and the valid options.
Authorization
No special authorization required.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
Chapter 1. pdadmin commands
131
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Examples
v 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 junction
Usage:
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 junctions
443 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 server
task 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 junction
Usage:
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 these
junctions when a rule failure reason is provided.
<junction point>Where to create the junction
See also
“help” on page 63
132
IBM Security Access Manager for Web Version 7.0: Command Reference
server task jmt
Clears or loads the junction mapping table data.
Requires authentication (administrator ID and password) to use this command.
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.
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
load
Loads the junction mapping table data, which is in the jmt.conf file. This
file does not exist by default, so you must create the file and add data.
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user is given
this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
Chapter 1. pdadmin commands
133
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
For more information about the WebSEAL junction mapping table, see the IBM
Security Access Manager for Web WebSEAL Administration Guide.
Example
The following example loads the junction mapping table data from the jmt.conf
file. 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 list
Lists all junction points on a WebSEAL server or server instance.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name list
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, if the configured name of a single WebSEAL server instance
is default. The host computer name where the WebSEAL server is
installed is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
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 is
given this permission by default.
134
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command, and returns an error
message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
For more information about WebSEAL junctions, see the IBM Security Access
Manager for Web WebSEAL Administration Guide.
Example
The following example lists all junction points on the default-webseald-cruz
WebSEAL server:
pdadmin> server task default-webseald-cruz list
Output is like:
/
/ssljct
/tcpjct
See also
“server
“server
“server
“server
“server
task
task
task
task
task
add” on page 117
create” on page 121
delete” on page 128
remove” on page 141
show” on page 143
server task offline
Places 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 an
offline operational state. No additional requests are sent to the specified server. If a
server is not specified, all servers that are at this junction are placed in an offline
operational state.
Chapter 1. pdadmin commands
135
Options
–i server_uuid
Specifies the UUID of the server to place in an offline operational state. If a
server is not specified, all servers that are at this junction are placed in an
offline operational state. Use the server task show command to determine
the ID of a specific server. (Optional)
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
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_nameinstance_name/junction_point object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
136
IBM Security Access Manager for Web Version 7.0: Command Reference
Example
The following example places the backappl server at the /pubs junction point in an
offline operational state. To determine the UUID of this junctioned 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-09267e38aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: 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
“server
“server
“server
“server
task
task
task
task
task
online”
throttle” on page 164
virtualhost offline” on page 180
virtualhost online” on page 182
virtualhost throttle” on page 188
server task online
Places 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 an
online operational state. The server now resumes normal operation. If a server is
not specified, all servers that are at this junction are placed in an online operational
state.
Options
–i server_uuid
Specifies the UUID of the server to place in an online operational state. If a
server is not specified, all servers that are at this junction are placed in an
online operational state. Use the server task show command to determine
the ID of a specific server. (Optional)
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
Chapter 1. pdadmin commands
137
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
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_nameinstance_name/junction_point object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
Example
The following example places the backappl server at the /pubs junction point in an
online operational state. To determine the UUID of this junctioned 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-09267e38aa77
Server State: running
138
IBM Security Access Manager for Web Version 7.0: Command Reference
Operational State: Offline
Hostname: 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
“server
“server
“server
“server
task
task
task
task
task
offline” on page 135
throttle” on page 164
virtualhost offline” on page 180
virtualhost online” on page 182
virtualhost throttle” on page 188
server task refresh all_sessions
Refreshes the credential for all sessions for a specified user.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name refresh all_sessions user_id
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL instance. You must
specify this full server name in the exact format as displayed in the output
of the server list command.
The instance_name specifies the configured name of the WebSEAL instance.
The webseald designation indicates that the WebSEAL service performs the
command task. The host_name is the name of the physical computer where
the WebSEAL server is installed.
For example, the configured name of a single WebSEAL instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-webseald-abc.ibm.com.
If an additional WebSEAL instance is configured and named web2, the full
WebSEAL server name is web2-webseald-abc.ibm.com.
user_id
Refreshes the credential for all sessions that are associated with the
specified user. Examples of user names are dlucas, sec_master, and "Mary
Jones".
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user is given
this permission by default.
Chapter 1. pdadmin commands
139
Note: This command is available only when WebSEAL is installed.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: For more information about the WebSEAL credential refresh, see the IBM
Security 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 reload
Reloads the junction mapping table from the database.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name reload
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-webseald-abc.ibm.com.
140
IBM Security Access Manager for Web Version 7.0: Command Reference
If an additional WebSEAL server instance is configured and named web2,
the full WebSEAL server name is web2-webseald-abc.ibm.com.
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user is given
this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
For more information about the WebSEAL junction mapping table, see the IBM
Security 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 remove
Removes the specified installed WebSEAL server or server instance from a
WebSEAL junction point.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name remove –i server_uuid
junction_point
Chapter 1. pdadmin commands
141
Options
–i server_uuid
Specifies the UUID of the server to be removed from the junction point.
See the server task show command for details about obtaining the UUID.
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
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_nameinstance_name/junction_point object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete 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 Access
Manager error messages by decimal or hexadecimal codes.
Note: For more information about how to remove a server from a WebSEAL
junction, see the IBM Security Access Manager for Web WebSEAL Administration
Guide.
This command is available only when WebSEAL is installed.
Example
The following example removes the backappl junctioned server from the /pubs
junction point. To determine the UUID of the server to be removed, run the server
task show command:
pdadmin> server task default-webseald-cruz show /pubs
142
IBM Security Access Manager for Web Version 7.0: Command Reference
Output is like:
Junction point: /pubs
...
Server 1:
ID: 6fc3187a-ea1c-11d7-8f4e-09267e38aa77
Server 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
“server
“server
“server
task
task
task
task
add” on page 117
create” on page 121
delete” on page 128
show”
server task show
Displays detailed information about the specified WebSEAL junction.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name show junction_point
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
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/
Chapter 1. pdadmin commands
143
junction_point object. For example, the sec_master administrative user is given
this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete the command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
For more information about WebSEAL junctions, see the IBM Security Access
Manager for Web WebSEAL Administration Guide.
Example
The following example shows information for the local root junction point / on the
WebSEAL server abc.ibm.com:
pdadmin> server task default-webseald-abc.ibm.com show
Output is like:
Junction point: /
Type: Local
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Root Directory: /opt/pdweb/www-default/docs
...
Server 1:
ID: 78a1eb8c-074a-11d9-abda-00096bda9439
...
See also
“server
“server
“server
“server
task
task
task
task
add” on page 117
create” on page 121
delete” on page 128
remove” on page 141
server task sms key change
Forces the creation of a new session management key.
You might want to forcibly create a key when you suspect that the existing key
was compromised.
Syntax
server task server_name–host_name sms key change
144
IBM Security Access Manager for Web Version 7.0: Command Reference
Options
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
cruz.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If there are multiple configured server instances on the same computer, for
example, the host cruz.dallas.ibm.com, and the configured name of the
WebSEAL server instance is webseal2-webseald, the server_name is
webseal2-webseald and the host_name is example.dallas.ibm.com. For this
example, the name of the server instance would be webseal2-websealdexample.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example forcibly creates a session management key for the
abc.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 show
Lists detailed information about the current session management key.
Syntax
server task server_name–host_name sms key show
Options
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
Chapter 1. pdadmin commands
145
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same machine, for
example:
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-websealdexample.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example returns detailed information about the current session
management key for the abc.ibm.com server:
pdadmin> server task default-webseald-abc.ibm.com sms key show
Output is like:
ID: 1
Created: 2004-03-03-09:00:03
Expires: 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 list
Lists all session management realms in the domain.
Syntax
server task server_name–host_name sms realm list
146
IBM Security Access Manager for Web Version 7.0: Command Reference
Options
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If there are multiple configured server instances on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
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
“server
“server
“server
list”
task
task
task
on page 112
sms realm show”
sms replica set list” on page 151
sms replica set show” on page 152
server task sms realm show
Lists all replica sets in the specified session management realm.
Syntax
server task server_name–host_name sms realm show realm_name
Chapter 1. pdadmin commands
147
Options
realm_name
Specifies the name of the realm. When you specify a realm, the output
contains only those replica sets in that realm.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example returns the replica sets in the ibm.com realm of the
abc.ibm.com server:
pdadmin> server task default-webseald-abc.ibm.com sms realm show ibm.com
See also
“server
“server
“server
“server
list”
task
task
task
on page 112
sms realm list” on page 146
sms replica set list” on page 151
sms replica set show” on page 152
server task sms session refresh all_sessions
Refreshes the credential for sessions for a specific user.
148
IBM Security Access Manager for Web Version 7.0: Command Reference
Syntax
server task server_name–host_name sms session refresh all_sessions user_name
–realm realm_name
Options
–realm realm_name
Specifies that name of the realm. The credentials of only those sessions that
belong to the specified realm are refreshed.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
v The host isexample.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-websealdexample.dallas.ibm.com.
user_name
Refreshes the credential for all sessions that are associated with the
specified user. Examples of user names are dlucas, sec_master, and “Mary
Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
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
Chapter 1. pdadmin commands
149
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 session
Refreshes the credential for a session.
Syntax
server task server_name–host_name sms session refresh session session_id
–realm realm_name
Options
–realm realm_name
Specifies that name of the realm. The credentials of only those sessions that
belong to the specified realm are refreshed.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
session_id
Specifies the identifier for the session to refresh.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
150
IBM Security Access Manager for Web Version 7.0: Command Reference
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
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 list
Lists 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_name
Indicates that the returned list of replica sets is limited to those replica sets
in the specified realm. (Optional)
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Chapter 1. pdadmin commands
151
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example lists the replica sets in the ibm realm of the abc.ibm.com
server:
pdadmin> server task default-webseald-abc.ibm.com sms replica set list -realm ibm
See also
“server
“server
“server
“server
list”
task
task
task
on page 112
sms realm list” on page 146
sms realm show” on page 147
sms replica set show”
server task sms replica set show
Lists all session management replicas in the specified replica that is set with the
time and date that each joined the realm.
Syntax
server task server_name–host_name sms replica set show replica_set_name
Options
replica_set_name
Specifies the name of the replica set.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
152
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example returns details about the ibm.com replica that is set of the
abc.ibm.com server:
pdadmin> server task default-webseald-abc.ibm.com sms replica set show ibm.com
See also
“server
“server
“server
“server
list”
task
task
task
on page 112
sms realm list” on page 146
sms realm show” on page 147
sms replica set list” on page 151
server task sms session list
Lists all session management sessions.
Syntax
server task server_name–host_name sms session list –realm realm_name pattern
maximum_return
Options
–realm realm_name
Specifies the name of the session management realm.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
v The host is example.dallas.ibm.com.
v The configured name of the WebSEAL server instance is
webseal2-webseald.
Then,
Chapter 1. pdadmin commands
153
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-websealdexample.dallas.ibm.com.
maximum_return
Specifies the maximum number of sessions to return. When there are more
matches than designated by this option, the output contains the number of
matches.
pattern
Specifies the pattern for returning user names. The pattern can include a
combination of wildcard and string constant characters. The pattern is
case-sensitive. For example, you can specify *luca* as the pattern to find
all users that contain the substring luca within the user name.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
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.com
sms session list -realm ibm.com *ons* 100
See also
“server
“server
“server
“server
list”
task
task
task
on page 112
sms realm list” on page 146
sms realm show” on page 147
sms replica set show” on page 152
server task sms session terminate all_sessions
Terminates all user sessions for a specific user.
Syntax
server task server_name–host_name sms session terminate all_sessions user_id
–realm realm_name
154
IBM Security Access Manager for Web Version 7.0: Command Reference
Options
–realm realm_name
Specifies that name of the session management realm.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
user_id
Specifies the name of the user. Examples of user names are dlucas,
sec_master, and "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example terminates all sessions for the dlucas user in the ibm.com
realm 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
Chapter 1. pdadmin commands
155
server task sms session terminate session
Terminates 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
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
session_id
Specifies the ID of a user session.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example terminates session 678 in the ibm.com realm of the
default-webseald-cruz WebSEAL server:
pdadmin> server task default-webseald-cruz sms session terminate \
session 678 -realm ibm.com
156
IBM Security Access Manager for Web Version 7.0: Command Reference
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 get
Displays the trace level for the session management server.
Syntax
server task server_name–host_name sms trace get
Options
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
Example
The following example returns the tracing level for the ivacld-cruz authorization
server:
pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace get
Chapter 1. pdadmin commands
157
See also
“server task sms trace set”
server task sms trace set
Sets 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.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when the session management
command-line extensions are installed to a hosting authorization server.
158
IBM Security Access Manager for Web Version 7.0: Command Reference
Example
The following example sets the tracing level to 1 on the ivacld-cruz authorization
server:
pdadmin> server task ivacld-cruz.dallas.ibm.com sms trace set 1
See also
“server task sms trace get” on page 157
server task stats
Manages the gathering and reporting of statistics for Security Access Manager
servers and server instances.
Requires authentication (administrator ID and password) to use this command.
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 statistics
for Security Access Manager servers and server instances. You can use the stats
commands with configuration setting that are defined by the stanza entries in the
server 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 gathering
and reporting statistics.
For example, statistics are enabled to create five statistics reports with each report
generated each day. You can use the stats on command to change the frequency
to every 12 hours. For this example, assume that the following command started
statistics 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 following
command:
Chapter 1. pdadmin commands
159
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 any
preexisting value. Entering the previous command does disable statistics from
being written to the previously defined log file. However, if you specified a
different destination, statistics reports would be written to the new destination
only. You cannot use the stats on command to write statistics reports to more than
one destination.
For more information about gathering statistics, see the IBM Security Access
Manager for Web Auditing Guide.
Options
component
Specifies the component about which to gather or report statistics.
count
Specifies the number of reports to send to a log file. When you use the
count option, you must specify the interval option. If you specify the
interval option without the count option, the duration of reporting is
indefinite.
After the count value is reached, reporting to a log file stops. Although
statistics are no longer sent to a log file, the statistic component is still
enabled. You can obtain reports from memory by using the stats get
command.
destination
Specifies where the gathered statistics are written, where destination can
be one of the following options:
file path=file_name
Specifies the fully qualified name of the log file.
log_agent
Specifies a directory where statistics information is gathered. For
more information about logging events, see the IBM Security Access
Manager for Web Troubleshooting Guide.
get
Displays the current report for a specific component or for all enabled
components. If you specify the component option, displays the current
report for that component; otherwise, displays the current report for all
enabled components.
interval
Specifies the interval in seconds when statistics are sent from memory to a
log file. When this option is specified, statistics are sent, by default, to the
server-specific log file designated by the logcfg entry in the server
configuration file. You can specify another location by using the
destination option. If an interval is not specified, statistics are not sent to
a log file, but remain in memory.
Although statistics are not sent to a log file, the statistic component is still
enabled. You can obtain reports from memory by using the stats get
command.
160
list
Lists all components that are available to gather and report statistics.
off
Disables gathering of statistics for a specific component or for all
IBM Security Access Manager for Web Version 7.0: Command Reference
components. If you specify the component option, disables gathering of
statistics for that component; otherwise, disables gathering of statistics for
all components.
on
Enables gathering of statistics for a specific component. When you enable
gathering of statistics, you can also set the reporting frequency, count, and
log file.
reset
Resets gathering of statistics for a specific component or for all enabled
components. If you specify the component option, resets gathering of
statistics for that component; otherwise, resets gathering of statistics for all
components.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
show
Lists all enabled components or indicates whether a specific component is
enabled. If you specify the component option and the component is
enabled, the output lists that component; otherwise, no output is
displayed. If you do not specify the component option, the output lists all
enabled components.
Return codes
0
The command completed successfully.
1
The command failed. See the IBM Security Access Manager for Web Error
Message Reference. This reference provides a list of the Security Access
Manager error messages by decimal or hexadecimal codes.
Examples
v 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.monitor
pd.log.EventPool.queue
v The following example:
Chapter 1. pdadmin commands
161
– Uses the status on command to enable gathering of statistics for the
pd.log.EventPool.queue component on the ivacld-mogman.admogman.com
authorization 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_sessions
Terminates all user sessions for a specific user.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name terminate all_sessions user_id
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL instance. You must
specify this full server name in the exact format as displayed in the output
of the server list command.
The instance_name specifies the configured name of the WebSEAL instance.
The webseald designation indicates that the WebSEAL service performs the
command task. The host_name is the name of the physical computer where
the WebSEAL server is installed.
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.
If an additional WebSEAL instance is configured and named web2, the full
WebSEAL server name is web2-webseald-abc.ibm.com.
user_id Specifies the name of the user. Examples of user names are dlucas,
sec_master, and "Mary Jones".
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user is given
this permission by default.
Note: This command is available only when WebSEAL is installed.
162
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal 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 the
default-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 session
Terminates a user session by using a session ID.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name terminate session session_id
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL instance. You must
specify this full server name in the exact format as displayed in the output
of the server list command.
The instance_name specifies the configured name of the WebSEAL instance.
The webseald designation indicates that the WebSEAL service performs the
command task. The host_name is the name of the physical computer where
the WebSEAL server is installed.
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.
Chapter 1. pdadmin commands
163
Then, the full WebSEAL server name is default-webseald-abc.ibm.com.
If an additional WebSEAL instance is configured and named web2, the full
WebSEAL server name is web2-webseald-abc.ibm.com.
session_id
Specifies the ID of a user session.
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user is given
this permission by default.
Note: This command is available only when WebSEAL is installed.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal 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 the
default-webseald-cruz WebSEAL server:
pdadmin> server task default-webseald-cruz terminate
session 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 throttle
Places 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
164
IBM Security Access Manager for Web Version 7.0: Command Reference
Description
The server task throttle command places the server that is at this junction in a
throttled operational state. Users can create a session with WebSEAL before the
invocation of this command. Only requests from such users are processed by the
specified server. If a server is not specified, all servers that are at this junction are
placed in a throttled operational state.
Options
–i server_uuid
Specifies the UUID of the server to throttle. If a server is not specified, all
servers that are at this junction are placed in a throttled operational state.
Use the server task show command to determine the ID of a specific
server. (Optional)
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
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.
Then, the full WebSEAL server name is default-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_point
Specifies the name of the directory in the WebSEAL protected object space
where the document space of the server is mounted.
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_nameinstance_name/junction_point object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
Chapter 1. pdadmin commands
165
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
Example
The following example places the backappl server that is located at the /pubs
junction point in a throttled operational state. To determine the UUID of this
junctioned 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-09267e38aa77
Server State: running
Operational State: Online
Hostname: 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
“server
“server
“server
“server
task
task
task
task
task
offline” on page 135
online” on page 137
virtualhost offline” on page 180
virtualhost online” on page 182
virtualhost throttle” on page 188
server task trace
Enables the gathering of trace information for components of installed Security
Access Manager servers or server instances.
Requires authentication (administrator ID and password) to use this command.
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 for
components of installed Security Access Manager servers or server instances that
support debug event tracing. The content of trace messages is undocumented and
166
IBM Security Access Manager for Web Version 7.0: Command Reference
is intended to be used for debugging purposes only. The format and content of
trace messages might vary between product releases.
Options
list [component]
Lists all enabled trace components that are available to gather and report
trace information. If you specify the component option and the component
is enabled, the output lists that component; otherwise, no output is
displayed. If you do not specify the component option, the output lists all
enabled components.
server_name–host_name
Specifies the name of the server or server instance. You must specify the
server name in the exact format as it is shown in the output of the server
list command.
For example, if the configured name of a single WebSEAL server on host
example.dallas.ibm.com is default, the server_name would be
default-webseald and the host_name would be example.dallas.ibm.com.
For this example, the name of the server would be default-websealdexample.dallas.ibm.com.
If multiple server instances are configured on the same computer, for
example:
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-websealdexample.dallas.ibm.com.
set component level [destination]
Sets the trace level and trace message destination for a specific component
and its subordinates. The value for the level option is a single integer
from 1 to 9, with 9 reporting the most detailed level of information. The
destination option specifies where the gathered trace information is
written and can be one of the following options:
file path=file_name
Specifies the fully qualified file name.
log_agent
Specifies a destination for the statistics information that is gathered
for the specified component. For more information about logging
events, see the IBM Security Access Manager for Web Administration
Guide.
show [component]
Shows the names and levels for all enabled trace components. If you
specify the component option, the output lists the name and level for the
specified component.
Return codes
0
The command completed successfully.
Chapter 1. pdadmin commands
167
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example enables the pdweb.debug trace component to level 2 and
then displays the output for all enabled components. WebSEAL–specific
components are prefixed with pdweb.
pdadmin sec_master> server task webseald-instance_name trace set
pdweb.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 trace
component to level 9. Then, the output for all enabled components is displayed.
Components that are specific to the web server plug-ins are prefixed with
pdwebpi.
pdadmin sec_master> server task pdwpi-tivoli.com trace set
pdwebpi.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 add
Adds an additional installed WebSEAL server or server instance to an existing
virtual host junction.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name virtualhost add –h host_name
[options] vhost_label
Options
–h host_name
Specifies the DNS host name or IP address of the target server. Valid
values for host_name include any valid IP host name. This option is
required. For example:
www.example.com
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
168
IBM Security Access Manager for Web Version 7.0: Command Reference
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
options
Specifies the options that you can use with the server task virtualhost
add command. (Optional) These options include:
–D "dn"
Specifies the distinguished name of the server certificate. This
value, matched with the actual certificate DN, enhances
authentication and provides mutual authentication over SSL. For
example, 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"
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–H host_name
Specifies the DNS host name or IP address of the proxy server.
Valid values for host_name include any valid IP host name. For
example:
proxy.www.example.com
This option is used for junctions that were created with the type of
tcpproxy or sslproxy.
–i
Indicates that the WebSEAL server does not treat URLs as
case-sensitive.
This option is used for junctions that were created with the type of
tcp or ssl.
–p port
Specifies the TCP port of the server. The default value is 80 for
TCP junctions and 443 for SSL junctions. This option is used for
junctions that were created with the type of tcp or ssl.
–P port
Specifies the TCP port of the proxy server. The default value is
7138.
For port, use any valid port number. A valid port number is any
positive number that is allowed by TCP/IP and that is not
currently being used by another application. Use the default port
number value, or use a port number that is greater than 1000 that
is not being used.
This option is used for junctions that were created with the type of
tcpproxy or sslproxy.
Chapter 1. pdadmin commands
169
–q path
Specifies the relative path for the query_contents script. By default,
Security Access Manager looks for this script in the /cgi_bin
subdirectory. If this directory is different or the query_contents file
is renamed, use this option to indicate to WebSEAL the new URL
to the file. Required for Windows virtual hosts.
This option is valid for all junction types except localtcp and
localssl.
–u uuid
Specifies the UUID of this server when connected to WebSEAL
over a stateful junction that was using the –s option. This option is
used for junctions that were created with the type of tcp or ssl.
–w
Indicates Microsoft Windows 32 bit (Win32) file system support.
This option is used for junctions that were created with the type of
tcp or ssl.
vhost_label
Specifies 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_nameinstance_name/@vhost_label object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete the command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
Example
The following example adds a server with host name xyz.ibm.com to an existing
virtual host junction with the label support-vhost-http, on the WebSEAL server
abc.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
170
IBM Security Access Manager for Web Version 7.0: Command Reference
“server task virtualhost remove” on page 184
“server task virtualhost show” on page 186
server task virtualhost create
Creates a virtual host junction.
Requires authentication (administrator ID and password) to use this command.
Syntax
For local junctions:
server task instance_name-webseald-host_name virtualhost create –t
type –d dir –v virtual-host-name [options] vhost_label
For non-local junctions:
server task instance_name-webseald-host_name virtualhost create –t
type –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_name
Specifies the DNS host name or IP address of the target server. This option
is valid only for non-local junctions; local junctions do not need a host
name. Valid values for host_name include any valid IP host name. For
example:
www.example.com
–t type
Specifies the type of virtual host junction. This option is required and must
be one of the following types:
v tcp
v tcpproxy
v ssl
v sslproxy
v localtcp
v localssl
–v virtual-host-name[:port]
WebSEAL selects a virtual host junction to process a request if the HTTP
Host header of the request matches:
v The virtual host name by the -v option and
v 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 the
request sent to the server.
The port number is required if the virtual host uses a non-standard port
for 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 –h
host_name and –p port options.
The –v option is required for localtcp and localssl type junctions
Chapter 1. pdadmin commands
171
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
options
Specifies the options that you can use with the server task virtualhost
create command. (Optional) These options include:
–A
Enables a virtual host junction to support the lightweight
third-party authentication mechanism (LTPA). This option requires
the –F and –Z options. The –A, –F, and –Z options all must be used
together.
This option is valid for all junction types except localtcp and
localssl.
–2
You can use this option with the –A option to specify that LTPA
version 2 cookies (LtpaToken2) are used. The –A option without the
–2 option specifies that LTPA version 1 cookies (LtpaToken) are
used.
–b BA_value
Defines how the WebSEAL server passes client identity information
in HTTP basic authentication (BA) headers to the virtual host,
which is one of the following values:
v filter
v ignore
v supply
v gso
This option is valid for all junction types except localtcp and
localssl. The default value is filter.
–B
Indicates that WebSEAL uses the BA header information to
authenticate to the virtual host and to provide mutual
authentication over SSL. This option requires the –U and –W
options.
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–c header_type
Inserts the Security Access Manager client identity in HTTP
headers across the virtual host junction. The header_type argument
can include any combination of the listed Security Access Manager
HTTP header types:
v {iv-user|iv-user-l}
v iv-groups
172
IBM Security Access Manager for Web Version 7.0: Command Reference
v iv-creds
v all
The header types must be comma-separated, and cannot have a
space between the types. For example: -c iv_user,iv_groups
Specifying –c all is the same as specifying –c
iv-user,iv-groups,iv-creds.
This option is valid for all junction types except localtcp and
localssl.
–C
Supports mutual authentication by enabling the front-end
WebSEAL server to pass its identity information to the back-end
WebSEAL server. The front-end WebSEAL server passes
information in a Basic Authentication (BA) header. Additionally,
the –C option enables the single sign-on functionality that is
provided by the –c option.
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–D "dn"
Specifies the distinguished name of the server certificate. This
value, matched with the actual certificate DN, enhances
authentication and provides mutual authentication over SSL. For
example, 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"
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–e encoding_type
Specifies the encoding to use when HTTP headers is generated for
virtual host junctions. This encoding applies to headers that are
generated with both the –c junction option and tag-value. Possible
values for encoding are as follows:
utf8_bin
WebSEAL sends the headers in UTF-8.
utf8_uri
WebSEAL sends the headers in UTF-8 but URI also
encodes them. This behavior is the default behavior.
lcp_bin
WebSEAL sends the headers in the local code page of the
WebSEAL server.
lcp_uri
WebSEAL sends the headers in the local code page of the
WebSEAL server, but URI also encodes them.
This option is valid for all junction types except localtcp and
localssl.
–f
Forces the replacement (overwrite) of an existing virtual host
junction.
This option is used for junctions that were created with any
junction type.
Chapter 1. pdadmin commands
173
–F "keyfile"
Specifies the location of the key file that is used to encrypt LTPA
cookie data.
The –F option requires –A and –Z options. The –A, –F, and –Z
options all must be used together.
This option is valid for all junction types except localtcp and
localssl.
–g vhost_label
The –g option causes a second more virtual host junction to share a
protected object space as the initial virtual host junction.
This option is appropriate for junction pairs only (two junctions by
using complementary protocols). The option does not support the
association of more than two junctions.
–H host_name
Specifies the DNS host name or IP address of the proxy server. The
–P option also supports proxy server junctions. Valid values for
host_name include any valid IP host name. For example:
proxy.www.example.com
This option is valid only with junctions that were created with the
type of tcpproxy or sslproxy.
–i
Indicates that the WebSEAL junction does not treat URLs as
case-sensitive. To correctly authorize requests for junctions that are
not case-sensitive, WebSEAL does the authorization check on a
lowercase version of the URL. For example, a web server that is
running on a Windows operating system treats requests for
INDEX.HTM and index.htm as requests for the same file.
Junctions to such a web server must be created with the –i or –w
option. ACLs or POPs that are attached to objects beneath the
junction point must use the lowercase object name. An ACL
attached to /junction/index.htm applies to all the following
requests 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 localtcp
and localssl. Local junctions are not case-sensitive only on Win32
platforms; all other platforms are case-sensitive.
–k
Sends WebSEAL session cookies to the back-end virtual host. By
default, cookies are removed from requests that are sent to the
server.
This option is valid for all junction types except localtcp and
localssl.
–K "key_label"
Specifies the key label of the client-side certificate that WebSEAL
must present to the server. Use of this option allows the virtual
host to authenticate the WebSEAL server by using client
certificates.
This option is valid only with junctions that were created with the
type of ssl and sslproxy.
174
IBM Security Access Manager for Web Version 7.0: Command Reference
–l percent
Defines the soft limit for consumption of worker threads.
This option is valid for all junction types except localtcp and
localssl.
–L percent
Defines the hard limit for consumption of worker threads.
This option is valid for all junction types except localtcp and
localssl.
–p port
Specifies the TCP port of the third-party server. The default value
is 80 for TCP junctions and 443 for SSL junctions.
This option is valid for all junction types except localtcp and
localssl.
–P port
Specifies the TCP port number for the HTTP proxy server. The –P
option is required when the –H option is used.
This option is valid only with junctions that were created with the
type of tcpproxy or sslproxy.
–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 the
query_contents file name is renamed, this option indicates to
WebSEAL the new URL to the file. Required for Windows virtual
hosts.
This option is valid for all junction types except localtcp and
localssl.
–r
Inserts the incoming IP address into the HTTP header across the
junction.
This option is valid for all junction types except localtcp and
localssl.
–R
Allows the request to proceed but provides the rule failure reason
to the junction in an HTTP header. If the –R option is not used and
a rule failure occurs, WebSEAL does not allow the request to
proceed.
This option is valid for all junction types except localtcp and
localssl.
–s
Indicates that the virtual host junction support stateful
applications. By default, virtual host junctions are not stateful.
This option is valid for all junction types except localtcp and
localssl.
–S
Indicates the location of the forms single sign-on configuration file.
This option is valid for all junction types except localtcp and
localssl.
–T {resource | resource_group}
Specifies the name of the GSO resource or resource group. This
option is required only when the –b gso option is used.
Chapter 1. pdadmin commands
175
This option is valid for all junction types except localtcp and
localssl.
–u uuid
Specifies the Universally Unique Identifier (UUID) of a server that
is connected to WebSEAL by using a stateful virtual host junction
(–s option).
This option is valid for all junction types except localtcp and
localssl.
–U "user_name"
Specifies the WebSEAL server user name. This option requires the
–B and –W options. WebSEAL uses the BA header information to
authenticate to the virtual host and to provide mutual
authentication over SSL.
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–w
Indicates Microsoft Windows 32 bit (Win32) file system support.
This option provides all the functionality that is provided by the –i
junction option. The option disallows requests that contain file
names that might be interpreted as Win32 file name aliases.
This option is valid for all junction types except localtcp and
localssl. Local junctions prohibit URLs that contain Win32 file
name 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 to
authenticate to the virtual host and to provide mutual
authentication over SSL.
This option is valid only with junctions that were created with the
type of ssl or sslproxy.
–Y
Enables Tivoli Federated Identity Manager single-signon (SSO) for
the junction.
Note: Before you use this option, you must first configure the
WebSEAL configuration file to support Tivoli Federated Identity
Manager single-signon over junctions.
–z replica_set
Specifies the replica set, as follows:
For SMS environments:
Sessions on the virtual host junction are managed under
the specified replica set. Used to group or separate login
sessions among multiple virtual hosts.
For non-SMS environments:
Sessions on the virtual host junction are managed under
the specified replica set. Controls the partitioning of the
WebSEAL session cache. The virtual host can be part of the
same replica that is set as any standard junction that is
assigned to that same replica set. Standard junctions are
assigned to replica sets through the standard-junctionreplica-set entry of the [session] stanza.
176
IBM Security Access Manager for Web Version 7.0: Command Reference
–Z keyfile_pwd
Specifies the password of the key file that is used to encrypt LTPA
cookie data. This option requires the –A and –F options. The –A, –F,
and –Z options all must be used together.
This option is valid for all junction types except localtcp and
localssl.
vhost_label
Specifies the label name of the virtual host junction.
Authorization
Users and groups that require access to this command must be given the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/@vhost_label object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete 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 Access
Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
For more information about gathering statistics, see the IBM Security Access
Manager for Web Troubleshooting Guide.
Example
The following example creates an SSL type virtual host junction with the
vhost-xy-https label. This junction serves the virtual host x.y.com on the
junctioned server cruz1.ibm.com. WebSEAL responds to the Host: x.y.com header
in SSL (HTTPS) requests by forwarding the requests across this virtual host
junction:
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
“server
“server
“server
“server
task
task
task
task
task
virtualhost
virtualhost
virtualhost
virtualhost
virtualhost
add” on page 168
delete”
list” on page 179
remove” on page 184
show” on page 186
server task virtualhost delete
Deletes a virtual host junction.
Requires authentication (administrator ID and password) to use this command.
Chapter 1. pdadmin commands
177
Syntax
server task instance_name-webseald-host_name virtualhost delete vhost_label
Description
The server list virtualhost delete command deletes a virtual host junction. A
virtual host junction cannot be deleted if a second virtual host junction refers to it
through the –g option. An error message is returned at such an attempt.
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
vhost_label
Specifies 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_nameinstance_name/@vhost_label object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete 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 Access
Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
Example
The following example deletes the virtual host junction support-vhost-https from
the WebSEAL server abc.ibm.com:
178
IBM Security Access Manager for Web Version 7.0: Command Reference
pdadmin> server task default-webseald-abc.ibm.com virtualhost delete \
support-vhost-https
See also
“server
“server
“server
“server
“server
task
task
task
task
task
virtualhost
virtualhost
virtualhost
virtualhost
virtualhost
add” on page 168
create” on page 171
list”
remove” on page 184
show” on page 186
server task virtualhost list
Lists all configured virtual host junctions by label name.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name virtualhost list
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
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 given
this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
Chapter 1. pdadmin commands
179
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
Example
The following example lists the label names of all virtual host junctions that are
configured on the abc.ibm.com WebSEAL server:
pdadmin> server task default-webseald-abc.ibm.com virtualhost list
Output is like:
pubs-vhost-http
sales-vhost-https
support-vhost-http
See also
“server
“server
“server
“server
“server
task
task
task
task
task
virtualhost
virtualhost
virtualhost
virtualhost
virtualhost
add” on page 168
create” on page 171
delete” on page 177
remove” on page 184
show” on page 186
server task virtualhost offline
Places the server that is at this virtual host junction in an offline operational state.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name virtualhost offline [–i
server_uuid] vhost_label
Description
The server task virtualhost offline command places the server that is at this
virtual host junction in an offline operational state. No additional requests are sent
to the specified server. If a server is not specified, all servers that are at this virtual
host junction are placed in an offline operational state.
Options
–i server_uuid
Specifies the UUID of the server to place in an offline operational state. If a
server is not specified, all servers that are at this virtual host junction are
placed in an offline operational state. Use the server task virtualhost
show command to determine the ID of a specific server. (Optional)
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
180
IBM Security Access Manager for Web Version 7.0: Command Reference
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
vhost_label
Specifies 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_nameinstance_name/@vhost_label object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
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 operational
state. To determine the UUID of this junctioned server, run the server task
virtualhost show command:
Chapter 1. pdadmin commands
181
pdadmin> server task default-webseald-abc.ibm.com \
virtualhost show support-vhost-https
Output is like:
Virtual Host label: support-vhost-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Throttled
Throttled at: 2005-03-01-17:07:24
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total 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
“server
“server
“server
“server
task
task
task
task
task
offline” on page 135
online” on page 137
throttle” on page 164
virtualhost online”
virtualhost throttle” on page 188
server task virtualhost online
Places the server that is at this virtual host junction in an online operational state.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name virtualhost online [–i
server_uuid] vhost_label
Description
The server task virtualhost online command places the server that is at this
virtual host junction in an online operational state. The server now resumes normal
operation. If a server is not specified, all servers that are at this virtual host
junction are placed in an online operational state.
Options
–i server_uuid
UUID of the server to place in an online operational state. If a server is not
182
IBM Security Access Manager for Web Version 7.0: Command Reference
specified, all servers that are at this virtual host junction are placed in an
online operational state. Use the server task virtualhost show command
to determine the ID of a specific server. (Optional)
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
vhost_label
Specifies 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_nameinstance_name/@vhost_label object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
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
Chapter 1. pdadmin commands
183
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 operational
state. To determine the UUID of this junctioned server, 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-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Offline
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total 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
“server
“server
“server
“server
task
task
task
task
task
offline” on page 135
online” on page 137
throttle” on page 164
virtualhost offline” on page 180
virtualhost throttle” on page 188
server task virtualhost remove
Removes the specified server from a virtual host junction.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name virtualhost remove –i
server_uuid vhost_label
Options
–i server_uuid
Specifies the UUID of the server to be removed from the virtual host
junction. For this command, the –i option, normally used to treat URLs as
184
IBM Security Access Manager for Web Version 7.0: Command Reference
case-sensitive, operates like the –u option. See the server task show
command for details about obtaining the UUID.
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
vhost_label
Specifies 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_nameinstance_name/@vhost_label object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete 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 Access
Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
Example
The following example removes the junctioned server int4.ibm.com from the
virtual host junction support-vhost-https. To determine the UUID of the server to
be 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-https
Type: SSL
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Basic authentication mode: filter
Chapter 1. pdadmin commands
185
Forms based SSO: disabled
Authentication HTTP header: do not insert
Remote Address HTTP header: do not insert
Stateful junction: no
Boolean Rule Header: no
Delegation support: no
Mutually authenticated: no
Insert WebSphere LTPA cookies: no
Insert WebSEAL session cookies: no
Request Encoding: UTF-8, URI Encoded
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1
Server 2:
ID: xycecc77-19ve-81y5-4h0a-90267hj5nn57
Server State: running
Hostname: int4.ibm.com
Port: 444
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total 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
“server
“server
“server
“server
task
task
task
task
task
virtualhost
virtualhost
virtualhost
virtualhost
virtualhost
add” on page 168
create” on page 171
delete” on page 177
list” on page 179
show”
server task virtualhost show
Displays information about the specified virtual host junction. The virtual host
junction must exist, or an error is displayed.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name virtualhost show vhost_label
186
IBM Security Access Manager for Web Version 7.0: Command Reference
Options
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
vhost_label
Specifies the label name of the virtual host junction.
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 this
permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not be able to successfully
complete the command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
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:
Chapter 1. pdadmin commands
187
Virtual Host label: support-vhost-https
Type: SSL
Junction hard limit: 0 - using global value
Junction soft limit: 0 - using global value
Active worker threads: 0
Basic authentication mode: filter
Forms based SSO: disabled
Authentication HTTP header: do not insert
Remote Address HTTP header: do not insert
Stateful junction: no
Boolean Rule Header: no
Delegation support: no
Mutually authenticated: no
Insert WebSphere LTPA cookies: no
Insert WebSEAL session cookies: no
Request Encoding: UTF-8, URI Encoded
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Total requests: 1
See also
“server
“server
“server
“server
“server
task
task
task
task
task
virtualhost
virtualhost
virtualhost
virtualhost
virtualhost
add” on page 168
create” on page 171
delete” on page 177
list” on page 179
remove” on page 184
server task virtualhost throttle
Places the server that is at this virtual host junction in a throttled operational state.
Requires authentication (administrator ID and password) to use this command.
Syntax
server task instance_name-webseald-host_name virtualhost throttle [–i
server_uuid] vhost_label
Description
The server task virtualhost throttle command places the server that is at this
virtual host junction in a throttled operational state. Users can create a session with
WebSEAL before the invocation of this command. Only requests from such users
continue to be processed by the specified server. If a server is not specified, all
servers that are at this virtual host junction are placed in a throttled operational
state.
188
IBM Security Access Manager for Web Version 7.0: Command Reference
Options
–i server_uuid
Specifies the UUID of the server to throttle. If a server is not specified, all
servers that are at this virtual host junction are placed in a throttled
operational state. Use the server task virtualhost show command to
determine the ID of a specific server. (Optional)
instance_name-webseald-host_name
Specifies the full server name of the installed WebSEAL server instance.
You must specify this full server name in the exact format as displayed in
the output of the server list command.
The instance_name specifies the configured name of the WebSEAL server
instance. The webseald designation indicates that the WebSEAL service
performs the command task. The host_name is the name of the physical
computer where the WebSEAL server is installed.
For example, the configured name of a single WebSEAL server instance is
default. The host computer name where the WebSEAL server is installed
is abc.ibm.com. Then, the full WebSEAL server name is
default-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.
vhost_label
Specifies 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_nameinstance_name/@vhost_label object. For example, the sec_master administrative
user is given this permission by default.
Return codes
0
The command completed successfully.
Note: For WebSEAL server task commands, the return code is 0 when the
command is sent to the WebSEAL server without errors. However, even
after the command was successfully sent, the WebSEAL server might not
be able to successfully complete the command. The WebSEAL server
returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Note: This command is available only when WebSEAL is installed.
Example
In the following example, the virtual host junction:
v Has the label support-vhost-https.
Chapter 1. pdadmin commands
189
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 operational
state. To determine the UUID of this junctioned server, 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-https
Type: SSL
...
Virtual hostname: support.ibm.com
Alias: ibm.com
Alias: support
Virtual Host junction protocol partner: support-vhost-http
Server 1:
ID: bacecc66-13ce-11d8-8f0a-09267ea5aa77
Server State: running
Operational State: Online
Hostname: int3.ibm.com
Port: 443
Server DN:
Query_contents URL: /cgi-bin/query_contents
Query-contents: unknown
Case insensitive URLs: no
Allow Windows-style URLs: yes
Current requests: 0
Total 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
“server
“server
“server
“server
task
task
task
task
task
throttle” on page 164
offline” on page 135
online” on page 137
virtualhost offline” on page 180
virtualhost online” on page 182
server task server restart
Restarts a WebSEAL server by using the Security Access Manager server task
framework.
This command requires authentication of administrator ID and password.
Syntax
server task server_name server restart
190
IBM Security Access Manager for Web Version 7.0: Command Reference
Options
server_name
Specifies the name of the Security Access Manager authorization server
restart.
Authorization
Users and groups that require access to this command must have the s
(administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name object. For example, the sec_master administrative user has this
permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not successfully complete the
command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format, for example, 0x14c012f2. See the IBM Security Access Manager for
Web Error Message Reference for a list of the Security Access Manager error
messages by decimal or hexadecimal codes.
Note: The restart is successful only if the WebSEAL server was started by using
the pdweb_start script. The script must be running as a daemon on AIX, Linux, or
Solaris, or as a service on Windows). The restart command does not work if the
WebSEAL server is running in the foreground.
The result of the restart is not displayed on the administration console. You must
examine 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 sync
Synchronizes configuration data between two WebSEAL servers by using the
Security Access Manager server task framework.
This command requires authentication of administrator ID and password.
Syntax
server task webseal_server server sync server_name
Options
webseal_server
Specifies the fully qualified server name of the installed WebSEAL instance.
server_name
Specifies the name of the Security Access Manager authorization server
Chapter 1. pdadmin commands
191
from which data is extracted. Configuration data on the host system is
backed up and then synchronized with this data.
Authorization
Users and groups that require access to this command must have the s
(administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name object. For example, the sec_master administrative user has this
permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not successfully complete the
command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format, for example, 0x14c012f2. See the IBM Security Access Manager for
Web Error Message Reference for a list of the Security Access Manager error
messages by decimal or hexadecimal codes.
Example
The following example synchronizes configuration data with server
default-webseald-abc.ibm.com:
pdadmin> server task default-webseald-abc.ibm.com server sync
master-webseald-abc.ibm.com
server task jdb export
Exports a junction database to a specified file.
This command requires authentication of administrator ID and password.
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 the
output of the server list command.
path=file_name
Absolute path of the file on the WebSEAL server to which the junction
database is exported.
Authorization
Users and groups that require access to this command must have the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user has this
permission by default.
192
IBM Security Access Manager for Web Version 7.0: Command Reference
Note: This command is available only when WebSEAL is installed.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not successfully complete the
command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format, for example, 0x14c012f2.
See the IBM Security Access Manager for Web Error Message Reference for a
list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Note: This command can be used with the jdb import command to replicate live
junction databases.
Example
The following example exports the junction database from the
default-webseald-abc-2.ibm.com server to a file named junction-db.xml in the
WebSEAL server tmp directory:
pdadmin> server task default-webseald-abc-2.ibm.com jdb export file
path=/tmp/junction-db.xml
server task jdb import
Imports a junction database from a specified file.
This command requires authentication of administrator ID and password.
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 the
output of the server list command.
path=file_name
Absolute path of the file on the WebSEAL server, from which the junction
database is imported.
Authorization
Users and groups that require access to this command must have the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user has this
permission by default.
Note: This command is available only when WebSEAL is installed.
Chapter 1. pdadmin commands
193
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not successfully complete the
command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format, for example, 0x14c012f2.
See the IBM Security Access Manager for Web Error Message Reference for a
list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Note: This command can be used with the jdb export command to replicate live
junction databases.
Example
The following example imports the junction database from the
default-webseald-abc-1.ibm.com server to a file named junction-db.xml in the
WebSEAL server tmp directory:
pdadmin> server task default-webseald-abc-1.ibm.com jdb import file
path=/tmp/junction-db.xml
server task cfgdb export
Exports the current configuration to a named file.
Use this command with the cfgdb import command to migrate the configuration
of a WebSEAL instance. The configuration database includes the WebSEAL
configuration and pre-configured data files, for example, the WebSEAL key files.
The [cfg-db-cmd:entries] and [cfg-db-cmd:files] stanzas stipulate which data
and files to include in (or exclude from) the configuration database.
This command requires authentication of administrator ID and password.
Syntax
server task server_name cfgdb export file path=file_name
Options
server_name
Specifies the name of the Security Access Manager authorization server on
which the configuration data is located.
file_name
Specifies the absolute path to and the file name of the new configuration
data file.
Authorization
Users and groups that require access to this command must have the s (server
administration) permission in the ACL that governs the /WebSEAL/host_name-
194
IBM Security Access Manager for Web Version 7.0: Command Reference
instance_name/ object. For example, the sec_master administrative user has this
permission by default.
Note: This command is available only when WebSEAL is installed.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not successfully complete the
command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format, for example, 0x14c012f2.
See the IBM Security Access Manager for Web Error Message Reference for a
list of the Security Access Manager error messages by decimal or
hexadecimal 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 import
Imports the configuration database from a specified file and applies this
configuration to the specified WebSEAL instance.
Use this command with the cfgdb export command to migrate the configuration of
a WebSEAL instance. The configuration database includes the WebSEAL
configuration 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 to
include in (or exclude from) the configuration database.
The cfgdb import command also creates a backup of the current configuration data
and stores it on the WebSEAL server, under the /etc/archive/instance directory.
This command requires authentication of administrator ID and password.
Syntax
server task server_name cfgdb import file path=file_name
Options
server_name
Specifies the name of the Security Access Manager Authorization Server on
which the configuration data is located.
file_name
Specifies the absolute path to and the file name of the new configuration
data file.
Chapter 1. pdadmin commands
195
Authorization
Users and groups that require access to this command must have the s (server
administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name/ object. For example, the sec_master administrative user has this
permission by default.
Note: This command is available only when WebSEAL is installed.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not successfully complete the
command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference for a
list of the Security Access Manager error messages by decimal or
hexadecimal 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 cat
Returns the contents of a specified file to the administration console. This
command requires authentication of administrator ID and password.
Syntax
server task server_name file cat file_name byte_offset [-max bytes] [-encode]
Options
server_name
Specifies the name of the Security Access Manager authorization server on
which the file is hosted.
file_name
Specifies the fully qualified name of the file which is to be retrieved.
byte_offset
Specifies the offset in bytes from the start of the file at which the data is
retrieved.
-max bytes
Specifies the maximum number of bytes to be returned from the file. If you
do not specify this parameter, the maximum number of bytes returned is
controlled by the max-file-cat-command-length value in the [server]
stanza. The max-file-cat-command-length value takes precedence over the
196
IBM Security Access Manager for Web Version 7.0: Command Reference
-max bytes value. If the specified file is larger than the
max-file-cat-command-length value, the returned data is truncated.
--encode
Designates that the contents of the file must be base-64 encoded before it is
returned. (Optional)
Authorization
Users and groups that require access to this command must have the s
(administration) permission in the ACL that governs the /WebSEAL/host_nameinstance_name object. For example, the sec_master administrative user has this
permission by default.
Return codes
0
The command completed successfully. For WebSEAL server task
commands, the return code is 0 when the command is sent to the
WebSEAL server without errors. However, even after the command was
successfully sent, the WebSEAL server might not successfully complete the
command. The WebSEAL server returns an error message.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format, for example, 0x14c012f2. See the IBM Security Access Manager for
Web Error Message Reference for a list of the Security Access Manager error
messages by decimal or hexadecimal codes.
Note: For more information about WebSEAL junctions, see the IBM Security Access
Manager 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) from
the 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 create
Creates a Security Access Manager user.
Requires authentication (administrator ID and password) to use this command.
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 Security
Access Manager user that additionally has the authority to use single sign-on to
work with web resources.
Chapter 1. pdadmin commands
197
You can create users in the Active Directory Lightweight Directory Service (AD
LDS) user registry. You must create such users in the same AD LDS partition
where the Access Manager Management Domain information is stored.
The –gsouser option enables global sign-on capabilities. Users that are created in
an Active Directory are automatically given the capability to own single sign-on
credentials. This capability cannot be removed. When you use an LDAP user
registry, 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 with
an initial password that is not checked by the existing global password policies. If
this option is not present in the command, the password that is provided is
checked against the global password policies. In this case, the user create
command fails if the password is invalid, and the error message includes
information about what conditions were not met.
However, if the administrator applies the password option on the user modify
command, the -no-password-policy option is not available. Therefore, the
modified password is always checked against the global password policy settings.
Options
–gsouser
Enables the global sign-on (GSO) capabilities for the user. Applies only to
users created in an LDAP user registry. Users that are created in a URAF
user registry are automatically granted this capability. (Optional)
–no-password-policy
Indicates that password policy is not enforced during the creation of the
user account. The non-enforcement does not affect password policy
enforcement after user creation. (Optional)
cn
Specifies the common name that is assigned to the user that is being
created. For example: "Mary"
dn
Specifies the registry identifier that is assigned to the user that is being
created. The registry identifier must be known before a new user account
can be created. The registry identifier must be unique within the user
registry. If the user registry is Active Directory, certain characters are not
allowed. See “Characters disallowed for distinguished names” on page 310
for 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 of
the group list is a parenthesized list of group names, which are separated
by spaces. The groups must exist, or an error is displayed. Examples of
groups: deptD4D and printerusers. (Optional)
password
Specifies the password that is set for the new user. Passwords must adhere
to the password policies set by the administrator.
sn
Specifies the surname of the user that is being created. For example:
"Jones"
user_name
Specifies the name for the user to create. This name must be unique. A
198
IBM Security Access Manager for Web Version 7.0: Command Reference
valid user name is an alphanumeric string that is not case-sensitive. If the
user registry is Active Directory, certain characters are not allowed. See
“Characters disallowed for user and group name” on page 309 for the list
of these characters. If the user is a GSO user, certain characters are not
allowed. See “Characters disallowed for GSO names” on page 311 for the
list of these characters.
Note: Consider that you did not change the 7 - bit checking default value
during configuration of the Sun web server. In this case, turn off checking
so that non-ASCII characters can be stored in attributes.
Examples of user names are dlucas, sec_master, "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example, entered as one line, creates user dlucas:
pdadmin sec_master> user create –gsouser dlucas "cn=Diana
Lucas,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 set
the account-valid option to yes.
See also
“user delete”
“user import” on page 200
“user modify” on page 203
user delete
Deletes the specified Security Access Manager user. Optionally deletes the
information of the user in the user registry.
Requires authentication (administrator ID and password) to use this command.
Syntax
user delete [–registry] user_name
Options
–registry
Deletes the information of the user from the user registry. If this option is
Chapter 1. pdadmin commands
199
not specified, the registry user information can be used to create another
Security Access Manager user by using the user import command.
(Optional)
user_name
Specifies the name of the account to be deleted. Any resource credentials
that are associated with a user account are automatically removed at the
same time the user account is deleted. The user must exist, or an error is
displayed.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal 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 import
Creates a Security Access Manager user by importing user data that exists in the
user registry.
Requires authentication (administrator ID and password) to use this command.
If the user registry is Active Directory Lightweight Directory Service (AD LDS),
import within the AD LDS partition where the Security Access Manager
management 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 account
valid, you must use the user modify command to set the account-valid option to
yes.
Options
–gsouser
Specifies that the user has single sign-on capabilities. (Optional)
200
IBM Security Access Manager for Web Version 7.0: Command Reference
dn
Specifies the registry identifier of the user that is being imported. This
identifier must exist in the user registry and must not be associated with
another user in the same Security Access Manager secure domain. The
format for a distinguished name is like:
cn=Claude Wright,ou=Austin,o=Tivoli,c=us
group_name
Specifies an optional group to which the user is being added. The group
must exist, or an error is displayed. (Optional)
Examples of group names are Credit, Sales, and Test-group.
user_name
Specifies a unique Security Access Manager user name. This user is created
from information that exists in the user registry. For URAF-based registries,
the user name must correspond to a short name already defined for the
user that is being imported from the user registry. An example of a
URAF-based registry is Active Directory. A valid user name is an
alphanumeric string that is not case-sensitive. If the user is a GSO user,
certain characters are not allowed. See “Characters disallowed for GSO
names” on page 311 for the list of these characters.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Example
The following example creates the user mlucaser by importing information from
the 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 list
Lists users by Security Access Manager user name or by registry identifier.
Requires authentication (administrator ID and password) to use this command.
Syntax
user list pattern max_return
user list-dn pattern max_return
Chapter 1. pdadmin commands
201
Options
list pattern max_return
Specifies the pattern for the principal name. The pattern can include a
mixture of wildcard and string constants. The specified pattern is
case-sensitive. For example: *luca*
The pattern max_return options specify the maximum number of entries
that are found and returned for a single request. The number that is
returned is also governed by the server configuration, which specifies the
maximum number of results that can be returned as part of a search
operation.
The actual maximum returned entries is the minimum number of results
between 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.conf
configuration file.
For a discussion of how to limit the number of users that are returned
from the user list command, see the IBM Security Access Manager for Web:
Performance Tuning Guide.
list-dn pattern max_return
Specifies the pattern for the common name (CN) portion of the registry
identifier of the user. When you specify the pattern, you can exclude the
cn= component. The pattern can include a mixture of wildcard and string
constants, and is case-sensitive. For example, *luca*.
The returned list contains users that are defined in the user registry but are
not necessarily Security Access Manager users. Users that are not Security
Access Manager users can be imported into Security Access Manager by
using the user import command.
Note: When the user registry contains many user definitions, use wildcard
characters with discretion. When a pattern includes one or more wildcard
characters, the command attempts to find all user definitions that match the
specified pattern. However, the command displays only the specified number of
matching definitions in the user registry.
For example, if the user registry contains 10,000 definitions, specifying a single
wildcard (user list * 100) displays only the first 100 matching definitions but
finds all 10,000 definitions.
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2).
See the IBM Security Access Manager for Web Error Message Reference. This
reference provides a list of the Security Access Manager error messages by
decimal or hexadecimal codes.
Examples
v The following example lists the users that match the specified pattern:
pdadmin sec_master> user list *luca* 2
202
IBM Security Access Manager for Web Version 7.0: Command Reference
The output is like:
dlucas
mlucaser
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=US
cn=Mike Lucaser,ou=Austin,o=Tivoli,c=US
See also
“user show” on page 205
user modify
Changes various user account attributes.
Requires authentication (administrator ID and password) to use this command.
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 a
disabled account. Valid values are yes and no.
password password
Modifies the user password. The new password must comply with
password policies in effect.
When a password is set or changed, the password must comply to:
v The defined Security Access Manager password policy and
v The password policies for any underlying operating systems or user
registry.
v
When the password policy is enforced, Security Access Manager first
validates compliance against the Security Access Manager password policy
currently in effect. Then, Security Access Manager validates compliance
against the underlying user registry. Although a password complies to the
defined Security Access Manager policy, it might fail against the password
policy of the underlying user registry.
Note: Old passwords can still be used after a password change when:
Chapter 1. pdadmin commands
203
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. Valid
values are yes and no. If the value is no, the password seems expired and
the user cannot log in using the password. For a user to log in, an
administrator must set the valid state to yes. The user can also authenticate
by using another method, such as using a certificate.
Another reason a user might not be able to authenticate with a specified
password is because the maximum password age was exceeded. If you
check and find that the password-valid is set to yes, then try changing the
value for the policy set max-password-age parameter. Only an
administrator or a user that has the authority can set the max-password-age
policy on a user account. A user cannot set this policy on their own
account. This policy sets the maximum time, in days, that a password is
valid. Time is relative to the last time the password was changed.
When you change the value for password-valid or reset policy set
max-password-age, you do not have to change the password.
If you reset a password, the password-valid parameter automatically
switches to back to yes, and the max-password-age parameter resets the age
to 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_name
Specifies the name of the account to be modified. The user must exist, or
an error is displayed. A valid user name is an alphanumeric string that is
not case-sensitive. If the user is a GSO user, certain characters are not
allowed. See “Characters disallowed for GSO names” on page 311 for the
list of these characters. Examples of user names are dlucas, sec_master,
and "Mary Jones"
description description
Specifies any text string that describes the user that is being created.
Examples of user description are "Head of department" and "Department
number of employee".
gsouser {yes|no}
Enables global sign-on (GSO) capabilities for the specified user. Valid
values are yes and no. This property cannot be changed for users that are
created in a URAF user registry.
Return codes
204
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
IBM Security Access Manager for Web Version 7.0: Command Reference
Examples
v 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 show
Displays the properties of the specified user.
This command requires authentication of administrator ID and password.
Syntax
user show user_name
user show-dn dn
user show-groups user_name
Options
show user_name
Specifies the name of the user to display. The user must exist, or an error is
displayed.
Based on the Policy Server and WebSEAL configuration settings, the
following information is displayed:
Last login: YYYY-mm-dd-HH:MM:SS
Last Password Change: YYYY-mm-dd-HH:MM:SS
The system displays the local time of the computer where pdadmin was
run. For more information about the last login and last password change
configuration settings, see the Appendix C. Configuration file stanza
reference in the IBM Security Access Manager for Web: Administration Guide.
Examples of user names are dlucas, sec_master, and "Mary Jones".
show-dn dn
Displays the user that is specified by the identifier of the user in the user
registry. The returned user is defined in the user registry, but it is not
necessarily a Security Access Manager user. Users that are not Security
Access Manager users can be imported into Security Access Manager by
use of the user import command. The format for a distinguished name is
like:
cn=Claude Wright,ou=Austin,o=Tivoli,c=us
Based on the Policy Server and WebSEAL configuration settings, the
following information is displayed:
Last login: YYYY-mm-dd-HH:MM:SS
Last Password Change: YYYY-mm-dd-HH:MM:SS
Chapter 1. pdadmin commands
205
The system displays the local time of the computer where pdadmin was
run. For more information about last login and last password change
configuration settings, see the Appendix C. Configuration file stanza
reference in the IBM Security Access Manager for Web Administration Guide.
show-groups user_name
Displays the groups in which the specified user is a member. The user
must exist, or an error is displayed.
Examples of user names are dlucas, sec_master, and "Mary Jones".
Return codes
0
The command completed successfully.
1
The command failed. When a command fails, the pdadmin command
provides a description of the error and an error status code in hexadecimal
format (for example, 0x14c012f2). See the IBM Security Access Manager for
Web Error Message Reference. This reference provides a list of the Security
Access Manager error messages by decimal or hexadecimal codes.
Examples
v The following example displays the user account information for testuser:
pdadmin sec_master> user show testuser
The output is like:
Login ID: testuser
LDAP DN: cn=testuser,o=tivoli,c=us
LDAP CN: test
LDAP SN: test
Description: a test user
Is SecUser: yes
Is GSO user: no
Account valid: no
Password valid: yes
Last login: 1999-09-05-01:08:55
Last Password Change: 1999-09-04-05:06:45
v The following example displays the groups of which the specified user is a
member:
pdadmin sec_master> user show-groups dlucas
The output is like:
sales
credit
engineering
v The following example provides more information about the user when the
registry identifier is specified:
pdadmin sec_master> user show-dn "cn=Diana Lucas,ou=Austin,o=Tivoli,c=US"
The output is like:
Login ID: dlucas
LDAP dn: cn=Diana Lucas,ou=Austin,o=Tivoli
Inc,c=US
LDAP cn: Diana Lucas
LDAP sn: Lucas
Description: Diana Lucas, Credit Dept HCUS
IS SecUser: true
IS GSO user: false
Account valid: true
206
IBM Security Access Manager for Web Version 7.0: Command Reference
Password valid: true
Last login: 1999-09-05-01:08:55
Last Password Change: 1999-09-04-05:06:45
Authentication mechanism: Default:LDAP
See also
“user list” on page 201
Chapter 1. pdadmin commands
207
208
IBM Security Access Manager for Web Version 7.0: Command Reference
Chapter 2. Security Access Manager utilities
In addition to the commands provided for the pdadmin utility, Security Access
Manager provides the following utilities for your use.
These utilities are separated into the following categories, with some utilities
defined in multiple categories:
v “Installation and configuration utilities”
v “Migration utilities” on page 210
v “WebSEAL utilities” on page 211
v “Session management server utilities” on page 211
v “Security Access Manager plug-in for web servers utilities” on page 211
v “Serviceability and problem determination utilities” on page 212
Installation and configuration utilities
Installation and configuration utilities are listed together in the following table for
reference.
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 and
Reporting Service client.
“amwebcfg” on page 217
Configures or unconfigures a WebSEAL server.
“amwpmcfg” on page 221
Configures or unconfigures the Web Portal Manager
component of Security Access Manager.
“bassslcfg” on page 226
Configures or modifies the configuration information of the
IBM 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 Windows
platforms.
“ivbase_setup” on page 233
Configures the Security Access Manager runtime on
Windows platforms.
“ivbase_uninst” on page 236
Unconfigures the Security Access Manager runtime on
Windows 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 Manager
configuration files.
“pdconfig” on page 260
Configures and unconfigures Security Access Manager
components.
“pdjrtecfg” on page 261
Configures the IBM Security Access Manager Runtime for
Java.
“pdproxycfg” on page 272
Configures and unconfigures a policy proxy server.
© Copyright IBM Corp. 2001, 2012
209
Table 18. Security Access Manager installation and configuration utilities (continued)
Utility
Description
“PDAcld_config” on page 247 Configures an Authorization server on AIX, Linux, and
Solaris platforms.
“PDAcld_unconfig” on page
250
Unconfigures an Authorization server on AIX, Linux, and
Solaris platforms.
“PDMgr_config” on page 267 Configures a Policy server on AIX, Linux, and Solaris
platforms.
“PDMgr_unconfig” on page
270
Unconfigures a Policy server on AIX, Linux, and Solaris
platforms.
“PDRTE_config” on page 275
Configures the Security Access Manager Runtime on AIX,
Linux, and Solaris platforms.
“PDRTE_unconfig” on page
278
Unconfigures the Security Access Manager Runtime on
AIX, Linux, and Solaris platforms.
“pdsmsclicfg” on page 279
Configures the command-line utility plug-in for the session
management 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 configuration
information of a resource manager to use an SSL connection
for communicating with the policy server.
This utility is used for C application servers only. For Java
application servers, use the equivalent
com.tivoli.pd.jcfg.SvrSslCfg Java class.
For information about this class, see the IBM Security Access
Manager for Web: Authorization Java Classes Developer
Reference.
Migration utilities
Migration utilities are listed together in the following table for reference.
Table 19 lists the utilities that can be used to migrate Security Access Manager user
registry data.
Table 19. Security Access Manager migration utilities
Utility
Description
“adschema_update” on page
212
Adds the new attribute for recording maximum concurrent
web sessions.
“ivrgy_tool” on page 242
Completes either of these actions:
v Updates the Security Access Manager schema on the
specified LDAP server.
v Applies the required ACLs to suffixes added to the
LDAP server after the policy server was configured.
“pdbackup” on page 254
210
Backs up, restores, and extracts Security Access Manager
data.
IBM Security Access Manager for Web Version 7.0: Command Reference
WebSEAL utilities
WebSEAL utilities are listed together in the following table for reference.
Table 20 lists the WebSEAL utilities.
Table 20. WebSEAL utilities
Utility
“amwebcfg” on page 217
Description
Configures or unconfigures a WebSEAL server.
“cdsso_key_gen” on page 229 Generates a key that is used during encrypting and
decrypting authentication tokens for Security Access
Manager WebSEAL cross-domain single sign-on.
“pdweb” on page 284
Starts, stops, or restarts a WebSEAL server or displays
server status.
“query_contents” on page 290 Returns the contents of the root directory of a web space on
a third-party web server.
Session management server utilities
Session management server utilities are listed together in the following table for
reference.
Table 21 lists the session management server (SMS) utilities. These utilities require
the installation of SMS. SMS provides a unified view of WebSEAL and plug-in for
web servers current sessions.
Table 21. Session management server utilities
Utility
Description
“pdsmsclicfg” on page 279
Configures the command-line utility plug-in for the session
management server.
“smsbackup” on page 291
Gathers information to help IBM Software Support in
problem determination.
“smscfg” on page 293
Configures the session management server.
“smsservicelevel” on page
300
Lists the current service level of the session management
server files on the local system.
Security Access Manager plug-in for web servers utilities
Security Access Manager plug-in for web servers utilities are listed together in the
following 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 as
a daemon or run it in the foreground.
“pdwebpi_start” on page 286
Starts, restarts, and stops the plug-in for web servers
process 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 for
web 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 on
a third-party web server.
Serviceability and problem determination utilities
Serviceability and problem determination utilities are listed together in the
following table for reference.
Table 23 lists the serviceability and problem determination utilities.
Table 23. Serviceability and problem determination utilities
Utility
“pdbackup” on page 254
Description
Backs up, restores, and extracts Security Access Manager
data.
“pdjservicelevel” on page 266 Returns the service level of installed Security Access
Manager files that use the IBM Security Access Manager
Runtime for Java package.
“pdservicelevel” on page 278
Returns the service level of installed Security Access
Manager files that use the Security Access Manager
Runtime package.
“pdversion” on page 282
Lists the current version of Security Access Manager
components 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 as
a daemon or run it in the foreground.
“pdwpi-version” on page 287 Lists the version and copyright information for plug-in for
web servers.
“smsbackup” on page 291
Gathers information to help IBM Software Support in
problem determination.
“smsservicelevel” on page
300
Lists the current service level of the session management
server files on the local system.
adschema_update
Modifies the Microsoft Active Directory schema to work with the current version
of 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 schema
for the current version of Security Access Manager.
212
IBM Security Access Manager for Web Version 7.0: Command Reference
Run this utility on the Active Directory domain controller against which the policy
server is configured after you upgrade to IBM Security Access Manager for Web,
version 7.0.
Parameters
–f schema_file
Specifies the name of the Active Directory schema file. By default, the
adschema.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_pwd
Specifies the password for the Active Directory administrator.
–r response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. There is no default response file name. The
response file contains stanzas and 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)
–u active_directory_administrator_id
Specifies 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 policy
server 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 an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
amauditcfg
Configures 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
Chapter 2. Security Access Manager utilities
213
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_file
cache_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_auth
yes –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 Auditing
Service client from the command line. The utility can be run in command-line
mode 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 the
response file. You must manually create the response file, and the response file
requires 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.
unconfig
Unconfigures the client.
214
IBM Security Access Manager for Web Version 7.0: Command Reference
–audit_id administrator_id
Specifies the WebSphere administrator who has the EventSource role that is
mapped to the CommonAuditService. This ID is authenticated through
WebSphere by using HTTP basic authentication. This parameter is valid
when the –enable_pwd_auth parameter is set to yes.
–audit_key_file key_file
Specifies the fully qualified name of the key file that is required for secure
communication with the web service. This parameter is required when the
–enable_ssl parameter is set to yes.
–audit_pwd audit_id_password
Specifies the password for the WebSphere administrator who has the
EventSource role that is mapped to the CommonAuditService. This
parameter is valid when the –enable_pwd_auth parameter is set to yes.
–audit_srv_url url
Specifies the URL of the web service. For secure communication, use the
following URL:
https://hostname:9443/CommonAuditService/services/Emitter
For nonsecure communication, use the following URL:
http://hostname:9080/CommonAuditService/services/Emitter
–audit_stash_file stash_file
Specifies the fully qualified name of the stash file that is required for
secure communication with the Common Audit web service. This
parameter is required when the –enable_ssl parameter is set to yes.
–disk_cache_file cache_file
Specifies the fully qualified name of the disk cache file. This parameter is
required 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, indicates
how to handle disk caching. The following values are valid:
always Indicates that audit events are always written directly to the disk
cache.
never
Indicates that audit events are written to the event queue. There is
no disk cache.
auto
Indicates that audit events are written to the event queue except
when the server is down or the event queue is full. Under these
conditions, 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 reporting
services client waits before cached events are discarded. The services client
might discard cached events when the temporary disk cache storage is
filled.
Valid values are -1, 0, number of seconds. A value of -1 indicates that
cached events are not discarded.
A value of 0 indicates that cached events are discarded immediately. A
specified number of seconds indicates that cached events are not discarded
until the specified number of seconds passes. The default value is -1.
(Optional)
Chapter 2. Security Access Manager utilities
215
This parameter takes effect only when –disk_cache_mode is set to always or
auto.
–enable_pwd_auth {yes|no}
Specifies whether password authentication is used. Valid values are yes or
no. 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 Common
Audit 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 without
parameters. When one or more parameters are specified, lists the specified
parameters and their descriptions.
–operations
Prints all the valid parameters.
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–srv_cfg_file configuration_file
Specifies the name of the configuration file that is associated with the
security server (the Common Audit client). During configuration, entries
are set to enable auditing. During an unconfiguration, the doAudit stanza
entry is set to no in the [cars-client] stanza of the server-specific
configuration 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 in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
216
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
IBM Security Access Manager for Web Version 7.0: Command Reference
Examples
The following example configures an authorization server by using SSL and
password 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
amwebcfg
Configures 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_root
doc_root
amwebcfg –action config –rspfile response_file
amwebcfg –action config –interactive
amwebcfg –action unconfig –inst_name instance_name –admin_id admin –admin_pwd
password
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 file
mode.
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 response
file. The response file requires all parameters. The response file must be created
manually.
Chapter 2. Security Access Manager utilities
217
Parameters
–?
Displays the syntax and an example for this utility.
–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 name
and returns the name value to the pdconfig utility. This parameter
is used only by pdconfig. Do not use this parameter from the
command line.
status Returns the status value to the pdconfig utility. This parameter is
used only by pdconfig. Do not use this parameter from the
command line.
unconfig
Unconfigures a WebSEAL instance.
–admin_id admin
Specifies the name of the Security Access Manager administrative user. The
default value is sec_master.
–admin_pwd password
Specifies the Security Access Manager administrative user password (the
administrative user is normally sec_master).
–cert_label label
Specifies the LDAP client certificate label. This parameter is used only
when SSL communication is enabled between WebSEAL and an LDAP
server (–ssl_yn yes).
When SSL communication is enabled between WebSEAL and the LDAP
server, SSL does not require an LDAP client certificate label. Thus this label
file is optional, even amwebcfg is called with –ssl_yn yes. When the client
label is not specified, SSL uses default certificate that is contained in the
keyfile.
Used with –action config.
–doc_root doc_root
Specifies the web document root directory. The directory must exist. Used
with –action config.
When this parameter is not supplied on the command line, amwebcfg
creates a default directory. The default directory path includes the instance
name, prefixed by www-. For example, when the instance name is web1, and
the doc_root is not specified on the command line, the following directory
is created:
On AIX, Linux, and Solaris operating systems
opt/pdweb/www-web1/docs
On Windows operating systems
installation_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.
218
IBM Security Access Manager for Web Version 7.0: Command Reference
On AIX, Linux, and Solaris operating systems
opt/pdweb/www-default/docs
On Windows operating systems
installation_directory\pdweb\www-default\docs
–help [options]
Lists each parameter and a one line description of it when specified
without an argument. When one or more arguments are specified,
WebSEAL lists each specified parameter and a one line description of it.
–host host_name
Specifies the host name that is used by the Security Access Manager policy
server to contact a WebSEAL server. This parameter is required for –action
config.
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. This
parameter is required for –action config. The valid Boolean indicators are
yes or no. There is no default value.
–http_port http_port
Specifies the port number for unsecure HTTP access. This parameter is
required for –action config when –http_yn is set to yes. You can use port
80 for HTTP. There is no default value.
–https_yn {yes|no}
Specifies whether HTTPS access is allowed to the WebSEAL instance. This
parameter is required for –action config. The valid Boolean indicators are
yes or no. There is no default value.
–https_port https_port
Specifies the port number for secure HTTP access. This parameter is
required for –action config when –https_yn is set to yes. You can use port
443 for HTTPS. There is no default value.
–inst_name instance_name
Specifies 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, amwebcfg
supplies a default instance name of default. This instance name can be
changed to another name (for example, webseal1).
–interactive
Specifies that the configuration is to be done interactively by the
administrator. WebSEAL displays a text-based menu and presents a series
of prompts to obtain the necessary configuration information from the
administrator.
Chapter 2. Security Access Manager utilities
219
Note: Interactive mode is supported only on AIX, Linux, and Solaris
operating systems. When this parameter is used on Windows operating
systems, an error message states that the parameter is not supported.
–domain am_domain
Specifies the name of the Security Access Manager management domain.
When this value is not supplied, the default value of default applies.
–ip_address ip_address
Specifies the logical network interface that is the IP address for the
WebSEAL server. This parameter is required with –action config only
when –nw_interface_yn is set to yes.
–key_file key_file
Specifies the LDAP SSL key file. This parameter is required with –action
config only when SSL communication is enabled between the WebSEAL
server and an LDAP server.
–key_file_pwd password
Specifies the LDAP SSL key file password. This parameter is required with
–action config only when SSL communication is enabled between the
WebSEAL server and the LDAP server.
–listening_port am_listening_port
Specifies the listening port number for the Security Access Manager policy
server. This listening port is the port on which the WebSEAL server and
the policy server communicate. The port must be greater than 1024, and
must 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 Boolean
indicators are yes or no. This parameter is required with –action config
when you add a WebSEAL instance. There is no default value.
–operations
Prints all the valid command-line options.
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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_port
Specifies the port number on which SSL communication takes place
between the WebSEAL server and the LDAP server. This parameter is
required only when –ssl_yn is set to yes as part of –action config. The
known port for SSL is 636. There is no default value.
–ssl_yn {yes|no}
Specifies whether to enable SSL communication between the WebSEAL
server 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.
220
IBM Security Access Manager for Web Version 7.0: Command Reference
Availability
This utility is in one of 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
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
v 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 a
logical network interface, and to not enable SSL communication with an LDAP
server:
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
amwpmcfg
Configures or unconfigures the Web Portal Manager component of Security Access
Manager.
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_id
websphere_admin] [–was_admin_pwd websphere_admin_password] [–trust_store
trust_store] [–trust_store_pwd trust_store_password] [–keyfile key_file]
Chapter 2. Security Access Manager utilities
221
[–key_pwd key_file_password] [–authzsvr authorization_server_host]
[–authzsvr_port authorization_server_port] [–admin_id sam_admin] [–admin_pwd
sam_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 Manager
component of Security Access Manager. You can use the amwpmcfg utility in the
following 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 Access
Manager Runtime for Java to WebSphere Application Server, version 8. After you
configure Security Access Manager Runtime for Java to WebSphere Application
Server, version 8, you can use the amwpmcfg utility to configure Web Portal
Manager.
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 security
is 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 Java
executable file in the path must be compatible with WebSphere Application
Server 8.0. You can use the WebSphere Application Server 8.0 JRE or the Java 6
supplied with IBM Security Access Manager 7.0.
222
IBM Security Access Manager for Web Version 7.0: Command Reference
The amwpmcfg utility sets the pd.cfg.home property in the following configuration
property 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 returns
the name value to the pdconfig utility. Only pdconfig uses this
parameter. Do not use this parameter from the command line.
status Determines the configuration status of Web Portal Manager and
return status to the pdconfig utility. Only pdconfig uses this
parameter. Do not use this parameter from the command line.
unconfig
Unconfigure Web Portal Manager for Security Access Manager.
–admin_id sam_admin
Specifies the name of the Security Access Manager administrator with the
appropriate administrative privileges. If you do not specify this parameter
during interactive mode, you are prompted to do so.
–admin_pwd sam_admin_password
Specifies the password for the Security Access Manager administrator. This
parameter is required. If you do not specify this parameter during
interactive mode, you are prompted to do so.
–authzsvr authorization_server_host
Specifies the host name of the Security Access Manager authorization
server. Valid values include any valid IP host name. (Optional) For
example:
example.dallas.ibm.com
–authzsvr_port authorization_server_port
Specifies the port number for the Security Access Manager authorization
server. The default value is 7136. (Optional)
–domain domain
Specifies the name of the domain. The domain must exist. Any security
policy that is a domain affects only those objects in that domain. Users
with authority to run tasks in one domain do not necessarily have
authority to run those same tasks in other domains. The default domain is
Default, which indicates the management domain.
–help [{–operations | –? | –usage}]
Provides online help for this utility. If you do not specify a parameter, the
entire usage statement displays Definite parameter.
–?
Provides the usage statement for this utility.
–operations
Prints all the valid command-line options.
–usage Provides the usage statement for this utility.
Chapter 2. Security Access Manager utilities
223
–interactive
Specifies interactive mode, which is a graphical interface, to configure or
unconfigure Web Portal Manager. If you do not specify a mode, the utility
runs in silent mode.
–key_pwd key_file_password
Specifies the existing password that is associated with the specified client
key file. This password was set when the key file was created. This
parameter is required when you use a secure connection to WebSphere
Application Server.
–keyfile key_file
Specifies the fully qualified file name of the key file. This key file holds the
client-side certificates for secure communication. This parameter is required
for a secure connection to WebSphere Application Server.
–policysvr policy_server_host
Specifies the host name of the Security Access Manager policy server. Valid
values include any valid IP host name. For example:
example.dallas.ibm.com
–policysvr_port policy_server_port
Specifies the port number for the Security Access Manager policy server.
The default value is 7135. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the silent configuration
response file. You can use a response file for configuration. There is no
default response file name. The response file contains stanzas and
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. 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
or
waspath=c:/Program Files/IBM/WAS_HOME
v The path must not include quotation marks.
–trust_store trust_store
Specifies the fully qualified file name of the truststore. This trust file
handles the server-side certificates for secure communication. The
truststore verifies the certificate that is presented by the server. The signer
of the certificate must be a trusted certificate authority (CA). This
parameter is required for a secure connection to WebSphere Application
Server.
–trust_store_pwd trust_store_password
Specifies the existing password that protects the truststore file. This
password was set when the truststore was created. This parameter is
required for a secure connection to WebSphere Application Server.
–was_admin_id websphere_admin
Specifies the name of the WebSphere administrator with the appropriate
administrative privileges. This parameter is required for a secure
224
IBM Security Access Manager for Web Version 7.0: Command Reference
connection to WebSphere Application Server. If you do not specify a
parameter, you are prompted to do so.
–was_admin_pwd websphere_admin_password
Specifies the password for the WebSphere administrator. This parameter is
required for a secure connection to WebSphere Application Server. If you
do not specify a parameter, you are prompted to do so.
–was_host websphere_host
Specifies the host name or IP address of the system where WebSphere
Application Server is installed. (Optional)
–was_port websphere_port
Specifies the SOAP port number for the WebSphere Application Server. The
default value is 8879 for Deployment Manager in a cluster environment
and 8880 for an application server in a single server environment.
(Optional)
–waspath websphere_installation_path
Specifies the full path to the installation directory for IBM WebSphere
Application Server. This directory is validated by checking for the wsadmin
script in the /bin directory. The configuration fails if a required version of
WebSphere Application Server is not installed.
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\Policy Director\sbin
When you select an installation directory other than the default, this utility is in
the /sbin directory under the installation directory. For example,
installation_directory/sbin.
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
The following example manually configures Web Portal Manager into WebSphere
Application 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
Chapter 2. Security Access Manager utilities
225
bassslcfg
Configures or modifies the configuration information of the IBM Security Access
Manager runtime.
Syntax
bassslcfg –chgpwd –e password_life [–rspfile response_file]
bassslcfg –config –c cert_file [–C compliance] –h host_name [–p server_port] [–e
password_life] [–t ssl_timeout] [–d primary_domain] [–a {yes|no}] [–rspfile
response_file]
bassslcfg –getcacert –c cert_file –h host_name [–p server_port] [–rspfile
response_file]
bassslcfg –getmgtdomain –h host_name [–p server_port] [–rspfile response_file]
bassslcfg –modify [–h host_name] [–e password_life] [–p server_port] [–t
ssl_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.conf
configuration file. The value must be yes or no. (Optional)
–c cert_file
Specifies the name of the policy server base-64 encoded, self-signed
certificate.
–C compliance
Specifies the compliance value for the [ssl] ssl-compliance configuration
file setting. This parameter is only required when the policy server is not
accessible (such as when regenerating certificates on the policy server
system). If not specified, the setting is retrieved from the policy server. The
compliance value must be one of the following settings:
fips
Enforces FIPS 140-2 protocols and algorithms. Security Access
Manager servers and applications generate and use SHA1 with
2048-bit RSA certificates. Only TLS versions 1.0, 1.1 and 1.2 are
available. 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 with previous
Tivoli Access Manager releases.
none
Specifies that no special compliance criteria are applied to TLS
communication. Security Access Manager servers and applications
generate and use SHA1 with 2048-bit RSA certificates. This setting
option is equivalent to the previous release setting [ssl]
ssl-enable-fips = no. This value is compatible with previous
Tivoli Access Manager releases.
sp800-131-strict
Enables strict NIST SP800-131a support. This conformance
enforcement is required by some agencies and businesses starting
in the year 2014. Security Access Manager servers and applications
226
IBM Security Access Manager for Web Version 7.0: Command Reference
generate and use SHA256 with 2048-bit RSA certificates. This value
is not compatible with prior releases of Tivoli Access Manager.
Older Tivoli Access Manager clients cannot interact with Security
Access Manager 7.0 running with this compliance setting. Only
TLS version 1.2 is available; all others are disabled.
sp800-131-transition
Enables NIST SP800-131a support at the transition level. This value
is valid until the end of the year 2013. This value has fewer
restrictions than the strict enforcement. Only TLS versions 1.0, 1.1
and 1.2 are available. SSL versions 2 and 3 are disabled and
unavailable.
Security Access Manager servers and applications generate and use
SHA256 with 2048-bit RSA certificates. This value is at a higher
level than is required by the standard and was chosen as it is a
level that is permitted by the strict enforcement that allows easy
migration from transition to strict. This value is not compatible
with previous Tivoli Access Manager releases. Older Tivoli Access
Manager clients cannot interact with Security Access Manager 7.0
running with this compliance setting.
suite-b-128
Enables NSA Suite B at 128-bit support. Security Access Manager
servers and applications generate, and use, SHA256 with 256-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Tivoli Access Manager 7.0 running with
this compliance setting. Only TLS version 1.2 is available; all others
are disabled.
suite-b-192
Enables NSA Suite B at 192-bit support. Security Access Manager
servers and applications generate, and use, SHA384 with 384-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Security Access Manager 7.0 running
with this compliance setting. Only TLS version 1.2 is available; all
others are disabled.
–chgpwd
Changes the key database password. A new random password is generated
and saved in the stash file.
–config
Configures the IBM Security Access Manager runtime so that pdadmin
commands and the svrsslcfg utility can communicate with the policy
server. Also creates a key and stash file.
–d primary_domain
Specifies 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 of
the IBM Security Access Manager runtime is used. The local domain value
is retrieved from the configuration file.
Chapter 2. Security Access Manager utilities
227
A valid local domain name is an alphanumeric, case-sensitive string. String
characters 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_life
Sets 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.
–getcacert
Downloads the root CA certificate to a file.
–getmgtdomain
Prints the name of the management domain from the policy server to
standard out (stdout).
–h host_name
Specifies the TCP host name of the policy server. Valid values include any
valid IP host name. For example:
host = libra
host = libra.dallas.ibm.com
–modify
Modifies the policy server configuration.
–p server_port
Specifies 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_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. There is no default response file name. The
response file contains stanzas and 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)
–t ssl_timeout
Specifies the SSL session timeout in seconds. The value must be from 1 to
86400. During a configuration action, the default value is 7200. (Optional)
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\Policy Director\sbin
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
228
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
cdsso_key_gen
Generates a key for use during encrypting and decrypting authentication tokens
for 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 of
the cross-domain single sign-on solution for WebSEAL.
This authentication solution uses authentication tokens. Authentication information
about a user in a WebSEAL domain is collected by the built-in single sign-on
authentication mechanism library. This information is placed in a token. This token
must be encoded before it can be sent to a second WebSEAL domain. When it is
received in the second WebSEAL domain, the token is decoded, and the
authentication information about the user is accessed.
The tokens are encoded by use of a key file. The key file is generated by the
cdsso_key_gen utility.
When a key file is generated, it must be manually copied to each WebSEAL server
in each domain. The assumption is that each specified domain participates in the
cross-domain single sign-on solution.
Parameters
path
Specifies the fully qualified path to the key file.
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/pdwebrte/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 in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
Chapter 2. Security Access Manager utilities
229
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Example
The following example generates a key and places it in the /tmp/keyfile file:
cdsso_key_gen /tmp/keyfile
ivacld_setup
Configures the Security Access Manager authorization server for Windows
platforms.
Syntax
ivacld_setup.exe [–?] [–a adminid] [–d domain_name] [–h host_name] [–i
instance_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 authorization
server on Windows platforms. You can run this utility directly from the command
line.
Parameters
–?
Prints a usage statement. (Optional)
–a adminid
Specifies the ID for the administrator of the management domain. The
default administrator ID is sec_master. (Optional)
–d domain_name
Specifies the domain name. The default value is Default, which indicates
the management domain. (Optional)
–h host_name
Specifies the fully qualified name of the host system for the authorization
server. The default value is the local host name. (Optional)
–i instance_name
Specifies the authorization server instance name. The default authorization
server instance name is always empty. Enter a unique name to configure
each additional authorization server. Instance names can contain all
alphanumeric characters; they also can use the hyphen (-) and underscore (
_ ) characters. An instance name cannot begin with a hyphen (-) character.
(Optional)
–p password
Specifies the password for the administrator ID, adminid. This parameter is
required.
–policysvr host_port_rank
Specifies the policy server host name, port, and rank. The policy server
host name is the name of the host on which the policy server runs. The
230
IBM Security Access Manager for Web Version 7.0: Command Reference
port is the port on which the policy server listens for requests. The rank is
an integer value that denotes priority. These three inputs are provided in a
string as hostname:port:rank for this value. This value would typically be
POLICYSVR_HOST:7135:1 where POLICYSVR_HOST is the host name of the
policy server.
–q
Runs the command in silent mode and does not output any message
boxes. Writes messages only to stderr. (Optional)
–r port
Specifies the administration request port. The default port is 7137.
(Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. There is no default response file name. The
response file contains stanzas and 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)
–t port
Specifies 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 in
the \sbin directory under the installation directory (for example:
installation_directory\sbin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error.
See the IBM Security Access Manager for Web Error Message Reference. This reference
provides a list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Example
The following example configures the authorization server with the default
management 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_uninst
Unconfigures the Security Access Manager authorization server for Windows
platforms.
Chapter 2. Security Access Manager utilities
231
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 authorization
server on Windows platforms. You can run this utility directly from the command
line.
Parameters
–?
Prints a usage statement. (Optional)
–a admin_id
Specifies the ID for the administrator of the management domain. The
default administrator ID is sec_master. (Optional)
–deconfig
Unconfigure the authorization server.
–i instance
Specifies the authorization server instance name. The default authorization
server instance name is always empty. Enter a unique name to configure
each additional authorization server. Instance names can contain all
alphanumeric characters; they also can use the hyphen (-) and underscore (
_ ) characters. An instance name cannot begin with a hyphen (-) character.
(Optional)
–p admin_pwd
Specifies the password for the administrator ID, admin_id. This parameter
is required.
–policysvr host_port_rank
Specifies the policy server host name, port, and rank. The policy server
host 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 is
an integer value that denotes priority. These three inputs are provided in a
string as hostname:port:rank for this value. This value would normally be
POLICYSVR_HOST:7135:1 where POLICYSVR_HOST is the host name of the
policy server.
–q
Runs in silent mode and do not output any message boxes. Writes only to
stderr. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. There is no default response file name. The
response file contains stanzas and 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)
Availability
By default, this utility is in the following directory on Windows operating systems:
C:\Program Files\Tivoli\Policy Director\sbin
232
IBM Security Access Manager for Web Version 7.0: Command Reference
When an installation directory other than the default is selected, this utility is in
the \sbin directory under the installation directory (for example:
installation_directory\sbin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error.
See the IBM Security Access Manager for Web Error Message Reference. This reference
provides a list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Example
The following example unconfigures the authorization server by using the default
management domain:
ivacld_uninst.exe -deconfig -a sec_master -p password -i instance
-policysvr libra.austin.example.com:7135:1
ivbase_setup
Configures the Security Access Manager runtime server for Windows platforms.
Syntax
ivbase_setup.exe [–?] [–a admin_ID] –c mgr_certfile [–d distinguished_name] [–D
distinguished_name] [–G] [–h host_name] –H hostname [–K key_file] [–l
local_domain_name] [–N key_file_dn] [–o global_catalog_port] [–p port] [–P
ldap_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 on
Windows platforms. You can run this utility directly from the command line.
Certain user registries require specific parameters. For an explanation of which
parameters are required for certain user registries, see the following parameter
descriptions.
Parameters
–?
Prints a usage statement. (Optional)
–a admin_ID
Specifies the Administrator ID to use during communication with the
Active Directory. This parameter is required if the -t parameter is
active_directory.
–c mgr_certfile
Specifies 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, the
certificate is downloaded from the policy server. This parameter is required
if the Security Access Manager policy server is not on this computer.
Chapter 2. Security Access Manager utilities
233
–d distinguished_name
Specifies the Distinguished Name of the Active Directory domain. This
parameter is required if the -t parameter is active_directory.
For example:
dc=ibm,dc=com
–D distinguished_name
Specifies the Distinguished Name (DN) of the data location on the Active
Directory server in which to store Security Access Manager data. This
parameter is required if the -G parameter is not used. If the -G parameter is
used, then the default value is the value of the -d parameter.
–G
Configures Security Access Manager with the Active Directory multiple
domain environment. Use this parameter to configure multiple domains.
(Optional)
–h host_name
Specifies the host name of the policy server. This parameter is required if
the Security Access Manager policy server is not on this computer. You can
specify any valid IP host name.
For example:
host_name = libra.dallas.example.com
–H hostname
Specifies the IP address or host name of the LDAP server or Active
Directory server. This parameter is required if reg_type is ldap or
active_directory. You can specify any valid IP host name.
For example:
hostname = libra
hostname = libra.us.example.com
–K key_file
Specifies the fully qualified file name of the key file. This key file holds the
client-side certificates for secure communication. This parameter is required
if the -Z parameter is used.
–l local_domain_name
Specifies the local domain name for the runtime that is being configured. A
local domain is a Security Access Manager secure domain that is used by
programs when no explicit domain is specified. A valid local domain name
is an alphanumeric, case-sensitive string. String characters are expected to
be characters that are part of the local code set. You cannot use a space in
the domain name. (Optional)
For example:
local_domain_name = Default
–N key_file_dn
Specifies the Distinguished Name for accessing the keyfile. This parameter
is required if the -Z parameter is used.
–o global_catalog_port
Specifies the port number for the Active Directory Global Catalog Server
when the -u parameter is used.
–p port
Specifies the port number for the Security Access Manager policy server.
This parameter is required if the Security Access Manager policy server is
not on this computer. The default value is 7135. (Optional)
234
IBM Security Access Manager for Web Version 7.0: Command Reference
–P ldap_port
Specifies the port number of the LDAP server when Secure Socket Layer
(SSL) is not used. Use the LDAP server-configured port number. The
default port number is 389. (Optional)
–q
Runs the command in silent mode and does not output any message
boxes. Write only to stderr. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–S ldap_port
Specifies the port number of the LDAP server when Secure Socket Layer
(SSL) is used. Use the LDAP server-configured port number. The default
port number is 636. (Optional)
–t reg_type {ldap | active_directory}
Specifies the type of registry server to set up. Valid responses are ldap, and
active_directory.
–T path
Enables 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 userPrincipalName
attribute of the Active Directory user object as its user ID. If not used, only
the default format of the userPrincipalName can be used as the user ID.
(Optional)
–v global_catalog_host
Specifies the Global Catalog server host name when the -u parameter is
used. (Optional)
For example:
gc_host = gcserver.us.ibm.com
–w admin_pwd
Specifies the Administrator password to use to communicate with Active
Directory. This parameter is required if the -t parameter is
active_directory.
–W key_file_password
Specifies the existing password that is associated with the specified
key_file. This password was set when the key file was created. This
parameter is required if the -Z parameter is used.
–Z
Specifies whether to enable SSL communication between the runtime and
the registry server. This parameter does not display with non-SSL
communication. (Optional)
Chapter 2. Security Access Manager utilities
235
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 in
the \sbin directory under the installation directory (for example:
installation_directory\sbin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error displays.
See the IBM Security Access Manager for Web Error Message Reference. This reference
provides a list of the Security Access Manager error messages by decimal or
hexadecimal codes.
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_uninst
Unconfigures 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 on
Windows platforms. You can run this utility directly from the command line.
Parameters
–?
Prints a usage statement. (Optional)
–deconfig
Unconfigures the runtime. This parameter is required.
–q
Runs in silent mode and does not output any message boxes. Writes only
to stderr. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
236
IBM Security Access Manager for Web Version 7.0: Command Reference
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 in
the \sbin directory under the installation directory (for example:
installation_directory\sbin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error.
See the IBM Security Access Manager for Web Error Message Reference. This reference
provides a list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Examples
The following example unconfigures the runtime:
ivbase_uninst.exe -deconfig
ivmgrd_setup
Configures 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}] –w
password [–y {yes|no}] [–Y restore_directory]
Description
The ivmgrd_setup utility configures the Security Access Manager policy server on
Windows platforms. You can run this utility directly from the command line.
Parameters
–?
Prints a usage statement. (Optional)
–a ldap_dn
Specifies the name of the management domain. Configuring the policy
server in the management domain creates the initial administrative
domain. The management domain name must be unique in the LDAP
server. The name must be an alphanumeric string up to 64 characters long
and is not case-sensitive. The default value is Default. (Optional)
–C compliance
Specifies the compliance value for the [ssl] ssl-compliance configuration
file setting. This parameter defaults to none, if not provided. (Optional) The
compliance value must be one of the following settings:
fips
Enforces FIPS 140-2 protocols and algorithms. Security Access
Manager servers and applications generate and use SHA1 with
Chapter 2. Security Access Manager utilities
237
2048-bit RSA certificates. Only TLS versions 1.0, 1.1 and 1.2 are
available. 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 with previous
Tivoli Access Manager releases.
none
Specifies that no special compliance criteria are applied to TLS
communication. Security Access Manager servers and applications
generate and use SHA1 with 2048-bit RSA certificates. This setting
option is equivalent to the previous release setting [ssl]
ssl-enable-fips = no. This value is compatible with previous
Tivoli Access Manager releases.
sp800-131-strict
Enables strict NIST SP800-131a support. This conformance
enforcement is required by some agencies and businesses that start
in the year 2014.
Security Access Manager servers and applications generate and use
SHA256 with 2048-bit RSA certificates. This value is not compatible
with prior releases of Tivoli Access Manager. Older Tivoli Access
Manager clients cannot interact with Security Access Manager 7.0
running with this compliance setting. Only TLS version 1.2 is
available; all others are disabled.
sp800-131-transition
Enables NIST SP800-131a support at the transition level. This value
is valid until the end of the year 2013. This value has fewer
restrictions than the strict enforcement. Only TLS versions 1.0, 1.1
and 1.2 are available. SSL versions 2 and 3 are disabled and
unavailable.
Security Access Manager servers and applications generate and use
SHA256 with 2048-bit RSA certificates. This value is at a higher
level than is required by the standard and was chosen as it is a
level permitted by the strict enforcement that allows easy
migration from transition to strict. This value is not compatible
with previous Tivoli Access Manager releases. Older Tivoli Access
Manager clients cannot interact with Security Access Manager 7.0
running with this compliance setting.
suite-b-128
Enables NSA Suite B at 128-bit support. Security Access Manager
servers and applications generate, and use, SHA256 with 256-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Tivoli Access Manager 7.0 running with
this compliance setting. Only TLS version 1.2 is available; all others
are disabled.
suite-b-192
Enables NSA Suite B at 192-bit support. Security Access Manager
servers and applications generate, and use, SHA384 with 384-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Security Access Manager 7.0 running
with this compliance setting. Only TLS version 1.2 is available; all
others are disabled.
238
IBM Security Access Manager for Web Version 7.0: Command Reference
–d dn_ldap-admin
Specifies the distinguished name of the LDAP administrator. The default
value is cn=root. (Optional)
–D {yes|no}
Specifies whether to enable the downloading of the root CA certificate for
the 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 to
use the appropriate FIPS secure communications protocol. The valid
response values are yes or no. The default value is no. (Optional)
–l certificate_life
Specifies the number of days that the SSL certificate file is valid. The
default number of days is 1460. (Optional)
–m password
Specifies the password for the administrator ID. The default administrator
ID is sec_master. This parameter is required when you use LDAP.
–q
Runs the command in silent mode and does not output any message
boxes. Writes only to stderr. (Optional)
–r port
Specifies the port number for the policy server. The default value is 7135.
(Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–s ldap_suffix
Creates the secAuthorityInfo object entry on the LDAP server when you
create:
v An Security Access Manager domain
v The initial management domain
This object represents the domain and is named by the secAuthority
attribute 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 the
management domain is Default, making the secAuthorityInfo object name
secAuthority=Default. (Optional)
–t ssl_timeout
Specifies 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 information
during the configuration of the policy server. The two LDAP data formats
are minimal and standard. The valid response values are yes or no. The
default value is no. (Optional)
Chapter 2. Security Access Manager utilities
239
–w password
Specifies the password for the dn_ldap_admin. This parameter is required
when you use LDAP.
–y {yes|no}
Specifies that you can configure a second policy server to a registry server
for migration purposes. The valid response values are yes or no. The
default value is no. (Optional)
–Y restore_directory
Specifies the fully qualified path for the directory where the extracted
pdbackup files are located. This parameter is required when -y is set to yes
which specifies a second policy server to configure.
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 in
the \sbin directory under the installation directory (for example:
installation_directory\sbin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, the software shows a description of
the error.
See the IBM Security Access Manager for Web Error Message Reference. This reference
provides a list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Example
The following example configures the policy server with LDAP as the user registry
and the default management domain. SSL communication with the LDAP server is
not enabled:
ivmgrd_setup.exe -f no -d "cn=root" -w password -v yes -m password -r 7135
ivmgrd_uninst
Unconfigures the Security Access Manager policy server for Windows platforms.
Syntax
ivmgrd_uninst [–?] [–d bind_dn] –deconfig [–q] [–R] [–rspfile response_file] [–w
bind_pwd]
Description
The ivmgrd_uninst utility unconfigures the Security Access Manager policy server
on Windows platforms. You can run this utility directly from the command line.
Parameters
–?
240
Prints a usage statement. (Optional)
IBM Security Access Manager for Web Version 7.0: Command Reference
–d bind_dn
Specifies the distinguished name of the LDAP administrator. The default
value is cn=root. (Optional)
–deconfig
Unconfigures the policy server.
–q
Runs in silent mode and does not output any message boxes. Writes only
to stderr. (Optional)
–R
Specifies whether to permanently remove domain information from the
registry. Using this parameter removes all domain, user, and group
information. 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)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–w bind_pwd
Specifies the password for the bind_dn. This parameter is required when
you use LDAP.
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 in
the \sbin directory under the installation directory. For example:
installation_directory\sbin.
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error.
See the IBM Security Access Manager for Web Error Message Reference. This reference
provides a list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Example
The following example unconfigures the policy server by using the default
management domain:
ivmgrd_uninst.exe -deconfig -d cn=root -w password -R
Chapter 2. Security Access Manager utilities
241
ivrgy_tool
Updates the Security Access Manager schema on an LDAP server. It also applies
the required access control lists (ACLs) to suffixes added to the LDAP server after
policy server configuration.
This utility is not supported with the Active Directory Lightweight Directory
Service (AD LDS) user registry. See the IBM Security Access Manager for Web
Installation Guide for information about updating the AD LDS schema for use with
Security Access Manager.
Syntax
Using add-acls:
ivrgy_tool –h host_name [–p port] [–D admin_dn] [F] [–g name] –w
admin_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] –w
admin_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] [–r
response_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-acls
parameter:
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 exist
on the top-level object of a partition split, you must create the correct ACLs on
each server.
With the ivrgy_tool and schema parameter, you can update the Security Access
Manager schema on a supported LDAP server.
The schema is defined in a set of files specific to the type of LDAP server. These
files are installed during IBM Security Access Manager runtime installation. These
files provide input to the automatic schema update process when you configure
the policy server.
Typically, the schema is updated when the policy server is configured. When you
migrate an existing installation of Security Access Manager, you must upgrade the
schema on the LDAP server to the current version with the ivrgy_tool utility.
The following files contain the LDAP schema:
242
IBM Security Access Manager for Web Version 7.0: Command Reference
secschema.def
Used for Tivoli Directory Server.
nsschema.def
Used for Sun Java System Directory Server.
novschema.def
Used for Novell eDirectory Server.
An administrator can apply and update the schema with one of these files as the
LDAP Data Interchange Format (LDIF) input to the ldapmodify utility. The
ldapmodify tool is a Tivoli Directory Server utility.
When an LDAP server is not supported by Security Access Manager, you cannot
use the ivrgy_tool utility to update the schema. In these cases, an administrator
must manually update the schema on the generic LDAP server.
When manually updating the schema, administrators must use the LDIF
definitions that are defined in the nsschema.def schema file as the basis for the
schema definitions. Administrators must modify the definitions in the schema file
to meet the requirements of their generic LDAP server.
Parameters
–d
Runs in verbose output mode for debugging purposes. (Optional)
–D admin_dn
Specifies the distinguished name of the LDAP administrator. The format
for a distinguished name is like cn=root. (Optional)
–F
Forces the addition of ACLs even if the domain is not defined on this
server. This parameter is valid only with the add-acls command. The
default value is not to force the addition of ACLs. (Optional)
–g name
Specifies Daemon type [acld-server or remote-acl-user]. The default
value is acld-server. (Optional)
–h host_name
Specifies the IP address or host name of the LDAP server. Valid values
include any valid IP host name. For example:
host = libra
host = libra.example.ibm.com
When used in a Tivoli Directory Server proxy environment, the value is the
server IP address or host name where you want to set the ACLs.
–K keyfile
Specifies the fully qualified path and file name of the SSL key database.
This parameter is required only when the –Z parameter is specified. Use
the SSL key file to handle certificates in LDAP communication. The file
type can be anything, but the extension, as shown in the following
example for the policy server, is typically .kdb.
Policy server on Windows
C:\Program Files\Tivoli\Policy Director\keytab\ivmgrd.kdb
Policy server on AIX, Linux, or Solaris
/opt/PolicyDirector/keytab/ivmgrd.kdb
Chapter 2. Security Access Manager utilities
243
–N key_name
Specifies the private key name for the keyfile.
–p port
Specifies the port number of the LDAP server. Use the LDAP
server-configured port number. The default port number is 636 if Secure
Sockets Layer (SSL) is used and 389 if SSL is not used. If not specified, the
default LDAP port is used. (Optional)
In a Tivoli Directory Server proxy environment, the value is the port
number of the server.
–P keyfile_password
Specifies the password for the SSL key database. This parameter is
required only if the –Z parameter is specified.
–r response_file
Specifies the fully qualified path and file name of the response file for
silent configuration. A response file can be used for configuration. There is
no default response file name. The response file contains stanzas and
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)
–R
Removes from registry for the uninstall command. The default value is
false. (Optional)
–s suffix
Specifies the LDAP suffix under which to create the Management Domain.
–S name
Specifies the Security Master Principal Name. The default is sec_master.
(Optional)
–v version
Specifies the data model version to use for the install command. The
default value is 6. (Optional)
–w admin_password
Specifies the password of the LDAP administrator.
–Z
Specifies to use SSL for a secure LDAP connection. (Optional)
add-acls domain_name
Indicates that the required access control lists (ACLs) must be applied to
all suffixes that are defined on the LDAP server for the specified domain.
When the policy server is configured, the management domain is created
with the default name of Default. When you use the add-acls parameters
in a Tivoli Directory Server proxy environment, always apply the ACLs to
the management domain at a minimum.
This option is useful for adding access control to suffixes that are added to
the LDAP server after the policy server is configured.
schema Updates the Security Access Manager schema. Use this parameter when
you 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.
244
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error is provided.
mgrsslcfg
Creates 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] [–t
ssl_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.conf
configuration file. The value must be yes or no. The default value is yes.
(Optional)
–C compliance
Specifies the compliance value for the [ssl] ssl-compliance configuration
file setting. For example, –C sp800-131-transition. When not provided,
the setting defaults to none. (Optional) The compliance value must be one
of the following settings:
fips
Enforces FIPS 140-2 protocols and algorithms. Security Access
Manager servers and applications generate and use SHA1 with
2048-bit RSA certificates. Only TLS versions 1.0, 1.1, and 1.2 are
available. 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 with
previous Tivoli Access Manager releases.
none
Specifies that no special compliance criteria are applied to TLS
communication. Security Access Manager servers and applications
generate and use SHA1 with 2048-bit RSA certificates. This setting
option is equivalent to the previous release setting [ssl]
ssl-enable-fips = no. This value is compatible with previous
Tivoli Access Manager releases.
sp800-131-strict
Enables strict NIST SP800-131a support. This conformance
enforcement is required by some agencies and businesses that start
in the year 2014.
Chapter 2. Security Access Manager utilities
245
Security Access Manager servers and applications generate and use
SHA256 with 2048-bit RSA certificates. This value is not compatible
with prior releases of Tivoli Access Manager. Older Tivoli Access
Manager clients cannot interact with Security Access Manager 7.0
running with this compliance setting. Only TLS version 1.2 is
available; all others are disabled.
sp800-131-transition
Enables NIST SP800-131a support at the transition level. This value
is valid until the end of the year 2013. This value has fewer
restrictions than the strict enforcement. Only TLS versions 1.0, 1.1,
and 1.2 are available. SSL versions 2 and 3 are disabled and
unavailable.
Security Access Manager servers and applications generate and use
SHA256 with 2048-bit RSA certificates. This value is at a higher
level than is required by the standard and was chosen as it is a
level permitted by the strict enforcement that allows easy
migration from transition to strict. This value is not compatible
with previous Tivoli Access Manager releases. Older Tivoli Access
Manager clients cannot interact with Security Access Manager 7.0
running with this compliance setting.
suite-b-128
Enables NSA Suite B at 128-bit support. Security Access Manager
servers and applications generate and use SHA256 with 256-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Tivoli Access Manager 7.0 running with
this compliance setting. Only TLS version 1.2 is available; all others
are disabled.
suite-b-192
Enables NSA Suite B at 192-bit support. Security Access Manager
servers and applications generate and use SHA384 with 384-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Security Access Manager 7.0 running
with this compliance setting. Only TLS version 1.2 is available; all
others are disabled.
–chgcert
Renews the SSL certificate. A new public-private key pair and certificate
are created and stored in the key database.
–chgpwd
Changes the key database password. A new random password is generated
and saved in the stash file.
Before you run this action, stop the policy server.
–config
Creates new key and stash files and generates new certificates for the
policy server.
–e password_life
Sets the key file password expiration time in days. (Optional)
During a configuration action (–config), the default value is 183.
If you modify this value:
246
IBM Security Access Manager for Web Version 7.0: Command Reference
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_life
Sets the maximum certificate expiration time in days. The actual time that
is used is the lesser of this value and the number of days before the CA
certificate for the policy server expires. The CA certificate lifetime is set to
7300 days at initial configuration of the policy server. (Optional)
During a configuration action (–config), the default value is 1460.
If
v
v
v
you modify this value:
Specify 0 to use the currently configured value.
Specify 1460, if the currently configured value cannot be determined.
Otherwise, specify a valid value from 1 to 7299.
–modify
Modifies the current configuration.
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–t ssl_timeout
Specifies the SSL session timeout in seconds. The ssl_timeout value must
be in the range from 1 to 86400. During configuration, the default value is
7200. (Optional)
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\Policy Director\sbin
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
PDAcld_config
Configures the Security Access Manager authorization server.
Chapter 2. Security Access Manager utilities
247
Syntax
PDAcld_config [–a adminid] [–D domain] [–f response_file] [–h host] –H host [–i
instance] [–k key_file] [–K key_file_password] [–L port] [–N key_file_label] [–O
port] –p password [–P port] [–r port] [–s silent{yes|no}] [–Z {yes|no}]
Description
The PDAcld_config utility configures the Security Access Manager authorization
server on AIX, Linux, and Solaris platforms. You can run this utility directly from
the command line.
Parameters
–a adminid
Specifies the ID for the Security Access Manager administrator of the
management domain. The default administrator ID is sec_master.
(Optional)
–D domain
Specifies the domain name. The default value is Default, which indicates
the management domain. (Optional)
–f response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–h host
Specifies the valid host name or valid IP of the system on which Policy
server runs. The default value is the host name of the local system.
(Optional)
–H host
Specifies the fully qualified name or valid IP of the host system for the
authorization server.
–i instance
Specifies the authorization server instance name. The default authorization
server instance name is always empty. Enter a unique name to configure
each additional authorization server. Instance names can contain characters
a-z, 0-9, -, and _. An instance name cannot begin with a hyphen (-)
character. (Optional)
–k key_file
Specifies the fully qualified file name of the client-side key file. This key
file holds the server-side certificates that are used in secure
communication. This parameter is required when -Z is set to yes, which
means that SSL communication is enabled. (Optional)
–K key_file_password
Specifies the existing password that is associated with the specified
key_file. This password was set when the key file was created. This
parameter is required if -Z is set to yes, which means that SSL
communication is enabled. (Optional)
248
IBM Security Access Manager for Web Version 7.0: Command Reference
–L port
Specifies the Secure Sockets Layer (SSL) port number of the LDAP server.
Use the LDAP server-configured port number. The default port number is
636. (Optional)
–N key_file_label
Specifies the server certificate label name that is in the key_file. The label
was 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 SSL
communication is enabled. (Optional)
–O port
Specifies the administration request port. The default port is 7137.
(Optional)
–p password
Specifies the password for the Security Access Manager administrator ID,
adminid.
–P port
Specifies the authorization request port number. The default port number
is 7136. (Optional)
–r port
Specifies 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 to
yes, the utility runs in silent mode. If set to no, the utility runs in
interactive mode. (Optional)
–Z {yes|no}
Specifies whether to enable SSL communication between the authorization
server and the registry server. The valid responses are yes or no. The
default value is no. (Optional)
Availability
This utility is in /opt/PolicyDirector/sbin, the default installation directory on
AIX, Linux, and Solaris operating systems.
Return codes
0
The utility ran successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error. See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Example
The following example configures the Security Access Manager Authorization
Server by using the default management domain. SSL communication with the
LDAP 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
Chapter 2. Security Access Manager utilities
249
PDAcld_unconfig
Unconfigures the Security Access Manager authorization server.
Syntax
PDAcld_unconfig [–a adminid] [–f response_file] [–h host] [–i instance] –p
password [–r port] [–s {yes|no}]
Description
The PDAcld_unconfig utility unconfigures the Security Access Manager
authorization server on AIX, Linux, and Solaris platforms. You can run this utility
directly from the command line.
Parameters
–a adminid
Specifies the identifier for the Security Access Manager administrator of the
management domain. The default administrator ID is sec_master.
(Optional)
–f response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–h host
Specifies the host name that is used by the policy server to contact this
server. The default value is the host name of the local system. (Optional)
–i instance
Specifies the authorization server instance name. The default authorization
server instance name is always empty. Enter a unique name to unconfigure
each additional authorization server. Instance names can contain characters
a-z, 0-9, -, and _. An instance name cannot begin with a hyphen (-)
character. (Optional)
–p password
Specifies the password for the Security Access Manager administrator ID,
adminid.
–r port
Specifies 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 to
yes, the utility runs in silent mode. If set to no, the utility runs in
interactive mode. (Optional)
Availability
This utility is in /opt/PolicyDirector/sbin, the default installation directory on
AIX, Linux, and Solaris operating systems.
250
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The utility ran successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error. See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
The following example unconfigures the Security Access Manager authorization
server:
./PDAcld_unconfig -a sec_master -p password -h libra.example.ibm.com -r 7135 -s yes
pdadmin_host
Generates configuration files that allow a single instance of the IBM Security
Access 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 each
policy 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 the
pdadmin command and the ivadmin_context_create3() administration API. Use the
pdadmin command option -I to specify the pd-hostname.conf file that you want to
use.
When the tool creates the /opt/PolicyDirector/etc/pd-hostname.conf file, a new
configuration item is added to the .conf file: [ssl] pdadmin-standalone = yes.
Use only one generated pd-hostname.conf per API process. A single Security
Access Manager API application cannot communicate simultaneously to multiple
policy servers.
You are not required to configure the IBM Security Access Manager runtime for
this feature to operate; however, then the PolicyDirector/etc/routing file is not
created. You can manually create one, or, if no routing file is present, then by
default NOTICE and NOTICE_VERBOSE messages are discarded (routed to DISCARD:).
Other types of messages are sent to standard error (routed to STDERR:). You can
override these defaults by setting environment variables such as SVC_FATAL to
specify where to route various types of messages.
Tivoli Common Directory for logging is not set by pdadmin_host. To enable logging
in the Tivoli Common Directory location, manually update the generated
Chapter 2. Security Access Manager utilities
251
configuration file. See the [pdrte] tivoli_common_dir setting in the
pd-hostname.conf file.
Parameters
–h hostname
Specifies the host name of the system that has a policy server.
Removes the previous configuration for a policy server host. (Optional)
–d
–r port
Specifies the port on which the policy server is listening. When not
provided, the default is 7135. (Optional)
–c certfile
Specifies the file that contains the certificate authority certificate for the
policy server. When not provided, the utility contacts the policy server for
the value. For security purposes, you can choose an alternate secure
method to place the file on the system before you use this option.
(Optional)
–l domain
Specifies the default domain to use with the policy server. When not
provided, the utility uses Default. If an empty string is provided, the tool
contacts the policy server to request the management domain name.
(Optional)
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/PolicyDirector/bin/
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 in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
pd_start
Stops, starts, and restarts servers on AIX, Linux, and Solaris operating systems.
Also displays server status.
Note: On Windows operating systems, use the Services folder.
252
IBM Security Access Manager for Web Version 7.0: Command Reference
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 manually
start, 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 the
command prompt is returned.
On AIX, Linux, and Solaris operating systems, server processes are normally
enabled and disabled through scripts that run at system startup and during system
shutdown. This technique is useful when you must customize an installation or
troubleshoot a problem.
To individually start the server process on the local AIX, Linux, or Solaris
operating system, enter the process name from the command line, as follows:
For the policy server
installation_directory/bin/pdmgrd
For the policy proxy server
installation_directory/bin/pdmgrproxyd
For each authorization server instance
installation_directory/bin/pdacld -routing instance-pdacld_routing
-config installation_directory/etc/instance-ivacld.conf
where instance- is the name of the authorization server instance (excluding the
trailing '-' character). For the empty instance name, do not add the instance-. For
the empty instance name, the -routing and -config parameters are optional.
Start the server processes in the following sequence:
1. Policy server
2. Policy proxy server
3. One or more authorization server instances
Stop the server processes in the following sequence:
1. All authorization server instances
2. Policy proxy server
3. Policy server
Note: To control the server processes in a Windows environment, use the Services
Control Panel.
Parameters
restart Stops and restarts all the Security Access Manager server processes on the
local computer.
start
Starts the Security Access Manager server processes that are not currently
running on the local system.
status Displays the state of each of the Security Access Manager server processes.
Chapter 2. Security Access Manager utilities
253
stop
Stops the Security Access Manager server processes that are running on the
local system.
Availability
By default on AIX, Linux, and Solaris operating systems, this utility is in the
/opt/PolicyDirector/bin directory.
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
v 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 the
following command:
pd_start status
Sample output:
Server
Enabled
Running
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
254
IBM Security Access Manager for Web Version 7.0: Command Reference
Instance
pdbackup –?
Description
Use the pdbackup utility to back up and restore Security Access Manager data. As
an alternative to a restore action, you can extract all archived files into a single
directory. This utility is most commonly used for backing up, restoring, and
extracting Security Access Manager component files.
Note: Before performing backup and restore actions, stop the Security Access
Manager servers on the target machine to ensure a consistent snapshot, or
replacement, of files. Stopping the Security Access Manager servers prevents the
servers from updating, and possibly overwriting, the files that you want to backup
or 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. If
you encounter this issue, use either of the following approaches to continue
restoring 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 for
parameters cannot be shortened.
–?
Displays the syntax and an example for this utility.
–action [backup|restore|extract]
Specifies to action to be performed. This parameter supports one of the
following values:
backup
Backs up the data, service information, or migration information to
an archive file. The archive file has a tar extension on AIX, Linux,
and Solaris operating systems and a dar extension on Windows
operating systems.
extract Extracts the data from an archive file to a specified directory. This
action is used during a two-machine migration only.
restore
Restores the data from the archive file.
–file filename
Specifies the name of the archive file. When this parameter is required, its
value must be the fully qualified name of the archive file. When this
parameter is optional, its value must be the name of the archive file only.
For the extract and restore actions, this parameter is required. For the
backup action, this parameter is optional.
Chapter 2. Security Access Manager utilities
255
When using the backup action, specifies a file name other than the default
name. The default name is the name of the service list file with a date and
time of the file creation. On AIX, Linux, and Solaris operating systems, the
default file name is list_file_ddmmmyyyy.hh_mm.tar. On Windows
operating systems, the default file name is
list_file_ddmmmyyyy.hh_mm.dar.
–list list_file
Specifies the fully qualified name of the list file. The list file is an ASCII
file that contains the information about the various files and data to back
up. These files are located in the /etc directory under the
component-specific installation directory. The following list contains the
default file name and location of each component-specific list file by
operating system. The assumption is that the default installation directory
was 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 information
On AIX, Linux, and Solaris operating systems:
/opt/PolicyDirector/etc/pdinfo.lst
On Windows operating systems:
C:\Program Files\Tivoli\Policy Director\etc\pdinfo.lst
WebSEAL 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 information
On AIX, Linux, and Solaris operating systems:
/opt/pdweb/etc/pdinfo-amwebbackup.lst
On Windows operating systems:
C:\Program Files\Tivoli\pdweb\etc\pdinfoamwebbackup.lst
Plug-in for web servers data
On AIX, Linux, and Solaris operating systems:
/opt/pdwebpi/etc/pdwebpi.lst
On Windows operating systems:
C:\Program Files\Tivoli\pdwebpi\etc\pdwebpi.lst
Plug-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 path
Specifies the target directory for the specified action. This parameter is
required with the extract action, but is optional with the backup and
restore actions.
When specified with the backup action, specifies the target directory for
the archive file. When not specified, the command uses the default
directory for the component. The following list contains the default
directory for each component by operating system:
256
IBM Security Access Manager for Web Version 7.0: Command Reference
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 are
extracted 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 archive
file are restored. By default, this path is one used during the backup
process. On Windows operating systems, the restore process does not
support the –path parameter. On Windows operating systems, the files
are restored to their original directory.
–usage
Displays 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 is
located in the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web: Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
v The following example backs up the Security Access Manager data on a
Windows operating system. The example uses default values for the archive
files:
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, the
pdbackup.lst_22dec2011.10_22.dar archive file is created and stored in the
C:\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.
Chapter 2. Security Access Manager utilities
257
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, the
pdinfo-amwebbackup.lst_22dec2011.10_22.tar archive file is created and stored
in 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 the
backup process.
v The following example restores the pdbackup.lst_22dec2011.10_22.dar archive
file 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, files
cannot be restored to another location.
v The following example restores the amwebbackup.lst_22dec2011.10_22.tar
archive file that is stored in the /var/pdbackup directory to the /amwebtest
directory:
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.tar
archive 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
pdconf
Displays 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 Manager
configuration file. You can run this utility directly from the command line. This
utility 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 Security
Access Manager for Web Installation Guide.
258
IBM Security Access Manager for Web Version 7.0: Command Reference
Parameters
–f file
Specifies the name of a configuration file. For example, pd.conf. This name
must have a fully qualified path name, unless you are already working in
the directory where the file is located.
–v
Displays the version number of the pdconf utility. If this option is
specified, all other valid options are ignored. (Optional)
The following example is the output that you might see when you use this
option:
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 required
information to complete the command. Command and corresponding
arguments include the following sets:
addentry [–obfuscate] stanza entry value
Adds an entry to the specified stanza in the configuration file.
addstanza stanza
Adds a stanza to the specified configuration file.
deleteentry stanza entry
Deletes an entry in the specified stanza in the configuration file.
deletestanza stanza
Deletes a stanza in the specified configuration file.
getentry stanza entry
Displays the value of an entry for the specified stanza in the
configuration file.
getstanza stanza
Displays the entries of a stanza and the associated values for the
configuration file.
setentry [–obfuscate] stanza entry value
Sets the value of an entry for the specified stanza in the
configuration file.
entry
Specifies the entry in the specified configuration file and
stanza.
–obfuscate
Identifies that a value (for example, a password) is not
stored in clear text. When you use the -obfuscate
parameter, an additional file, called file.obf, is created to
store the obfuscated value.
stanza Specifies the name of a stanza in the configuration file.
value
Specifies the configuration value for the specified entry. If
the value is specified as a '-', the value is read from
standard input (stdin).
Availability
The pdconf utility is in the following directory by default:
Chapter 2. Security Access Manager utilities
259
AIX, Linux, and Solaris
/opt/PolicyDirector/sbin/
Windows
C:\Program Files\Tivoli\Policy Director\sbin\
When you select an installation directory other than the default, this utility is in
the sbin directory under the installation directory. For example, on Windows:
installation_directory\sbin.
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error displays.
See the IBM Security Access Manager for Web Error Message Reference. This reference
provides a list of the Security Access Manager error messages by decimal or
hexadecimal codes.
Examples
v 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 manager
master-host =
master-port = 7135
management-domain = Default
v The following example retrieves the manager stanza from the pd.conf
configuration file on Windows.
C:\Program Files\Tivoli\Policy Director\sbin\pdconf -f "C:\Program Files\Tivoli\
Policy Director\etc\pd.conf" getstanza manager
master-host =
master-port = 7135
management-domain = Default
pdconfig
Configures and unconfigures Security Access Manager components.
Syntax
pdconfig
Note: Before you run the pdconfig utility, you must set the PATH environment
variable 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 the
topics about installing IBM Java Runtime in the IBM Security Access Manager for
Web Installation Guide for information about setting this environment variable.
Description
When you configure Security Access Manager with the pdconfig utility, you are
prompted for several options. Use the IBM Security Access Manager for Web
Installation Guide for option descriptions to help you provide correct values.
260
IBM Security Access Manager for Web Version 7.0: Command Reference
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 close
the configuration utility.
If you must comply with security standards such as FIPS 140-2, NIST SP800-131a
or 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 the
ssl-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 configure
WebSphere Application Server to enable the same security standard. If the security
standard settings do not match, Web Portal Manager configuration fails. To enable
the same security setting in WebSphere Application Server, see
http://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
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/PolicyDirector/bin
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 in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
pdjrtecfg
Configures or unconfigures IBM Security Access Manager Runtime for Java.
Syntax
Configure in full mode
Chapter 2. Security Access Manager utilities
261
pdjrtecfg –action config –host policy_server_host [–port
policy_server_port] [–java_home jre_home] [–domain domain_name]
[–config_type full] [–enable_tcd [–tcd path]][–cfgfiles_path
path_to_config_files [–alt_config]]
Configure in stand-alone mode
pdjrtecfg –action config –config_type standalone [–cfgfiles_path
path_to_config_files [–alt_config]]
Configure in interactive mode
pdjrtecfg –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 Java
applications to manage and use Security Access Manager security.
The pdjrtecfg utility adds or updates Security Access Manager .jar files in the
jre_home\lib\ext directory and backs up the existing files. The utility does not
modify any other .jar files in this directory.
More than one Java runtime can exist on the same computer. Use the pdjrtecfg
utility to configure IBM Security Access Manager Runtime for Java independently
to 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 location
outside of the WebSphere JRE. With WebSphere Application Server, version 8, the
IBM Security Access Manager Runtime for Java configuration files and .jar files
are in the WAS_Home/tivoli/tam directory.
You can configure IBM Security Access Manager Runtime for Java into WebSphere
Application 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
262
IBM Security Access Manager for Web Version 7.0: Command Reference
v Interactively with either pdconfig or pdjrtecfg -action config -interactive.
When pdjrtecfg runs with -interactive, the utility detects WebSphere
Application Server, version 8, and automatically provides the -cfgfiles_path
and -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 Java
component.
name
Retrieves the IBM Security Access Manager Runtime for Java
component package name and returns the name value to the
pdconfig utility. Only pdconfig uses this parameter. Do not use this
parameter from the command line.
status Determines and returns the IBM Security Access Manager Runtime
for Java component configuration status information to the
pdconfig utility. Only pdconfig uses this parameter. Do not use this
parameter from the command line.
unconfig
Unconfigures the IBM Security Access Manager Runtime for Java
component.
–alt_config
Specifies either to add the PD.jar to a specified directory or to update an
existing file. The –cfgfiles_path path_to_config_files option specifies a
directory 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 under
the WebSphere Application Server JRE directory.
WebSphere Application Server, version 8, adds the WAS_HOME/tivoli/tam
directory to its java.ext.dirs property for use with Security Access
Manager. To use the new directory, you must specify WAS_HOME/tivoli/tam
for the –cfgfiles_path path_to_config_files parameter along with
–alt_config so that PD.jar is available to the WebSphere Application
Server JVM.
–cfgfiles_path path_to_config_files
Specifies an alternative location for the PolicyDirector directory that
contains the IBM Security Access Manager Runtime for Java configuration
files. Typically, the PolicyDirector directory is at the root of the JRE
directory that is being configured. (See -java_home.) (Optional)
If you use this option, then applications that use the PD.jar API in this
Java Runtime must set the Java System property, pd.cfg.home with the
same 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 the
WebSphere Application Server JRE directory.
Chapter 2. Security Access Manager utilities
263
WebSphere Application Server, version 8, stores Security Access Manager
configuration 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 the
PD.jar file. The PolicyDirector subdirectory contains the PD.properties
file.
For example, if you install WebSphere Application Server, version 8, at a
location 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 the
generation of the server-side certificate for the policy server.
standalone
Completes all the required configuration steps, except for the
generation of the server-side certificate for the policy server. With
this configuration, you can use the Security Access Manager Java
APIs without requiring a policy server. Typically, this configuration
is used to configure a Security Access Manager development
environment.
–domain domain_name
Specifies the local domain name for the Java runtime. A local domain is a
Security Access Manager secure domain that is used by programs when no
explicit domain is specified. If you do not specify this parameter, the local
domain defaults to the management domain. (Optional)
–enable_tcd [–tcd path]
Enables Tivoli Common Directory (TCD) logging, if it is not already
enabled. It also specifies the fully qualified path location for common
logging. When TCD is enabled, all Security Access Manager message log
files are placed in this common location. (Optional)
–help [options]
Provides online help for one or more utility options. It shows descriptions
of the valid command-line options. Alternatively, it provides online help
about a specific command-line parameter. (Optional)
–host policy_server_host
Specifies the Security Access Manager policy server host name. Valid
values include any valid IP host name. Examples:
host = libra
host = libra.example.ibm.com
–interactive
Specifies the interactive mode in which the user is prompted for
configuration information for the IBM Security Access Manager Runtime
for Java component. If not specified, the configuration program runs in
non-interactive (silent) mode. (Optional)
–java_home jre_path
Specifies the fully qualified path to the Java runtime, such as the directory
that ends in JRE. If you do not specify this parameter, the home directory
264
IBM Security Access Manager for Web Version 7.0: Command Reference
for the JRE in the PATH statement is used. If the home directory for the
JRE is not in the PATH statement, this utility fails. (Optional)
During unconfiguration, you can specify the all parameter that
unconfigures all configured JREs.
–operations
Prints all the valid command-line options. (Optional)
–port policy_server_port
Specifies the Security Access Manager policy server port number. The
default value is 7135. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the silent configuration
response file. You can use a response file for configuration. There is no
default response file name. (Optional)
The response file contains parameter=value pairs. The following rules
apply 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
or
java_home=c:/Program Files/IBM/Java60
v The path must not include quotation marks.
–usage Shows the syntax for this utility. (Optional)
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\Policy Director\sbin
When you select an installation directory other than the default, this utility is in
the /sbin directory under the installation directory. For example,
installation_directory/sbin.
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided. For example,
0x15c3a00c. See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
v The following example configures the IBM Security Access Manager Runtime for
Java component:
Chapter 2. Security Access Manager utilities
265
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 Runtime
for Java component:
pdjrtecfg -action unconfig -java_home "C:\Program Files\IBM\Java60\jre"
v The following example uses command-line configuration of WebSphere
Application 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
pdjservicelevel
Returns the service level of installed Security Access Manager files that use the
IBM 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 returns
the name 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 written
to standard output. Generally, ASCII files and other such files do not have service
levels.
Note: For this utility to determine the service level of a JAR file, the Java jar
utility must exist in the system PATH statement. When the jar utility cannot be
found, the service level that is reported for all JAR files is "Unknown".
Parameters
directory
Specifies the fully qualified name of the directory.
Availability
This utility is installed as part of the IBM Security Access Manager Runtime for
Java package. It 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\Policy Director\sbin
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
266
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
PDMgr_config
Configures the Security Access Manager policy server for AIX, Linux, and Solaris
platforms.
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}] [–J
standby_server_conf_file] [–k key_file] [–K key_file_password] [–l
certificate_life] [–L port] –m password [–N key_file_label] [–r port] [–s
silent{yes|no}] [–S ldap_suffix] [–v use_minimal_data_format {yes|no}] –w
password [–Z use_ssl {yes|no}]
Description
The PDMgr_config utility configures the Security Access Manager policy server on
AIX, Linux, and Solaris platforms. You can run this utility directly from the
command line.
Parameters
–C compliance
Specifies the compliance value for the [ssl] ssl-compliance configuration
file setting. (Optional) If not specified, this value defaults to the [ssl]
ssl-compliance value that is currently set in the pd.conf file. The
compliance value must be one of the following settings:
fips
Enforces FIPS 140-2 protocols and algorithms.
Security Access Manager servers and applications generate and use
SHA1 with 2048-bit RSA certificates. Only TLS versions 1.0, 1.1,
and 1.2 are available. 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 with previous Tivoli Access Manager releases.
none
Specifies that no special compliance criteria are applied to TLS
communication. Security Access Manager servers and applications
generate and use SHA1 with 2048-bit RSA certificates. This setting
option is equivalent to the previous release setting [ssl]
ssl-enable-fips = no. This value is compatible with previous
Tivoli Access Manager releases.
sp800-131-strict
Enables strict NIST SP800-131a support. This conformance
enforcement is required by some agencies and businesses that start
in the year 2014.
Chapter 2. Security Access Manager utilities
267
Security Access Manager servers and applications generate and use
SHA256 with 2048-bit RSA certificates. This value is not compatible
with prior releases of Tivoli Access Manager. Older Tivoli Access
Manager clients cannot interact with Security Access Manager 7.0
running with this compliance setting. Only TLS version 1.2 is
available; all others are disabled.
sp800-131-transition
Enables NIST SP800-131a support at the transition level. This value
is valid until the end of the year 2013. This value has fewer
restrictions than the strict enforcement. Only TLS versions 1.0, 1.1,
and 1.2 are available. SSL versions 2 and 3 are disabled and
unavailable.
Security Access Manager servers and applications generate and use
SHA256 with 2048-bit RSA certificates. This value is at a higher
level than is required by the standard and was chosen as it is a
level permitted by the strict enforcement that allows easy
migration from transition to strict. This value is not compatible
with previous Tivoli Access Manager releases. Older Tivoli Access
Manager clients cannot interact with Security Access Manager 7.0
running with this compliance setting.
suite-b-128
Enables NSA Suite B at 128-bit support. Security Access Manager
servers and applications generate and use SHA256 with 256-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Tivoli Access Manager 7.0 running with
this compliance setting. Only TLS version 1.2 is available; all others
are disabled.
suite-b-192
Enables NSA Suite B at 192-bit support. Security Access Manager
servers and applications generate and use SHA384 with 384-bit
ECDSA certificates. This value is not compatible with previous
Tivoli Access Manager releases. Older Tivoli Access Manager
clients cannot interact with Security Access Manager 7.0 running
with this compliance setting. Only TLS version 1.2 is available; all
others are disabled.
–d dn_ldap-admin
Specifies the distinguished name of the LDAP administrator. The default
value is cn=root. (Optional)
–D ldap_dn
The name of the management domain. Configuring the policy server in the
management domain creates the initial administrative domain. The
management domain name must be unique within the LDAP server. The
name must be an alphanumeric string up to 64 characters long and not
case-sensitive. The default value is Default. (Optional)
–f response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
268
IBM Security Access Manager for Web Version 7.0: Command Reference
–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 to
use the appropriate FIPS secure communications protocol. The valid
responses 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 policy
server might be configured for standby purposes only. Valid values are yes
or no. The default value is no. This parameter applies only to the AIX
platform. (Optional)
–J standby_server_conf_file
The fully qualified location of the ivmgrd.conf file, which is the existing
primary policy server configuration file. For example, if the shared
directory is /share, enter /share/PolicyDirector/ivmgrd.conf. This
parameter applies only to the AIX platform. (Optional)
–k key_file
Specifies the fully qualified file name of the client-side key file. This key
file holds the server-side certificates that are used in secure
communication. This parameter is required when use_ssl is set to yes,
which enables SSL communication. (Optional)
–K key_file_password
Specifies the password that is associated with the specified key_file. This
password was set when the key file was created. This parameter is
required if use_ssl is yes. (Optional)
–l certificate_life
Specifies the number of days that the SSL certificate file is valid. The
default number of days is 1460. (Optional)
–L port
Specifies the Secure Sockets Layer (SSL) port number of the LDAP server.
Use the LDAP server-configured port number. The default port number is
636. (Optional)
–m password
Specifies the password for the Security Access Manager administrator ID.
The default administrator ID is sec_master.
–N key_file_label
Specifies the server certificate label name that is in the key_file. This label
was 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 SSL
communication. (Optional)
–r port
Specifies 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 to
yes, the utility runs in silent mode. If set to no, the utility runs in
interactive mode. (Optional)
–S ldap_suffix
The software creates the secAuthorityInfo object entry on the LDAP server
when you create:
v ASecurity Access Manager domain.
Chapter 2. Security Access Manager utilities
269
v The initial management domain.
This object represents the Security Access Manager domain and is named
by using the secAuthority attribute with 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 the
management domain is Default, making the secAuthorityInfo object name
secAuthority=Default. (Optional)
–v use_minimal_data_format {yes|no}
When you configure the policy server, you can select the LDAP data
format for user and group tracking information. The two LDAP data
formats are minimal and standard. The valid responses are yes or no. The
default value is yes. (Optional)
–w password
Specifies the password for the dn_ldap_admin.
–Z use_ssl {yes|no}
Specifies whether to enable SSL communication between the Security
Access Manager policy server and the registry server. The valid responses
are yes or no. The default value is no. (Optional)
Availability
This utility is in /opt/PolicyDirector/sbin, the default installation directory on
AIX, Linux, and Solaris operating systems.
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
0
The utility ran successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error. See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
The following example configures the Security Access Manager policy server by
using LDAP as the user registry and the default management domain. SSL
communication 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_unconfig
Unconfigures the Security Access Manager policy server on AIX, Linux, and Solaris
platforms.
Syntax
PDMgr_unconfig [–d dn_ldap-admin] [–f response_file] [–R remove_registry
{yes|no}] [–s silent {yes|no}] [–w password]
270
IBM Security Access Manager for Web Version 7.0: Command Reference
Description
The PDMgr_unconfig utility unconfigures the Security Access Manager policy server
on AIX, Linux, and Solaris platforms. You can run this utility directly from the
command line.
Parameters
–d dn_ldap-admin
Specifies the distinguished name of the LDAP administrator. The default
value is cn=root. (Optional)
–f response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–R remove_registry {yes|no}
Specifies whether or not to permanently remove domain information from
the registry. (Optional)
If set to yes
If set to no
All domain, user, and group information is
removed
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 to
yes, the utility runs in silent mode. If set to no, the utility runs in
interactive mode. (Optional)
–w password
Specifies the password for the dn_ldap_admin. This parameter is required
when you use an LDAP user registry.
Availability
This utility is in /opt/PolicyDirector/sbin, the default installation directory on
AIX, Linux, and Solaris operating systems.
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
0
The utility ran successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error. See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Chapter 2. Security Access Manager utilities
271
Examples
The following example unconfigures the Security Access Manager policy server
and removes all domain, user, and group information from the registry:
./PDMgr_unconfig -d "cn=root" -w password -R yes -s yes
pdproxycfg
Configures or unconfigures a policy proxy server.
Syntax
pdproxycfg –action config [–admin_id administrator_id] –admin_pwd
administrator_password [policysvr policy_server_name] [–admin_port
policy_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 command
line. The utility can be run in interactive mode, command-line mode, or response
file mode. In interactive mode, the user is prompted to supply the necessary
values. In command-line mode, all options can be specified from the command
line.
In response file mode, the utility obtains the necessary parameters from the
response file. When the response file does not contain a necessary parameter, the
user 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
272
Retrieves the policy proxy server name and returns the name value
to the pdconfig utility. This parameter is used only by the pdconfig
utility. Do not use this parameter from the command line.
IBM Security Access Manager for Web Version 7.0: Command Reference
status Returns the status value to the pdconfig utility. This parameter is
used only by the pdconfig utility. Do not use this parameter from
the command line.
unconfig
Unconfigures a policy proxy server.
–admin_id administrator_id
Specifies the name of the administrative user in the Default domain. The
policy proxy server represents the policy server. Therefore, the policy proxy
server is able to represent all the defined domains at the policy server. The
policy proxy server must be configured into the Default domain. The
default value is sec_master. (Optional)
–admin_port policy_server_port
Specifies the port number of the Security Access Manager policy server.
The default port number is 7139. (Optional)
–admin_pwd administrator_password
Specifies the password of the administrative user. The default value is
sec_master.
–help [options]
Returns online help for one or more utility options by displaying
descriptions of the valid command-line options. Alternatively, provides
online help about a specific command-line option. (Optional)
–host proxy_server_name
Specifies the host name that is used by the policy server to contact the
policy proxy server. Valid values include any valid IP host name. For
example:
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 the
administrator (yes) or silently (no). (Optional)
–key_label label
Specifies the label of the SSL LDAP client certificate. This parameter is
used only when SSL communication is enabled between the policy proxy
server and an LDAP server. (Optional)
–key_pwd password
Specifies the password of the LDAP SSL key file. This parameter is
required only when SSL communication is enabled between the policy
proxy server and the LDAP server. (Optional)
–keyfile keyfile
Specifies the LDAP SSL key file. This parameter is required only when SSL
communication is enabled between the policy proxy server and an LDAP
server. (Optional)
–operations
Prints all the valid command-line options. (Optional)
-policysvr policy_server_name
Specifies the host name of the Security Access Manager policy server or
other policy proxy server that can be used for configuration and
unconfiguration. (Optional)
Chapter 2. Security Access Manager utilities
273
–proxy_port proxy_server_port
Specifies the port on which the policy proxy server listens for incoming
proxy requests. The default value is 7138. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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
v The path must not include quotation marks.
–ssl_enabled {yes|no}
Specifies whether to enable SSL communication between the policy proxy
server and the LDAP server. Valid indicators are yes or no. (Optional)
–ssl_port ssl_port
The port number on which SSL communication takes place between the
policy proxy server and the LDAP server. This parameter is used only
when SSL communication is enabled between the policy proxy server and
an LDAP server. (Optional)
–usage Displays the syntax for this utility. (Optional)
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\Policy Director\sbin
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
274
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
IBM Security Access Manager for Web Version 7.0: Command Reference
Example
The following example configures a policy proxy server with SSL communication
enabled 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_config
Configures the Security Access Manager Runtime on AIX, Linux, and Solaris
platforms.
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] [–l
local_domain] [–P port] [–r port] [–R dnforaccess] [–s silent {yes | no}] [–S
local_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 command
line.
Parameters
–c certificate
Specifies the name of the policy server base-64 encoded, self-signed
certificate. For example, /var/PolicyDirector/keytab/pdcacert.b64
If the certificate file is not specified, the certificate is downloaded from the
Security Access Manager policy server. (Optional)
–d ad_domain
Specifies 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 and
the registry server. The valid responses are yes and no. The default value is
no. (Optional)
–f key_file
Specifies the fully qualified file name of the client-side key file. The key file
holds the server-side certificates that are used in secure communication.
This parameter is required when use_ssl is set to yes, which means that
SSL communication is enabled. (Optional)
–F key_file_password
Specifies the existing password that is associated with the specified
Chapter 2. Security Access Manager utilities
275
key_file. This password was set when the key file was created. This
parameter is required if use_ssl is set to yes. (Optional)
–g key_file_label
Specifies the server certificate label name that is in the key_file. The label
was set when server certificate was imported in client-side key file. This
parameter is required when use_ssl is set to yes, which means that SSL
communication is enabled. (Optional)
–G ad_multiple_domain {yes|no}
Configures Security Access Manager in Active Directory multiple domain
environment. The valid responses are yes and no. The default value is no.
(Optional)
–h policy_server_host_name
Specifies the host name of the Security Access Manager policy server. This
parameter is required if local_policy_server is no. You can specify any
valid IP host name. For example: libra.example.ibm.com. (Optional)
–H LDAP_server_host_name
Specifies the IP address or host name of the LDAP server. You can specify
any valid IP host name. For example:
host = libra
host = libra.dallas.ibm.com
–i response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–l local_domain
Specifies 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 by
programs when no explicit domain is specified. If the parameter is not
specified, the local domain defaults to the management domain.
A valid local domain name is an alphanumeric, case-sensitive string. Valid
characters are a-z, 0-9, -, and _.
–P port
Specifies the port number of the LDAP server. Use the LDAP
server-configured port number. The default port number is 636 if Secure
Sockets Layer (SSL) is used and 389 if SSL is not used. (Optional)
–r port
Specifies the port number for the Security Access Manager Policy server.
This parameter is required if local_policy_server is no. The default value
is 7135. (Optional)
–R dnforaccess
Specifies the distinguished name (DN) for the data location on the Active
Directory server that stores Security Access Manager data.
The parameter is required if ad_multiple_domain is no. If
ad_multiple_domain is yes, then the default value is the value of
ad_domain.
276
IBM Security Access Manager for Web Version 7.0: Command Reference
–s silent {yes | no}
Specifies silent configuration. The valid responses are yes or no. If the
value is yes, the utility runs in silent mode. If the value is no, the utility
runs in interactive mode. (Optional)
–S local_policy_server {yes | no}
Indicates whether the policy server is installed on the same computer. The
valid 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 Access
Manager. The valid responses are ldap and active_directory_ldap.
–T tivoli_common_directory
Enables Tivoli Common Directory logging and specifies the fully qualified
path location for common logging. When Tivoli Common Directory is
enabled, all of the Security Access Manager message log files are placed in
this common location. (Optional)
–u ad_alt_upn {yes | no}
Security Access Manager supports an email address (alternative format) of
the userPrincipalName attribute of the Active Directory user object as its
user ID. The valid responses are yes and no. If set to no, only the default
format of the userPrincipalName can be used as the Security Access
Manager user ID. The default value is no. (Optional)
–v ad_gc_server
Security Access Manager supports an email address (alternative format) of
the userPrincipalName attribute of the Active Directory user object as its
user ID. Specify the Global Catalog server host name, such as
gcserver.us.ibm.com, to enable the support.
If not specified, only the default format of the userPrincipalName can be
used as the Security Access Manager user ID. (Optional)
Availability
This utility is in /opt/PolicyDirector/sbin, the default installation directory on
AIX, Linux, and Solaris operating systems.
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
0
The utility ran successfully.
1
The utility failed. When a utility fails, the software a description of the
error. See the IBM Security Access Manager for Web Error Message Reference.
This reference provides a list of the Security Access Manager error
messages by decimal or hexadecimal codes.
Examples
The following example configures the Security Access Manager Runtime by using
LDAP 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
Chapter 2. Security Access Manager utilities
277
PDRTE_unconfig
Unconfigures the Security Access Manager Runtime on AIX, Linux, and Solaris
platforms.
Syntax
PDRTE_unconfig
Description
The PDRTE_unconfig utility unconfigures the Security Access Manager Runtime on
AIX, Linux, and Solaris platforms. You can run this utility directly from the
command line. The utility does not require any parameters.
Availability
This utility is in /opt/PolicyDirector/sbin, the default installation directory on
AIX, Linux, and Solaris operating systems.
When an installation directory other than the default is selected, this utility is in
the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
0
The utility ran successfully.
1
The utility failed. When a utility fails, the software displays a description
of the error. See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal 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 the
Security Access Manager Runtime package.
Note: This utility is for use by support personnel.
Syntax
pdservicelevel directory
Description
The pdservicelevel utility recursively scans the specified directory and returns the
name and service level for each file to standard output. Only executable programs,
shared libraries, archives, and other such files have a service level.
278
IBM Security Access Manager for Web Version 7.0: Command Reference
If the service level for a file cannot be determined, the string "Unknown" is written
to standard output. Generally, ASCII files and other such files do not have service
levels.
Note: For this utility to determine the service level of a JAR file, the Java jar
utility must exist in the system PATH statement. When the jar utility cannot be
found, the service level that is reported for all JAR files is "Unknown".
Parameters
directory
Specifies the fully qualified name of the directory.
Availability
This utility is installed as part of the Security Access Manager Runtime package. It
is located 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\Policy Director\sbin
When an installation directory other than the default is selected, this utility is
located in the /sbin directory under the installation directory (for example,
installation_directory/sbin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web: Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
pdsmsclicfg
Configures the command-line administration utility for the session management
server.
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
Chapter 2. Security Access Manager utilities
279
Description
The pdsmsclicfg utility configures or unconfigures the session management server
command-line administration utility. A log of the configuration progress is written
to 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 a
configured aznapi application. The program prompts the user to specify the
location of the web service. The location of the web service is defined by a host
name and port that are separated by a semicolon.
The user can specify multiple locations, when each location is separated by a
comma. If this web service uses a secure connection, the program prompts the user
for the SSL options. You must also specify the session management server instance.
The configuration information is saved to /opt/pdsms/etc/pdsmsclicfg.conf. The
presence of this configuration file is used to determine the configuration status of
the 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.
unconfig
Fully unconfigures the command-line administration utility. No
other parameters are required.
name
Displays the translated "Session Management Command Line"
name. No other options are required.
upgrade
Configures an upgrade from a previous version.
version
Displays the version number for the currently installed SMS CLI
package.
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
280
IBM Security Access Manager for Web Version 7.0: Command Reference
–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 Manager
administration framework is required. The default value is no. (Optional)
–aznapi_app_config_file path_name
Specifies the fully qualified name of the configuration file for the hosting
authorization server. Only required if Security Access Manager integration
is enabled. (Optional)
–webservice_location host:port
Specifies the location of the session management server Administration
web service. The location is the name of the hosting server and the port on
which the web service is located. Multiple locations can be specified. When
you specify multiple locations, separate the locations with commas.
(Optional)
–instances name1,name2
The session management server instances which are to be administered.
The instance names must be separated by a comma. The default value is
DSess. (Optional)
-ssl_enable {yes|no}
Indicates whether SSL communication with the web server must be
enabled. (Optional)
–sslkeyfile path
Specifies the fully qualified name of the SSL key file to use during
communication with the session management server web service. Use this
parameter only when the -ssl_enable parameter is set to yes. (Optional)
–sslkeyfile_label label
Specifies the SSL key file label of the certificate to be used. Use this
parameter only when the -ssl_enable parameter is set to yes. (Optional)
–sslkeyfile_stash path
Specifies the fully qualified name of the stash file that contains the
password for the SSL key file. Use this parameter only when the
-ssl_enable parameter is set to yes. (Optional)
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/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. The
pdsmsclicfg command starts the wizard.
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Chapter 2. Security Access Manager utilities
281
Return codes
0
The utility completed successfully.
non-zero
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
pdversion
Lists the current version of Security Access Manager components that are installed
on the system.
Syntax
pdversion [–key key1, key2...keyX] [–separator delimiter_character]
Parameters
–key key1, key2...keyX
Specifies the component or components of the current version. (Optional)
The following are possible values of –key:
v pdacld – Security Access Manager Authorization Server
v pdauthadk – Security Access Manager Application Developer Kit
v pdjrte – Security Access Manager Runtime for Java
v pdmgr – Security Access Manager Policy Server
v pdmgrprxy – Security Access Manager Policy Proxy Server
v pdrte – Security Access Manager Runtime
v pdsms – Security Access Manager Session Manager Server
v pdweb – Security Access Manager WebSEAL
v pdwebars – Security Access Manager Attribute Retrieval Service
v pdwebadk – Security Access Manager Web Security ADK
v pdwebrte – Security Access Manager Web Security Runtime
v pdwebpi – Security Access Manager Plug-in for Web Servers
v pdwebpi.apache – Security Access Manager Plug-in for Apache
v pdwebpi.ihs – Security Access Manager Plug-in for IBM HTTP Server
v pdwpm – Security Access Manager Web Portal Manager
v tivsecutl – IBM Tivoli Security Utilities
The version information for the various blades shows up when the blade packages
are installed on the system. The following components are basic components:
v Security Access Manager Runtime
v Security Access Manager Policy Server
v Security Access Manager Web Portal Manager
v Security Access Manager Application Developer Kit
v Security Access Manager Authorization Server
v Security Access Manager Runtime for Java
v Security Access Manager Policy Proxy Server
The following components are blades:
v Security Access Manager Plug-in for web Servers
v Security Access Manager WebSEAL
282
IBM Security Access Manager for Web Version 7.0: Command Reference
v
v
v
v
Security Access
Security Access
Security Access
Security Access
Manager web Security Runtime
Manager web Security ADK
Manager Session Manager Server
Manager Attribute Retrieval Service
–separator delimiter_character
Specifies the separator that is used to delimit the description of the
component from its version. (Optional)
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/PolicyDirector/bin
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 in
the /bin directory under the installation directory (for example, installation
directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
v 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 description
from its version:
> pdversion -key pdrte -separator X
Security Access Manager
RuntimeX7.0.0.0
Chapter 2. Security Access Manager utilities
283
pdweb
Starts, 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 stop
WebSEAL servers.
Parameters
instance_name
Specifies the name of the WebSEAL instance in the format
server_name–host_name.
For example, for a single WebSEAL server, server_name is
default-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 is
webseal2, 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.
restart
Specifies a WebSEAL server to restart. The instance name argument is
optional. When no instance name is supplied, all instances are restarted.
start
Specifies a WebSEAL server to start. The instance name argument is
optional. 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 is
optional. 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:
284
IBM Security Access Manager for Web Version 7.0: Command Reference
/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 in
the /bin directory under the installation directory (for example, installation
directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x14c012f2). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Examples
v 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 Servers
ServerEnabledRunning
-------------------------------------websealdyesyes
webseald-webseal2yesyes
webseald-webseal3yesyes
pdwebpi
Returns 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 the
foreground.
Syntax
pdwebpi [–foreground] [–version]
Description
The pdwebpi utility returns the current version of Security Access Manager plug-in
for web servers. Also, specifies whether to run plug-in for web servers as a
daemon or run it in the foreground.
Chapter 2. Security Access Manager utilities
285
Note: When you use Windows Remote Desktop Connection, you must run the
plug-in as a service.
Parameters
–foreground
Runs the Plug-in for the binary file of the web server in the foreground as
opposed to running it as a daemon. (Optional)
–version
Specifies the version information for the plug-in for web servers
installation. (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
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example, installation
directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x14c012f2). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
pdwebpi_start
Controls the plug-in for web servers processes in AIX, Linux, and Solaris
installations 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-in
for web servers process in an AIX, Linux, or Solaris environment.
Note: To control the plug-in process in a Windows environment, use the Services
Control Panel.
286
IBM Security Access Manager for Web Version 7.0: Command Reference
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 in
the /sbin directory under the installation directory (for example, installation
directory/sbin).
Return codes
0
The utility completed successfully.
1
An error occurred.
pdwpi-version
Lists 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 package
version. (Optional)
–V
Displays the version information for the pdwpi-version installable file.
(Optional)
binary [binary]
Displays version information for the specified installable files. If no
installable file is specified, displays all files. (Optional)
Availability
This utility is in one of 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
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example, installation
directory/bin).
Chapter 2. Security Access Manager utilities
287
Return codes
0
The utility completed successfully.
1
An error occurred.
pdwpicfg
Configures or unconfigures the plug-in for web servers.
Syntax
pdwpicfg –action config –admin_id admin_id –admin_pwd password [–auth_port
port_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_port
port_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 following
values:
config Configures the Security Access Manager plug-in for web servers.
unconfig
Unconfigures the Security Access Manager plug-in for web servers.
–admin_id admin_id
Specifies the administration user identifier (the administrative user is
normally sec_master).
–admin_pwd password
Specifies the password for the administrative user.
–auth_port port_number
Specifies the port number of the authorization server. The default value is
7237. (Optional)
288
IBM Security Access Manager for Web Version 7.0: Command Reference
–help [options]
Lists the name of the parameter and a short description. If one or more
options are specified, it lists each parameter and a short description.
(Optional)
–interactive {yes|no}
Enables interactive mode for the utility if yes; otherwise, disables
interactive 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 keyfile
Specifies the LDAP SSL key file. There is no default value. Specify this
parameter 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 label
Specifies the LDAP SSL key label. There is no default value. Specify this
parameter 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 password
Specifies the LDAP SSL key file password. (Optional)
–operations
Lists 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 part
of the unconfiguration process. The default value is none. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–ssl_enable {yes|no}
Enables SSL communications with LDAP if yes; otherwise, disables SSL
communications with LDAP. The default value is yes. (Optional)
–ssl_port port_number
Specifies the LDAP SSL port. The default value is 636. (Optional)
–usage Displays the syntax and an example for this utility. (Optional)
–vhosts virtual_host_id
Specifies the identifiers of the virtual hosts to protect. The value must be in
the format of a comma-separated list of virtual host IDs. There must be no
spaces between the virtual host IDs.
Chapter 2. Security Access Manager utilities
289
–web_directory installation_directory
Specifies 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 be
installed. This parameter defaults to the type and location of the
configured web server. (Optional) The following choices are supported:
ihs
For IBM HTTP Server
iis
For Internet Information Server
apache
For the Apache Server
Availability
This utility is in one of 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
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x14c012f2). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
query_contents
Returns the contents of the root directory of a web space on a third-party web
server.
Syntax
query_contents
Description
Returns the contents of the specified web space on a third-party web server. The
contents are used to construct a protected object space for use by Security Access
Manager administrators.
The query_contents utility is distributed with WebSEAL. The typical usage of the
utility is to copy it to a junctioned web server and run it there. The utility returns a
list of the hierarchy of files that must be protected by Security Access Manager.
This list enables the Security Access Manager administrative GUI (Web Portal
Manager) to display to the administrator a list of resources to be managed.
290
IBM Security Access Manager for Web Version 7.0: Command Reference
The utility is provided on AIX, Linux, and Solaris operating systems as a shell
script, query_contents.sh. On Windows operating systems, it is provided as a
query_contents.exe executable file. WebSEAL also includes source to the utility, a
sample configuration file, and an HTML help file. Administrators can use these
files to configure query_contents and, when needed, to modify its behavior.
Administrators must review the documentation on WebSEAL junctions and
query_contents before running this utility. For more information, see the IBM
Security Access Manager for Web WebSEAL Administration Guide.
Parameters
None.
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/pdweb/query_contents
v On Windows operating systems:
c:\Program Files\Tivoli\pdweb\query_contents
Return codes
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
Example
This example displays the contents of a web space hierarchy.
http://server_name/cgi-bin/query_contents?dirlist=/
smsbackup
Gathers information to help IBM Software Support in problem determination.
Note: This utility is for use by support personnel.
Syntax
For local mode
smsbackup –local [–was_home path] [–list list] [–path output]
For remote mode
smsbackup [–was_home path] [–wsadmin_options options] [–list list] [–path
output]
Description
The smsbackup gathers information to help IBM Software Support in problem
determination. It has two modes:
Chapter 2. Security Access Manager utilities
291
Local mode
Gathers information from the local system only. Does not require an
operational WebSphere environment. To gather information about all
members in the cluster, run the utility on each node in the cluster.
Remote mode
Gathers information about the entire environment. Requires an operational
WebSphere environment.
The utility is provided on AIX, Linux, and Solaris operating systems as a shell
script, smsbackup.sh. On Windows operating systems, it is provided as a batch
script, smsbackup.bat.
When the utility runs in local mode, you must copy the following files to each
member in the cluster, maintaining directory structure:
v /bin/smsbackup.sh
v /bin/smsbackup.bat
v /etc/smsbackup.lst
v /lib/smscfg.jar
v /nls/java/message.jar
Parameters
–local Indicates that the utility runs in local mode.
–list list
Specifies the .lst file that describes the information to gather. If not
specified, the smsbackup.lst file in the sms_installation_directory/etc
directory is used. (Optional)
–path output
Specifies the directory for the created JAR file. The JAR file contains the
gathered information. (Optional)
–was_home path
Specifies the home directory of the WebSphere Application Server. This
value must be set on the command line or in the WAS_HOME
environment variable. (Optional)
–wsadmin_options options
Specifies options to pass directory to the wsadmin utility. Use this parameter
to pass non-default binding information before the backup operation runs
through the WebSphere cluster. Examples of non-default binding
information include the user name and password. (Optional)
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/pdsms/bin
v On Windows operating systems:
c:\Program Files\Tivoli\PDSMS\bin
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example,
installation_directory/bin).
292
IBM Security Access Manager for Web Version 7.0: Command Reference
Return codes
0
The utility completed successfully.
non-zero
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
smscfg
Deploys and configures the session management server.
Syntax
smscfg –action {config|unconfig|deploy|undeploy|extract|upgrade|revert}
Configuration
smscfg –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] [–keyfile
file_name] [–key_pwd password] [–instance instance_name] [–session_realm
realm:max_login=replica_set1_name,replica_set2_name,...]
[–session_realm_remove realm_name] [–enable_tcd {yes|no}] [–tcd
fully_qualified_directory_name] [–enable_sam_integration {yes|no}]
[–policysvr_host host_name] [–policysvr_port port] [–admin_id
administrator_id] –admin_pwd[ password] [–domain domain] [–authzsvr
host_name:port:rank] [–cred_refresh_rule rule] [–enable_last_login
{yes|no}][–enable_last_login_database {yes|no}] [–last_login_table
last_login_database_table_name] [–last_login_max_entries
max_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_properties
file_name][–key_lifetime key_lifetime] [–client_idle_timeout timeout]
Configuration with response file
smscfg –action config –rspfile file_name
Configuration, interactive
smscfg –action config –interactive
Unconfiguration
smscfg –action unconfig [–interactive {yes|no}] [–rspfile file_name]
[–record file_name] [–was_port port] [–was_enable_security {yes|no}]
[–was_admin_id administrator_id] [–was_admin_pwd password]
[–trust_store file_name] [–trust_store_pwd password] [–keyfile file_name]
[–key_pwd password] [–instance instance_name] [–admin_id
administrator_id] [–admin_pwd password] [–remove_last_login_db
{yes|no}]
Unconfiguration, response file
smscfg –action unconfig –rspfile file_name
Unconfiguration, interactive
smscfg –action unconfig –interactive
Chapter 2. Security Access Manager utilities
293
Deployment
smscfg –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] [–keyfile
file_name] [–key_pwd password] [–instance instance_name]
[–enable_database_storage {yes|no}][–database_name
database_name][–virtual_host host_name] [–clustered {yes|no}] [–was_node
node_name] [–was_server server_name] [–was_cluster cluster_name]
Undeployment
smscfg –action undeploy [–interactive {yes|no}] [–rspfile file_name]
[–record file_name] [–was_port port] [–was_enable_security {yes|no}]
[–was_admin_id administrator_id] [–was_admin_pwd password]
[–trust_store file_name] [–trust_store_pwd password] [–keyfile
file_name] [–key_pwd password] [–instance instance_name]
Extract
smscfg –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] [–keyfile
file_name] [–key_pwd password] [–instance instance_name]
Upgrade
smscfg –action upgrade [–interactive {yes|no}] [–rspfile file_name]
[–record file_name] [–was_port port] [–was_enable_security {yes|no}]
[–was_admin_id administrator_id] [–was_admin_pwd password]
[–trust_store file_name] [–trust_store_pwd password] [–keyfile
file_name] [–key_pwd password] [–instance instance_name]
Revert
smscfg –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] [–keyfile
file_name] [–key_pwd password] [–instance instance_name]
Utility help
smscfg –help option
smscfg –usage
smscfg –?
Description
The smscfg utility deploys, configures, or unconfigures session management server
instances. It can also be used to extract the session management server
configuration, or to install and remove fix pack upgrades.
A log of the configuration progress is written to msg_smscfg.log log file. This log
file 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.
294
IBM Security Access Manager for Web Version 7.0: Command Reference
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:
deploy
Deploys the session management server instance to a WebSphere
Application Server.
undeploy
Removes a session management server instance from a WebSphere
Application Server.
config Configures or reconfigures a deployed session management server
instance.
unconfig
Unconfigures a session management server instance.
extract Extracts the configuration information from a session management
server instance.
upgrade
Upgrades to a new session management server fix pack.
revert Reverts to the previous session management server fix pack.
–admin_id administrator_id
Specifies the Security Access Manager administration ID. The default value
is sec_master. This parameter is required when –enable_sam_integration
is set to yes. (Optional)
–admin_pwd password
Specifies the password for the Security Access Manager administrator. This
parameter is required when you specify the –admin_id parameter.
(Optional)
–auditing_properties file_name
Specifies the path to the properties file which contains the configuration of
the auditing component. (Optional)
–authzsvr host_name:port:rank
Specifies the host name, port number, and rank of the Security Access
Manager authorization server. This optional parameter can be specified
multiple times.
A Security Access Manager authorization server is required to use either of
these functionalities:
v Session refresh capabilities
v 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 timeout
Specifies the client idle timeout in seconds after which a client is
considered idle. A client is considered idle if it is not actively requesting
updates from the session management server. (Optional)
Chapter 2. Security Access Manager utilities
295
–clustered {yes|no}
Whether the application is deployed to a WebSphere cluster. The default
value is no. (Optional)
–cred_refresh_rule rule
Specifies rules to preserve when a user credential is refreshed. The default
credential refresh rule set is preserve=tagvalue_*. (Optional)
–database_name database
Specifies the name of the WebSphere JDBC data source. The session
management server uses this data source to access the database where the
server stores its data. There is no default value. (Optional)
–domain domain
Specifies the name of the Security Access Manager policy domain. This
parameter is required when –enable_sam_integration is set to yes. The
default 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 only
meaningful in the context of WebSphere Application Server single server
deployments. If the application is deployed to a cluster, this parameter is
redundant. The default value is no. Setting this parameter to no sets the
database 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. The
default value is no. (Optional)
–enable_last_login {yes|no}
Indicates whether last login information is stored. When set to yes, you
must specify the following parameters or accept their default values:
v –last_login_jsp_file
v –last_login_max_entries
v –last_login_table
The default value is no (not to enable the recording of last login
information). The –enable_last_login field is only required if you install
into a stand-alone application server. When you install into a cluster this
field is not required. (Optional)
–enable_last_login_database {yes|no}
Indicates whether last login information is stored to a database. The
default value is no. (Optional)
–enable_tam_integration {yes|no}
Indicates whether to enable integration with Security Access Manager or to
change enablement. When set to yes, you must specify the following
parameters or accept their default values, where applicable:
v –policysvr_host
v –policysvr_port
v –authzsvr
v –admin_id
v –admin_pwd
v –domain
The default value is no. (Optional)
296
IBM Security Access Manager for Web Version 7.0: Command Reference
–enable_tcd {yes|no}
Indicates whether Tivoli Common Directory logging is required. When set
to 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 or
more options are specified, it lists each parameter and a short description.
(Optional)
–instance instance_name
Specifies the name of the instance to be administered. The default value is
DSess. (Optional)
–interactive {yes|no}
Indicates whether the configuration is interactive. The default value is yes.
(Optional)
–key_lifetime lifecycle
Specifies the lifetime in seconds of the key for the session management
server. After the defined lifecycle completes, a new key is generated. If this
value is set to zero, keys are not automatically generated. (Optional)
–key_pwd password
Specifies the password to access the server-side certificates. This parameter
is required when you specify the –keyfile parameter. (Optional)
–keyfile file_name
Specifies the fully qualified name for the keystore when a secure
connection is made to WebSphere Application Server. The keystore holds
the server-side certificates. This parameter is required when you specify
the –was_admin_id parameter. (Optional)
–last_login_jsp server_jsp_name
The server-side path for the last login JSP file. server_jsp_name is an
optional argument. (Optional)
–last_login_jsp_file file_name
Specifies the fully qualified name of the last login JSP file to use for
recording last login information. This parameter is required when the
–enable_last_login parameter is set to yes. The default value is
installation_directory/etc/lastLogin.jsp. (Optional)
Note: Configuration of the lastLogin.jsp file can produce a long web
browser URL, which can exceed the limits that are imposed by some proxy
servers. Access the WebSphere ISC by using a direct connection to the
Internet.
–last_login_max_entries maximum_entries
Specifies the maximum number of entries to be stored in the memory
cache for recording last login information. This parameter is required when
the –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 a
stand-alone application server. When you install into a cluster, this field is
not required. (Optional)
–last_login_table table_name
Specifies the name of the database table to use for recording last login
information. This parameter is required when the –enable_last_login
parameter is set to yes. The default value is AMSMSUSERINFOTABLE.
(Optional)
Chapter 2. Security Access Manager utilities
297
–operations
Lists each of the parameter names, one after another, without a description.
(Optional)
–policysvr_host host_name
Specifies the host name of the Security Access Manager policy server. This
parameter is required when –enable_sam_integration is set to yes.
(Optional)
–policysvr_port port
Specifies the port of the Security Access Manager policy server. This
parameter is required when you specify the –host parameter. (Optional)
–record file_name
Specifies the name of the response file to which configuration parameters
are recorded. (Optional)
–remove_last_login_db {yes|no}
Indicates whether the last login database must be removed. The default
value is no. (Optional)
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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 realm
name or any of the replica set names contain spaces, the entire argument
must be specified within quotation marks.
The max_logins parameter is used to specify the maximum number of
concurrent login events that are permitted for the session realm. If the
max_logins parameter is not supplied, there are an unlimited number of
concurrent 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 name
contain spaces, the entire argument must be specified within quotation
marks. (Optional)
–tcd path_name
Specifies the fully qualified directory for Tivoli Common Directory logging.
This parameter is required when –enable_tcd is set to yes. If the Tivoli
Common Directory is configured on the target system, this option is
ignored. (Optional)
–trust_store file_name
Specifies the fully qualified name for the truststore when a secure
connection is made to WebSphere Application Server. The truststore holds
the client-side certificates. This parameter is required when you specify the
–was_admin_id parameter. (Optional)
–trust_store_pwd password
Specifies the password to access the client-side certificates. This parameter
is required when you specify the –trust_store parameter. (Optional)
298
IBM Security Access Manager for Web Version 7.0: Command Reference
–usage Displays the syntax and an example for this utility. (Optional)
–virtual_host host_name
Specifies the name of the WebSphere virtual host to which to deploy the
session management server application. If not specified, the application is
deployed on the default virtual host. (Optional)
–was_admin_id administrator_id
Specifies the name of the administrator to use when a secure connection is
made to WebSphere Application Server. In interactive mode, this parameter
is optional unless you are making a secure connection. When you use this
parameter, you must specify the –was_admin_pwd parameter. When not
making a secure connection, this parameter is optional. (Optional)
–was_admin_pwd password
Specifies the password to use when a secure connection is made to
WebSphere Application Server. The administrator can use this password.
(Optional)
–was_cluster cluster_name
Specifies the name of the WebSphere cluster to which to deploy the session
management server application. This parameter is mutually exclusive with
the –was_server parameter. (Optional)
When you are using WebSphere Network Deployment and –was_cluster is
specified, and there is only one cluster, the application is deployed to that
cluster.
The application is deployed to that server when you are using WebSphere
Network 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 a
secure connection. When set to yes, you must specify the following
parameters:
v –was_admin_id
v –was_admin_pwd
v –trust_store
v –trust_store_pwd
v –keyfile
v –key_pwd
The default value is no. (Optional)
–was_node node_name
Specifies the name of the WebSphere node. (Optional)
–was_port port
Specifies the SOAP port to use on the WebSphere server. This parameter is
always required unless the –interactive parameter is set to yes.
–was_server server_name
Specifies the name of the WebSphere server to which to deploy the session
management server application. This parameter is mutually exclusive with
the –was_cluster parameter. (Optional) The application is deployed to the
server to which this configuration utility is connected when:
v WebSphere Application Server is in a single server deployment, and
Chapter 2. Security Access Manager utilities
299
v –was_server is not specified.
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/pdsms/bin
v On Windows operating systems:
c:\Program Files\Tivoli\PDSMS\bin
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
non-zero
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
smsservicelevel
Lists the current service level of the session management server files on the local
system.
Note: This utility is for use by support personnel.
Syntax
smsservicelevel [directory [directory] ...] [file [file] ...]
Description
The smsservicelevel utility recursively scans the specified directory. The utility
returns to the standard output device the name and service level for session
management server files. The files match Security Access Manager conventions.
The utility is provided on AIX, Linux, and Solaris operating systems as a shell
script, smsservicelevel.sh. On Windows operating systems, it is provided as a
batch script, smsservicelevel.bat.
Parameters
directory
Specifies the directories that the utility searches for service level
information. (Optional)
files
300
Specifies particular files that the utility searches. (Optional)
IBM Security Access Manager for Web Version 7.0: Command Reference
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/pdsms/bin
v On Windows operating systems:
c:\Program Files\Tivoli\PDSMS\bin
When an installation directory other than the default is selected, this utility is in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
0
The utility completed successfully.
non-zero
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
svrsslcfg
Configures, unconfigures, or modifies the configuration information of a resource
manager to use an SSL connection for communicating with the policy server.
This utility is used for C application servers only. For Java application servers, use
the equivalent com.tivoli.pd.jcfg.SvrSslCfg Java class. For information about
this Java class, see the IBM Security Access Manager for Web Authorization Java
Classes Developer Reference.
Syntax
svrsslcfg –add_replica –f cfg_file –h host_name [–p server_port] [–k
replica_rank] [–rspfile response_file]
svrsslcfg –chg_replica –f cfg_file –h host_name [–p server_port] [–k
replica_rank] [–rspfile response_file]
svrsslcfg –chgcert –f cfg_file –P password [–A admin_id] [–rspfile
response_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 –P
password [–S password] [–A admin_id] [–t ssl_timeout] [–e password_life] [–l
listening_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] [–l
listening_mode] [–rspfile response_file]
Chapter 2. Security Access Manager utilities
301
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] [–h
host_name] [–o login_domain] [–rspfile response_file]
Parameters
–a refresh_mode
Sets the certificate and key file password auto-refresh entry in the
configuration file. The default value is yes. (Optional)
–A admin_id
Specifies the name of the Security Access Manager administrator. The
default value is sec_master. (Optional)
A valid administrative ID is an alphanumeric, case-sensitive string. String
values are expected to be characters that are part of the local code set. You
cannot use a space in the administrative ID.
For example, for US English, the valid characters are the letters a-Z, the
numbers 0-9, a period (.), an underscore (_), a plus sign (+), a hyphen (-),
an at sign (@), an ampersand (&), and an asterisk (*). If there are limits, the
minimum and maximum lengths of the ID are imposed by the underlying
registry. See the information about user registry differences in the IBM
Security Access Manager for Web Installation Guide.
–add_replica
Adds an authorization server replica to the configuration of a resource
manager. A resource manager can contact a replica server for authorization
decisions.
-C cert_file
Specifies the fully qualified name of the file that contains the base-64
encoded SSL certificate that is used when the server authenticates directly
with the user registry. (Optional)
–chg_replica
Changes attributes for the replica server. The replica host name is used to
identify the replica server and cannot be changed by this action.
–chgcert
Renews the SSL certificate of the resource manager. Before you run this
action, 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 certificate
request. The certificate request that contains the new public key for the
resource manager is sent to the Security Access Manager policy server.
The policy server signs the request and sends the newly signed
certificate back to the resource manager. The resource manager stores the
signed certificate in a secure keystore and also stores the new private
key for the resource manager.
The lifetime of the new certificate is determined by the policy server
ssl-cert-life entry in the ivmgrd.conf configuration file. This
parameter determines the number-of-days value for the lifetime of a
certificate. Any issued or renewed certificates must use this value. The
default value is 1460.
v The certificate for a resource manager must be renewed if it expired or if
it was compromised. Also, the certificate must be renewed to adhere to
302
IBM Security Access Manager for Web Version 7.0: Command Reference
any changes in the security policy. If both the certificate and the
password to the key database file that contains the certificate expire, the
password must be refreshed first.
–chgport
Changes the listening port for a resource manager. Before you run this
action, ensure that the policy server is running.
–chgpwd
Changes the key file password for a resource manager. Before you run this
action, ensure that the policy server is running.
–config
Configures a resource manager.
–D description
Specifies a description for the application. 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 code set. Spaces are allowed. If the
description contains a space, ensure that you enclose the description in
double quotation marks. (Optional)
–d kdb_dir
Specifies the directory that is to contain the key files for the server. A valid
directory name is determined by the operating system. Do not use relative
directory names. For example:
On AIX, Linux, and Solaris operating systems
/opt/PolicyDirector/keytab/ivmgrd.kdb
On Windows operating systems
C:\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 user
is ivmgr.
–e password_life
Sets the key file password expiration time in days. This parameter is
required.
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_file
Specifies the configuration path and file name. A file name must be an
absolute 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 systems
C:\Program Files\Tivoli\Policy Director\etc\activedir.conf
–g group_list
Specifies a list of groups to which this server must be added. The
following names are not supported in this list: ivacld_servers and
remote_acl_users. The list of names must be separated by commas with no
empty space. If a group name contains a space, the entire list must be
enclosed in double quotation marks. (Optional)
Chapter 2. Security Access Manager utilities
303
–h host_name
For a configuration action (–config) or an unconfiguration action
(–unconfig), specifies the TCP host name that is used by the policy server
to 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 name
that is returned by the operating system.
v If not specified during an unconfiguration action, the value is retrieved
from the configuration file. The default value is used only if a value
cannot be determined from the configuration file. The default is the local
host name that is returned by the operating system.
For all other actions, specifies the TCP host name of an authorization
server replica.
Valid values include any valid IP host name. Examples:
host = libra
host = libra.dallas.ibm.com
–k replica_rank
Specifies the replica order of preference among other replicas. Replica
servers with higher ranks are used preferentially. For example, a resource
manager contacts a replica server with a ranking of 10 before it contacts a
replica server with a ranking of 9. The default value is 10. (Optional)
–l listening_mode
Sets the listening-enabled entry in the configuration file. The value must be
yes or no. If not specified, the default is no. A value of yes requires that the
–r parameter has non-zero value. (Optional)
–modify
Changes the current configuration of a resource manager. Before you run
this action, ensure that the policy server is running.
This action fails only if you are not authorized to run the utility or the
policy server cannot be contacted. This action is designed to clean up a
partial or damaged configuration. The action also ensures that errors are
not reported for information that is not valid and that is missing.
–n appl_name
Specifies the name of the application. The name is combined with the host
name to create unique names for Security Access Manager objects that are
created for your application. The following names are reserved for Security
Access Manager applications: ivacld, secmgrd, ivnet, and ivweb.
–o login_domain
Specifies the domain name for the domain to which this server is
configured. This domain must exist and an administrator ID and password
must be valid for this domain. (Optional)
If not specified, the local domain that is specified during IBM Security
Access Manager runtime configuration is used. The local domain value is
retrieved from the configuration file.
A valid domain name is an alphanumeric, case-sensitive string. String
values are expected to be characters that are part of the local code set. You
cannot use a space in the domain name.
For example, for US English the valid characters for domain names are the
letters a-Z, the numbers 0-9, a period (.), an underscore (_), a plus sign (+),
a hyphen (-), an at sign (@), an ampersand (&), and an asterisk (*). The
304
IBM Security Access Manager for Web Version 7.0: Command Reference
minimum and maximum lengths of the domain name, if there are limits,
are imposed by the underlying registry. See the topic about user registry
differences in the IBM Security Access Manager for Web Installation Guide.
–p server_port
Specifies the port number on which the replica server listens for requests.
The default value is 7136. (Optional)
–P password
Specifies the password for the Security Access Manager administrator user
(admin_id). If this parameter is not specified, the administrator is
prompted, and the password is read from standard input (stdin).
–r port_number
Sets the listening port number for the server. A value of 0 can be specified
only if the [aznapi-admin-services] stanza in the configuration file is
empty.
During a configuration action, such as –config, this parameter is required.
–rmv_replica
Removes an authorization server replica from the configuration of a
resource manager.
–rspfile response_file
Specifies the fully qualified path and file name of the response file to use
during silent configuration. A response file can be used for configuration.
There is no default response file name. The response file contains stanzas
and 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)
–s server_mode
Specifies the mode in which the application operates. This value must be
either local or remote.
–S password
Specifies the server password. This parameter is required. A password is
created by the system and the configuration file is updated with the
password created by the system. It is saved as an obfuscated value by
using the pd-user-pwd stanza entry in the [aznapi-configuration] stanza
in the configuration file that is specified with the –f parameter. If this
parameter is not specified, the server password is read from standard
input.
–t ssl_timeout
Specifies the SSL session timeout in seconds. The value must be in the
range 1 - 86400. The default value is 7200. (Optional)
–unconfig
Unconfigures a resource manager. The key files are deleted, and the server
is 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 a
combined length that exceeds 64 bytes, svrsslcfg truncates the appsrv_id portion of
the name. This scenario happens when you create the account in an Active
Directory registry.
Chapter 2. Security Access Manager utilities
305
Availability
This utility is in one of the following default installation directories:
v On AIX, Linux, and Solaris operating systems:
/opt/PolicyDirector/bin
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 in
the /bin directory under the installation directory (for example,
installation_directory/bin).
Return codes
306
0
The utility completed successfully.
1
The utility failed. When a utility fails, a description of the error and an
error status code in hexadecimal format is provided (for example,
0x15c3a00c). See the IBM Security Access Manager for Web Error Message
Reference. This reference provides a list of the Security Access Manager
error messages by decimal or hexadecimal codes.
IBM Security Access Manager for Web Version 7.0: Command Reference
Appendix A. Password limitations and characters allowed in
object names
When you specify Security Access Manager user names, group names,
distinguished names, POP names, ACL policies, authorization rules, and domain
names, certain characters might be disallowed.
Some factors that affect which characters are allowed are restrictions of the
underlying 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 308
v “Characters allowed for secure domain names” on page 308
v “Characters disallowed for user and group name” on page 309
v “Characters disallowed for distinguished names” on page 310
v “Characters disallowed for GSO names” on page 311
v “Characters disallowed for authorization rule names” on page 311
v “Characters disallowed for ACL policy names” on page 312
v “Characters disallowed for POP names” on page 313
General password policies
You can change global user settings, such as password policies, login-failure
policies, access policies, and account expiration policies. Additionally, you can
override global password policies by setting individual password policies for the
specified 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 the
following types of global password policies for all users:
Minimum length that is allowed for a password
Maximum age that is allowed for a password
Minimum number of alphanumeric characters that are allowed in a password
Minimum number of non-alphanumeric characters that are allowed in a
password
v Maximum number of repeated characters that are allowed in a password
v Whether spaces are allowed in the password
v
v
v
v
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.
© Copyright IBM Corp. 2001, 2012
307
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 to
complete. 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 names
There are password characters that are valid, but must be treated differently when
you run the pdadmin utility. These special characters have special meaning to the
utility.
Enclose the password or user name in double quotation marks (") to escape the
special 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 or
user name in double quotation marks and use the backward slash (\) escape
character. 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 and
escape character are needed.
The following special characters either must not be used or they must be escaped
when 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 when
setting or modifying the password with the user modify command:
v Hyphen (-)
v Left brace ({)
v Number sign (#)
Characters allowed for secure domain names
A valid local domain name is an alphanumeric, case-sensitive string. String
characters are expected to be characters that are part of the local code set.
The following characters, numbers, and special characters can be used for secure
domain names during use of the pdadmin commands or Web Portal Manager.
For example, for US English, secure domain names can contain a combination of
the following characters:
v Letters (a-z A-Z)
v Numbers (0–9)
v Ampersand (&)
v Asterisk (*)
308
IBM Security Access Manager for Web Version 7.0: Command Reference
v
v
v
v
v
At sign (@)
Hyphen (-)
Period (.)
Plus sign (+)
Underscore (_)
You cannot use a space in the domain name. The minimum and maximum lengths
of the domain name, if there are limits, are imposed by the underlying registry. See
the section on user registry differences in the IBM Security Access Manager for Web
Installation Guide.
Characters disallowed for user and group name
Environment aspects such as registries and command shells can affect special
character handling. Because of the variability of special character handling in
general, avoid the use of special characters.
Avoid the following character in user and group names that are defined by using
distinguished name strings:
v Forward slash (/)
If Microsoft Active Directory is the user registry, care must be taken with user
names and group names that contain the following character:
v Period (.)
A period (.) cannot be the last character of a user or group short name; for
example:jdoe and jdoe.@my_ad_domain.com are invalid user names.
If Microsoft Active Directory is the user registry, user names and group names can
contain 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. For
example, [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
v
v
v
v
Note: Add a prefix with a backward slash (\) to escape any double quotation
character in the user name.
Backward slash (\)
Left angle bracket (<)
Right angle bracket (>)
Semicolon (;)
If you use special characters with the pdadmin utility, enclose each argument of the
user or group command with double quotation marks. The double quotation
marks allow the argument to be entered without being subject to interpretation by
the operating system shell command processor.
Because of the variability of special character handling in general, avoid the use of
special characters.
Characters disallowed for distinguished names
Certain 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. The
following 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 the
backward slash (\) character in distinguished names.
Characters disallowed for Microsoft Active Directory
distinguished names
If Microsoft Active Directory is the user registry, certain special characters are not
allowed in a distinguished name (DN). However, if the character is preceded by an
additional escape character or is encoded in hexadecimal, then, it is allowed in a
DN.
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 string
v A space at the end of the string
v 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 the
backward slash (\) character in distinguished names.
310
IBM Security Access Manager for Web Version 7.0: Command Reference
For other reserved characters, such as an equal sign (=), asterisk (*), or a
non-UTF-8 character, the character must be encoded in hexadecimal.
Example 1
To create a user with a distinguished name that contains a comma next to
the separator:
pdadmin sec_master> user create "johndoe"
"cn=doe\,john,cn=users,dc=mydomain,dc=com" John Doe password1
Example 2
To 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 3
To 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 names
Certain characters are disallowed for GSO names.
You cannot use the following characters to create a global sign-on (GSO) user
name, 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 of
other LDAP-related data are: common name (CN), distinguished name (DN), and
short name (SN) of a user.
Before you use any of these characters in user and group names, consult the
documentation for your user registry to determine the effect of special characters.
Characters disallowed for authorization rule names
Certain characters are disallowed for authorization rule names.
Appendix A. Password limitations and characters allowed in object names
311
These characters cannot be used in the name of an authorization rule 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 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 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 ACL policy names
Certain characters are disallowed for ACL policy names.
These characters cannot be used in the name of an access control list (ACL) policy
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 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.
312
IBM Security Access Manager for Web Version 7.0: Command Reference
Characters disallowed for POP names
Certain 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. String
values are expected to be characters that are part of the local code set. Spaces are
not allowed.
Note: Although a POP name can contain 1 or more of these characters, the results
of using such a POP are undefined.
Appendix A. Password limitations and characters allowed in object names
313
314
IBM Security Access Manager for Web Version 7.0: Command Reference
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 all
parameters.
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 key
value 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. The
following example shows that when there is a -parameter specified in
command-line mode, the key in response file mode is the same, but without the
preceding dash.
Examples
v 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 = 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
audit_pwd = password
v In contrast, the following example uses command-line mode to configure an
audit 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
© Copyright IBM Corp. 2001, 2012
315
316
IBM Security Access Manager for Web Version 7.0: Command Reference
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 in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law :
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain
transactions, 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 be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
© Copyright IBM Corp. 2001, 2012
317
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
2Z4A/101
11400 Burnet Road
Austin, 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 material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurement may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
318
IBM Security Access Manager for Web Version 7.0: Command Reference
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. 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 application
programs conforming to IBM's application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must
include 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 rights
reserved.
If you are viewing this information in softcopy form, the photographs and color
illustrations might not be displayed.
Trademarks
IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of
International 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 and
trademark information" at www.ibm.com/legal/copytrade.shtml.
Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered
trademarks 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 and
Telecommunications Agency which is now part of the Office of Government
Commerce.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo,
Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States
and other countries.
Linux is a trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
ITIL is a registered trademark, and a registered community trademark of the Office
of Government Commerce, and is registered in the U.S. Patent and Trademark
Office.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Cell Broadband Engine and Cell/B.E. are trademarks of Sony Computer
Entertainment, Inc., in the United States, other countries, or both and is used under
license therefrom.
Notices
319
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
320
IBM Security Access Manager for Web Version 7.0: Command Reference
Index
A
access control list (ACL) commands
acl attach 21
acl create 22
acl delete 23
acl detach 24
acl find 25
acl list 26
acl modify 26
acl show 30
access control lists 242
accessibility xiii
ACL policy names
disallowed characters 312
action
group create 34
group delete 34
group list 35
action commands
action create 31
action delete 33
action group create 34
action group delete 34
action group list 35
action list 35
adschema_update utility 212
allowed character
secure domain names 308
amauditcfg utility 213
amwebcfg utility 217
amwpmcfg utility 221
attach
access control list (ACL) 21
protected object policy (POP) 90
auditing
configuring 213
starting 213
stopping 213
authorization commands
attach
authzrule 37
authzrule
attach 37
create 38
delete 39
detach 40
find 40
list 41
modify 42
show 43
create
authzrule 38
delete
authzrule 39
detach
authzrule 40
find
authzrule 40
list
authzrule 41
© Copyright IBM Corp. 2001, 2012
authorization commands (continued)
modify
authzrule 42
show
authzrule 43
authorization rule names
disallowed characters 312
authorization server 230, 232
B
bassslcfg
change password 226
configure 226
get certificate 226
get management domain
modify 226
ping server 226
bassslcfg utility 226
226
C
caches, flushing HTML document 120
CARS 213
cdsso_key_gen utility 229
character limitations
passwords 308
user names 308
command
access control 10
access control list 10
action 10
action commands 10
authorization
rule 11
authorization rule commands 11
category 9
configuration 11
configuration commands 11
context 12
context commands 12
domain 12
domain commands 12
group 12
group commands 12
list 10, 11, 12, 13, 14, 15, 16, 17, 18
login 13
login and logout commands 13
logout 13
object 13
object commands 13
object space 14
object space commands 14
policy 14
policy commands 14
POP 15
protected object policy 15
protected object policy (POP)
commands 15
command (continued)
resource commands
list 15
resource credential commands
list 15
resource group commands
list 15
server 16
server commands 16
server task
Session Management Server 17
server task commands
Session Management Server 17
WebSEAL 19
user 18
user commands 18
user create 18
user delete 18
user import 18
user list 18
user modify 18
user show 18
command modes
interactive 4
multiple 5
single 4
command option processing 9
Common Audit Web service
configuring 213
unconfiguring 213
config commands
modify 44
show 46
configure
smscfg utility 293
context commands
show 48
create
access control list (ACL) 22
actions 31
domain commands 49
group 56
object 69
object space 81
protected object policy (POP) 91
rsrc 99
rsrccred 102
rsrcgroup 108
user 197
credentials
refreshing, WebSEAL 139
D
DB2 xii
delete
access control list (ACL)
actions 33
domain commands 51
group 57
object 71
23
321
delete (continued)
objectspace command 82
protected object policy (POP) 92
rsrc 100
rsrccred 104
rsrcgroup 109
user 199
detach
access control list (ACL) 24
protected object policy (POP) 92
disallowed character
ACL policy names 312
authorization rule names 312
distinguished names 310
group names 309
GSO names 311
POPs 313
user names 309
distinguished names
disallowed characters 310
doAudit stanza entry 213
document cache, HTML flushing 120
domain
login
local 8
other 8
domain commands
create 49
delete 51
list 52
modify 53
show 54
domain names
secure
allowed characters 308
dynamic URL, reloading 130
E
education xiv
error messages
display 54
error, errors
handle 6
handling 6
return code 6
errtext command 54
exists
object 68, 72
G
group commands
group create 56
group delete 57
group import 58
group list 59
group modify 61
group show 62
322
309
311
H
HTML document cache, flushing
120
I
IBM
Software Support xiv
Support Assistant xiv
iKeyman xii
import
group 58
user 200
interactive command mode 3, 4
ivacld_setup
configuring authorization server 230
ivacld_uninst
unconfiguring authorization
server 232
ivbase_setup
configuring runtime server 233
ivbase_uninst
unconfiguring runtime 236
ivmgrd_setup
configuring policy server 237
ivmgrd_uninst
unconfiguring policy server 240
ivrgy_tool utility 242
J
F
find
access control list (ACL) 25
protected object policy (POP)
group names
disallowed characters
gskcapicmd xii
gskikm.jar xii
GSKit
documentation xii
GSO names
disallowed characters
93
JMT 133
junction mapping table
clearing 133
loading 133
reloading 140
junctioned server
adding 117
adding virtual host junctions
creating 121
creating virtual host junctions
removing 141, 184
virtual host offline 180
virtual host online 182
virtual host throttle 188
junctioned servers
deleting 128
deleting virtual host junctions
listing details 143
listing details of virtual host
junctions 186
restarting 190
synchronizing 191
transferring contents 196
junctions
adding junctioned server 117
adding virtual host junctions
168
171
177
168
IBM Security Access Manager for Web Version 7.0: Command Reference
junctions (continued)
creating junctioned server 121
creating virtual host junctions 171
deleting junctioned server 128
deleting virtual host junctions 177
listing 134
listing details, junctioned servers 143
listing virtual host junction
details 186
listing virtual host junctions 179
offline operational state 135
online operational state 137
removing junctioned server 141
removing server from virtual host
junction 184
throttle operational state 164
virtual host offline 180
virtual host online 182
virtual host throttle 188
K
key xii
keys
creating, session management
server 144
displaying details, session
management server 145
L
LDAP server 242
on z/OS xii
limitations, characters
passwords 308
user names 308
list
access control list (ACL) 26
actions 35
domain commands 52
group 59
object 73
objectspace command 83
protected object policy (POP)
server tasks 113
servers 112
locale, locales
non-English 6
94
M
mgrsslcfg
change certificate 245
change password 245
configure 245
modify 245
Microsoft Active Directory, disallowed
distinguished names 310
modify
access control list (ACL) 26
config commands 44
domain commands 53
group 61
object 75
protected object policy (POP) 95
rsrccred 106
modify (continued)
rsrcgroup 110
user 203
multiple command mode
3, 5
O
object
listandshow 74
object commands
object create 69
object delete 71
object exists 68, 72
object list 73
object listandshow 74
object modify 75
object show 77
object name
characters 307
characters allowed 307
object space commands
objectspace create 81
objectspace delete 82
objectspace list 83
online
publications ix
terminology ix
P
passwords
character limitations 308
general policies 307
limitations 307
pd_start utility 252
pdacld_config
configuring authorization server 248
pdacld_unconfig
unconfiguring authorization
server 250
pdadmin
command 1
command option processing 9
help 63
login 65
modes 3
syntax 1
utility 1
pdadmin utilities
exit command line mode 55
logout 67
quit command line mode 55
pdadmin_host 251
pdbackup utility 254
pdconf
configuring 258
pdconfig utility 260
pdinfo utility (deprecated) 254
pdjrtecfg
configuring Java runtime
component 261
pdmgr_config
configuring policy server 267
pdmgr_unconfig
unconfiguring policy server 270
pdproxycfg utility 272
pdrte_config
configuring runtime 275
pdrte_unconfig
unconfiguring runtime 278
pdservicelevel utility 266, 278
pdsmsclicfg
configure 279
pdversion utility 282
pdweb 284
pdweb utility 290
pdwebpi 285
pdwebpi_start 286
pdwpi-version 287
pdwpicfg utility 288
policy commands
policy get 84
policy set 86
policy server 237, 240
multiple 251
unconfigure 270
POPs
disallowed characters 313
problem-determination xiv
protected object policies 313
protected object policy 313
protected object policy (POP) commands
pop attach 90
pop create 91
pop delete 92
pop detach 92
pop find 93
pop list 94
pop modify 95
pop show 98
publications
accessing online ix
list of for this product ix
R
read 1
reading 1
realms
displaying details, session
management server 147
listing, session management
server 146
replica sets
displaying details, session
management server 152
listing, session management
server 151
replicate server 115
resource commands
rsrc create 99
rsrc delete 100
rsrc list 101
rsrc show 102
rsrccred create 102
rsrccred delete 104
rsrccred list user 105
rsrccred modify 106
rsrccred show 107
rsrcgroup create 108
rsrcgroup delete 109
rsrcgroup list 110
rsrcgroup modify 110
resource commands (continued)
rsrcgroup show 112
response files 315
restore data
backing up 254
extracting 254
restoring 254
return code
command
interactive 7
multiple 8
single command 7
rsrc
list 101
rsrccred
list user 105
rsrcgroup
list 110
runtime 236
S
schema
update 242
secure domain names
allowed characters 308
Security Access Manager
configuration
utilities 209
configuration utilities 209
installation
utilities 209
installation utilities 209
migration
utilities 210
migration utilities 210
Plug-in for Web servers
utilities 211
Plug-in for Web servers utilities 211
Problem determination
utilities 212
Problem determination utilities 212
Serviceability
utilities 212
Serviceability and problem
determination utilities 212
Serviceability utilities 212
Session management server
utilities 211
Session management server
utilities 211
utilities 209
Web servers 211
WebSEAL
utilities 211
WebSEAL utilities 211
server commands
admin show conf 36
server list 112
server listtasks 113
server replicate 115
server show 116
server task add 117
server task cache flush all 120
server task cfgdb export 194
server task cfgdb import 195
server task create 121
Index
323
server commands (continued)
server task delete 128
server task dynurl update 130
server task file cat 196
server task help 131
server task jdb export 192
server task jdb import 193
server task jmt 133
server task list 134
server task offline 135
server task online 137
server task refresh all_sessions 139
server task reload 140
server task remove 141
server task server restart 190
server task server sync 191
server task show 143
server task sms key change 144
server task sms key show 145
server task sms realm list 146
server task sms realm show 147
server task sms refresh
all_sessions 149
server task sms refresh session 150
server task sms replica set list 151
server task sms replica set show 152
server task sms session list 153
server task sms trace get 157
server task sms trace set 158
server task stats 159
server task terminate
all_sessions 154, 162
server task terminate session 156,
163
server task throttle 164
server task trace 166
server task virtualhost add 168
server task virtualhost create 171
server task virtualhost delete 177
server task virtualhost list 179
server task virtualhost offline 180
server task virtualhost online 182
server task virtualhost remove 184
server task virtualhost show 186
server task virtualhost throttle 188
server list command 112
server listtasks command 113
server replicate command 115
server show command 116
server task commands
add 117
cache flush all 120
cfgdb export 194
cfgdb import 195
create 121
delete 128
dynurl update 130
file cat 196
help 131
jdb export 192
jdb import 193
jmt 133
list 134
offline 135
online 137
refresh all_sessions 139
refresh session 150
324
server task commands (continued)
reload 140
remove 141
server restart 190
server sync 191
show 143
stats 159
terminate all_sessions 154, 162
terminate session 156, 163
throttle 164
trace command 166
trace get 157
trace set 158
virtualhost add 168
virtualhost create 171
virtualhost delete 177
virtualhost list 179
virtualhost offline 180
virtualhost online 182
virtualhost remove 184
virtualhost show 186
virtualhost throttle 188
server task session commands
refresh all sessions 149
server task sms key command
change 144
show 145
server task sms realm command
list 146
show 147
server task sms replica command
set list 151
set show 152
server task sms session command
list 153
session management server
creating keys 144
displaying details, keys 145
displaying details, replica sets 152
displaying replica sets in realms 147
listing realms 146
listing replica sets 151
listing sessions 153
refreshing credentials 149, 150
sessions
listing, session management
server 153
show
access control list (ACL) 30
config commands 46
context commands 48
domain commands 54
group 62
object
show 77
protected object policy (POP) 98
rsrc 102
rsrccred 107
rsrcgroup 112
server 116
user 205
single command mode 3, 4
smsbackup utility 291
smscfg utility 293
smsservicelevel utility 300
special characters, allowed
secure domain names 308
IBM Security Access Manager for Web Version 7.0: Command Reference
special characters, disallowed
ACL policy names 312
authorization rule names 312
distinguished names 310
group names 309
GSO names 311
POPs 313
user names 309
stanza entries
doAudit 213
statement 1
statistics 159
svrsslcfg
add replica 301
change certificate 301
change password 301
change port 301
change replica 301
configure 301
modify 301
remove replica 301
unconfigure 301
syntax 1
T
terminology ix
Tivoli Directory Integrator xii
Tivoli Directory Server xii
trace level
displaying 157
setting 158
trace, enabling 166
training xiv
troubleshooting xiv
U
URL, reloading dynamic 130
user
list 201
user commands
user create 197
user delete 199
user import 200
user list 201
user modify 203
user show 205
user names
character limitations 308
disallowed characters 309
user sessions
terminating 156, 163
terminating all 154, 162
utilities
adschema_update 212
amauditcfg 213
amwebcfg 217
amwpmcfg 221
bassslcfg 226
cdsso_key_gen 229
ivacld_setup 230
ivacld_uninst 232
ivbase_setup 233
ivbase_uninst 236
ivmgrd_setup 237
utilities (continued)
ivmgrd_uninst 240
ivrgy_tool 242
mgrsslcfg 245
pd_start 252
pdacld_config 248
pdacld_unconfig 250
pdbackup 254
pdconf 258
pdconfig 260
pdinfo (deprecated) 254
pdjrtecfg 261
pdmgr_config 267
pdmgr_unconfig 270
pdproxycfg 272
pdrte_config 275
pdrte_unconfig 278
pdservicelevel 266, 278
pdsmsclicfg 279
pdversion 282
pdweb 284, 290
pdwebpi 285
pdwebpi_start 286
pdwpi-version 287
pdwpicfg 288
smsbackup 291
smscfg 293
smsservicelevel 300
svrsslcfg 301
W
Web Portal Manager
configure using amwpmcfg 221
WebSphere Application Server Network
Deployment xii
WebSphere eXtreme Scale xii
Index
325
326
IBM Security Access Manager for Web Version 7.0: Command Reference
Printed in USA
SC23-6512-02