DirectoryCommand tool

You can use the DirectoryCommand tool to run some of the same operations that can be from the Web Console. With the tool, you can add users, add groups, add users to groups, add roles to users, add roles to groups, and so on.

Usage

On the services tier, the command is installed in the following location:

IS_install_path/ASBServer/bin/DirectoryCommand.sh
IS_install_path\ASBServer\bin\DirectoryCommand.bat

On the engine and client tiers, the command is installed in the following location:

IS_install_path/ASBNode/bin/DirectoryCommand.sh
IS_install_path\ASBNode\bin\DirectoryCommand.bat

The command has many options that control a separate operation. The tool supports multiple operations to be specified at the same time. For example, you could specify both the -add_user and the -add_group options in the same run of the tool. The operations can be run in batch by using the -file option, or they can be run in a script. See the examples at the bottom of this topic.

Syntax

DirectoryCommand
  [-{add_ds_credentials | ds_cred} value]
  [-{add_group | a_grp} value]*
  [-{add_user | a_usr} value]*
  [-{add_users_group | a_usr_grp} value]*
  [-{assign_group_roles | grp_roles} value]* 
  [-{assign_user_roles | usr_roles} value]* 
  [-{assign_project_group_roles | proj_grp_roles} value] 
  [-{assign_project_user_roles | proj_usr_roles} value] 
  [-authfile value] 
  [-{datastage_server | ds_svr} value] 
  [-{delete_group | del_grp} value] 
  [-{delete_user | del_usr} value] 
  [-{details | det}] 
  [-{file | f} value] 
  [-force] 
  [-{get_default_ds_credentials | get_dflt_ds_cred}] 
  [-{help | ?}] 
  [-host value] 
  [-list value] 
  [-{log | l} value] 
  [-{logerror | error} value] 
  [-{loginfo | info} value] 
  [-{loglevel | level} value] 
  [-{password | pwd} value] 
  [-port value] 
  [-primary] 
  [-{remove_group_roles | rm_grp_roles} value] 
  [-{remove_project_group_roles | rm_proj_grp_roles} value] 
  [-{remove_project_user_roles | rm_proj_usr_roles} value] 
  [-{remove_user_roles | rm_usr_roles} value] 
  [-{remove_users_group | rm_usr_grp} value] 
  [-{results | res} value] 
  [-{separator | sep} value] 
  [-{set_default_ds_credentials | set_dflt_ds_cred} value] 
  [-{set_shared_registry | shr_reg} value] 
  [-{sub_list_separator | sub_list_sep} value] 
  [-{update_group | upd_grp} value] 
  [-{update_user | upd_usr} value] 
  [-{user | usr} value] 
  [-{verbose | v}]

Parameters

Command parameter syntax

The {x | y} syntax of the parameters indicates that you can enter either the long form of the parameter (x) or the shortcut parameter name (y). The value indicates that a value must be specified. Each parameter description that follows indicates the syntax of the parameters and associated values. The asterisk (*) on the specification means that the command parameter can be repeated multiple times in the same command line.

Value lists and sublists

Most of the operational parameters have values that consist of lists and sublists.

In the value list syntax, [~value]* means that you can optionally specify a list of the indicated values separated by the separator character, a tilde (˜) by default
A list is a set of values separated by a character, a tilde (~) by default. In some lists, the actual value assigned is determined by the position of the value in the list, such as in the -add_group and -add_user options. For each value in the list, if not all values are assigned between values, at least the separator character must be specified so that the position can be determined. Any trailing separators, however, should be omitted.
```
ListValue1~ListValue2~~~ListValue5
```
For example, the following list is used to add a new user and assign the user ID, password, first name, last name, job title, and business phone number:
```
-add_user "jsmith~pa55word~John~Smith~DS Admin~~~~~408-555-0122"
```
A sublist is a set of values also separated by a character. Sublists differ from lists in that they are accompanied by another sublist, separated by a different character, a dollar sign ($) by default. For sublists, the values are not positional. The values of each sublist are assigned to the values of the accompanying sublists.
```
Sublist1Value1~Sublist1Value2$Sublist2Value1$Sublist3Value1~Sublist3Value2
```
For example, the following sublists are used to assign the roles in the right sublist to the user in the left sublist:
```
-assign_user_roles adminUser$SuiteUser~DataStageAdmin
```
Note: On Linux and UNIX, the dollar sign ($) is a special character that must be escaped with a backslash (\). The above example would be specified as follows:
```
Sublist1Value1~Sublist1Value2\$Sublist2Value1\$Sublist3Value1~Sublist3Value2
```
Alternatively, you can specify the entire list in quotation marks ("):
```
"Sublist1Value1~Sublist1Value2$Sublist2Value1$Sublist3Value1~Sublist3Value2"
```

[-{add_ds_credentials | ds_cred} value ]

Maps one or more user credentials to the specified operating system user credentials for the engine, which is specified with the -datastage_server parameter, which must be included with this one. Specify the value as one string with the following syntax:

userID[~userID]*$credUserID~credPassword

The value must contain at least one sublist separator character ($). If multiple user IDs are specified, they are all assigned the specified credentials. The password value can be specified as plain text or as text encrypted with the encrypt command.

To clear the credentials, pass a quoted exclamation mark ("!") as either the credUserId or credPassword values.

[-{add_group | a_grp} value]*

Create a group. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

groupId~name~groupType~webAddress
~location~officePhoneNumber~cellPhoneNumber
~pagerNumber~faxNumber~emailAddress
~businessAddress~organization

Each entry in the value must contain at least one separator character (~).

[-{add_user | a_usr} value]*

Create a user. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

userId~password~firstName~lastName
~title~jobTitle~homePhoneNumber~imName
~location~officePhoneNumber~cellPhoneNumber
~pagerNumber~faxNumber~emailAddress
~businessAddress~organization

Each entry in the value must contain at least one separator character (~). The password value can be specified as plain text or as text encrypted with the encrypt command.

[-{add_users_group | a_usr_grp} value]*

Add users to groups. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

userId[~userId]*$groupId[~groupId]*

The value must contain at least one sublist separator character ($). For sublists that contain multiple entries, each entry of one sublist is assigned to each entry of the other sublist.

[-{assign_group_roles | grp_roles} value]*

Assign roles to groups. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

groupId[~groupID]*$roleID[~roleID]*

The value must contain at least one sublist separator character ($). For sublists that contain multiple entries, each entry of one sublist is assigned to each entry of the other sublist.

[-{assign_user_roles | usr_roles} value]*

Assign roles to users. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

userId[~userId]*$roleId[~roleId]*

The value must contain at least one sublist separator character ($). For sublists that contain multiple entries, each entry of one sublist is assigned to each entry of the other sublist.

[-{assign_project_group_roles | proj_grp_roles} value]

Assign project group roles. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

projectName[~projectName]*$groupId[~groupId]*$roleId

The value must contain 2 sublist separator characters ($). For sublists that contain multiple entries, each entry of each sublist is assigned to each entry of the other sublists. The projectName values are case sensitive and must be in the format of DSServer/projectID, where DSServer must match the registered engine name. The name could be registered as the short host name or as the fully qualified host name with a domain. Whichever way it is registered, this is how it must be specified here. You can see a list of project names by using the -list DSPROJECTS option. The roleID must be an InfoSphere® DataStage® project role.

[-{assign_project_user_roles | proj_usr_roles} value]

Assign project user roles. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

projectName[~projectName]*$userId[~userId]*$roleId

[-authfile value]

Use the specified credentials file for the credentials of the administrator user ID running this command. Either the -authfile option or the -user and -password options are required.

[-{datastage_server | ds_svr} value]

Specifies the host name or configured alias name of the InfoSphere Information Server engine to use when setting the shared registry and when setting and getting the engine credentials. The value cannot contain a forward slash character (/). The value is validated against the engines that are registered with IBM® InfoSphere Information Server.

You must specify this -datastage_server parameter when you use following parameters:

-add_ds_credentials
-get_default_ds_credentials
-set_default_ds_credentials
-set_shared_registry

[-{delete_group | del_grp} value]

Delete existing groups. Specify the value as one string with the following syntax:

groupID[~groupID]*

You will be prompted to confirm the delete unless the -force option is specified. If a specified group does not exist, it will be ignored.

[-{delete_user | del_usr} value]

Delete existing users. Specify the value as one string with the following syntax:

userID[~userID]*

You will be prompted to confirm the delete unless the -force option is specified. If a specified user does not exist, it will be ignored.

[-{details | det}]

Provides additional information in the output when used with the -list option for USERS and GROUPS.

For users, the following information is provided:

detailed user information
groups that the user is a member of
suite and product roles that are assigned to the user
mapped engine credentials for this user

For groups, the following information is provided:

detailed group information
suite and product roles that are assigned to the group

[-{file | f} value]

Read the commands from a file. When you specify the -file option, other specified command options are ignored. See the end of this topic for an example of how to use the -file option. If you intend to load a large number of users with the file option, break them up so that each file contains about 100 users to avoid server time outs.

In a file, each command must be specified on a separate line and must end with a semicolon (;). This is true even for command options that have additional required options, such as -separator, -sublist_separator, -datastage_server, -details, and -force. The commands with these options must also each be on a separate line, and the line must be terminated with a semicolon. The value specified for these applies to all commands included in the file.

[-force]

Suppress the confirmation prompt for the -delete_user and -delete_group options.

[-{get_default_ds_credentials | get_dflt_ds_cred}]

Retrieve the default credentials for the InfoSphere Information Server engine that is specified with the -datastage_server option.

[-{help | ?}]

Display usage information.

[-host value]

The host name of the services tier computer. The default value is localhost.

[-list value]

List the existing users, groups, InfoSphere DataStage projects, or system-defined roles. Specify the value as one string with the following syntax:

type[~type]*

The type values can be USERS, GROUPS, ROLES, DSPROJECTS, or ALL.

[-{log | l} value]

Print all runtime output to the specified file.

[-{logerror | error} value]

Print all ERROR and FATAL runtime logging messages to the specified file.

[-{loginfo | info} value]

Print all INFO, WARN, DEBUG, and TRACE runtime logging messages to the specified file.

[-{loglevel | level} value]

The level at which runtime logging messages are enabled. The value can be FATAL, ERROR, INFO, WARN, DEBUG, TRACE, or ALL.

[-{password | pwd} value]

The password for the suite administrator user ID running this command.

[-port value]

The HTTPS port of the services tier computer. The default value is 9443.

[-primary]

Log in to the primary services host if one is available. If this option is used, the -host and -port options are ignored.

[-{remove_group_roles | rm_grp_roles} value]

Removes roles from groups. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

groupId[~groupId]*$roleId[~roleId]*

The value must contain at least one sublist separator character ($). For sublists that contain multiple entries, each entry of the role sublist is removed from each entry of the group sublist.

[-{remove_project_group_roles | rm_proj_grp_roles} value]

Removes project user roles. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

projectName[~projectName]*$groupId[~groupId]*$roleId[~roleId]*

For sublists that contain multiple entries, each entry of the group and role sublists are removed from each entry of the project sublist. The projectName values are case sensitive and must be in the format of DSServer/projectID, where DSServer must match the registered engine name. The name could be registered as the short host name or as the fully qualified host name with a domain. Whichever way it is registered, this is how it must be specified here. You can see the list of project names by using the -list DSPROJECTS option.

[-{remove_project_user_roles | rm_proj_usr_roles} value]

Removes project user roles. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

projectName[~projectName]*$userId[~userId]*$roleId[~roleId]*

For sublists that contain multiple entries, each entry of the user and role sublists are removed from each entry of the project sublist. The projectName values are case sensitive and must be in the format of DSServer/projectID, where DSServer must match the registered engine name. The name could be registered as the short host name or as the fully qualified host name with a domain. Whichever way it is registered, this is how it must be specified here. You can see the list of project names by using the -list DSPROJECTS option.

[-{remove_user_roles | rm_usr_roles} value]

Removes roles from users. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

userId[~userId]*$roleId[~roleId]*

The value must contain at least one sublist separator character ($). For sublists that contain multiple entries, each entry of the role sublist is removed from each entry of the user sublist.

[-{remove_users_group | rm_usr_grp} value]

Removes users from groups. Multiple instances of this option can be specified. Specify the value as one string with the following syntax:

groupId[~groupId]*$userId[~userId]*

The value must contain at least one sublist separator character ($). For sublists that contain multiple entries, each entry of the user sublist is removed from each entry of the group sublist.

[-{results | res} value]

Print all the runtime output to the specified file.

[-{separator | sep} value]

Overrides the default list separator (~). The value can be any single character other than those listed:

^ (caret)
& (ampersand)
* (asterisk)
- (dash or hyphen)
| (pipe)
" (quotation mark)
< (less than)
> (greater than)

Linux cue graphic UNIX cue graphic If you want to specify a character value that has special meaning to the command shell (for example, # or !), specify the character in single quotes, such as: -separator '#'. Then, when used in the command shell, ensure that the special character is escaped, such as \#, or specify the list within quotation marks.

[-{set_default_ds_credentials | set_dflt_ds_cred} value]

Sets the default InfoSphere Information Server engine credentials. Specify the value as one string with the following syntax:

credUserId~credPassword

The value must contain at least one separator character (~). The credentials are set for the server specified by the -datastage_server option. The specified engine must be registered with InfoSphere Information Server. The password value can be specified as plain text or as text encrypted with the encrypt command.

To clear the default credentials, pass a quoted exclamation mark ("!") as either the credUserId or credPassword values.

[-{set_shared_registry | shr_reg} {ON|OFF}]

Sets the flag that indicates whether InfoSphere Information Server and InfoSphere DataStage share the same user registry. The valid values are ON or OFF.

[-{sub_list_separator | sub_list_sep} value]

Overrides the default list separator ($). The value can be any single character other than those listed:

^ (caret)
& (ampersand)
* (asterisk)
- (dash or hyphen)
| (pipe)
" (quotation mark)
< (less than)
> (greater than)

[-{update_group | upd_grp} value]*

Update an existing group. Multiple instances of this option can be specified. The group being updated must exist. Specify the value as one string with the following syntax:

groupId~name~groupType~webAddress
~location~officePhoneNumber~cellPhoneNumber
~pagerNumber~faxNumber~emailAddress
~businessAddress~organization

Each entry in the value must contain at least one separator character (~). A value of ‘!‘ specified for a group setting will clear the setting.

[-{update_user | upd_usr} value]

Update an existing user. Multiple instances of this option can be specified. The user being updated must exist. Specify the value as one string with the following syntax:

userId~password~firstName~lastName
~title~jobTitle~homePhoneNumber~imName
~location~officePhoneNumber~cellPhoneNumber
~pagerNumber~faxNumber~emailAddress
~businessAddress~organization

Each entry in the value must contain at least one separator character (~). A value of ‘!‘ specified for a user setting other than password will clear the setting. The password value can be specified as plain text or as text encrypted with the encrypt command.

[-{user | usr} value]

The suite administrator user ID running this command. Either the -authfile option or the -user and -password options are required.

[-{verbose | v}]

Display detailed runtime output other than logging messages.

Example: Writing a script to quickly add users to a typically used project

Suppose you regularly add new InfoSphere DataStage users to multiple projects with various group assignments. You could create a script for these operations:

#!/bin/sh
echo Adding a typical DataStage user with the default password.

npass={iisenc}HEf6s6cG+Ee6NdGDQppQNg==
nrole=DataStageUser
prole=DataStageOperator
cmd=/opt/IBM/InformationServer/ASBNode/bin/DirectoryCommand.sh
af=/opt/IBM/InformationServer/ASBNode/conf/isadmin.credentials

echo New user ID to create:
read nuser
echo First name for the user:
read fname
echo Last name for the user:
read lname

$cmd -authfile $af -a_usr $nuser~$npass~$fname~$lname
$cmd -authfile $af -usr_roles $nuser\$$nrole
$cmd -authfile $af -a_usr_grp $nuser\$dsusr~qsusr
$cmd -authfile $af -proj_usr_roles \
HOSTNAME/DSProd~HOSTNAME/DSDev\$$nuser\$$prole

@echo off
setlocal

echo Adding a typical DataStage user with the default password.

set npass={iisenc}HEf6s6cG+Ee6NdGDQppQNg==
set nrole=DataStageUser
set prole=DataStageOperator
set cmd=C:\IBM\InformationServer\ASBNode\bin\DirectoryCommand.bat
set af=C:\IBM\InformationServer\ASBNode\conf\isadmin.credentials

echo New user ID to create
set /p nuser="--> "
echo First name for the new user
set /p fname="--> "
echo Lastname for the new user
set /p lname="--> "

call %cmd% -authfile %af% -a_usr %nuser%~%npass%~%fname%~%lname%
call %cmd% -authfile %af% -usr_roles %nuser%$%nrole%
call %cmd% -authfile %af% -a_usr_grp %nuser%$dsusr~qsusr
call %cmd% -authfile %af% ^
-proj_usr_roles HOSTNAME/DSProd~HOSTNAME/DSDev$%nuser%$%prole%

In this example, the following values would need to be replaced with actual values. The groups and projects must be created before running the command.

dsusr and qsusr: groups that the user is being added to
HOSTNAME: the registered engine host name or configured DSAlias for the engine.
DSProd and DSDev: project names that the user is being added to as an InfoSphere DataStage operator.

This script would create the specified user ID and assign the default password, which has been encrypted with the encrypt command and pasted into the script. (You could send e-mail with the plain text password to the user with a request to change it upon first login.) The DirectoryCommand then assigns the user to the DataStageUser role. It then assigns the user to the dsusr and qsusr groups. It then assigns the user to the DSProd and DSDev projects on the InfoSphere Information Server engine, indicated here as HOSTNAME. And, in the same command, assigns the user to the DataStageOperator project role.

Example: Using the -file option to migrate users

Create the list of users:

DirectoryCommand -authfile admin.creds
 -host original_services_tier_host
 -port original_services_tier_port
 -list ALL -details -results userlist.txt

Edit the list of users into a format that the -file option can use:

-add_user TestOper~TempP4ss~TestOperFirst~TestOperLast;
-add_user TestSuOper~TempP4ss~TestSuOperFirst~TestSuOperLast;
-add_user TestProMan~TempP4ss~TestProManFirst~TestProManLast;
-add_user adminUser~TempP4ss~adminUserFirst~adminUserLast;
-add_user wasUser~TempP4ss~wasUserFirst~wasUserLast;
-assign_user_roles TestOper$SuiteUser~DataStageUser~FastTrackUser~GlossaryUser;
-assign_user_roles TestSuOper$SuiteUser~DataStageUser;
-assign_user_roles TestProMan$SuiteUser~DataStageUser;
-assign_user_roles adminUser$SuiteUser~DataStageAdmin;
-assign_user_roles wasUser$SuiteAdmin~DataStageAdmin;
-add_group TestGroup~TestGroup~TestGroup;
-add_users_group TestOper~TestSuOper~TestProMan~adminUser$TestGroup;
-proj_usr_roles dshost/dstage1~dshost/dstage2$TestOper$DataStageOperator;
-proj_usr_roles dshost/dstage1~dshost/dstage2$TestSuOper$DataStageSuperOperator;
-proj_usr_roles dshost/dstage1~dshost/dstage2$TesProMan$DataStageProductionManager;

Run the directory command to migrate the users to the new server:

DirectoryCommand -authfile admin.creds -host new_server
-port new_port -file userlist.txt