ACEBulkAdmin Guide

Professional Services
Custom Application Guide

ACEBulkAdmin
Revision: Issued: Revised:
2.2.16 February 15, 2001 22, June, 2011
Copyright 2005 by RSA Security Inc., Bedford, Massachusetts. All rights reserved.
RSA Security
Confidence Inspired
RSA Professional Services
Custom Application Guide.
TABLE OF CONTENTS CUSTOM APPLICATION GUIDE ................................................................................ 1 INTRODUCTION ................................................................................................................ 5 Security Considerations .............................................................................................. 5 Operating Systems Supported ..................................................................................... 5 ACE/Server Versions Supported ................................................................................. 5 Admin API Limitations................................................................................................ 5 Common to all versions .............................................................................................. 5 ACE/Server v4.1 .......................................................................................................... 6 ACE/Server v5.0 .......................................................................................................... 6 ACE/Server v5.1 .......................................................................................................... 6 INSTALLATION AND OPERATING INSTRUCTIONS .............................................................. 6 Operating System Independent Requirements ............................................................ 7 Microsoft Windows Specific Requirements ................................................................. 7 UNIX Specific Requirements....................................................................................... 7 Operating Instructions ................................................................................................ 8 COMMAND-LINE OPTIONS ................................................................................................ 9 INPUT FILE PROCESSING ................................................................................................ 14 Implementation ......................................................................................................... 14 Preparing the Datafile .............................................................................................. 15 Header lines .......................................................................................................... 15 Field Definitions ................................................................................................... 17 Input Parameter File................................................................................................. 22 Command Reject File ................................................................................................ 22 Reporting and logging .............................................................................................. 23 Default File Names ................................................................................................... 23 Input Template Files ................................................................................................. 24 Sample CSV Format Data ......................................................................................... 24 Sample Quoted Text Format Data ............................................................................ 24 PASSWORDS ................................................................................................................... 24 FUNCTION DESCRIPTIONS .............................................................................................. 26 ADD FUNCTIONS ......................................................................................................... 26 Add User ................................................................................................................... 26 Add User and Token.................................................................................................. 26 Add User and Token Automatic ................................................................................ 27 Add User and Password............................................................................................ 27 Add User Remote ...................................................................................................... 28 Add Token to User .................................................................................................... 29 Add Token to User Automatic ................................................................................... 29 Add Password to User .............................................................................................. 30 Add User to Group .................................................................................................... 30 Add User to Client .................................................................................................... 31 Add Group ................................................................................................................. 31 Add Group to Client .................................................................................................. 31
ACEBulkAdmin Guide.doc
2 / 94
Revised: June 22, 2011
Add Group to Site...................................................................................................... 31 Add AgentHost (Version 5.0 and later)..................................................................... 32 Add Secondary Node to AgentHost (Version 5.0 and later) ..................................... 33 Add Client ................................................................................................................. 34 Add Client to Site ...................................................................................................... 35 Add Site ..................................................................................................................... 35 Add Client Extension Data........................................................................................ 35 Add Group Extension Data ....................................................................................... 35 Add Site Extension Data ........................................................................................... 36 Add Token Extension Data........................................................................................ 36 Add User Extension Data.......................................................................................... 36 Add System Extension Data ...................................................................................... 37 Assign Profile ............................................................................................................ 37 CHANGE FUNCTIONS ................................................................................................... 38 Change or Add User ................................................................................................. 38 Change or Add User and Token................................................................................ 38 Change or Add User and Password ......................................................................... 39 Change User Data .................................................................................................... 40 Change User Remote ................................................................................................ 40 Change PIN Status .................................................................................................... 41 Change Token Status................................................................................................. 42 Change Token Status eXtended ................................................................................. 42 Change Temporary User........................................................................................... 43 Change Token (Immediate) ....................................................................................... 43 Change Token (on First Use of New Token) ............................................................. 43 Change Groups Site ................................................................................................. 44 Change Clients Site ................................................................................................. 44 Change Client Extension Data.................................................................................. 44 Change Group Extension Data ................................................................................. 44 Change Site Extension Data ..................................................................................... 45 Change Token Extension Data.................................................................................. 45 Change User Extension Data.................................................................................... 45 Change or Add User Extension Data........................................................................ 45 Change System Extension Data ................................................................................ 46 Set Agent Host (Version 5.0 and later) ..................................................................... 46 Set Emergency Access Fixed ..................................................................................... 47 Set Emergency Access OTP ...................................................................................... 48 Set Emergency Access OFF ...................................................................................... 49 Update User Data ..................................................................................................... 49 DELETE FUNCTIONS .................................................................................................... 51 Delete Admin Privileges ........................................................................................... 51 Delete User from Group ........................................................................................... 51 Delete User from Client ............................................................................................ 51 Delete Group from Client ......................................................................................... 51 Delete Group from Site ............................................................................................. 52 Delete Client from Site .............................................................................................. 52
3 / 94
Delete Group ............................................................................................................. 52 Delete Client ............................................................................................................. 53 Delete Secondary Node from AgentHost (Version 5.0 and later)............................. 53 Delete Site ................................................................................................................. 53 Delete Client Extension Data.................................................................................... 53 Delete Group Extension Data ................................................................................... 54 Delete Site Extension Data ....................................................................................... 54 Delete Token ............................................................................................................. 54 Delete Token Extension Data.................................................................................... 54 Delete User Extension Data...................................................................................... 55 Delete System Extension Data .................................................................................. 55 Delete User ............................................................................................................... 55 Rescind Token (Version 4.0 and later) ..................................................................... 55 Unassign Profile ....................................................................................................... 56 Unassign Token ......................................................................................................... 56 LIST FUNCTIONS .......................................................................................................... 57 Set Sort Order ........................................................................................................... 57 List Token Data (Depreciated) ................................................................................. 58 List and/or Delete Log Data ..................................................................................... 58 List History................................................................................................................ 60 List Secondary Nodes for Agent Host (Version 5.0 and later) ................................. 61 List User Info by Field .............................................................................................. 62 List User Info for User .............................................................................................. 67 List Token Info by Field ............................................................................................ 67 List Token Info For TokenSerial ............................................................................... 72 MULTIPLE TOKEN ACTION ............................................................................................. 73 Multiple Softtoken Deployment (ACE Server Version 5.1 and later) ....................... 73 Multiple Token Assignment ....................................................................................... 76 Multiple Token Disable/Rescind ............................................................................... 79 Multiple Token Replacement..................................................................................... 82 GENERAL FUNCTIONS ................................................................................................. 86 Change Input Format ................................................................................................ 86 Change Results File Name ........................................................................................ 87 Quit ........................................................................................................................... 87 Run Script command ................................................................................................. 88 COMMAND TABLE (ALPHABETIC LISTING OF COMMANDS) ............................................ 89
4 / 94
Introduction
This document defines the capabilities of a custom application called ACEBulkAdmin. This application has been developed using RSAs ACE/Server Admin APIs. This utility enables ACE/Server administrators to do administration from the command line or in background mode. ACEBulkAdmin implements a majority of the functions available through the ACE/Server Administration GUI. ACEBulkAdmin provides a mechanism to perform ADD, CHANGE and DELETE operations using data from a flat (CSV, Comma Separated Variable or double-quoted text format) input file. ACEBulkAdmin also allows an ACE/Server administrator to LIST tokens and users that are selected based on specified criteria.
Security Considerations
It should be noted that the appropriate operating system access rights should be used to protect this application. Use of this utility by unauthorized persons could lead to loss of data and denial of service to affected users.
Operating Systems Supported

ACEBulkAdmin supports all systems supported by respective ACE Server releases.
ACE/Server Versions Supported

All ACE Server versions from 4.1 through 6.1.2 are supported. Functionality supported on later releases will produce error messages if run on an earlier release.
Admin API Limitations

The ACE/Server Admin API currently has a number of limitations that vary depending on the version of ACE/Server:
Common to all versions

Administrator status of a user cannot be modified. Realming cannot be administered. RADIUS Profiles cannot be administered. Task Lists cannot be administered. Global System parameters cannot be administered. Client names/IP addresses must be resolvable either by a local Hosts file, NIS/WINS or DNS. Clients with Secondary Nodes cannot be deleted until all Secondary Nodes have been deleted manually using the standard ACE/Server sdadmin or Remote Admin packages.
5 / 94
ACE/Server v4.1
Static passwords can be added to users, but once added there is no mechanism to delete the password. The password can now be changed using the Change PIN Status function. It is also now possible to delete a user with a password using the Delete User function only. The limitation that previously did not allow all Tokens to be removed from the User without also deleting the User is now resolved with the introduction of a new function Rescind Token in ACE/Server v4.0 ListTokensByField. This command is the token version of the ListUsersByField command released with version 4.0. If the database if 5.0 or later, ACEBulkAdmin will use this command where appropriate; otherwise, most of the functionality of this command has been coded into ACEBulkAdmin for use in pre version 5.0 databases. It should be understood that this approach is significantly slower than the API command and may not be usable in large pre 5.0 databases.
ACE/Server v5.0
AgentHost commands have been added in version 5.0. These commands super class many of the client commands. If the current database if pre version 5.0, use the client commands. In this version of ACEBulkAdmin, a new command line option (-sv <version>) has been added. This is most likely not a useful feature for clients, but is useful for RSA testing. Unless one is instructed by RSA, please do not use this command line option.
ACE/Server v5.1
In version 5.1 and above, the apidemon is expected to be in ace/utils/toolkit rather than in the admin application's directory
Installation and Operating Instructions

ACEBulkAdmin is a script and is interpreted by tcl-sd.exe. Tcl-sd.exe must be located in the same directory as apidemon.exe. Tcl-sd.exe and apidemon.exe are installed in c:/ace/utils/tcl/bin by default. This location may be different depending on where ACE/Server was installed. The ACEBulkAdmin.tcl script file may be installed in any location, however it is suggested that it be installed in the ACE/Server utils/tcl/bin directory. If it is installed in any directory other than the default directory, it will be necessary to fully qualify file path names. In version 5.1, the apidemon.exe has been moved to the toolkit folder, but tcl-sd is still in the utils/tcl/bin folder. ACEBulkAdmin.tcl may be in any directory but it still is easier to run from the same directory as tcl-sd.exe or make ace/utils/tcl/bin the current directory.
6 / 94
Operating System Independent Requirements

The ACEBulkAdmin application must have a copy of the correct apidemon executable in the same directory as tcl-sd.exe. The build version of ACEBulkAdmin can be determined using the v option. The user account executing ACEBulkAdmin must have ACE/Server administrator rights for the scope of data being accessed. The user account executing ACEBulkAdmin must have write permission for the directory containing the ACEBulkAdmin.tcl script file and the apidemon.exe executable. Write permission is also necessary for any target output files. ACE/Server database brokers must be running before the application is used. The easiest way to confirm this is to open a standard local or remote admin session.
Microsoft Windows Specific Requirements

The VAR_ACE environment variable is required for the TCL Interpreter (tcl-sd.exe) and will need to be assigned prior to running the application. This environment variable must contain the path of the ACE/Server data directory. As of version 2.1.0, this variable is no longer required.
UNIX Specific Requirements

Before using the TCL environment in UNIX, it must be set up. The setup instructions differ between ACE Server 4.1 and ACE Server 5.0 as shown below: 1. ACE Server 4.1 a. Uncompress and extract the common.Z file in the utils directory. This has two subdirectories, bin and lib b. Run the setup program and set the variables as shown in the output. 2. ACE Server 5.0 a. The common.Z file does not exist because the bin and lib directories are already set up on the ACE Server. b. Run the utils/admenv program. This will return the necessary environment variables that need to be set up in order to run the TCL environment as shown in this screen shot:
7 / 94
3. In either 4.1, 5.0.x, or 5.1, it is recommended that these variables be set in the users .profile (Bourne shell), .kshrc (Korn shell) or .cshrc (C Shell) files. Shown below is an example of how to set a variable for each type of shell: Bourne Shell (/bin/sh): VAR_NAME=var_value; export VAR_NAME Korn Shell (/bin/ksh): export VAR_NAME=var_value C Shell (/bin/csh): setenv VAR_NAME var_value 4. Test the TCL implementation: a. Go to the utils/tcl/bin directory and run ./tcl-sd test.tcl. This should be done as a user who has administrative rights to the ACE database. b. The output should list all of the agent hosts (clients in 4.1) in the ACE Server database.
Operating Instructions
To execute the utility, run either tcl-sd.exe or wish-sd.exe and include ACEBulkAdmin.tcl as a command line parameter along with command-line options, e.g. ./tcl-sd ./ACEBulkAdmin.tcl -i inputfile.csv
8 / 94
Command-line options
The ordering of the parameters is not critical. One or more spaces are required between the parameter key and its value. Usage: ACEBulkAdmin or ACEBulkAdmin -v or ACEBulkAdmin gta <tempname> or ACEBulkAdmin gtc <tempname> or ACEBulkAdmin ini <inifile> or ACEBulkAdmin [-debug] [-format <dateformat>] [-g] [-gdir <directory>][-i <datafile>] [-loggingoff] [-m <value>] [-newlog] [-nolog] [-o <results file>] [-p <value>] [-r <results file>] [-rej <command reject file>] [-verbose] [-x <value>] [] denotes an optional parameter. <> denotes a value. | denotes a choice The characters [, ], <, & > are only used to clarify the usage of the parameters and should not be included in the actual data. <null> Executing ACEBulkAdmin with a null parameter list will display a usage report on stderr.
-debug
Setting this option disables all calls to the ACE/Server API and forces a successful return result. This allows processing an input file with out making any changes to the database or testing various features when a database is not present. Debug option will allow validating an input file for required fields without making changes to the database. Please, note that the debug option does not perform any of the validations performed by the ACE/Server, such as rejecting an attempt to add a user that already exists in the database. -format <mdy | dmy | ymd | ydm> This option is used to inform ACEBulkAdmin of date layouts used in the ACE/Server database. The default is mdy. This option is only meaningful for the ltd (list token data) command.
ACEBulkAdmin Guide.doc 9 / 94 Revised: June 22, 2011
-g Turns on the option to output SecurID Software Token database files for tokens assigned during ACEBulkAdmin processing. Files are named based on the default login name or token serial number of the user, and are given the extension .sdtid. For example, if the default login name is juser, then the filename will be juser.stdid. By default, files are stored in the current directory, but this may be changed using the gdir option. -gdir <dirname> specifies that SecurID Software Token database files should be stored in the directory specified by <dirname>. The g option must also be specified to cause the database files to be saved. -gta <tempname> Generate a quoted ASCII (quoted text) template file. This file contains a header line and a line with the correct number of empty quoted strings. One or more comment lines are also emitted. This can be used as the base file for developing a quoted text input file. <tempname> is a fully qualified path and file name to be used for this file and must be less than 128 characters. -gtc <tempname> Generate a CSV template file. This file contains a header line and a line with the correct number of empty columns. One or more comment lines are also emitted. This file can be used as the base for developing a CSV input file. <tempname> is a fully qualified path and file name to be used for this file and must be less than 128 characters. -i <datafile> | stdin where <datafile> is the path to the CSV or Quoted Text ASCII formatted input file. The pathname must be less than 128 characters. The literal stdin may be supplied to redirect system standard input into ACEBulkAdmin. The quit command is used to terminate a standard input file. -ini <inifile> where <inifile> is the path to the input parameter file. The pathname must be less than 128 characters. If this parameter is used, it must be the first parameter on the command line. All other command line parameters will be ignored. This is a text file containing input parameters and is formatted as described below. -m <0 | 1 | 2 | 3> The default messaging level is 0, log all messages. Levels 1, 2 and 3 all log BOJ, EOJ and application error messages and do not log information messages. In addition, level 1 logs successful command messages, level 2 logs failed command messages and level 3 logs successful and failed command messages.
10 / 94
Msg Type / Level
Boj Eoj Info Error Successful Failure
0 Yes Yes Yes Yes Yes Yes
1 Yes Yes No Yes Yes No
2 Yes Yes No Yes No Yes
3 Yes Yes No Yes Yes Yes
An example of each message type:

BOJ Info Error : 2001-02-16 14:31:12 - RSA ACEBulkAdmin version 1.0, February, 2001; Input = new.csv : : 2 - processCommand 4 - addUser - Log File Opened - couldn't open "newFile.csv": no such file - Unknown Action field: "xyz" - CB1, BigFoot2
Failure: Line Success: Line EOJ
: 2001-02-16 14:31:18 - Terminating
-loggingoff Turns off ACE/Server logging of database updates. This option can be used to improve performance. However, the audit trail of database changes is lost. -newlog This option forces ACEBulkAdmin to create a new log as opposed to the default option that appends new log information to any previous log information. -nolog Turns off all ACEBulkAdmin logging. ACE/Server logging is not affected. -o <log file> | stderr | stdout where <log file> is the path to a file for storing the log output. If not specified the message information will be printed to the standard output channel, where it may be redirected using standard operating system conventions. The pathname must be less than 128 characters. The output filename is optional, if not specified the default is ACEBulkAdminlog.txt and will be placed in the current directory. Either the literal stderr or stdout may be used to redirect log output to system standard error or standard output files. -p <1 | 2 | . . . 3600> Enables the displaying of a progress report and the time delay in seconds between updates. If enabled, the progress report will display on stderr. -r <results file> | stdout | stderr where <results file> is the path and file name for storing the results of a List command. This file is overwritten on each execution of ACEBulkAdmin. If this option is not specified a default file name of
11 / 94
ACEBulkAdminResults.txt and will be created in the current directory. . Either the literal stderr or stdout may be used to redirect log output to system standard error or standard output files. -rej <command reject file> where <command reject file> is a fully qualified path and file name to be used for this file and must be less than 128 characters. This is a file containing rejected input records in the same format as the input file. If this option is not specified a default file name of ACEBulkAdminRejects and will be created in the current directory. If the default file name is used, the file extension of the command input file would be appended to it. -s <character> Change default group and site separator character. Supplied value may be quoted to avoid command line issues, i.e. # is OK, but | is necessary to avoid conflicting with command line pipe symbol. -sv <version> Overrides the custom admin API version number with the supplied version -v Returns ACEBulkAdmin version number. -verbose Enable enhanced logging. This function is normally only used for debugging. It mostly generates Information message types and records program flow. Use of the option can severely degrade program performance. -x <0 | 1> Defines if a datestamp is inserted into the name of the following files: log file (-o), reject file (-rej), results file (-r) and the software token database files (-gdir). If not specified, default is 0.
Caution: Redirecting the ACEBulkAdmin log and results files to stderr and stdout may cause serious performance issues and in some instances cause a system crash. This is especially true for users with vary large databases. Inter-process piping may exceed system queuing limits. Interference can be decreased by disabling ACE and ACEBulkadmin logging, but this should only be done when it has been established that these functions are not needed. Security and accounting auditors get particularly nervous when logging functions are disabled. A worst case scenario dry run should be performed to insure that performance and operation are acceptable. Also, large ACEBulkAdmin runs against a single ACE/Server may degrade authentication performance. Consider adding one or more replica
12 / 94
servers for authentication, performing administrative functions only on the master.
13 / 94
Input File Processing

Implementation
The input file will be processed in sequential order. It is up to the ACE Administrator to arrange transactions in logical order. For example, if a user is being added and the group field contains an entry, then the group must already exist for the association to be successful. No attempt will be made to add the group from the add user command. Each command will consist of an action code, required fields and zero or more optional fields. Commands consist of two or more character codes. For a command to succeed, all required fields must be present, although it may still fail for other reasons. Some optional fields may cause a subordinate command to be executed. Failure of the subordinate command will not cause the primary command to fail. An example of this is adding a user and a group association. If the user add is successful, then a group association will be attempted. If the group association fails it will be logged, but the add user still stands. For example, in the following input file, we are trying to add William Clinton as a new user. In addition we would like to make William Clinton a member of BigGroup6
Input: Action,LastName,FirstName,DefLogin,,,,,,,GrpName au,Clinton,William,CIC,,,,,,,BigGroup6
Examining the log, we see that the primary command, adding William Clinton as a new user was successful, however, the secondary command of making William Clinton a member of BigGroup6 failed because there is no such group. If we examine the database, we will find that William Clinton is now a valid user, but he is not a member of BigGroup6. In other words, the primary command still stands, but the secondary command does not.
Log: BOJ : 2001-02-15 15:36:54 - RSA ACEBulkAdmin version 1.0, February, 2001; Input = testaubg.csv Info : - Log File Opened Success: Line 2 - addUser - CIC, Clinton Failure: Line 2 - addUserToGroup - CIC, BigGroup6 ; Group Not Found Info : - End of input file: 2 of 2 processed Info : - Closing input file Info : - Closing rejected actions file Info : - Log file Closed EOJ : 2001-02-15 15:36:54 - Terminating
Examining the command reject file, we see the original input line and a comment specifying that the group was not found.
Command Reject file: Action,LastName,FirstName,,,,,,,GrpName // Line 2: Sd_AddLoginToGroup Error Group Not Found au,Clinton,William,CIC,,,,,,,BigGroup6
14 / 94
To correct the error, change the AU action to AG in order to add the group. Then duplicate the line and change the AG to AUG in order to add the user to the group. Submit this file as input to the next ACEBulkAdmin run.
Corrected input file:: Action,LastName,FirstName,,,,,,,GrpName // Line 2: Sd_AddLoginToGroup Error Group Not Found ag,Clinton,William,CIC,,,,,,,BigGroup6 aug,Clinton,William,CIC,,,,,,,BigGroup6
The AG command will ignore the unused fields (LastName, FirstName and DefLogin) and create a group titled BigGroup6. The AUG command will add William Clinton to BigGroup6 because William is a valid user (from the earlier run) and BigGroup6 is now a valid group from this run.
(Note: Minor editing was performed on the above examples to facilitate fitting them into this document)
A table of currently supported commands can be found at the end of this document.
Preparing the Datafile

The data file may either be in CSV (Comma Separated Variable) or Quoted Text format. In CSV format, a comma separates each data field with no double quotes (). In Quoted Text format each field is surrounded by double quotes and then separated by a space. For either format a comma is an illegal character within a field. The best environment to create the data file is a Spreadsheet or Word Processor application that is capable of saving in CSV format, e.g. Microsoft Excel. It is not necessary for input lines to contain empty fields beyond the last significant data entry field. For example, addGroup (AG) need only have all fields through the GrpName field, whereas addSite (AS) would contain all fields because SiteName is the last possible field. The unused fields would be delimited by ,, (comma comma) for CSV files and (double quote double quote) for Quoted Text files. Comments may be placed anywhere in the input file. A comment is any line beginning with two forward slashes //. Header lines A header is used to indicate what data is present and what order it will appear in the input file. Header lines are optional, however if a header is present, it must be the first line of input and its first field must be Action or Action. All other fields and their position are optional. If a header line is not provided, the following header is assumed. Available field names: Action, LastName, FirstName, DefLogin, DefShell, TokSerial, ReplTokSerial, TokEnabled, SetPin, CreatePin, PinMode, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData, ExtnTable, SiteName, ClntType, ClntEncryption ,ClntFlags, AgentHostName, AgentHostAddress, AgentHostType, AgentHostEncryptionType, AgentHostFlags, ActingMaster,
15 / 94
ActingSlave, SharedSecret, SecondaryNodeName, SecondaryNodeAddress, AgentHostKey, ParameterType, ActionControl, SoftIDParams, SoftIDPW, RemoteAlias, RealmName, CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable, ProfileName, rangeMode, startRange, endRange, passWord, fileName, copyProtect, overOption, logFile, closeOption The header line is not case sensitive. For a quoted ASCII text file, the default header fields are the same as the above CSV header, however the field names would be bounded by quotes and they would be separated by a space, not a comma. Because a header line can only appear as the first line of input, it is in effect for the entire input file, unless it is replaced by a new header via the CIF command (Change Input Format). The CIF command may be issued in any position of the input file and may appear any number of times. Its only prerequisite is that it must always contain an action field. Any additional parameters must be picked from the available field names listed above. The action field, along with any other fields may be arranged in any order. Although not required, it is good programming practice to make the action field the first field of all input lines. If a CIF command positions the action field in other than the first field, then a subsequent CIF command would have to be carefully formatted in order to insure that the CIF action appears in the correct column. A CIF command is simply a header preceded by the command CIF. An example of a CIF command is: cif,action,grpname This would imply that all input following this CIF action would consist only of an action code followed by a grpname. This example would be useful if a large number of groups are to be created. It would only be necessary to provide the command, say AG and the groupname for each group to be created. Compatibility with ACE/Server version 5.0 required that new functionality be added to ACEBulkAdmin. New field labels have been added to accommodate the new functions. It should be pointed out, that four labels now have synonyms. Although the old label and its synonym represent essentially the same entity, they are not interchangeable. The old labels are used with the old functions and the new labels are used with the new functions. The reason for this is to keep ACEBulkAdmin aligned as closely as possible with the Administrative API. This can be a little disconcerting as the label AgentHostName would be used with AddAgentHost to establish a new agent host (previously client), however, ClentName would be used with DeleteClient. If we are adding and deleting the same entity, then AgentHostName and ClentName represent this entity to their respective functions. The function definitions below will list which labels should be used with each function. Each function is explained in detail below. The fields fall into two categories:
16 / 94
Required The function cannot be performed without this data and will return an error if missing. Optional The function will use the data if provided. Field Definitions These definitions are general in nature and tend to duplicate definitions used for the older BulkLoad (now depreciated) product. However, specific commands may use some fields in a non standard manner in order to keep the number of fields to a reasonable level. The SetPIN field is an example of such a definition. Although its intended use is for pin numbers for related commands, it is also used to supply passwords for password related commands. Action Action to perform. LastName Users real Surname or Family name, maximum 24 characters. FirstName Users real Christian or first name, maximum 24 characters. DefLogin Users default login or account name; used when assigning a user to a Group or Client where a Group/Client specific login name is not supplied, maximum 48 characters. DefShell Users default shell; used when assigning a user to a Group or Client where the Group/Client specific shell is not supplied, maximum 256 characters. TokSerial Token serial number, up to 12 numeric characters (0-9), leading zeros are optional. ReplTokSerial Replacement Token serial number, up to 12 numeric characters (0-9), leading zeros are optional. If only the Token Serial number is specified the Token will be replaced immediately. TokEnabled Post-assignment Token status, single character, 0 (zero) = disabled or 1 (one) = enabled. If not specified will default to 0 (disabled). Note, this action only affects the Token specified. Static passwords cannot be enabled/disabled. SetPin
17 / 94
Sets the PIN status: G, g or -1 = A random PIN is generated by the system and output to screen and/or logfile. C, c or 0 = New PIN Mode, PIN Cleared. N = New PIN Mode, Old PIN Required, not valid in Action = Add mode. Any other string value will attempt to set the PIN to that value. System PIN rules will govern the success of setting the PIN. This field is also used to supply a password for some of the password related commands. For the emergency access commands, this field is used to supply a password or it is a three-position field with the following format describing the format of the generated passwords: NnLnFn N - number of one time passwords (OTP) to issue. L - password length ( 4 8). F Flags
1 digits only 2 letters only 3 digits and characters only 4 punctuation only 5 digits and symbols only 6 letters and symbols only 7 letters, integers and symbols
CreatePin Sets the method of allocating a PIN when in New PIN Mode: System = System Generated random PIN. User = User Generated PIN. Either = System or User Generated, user decides at time of change. Case is not significant. If a password is being assigned, this field determines the validity period of the password. The format is DnHn, e.g. D90H0 = 90 days, D0H12 = 12 hours. If not specified, the default is 30 days. Days can range from 0 through 365 and hours can range from 0 through 23. For the emergency password commands, an L component may be present (DnHnLn). The L component represents the Number of hours until the
emergency access mode expires (default 24). RSA ACE/Server cannot accept onetime passwords with an expiration date of more than 210,240 hours (24 years). If the L component is greater than 0, the D and H components are ignored.
PinMode
18 / 94
Used to indicate whether or not new PIN mode should be set. GrpName Name of the Group to register the user in, maximum 48 characters.
Note: The ACE/Server and its API support two types of group names. GrpName may contain just a group name or a group name concatenated with a site name. The format of a concatenated group/site name is groupname<separator>sitename. The default separator character is '@'. Therefore the default form of this syntax is groupname@sitename. The concatenated form is the default with ACE/Server 5.x and above. To use the groupname-only form, the 'USESITE' parameter must be set false in an apidemon.ini file. To utilize an apidemon.ini file with AceBulkAdmin it must be placed in the same directory as the tcl interpreter (typically /ace/utils/tcl/bin). See the ACE Administration Toolkit Reference for more information.
GrpDefLogin Users login or account name for ACE/Agents that the specified Group is activated on, maximum 48 characters. If not supplied, DefLogin value will be used. GrpDefShell Users shell for ACE/Agents that the specified Group is activated on, maximum 256 characters. If not supplied, DefShell value will be used. ClntName Name of the Client (Agent) to register the user on, maximum 48 characters. ClntDefLogin Users login or account name for the specified Client, maximum 48 characters. If not supplied, DefLogin value will be used. ClntDefShell Users shell for the specified Client, maximum 256 characters. If not supplied, DefShell value will be used. ExtnKey Name of extension key in ACE/Server database, maximum 48 characters. ExtnData Data associated with the specified extension key, maximum 80 characters. ExtnTable This field is not used by ACEBulkAdmin. SiteName Name of the Site. ClntType Client platform type ClntEncryption
19 / 94
Client encryption type. When ever possible chose DES over SDI. ClntFlags Client properties. CompareField Used in the list commands to indicate which field to use as a filter/selector for report data selection. If this field is zero, or empty, the CompareType field is assumed to also be zero or empty. Consult the individual list command definitions for allowable entries for this field. CompareType Used in the list commands to indicate what type of comparison to apply to the CompareField. If this field is zero, or empty, the CompareField field is assumed to also be zero or empty. Consult the individual list command definitions for allowable entries for this field. CompareValue This field is used to supply values for list command filter/selector report data selection. Consult the individual list command definitions for allowable entries for this field. OutputOption This field is used to apply formatting and other options to the list commands. It is used to declare whether or not a header line should be output to the list and for version 5.0 and later, whether or not extended user fields should be output to the list. Consult the individual list command definitions for allowable entries for this field ExtnDataOption This field is used to indicate whether or not user extension data should be included in the list. Consult the individual list command definitions for allowable entries for this field MiscVariable This field is used in various commands and is used to supply miscellaneous information to the command. The definition of the contents of this field can be found in the specific command descriptions where it is declared. SoftIDParams This field is used by the add-token commands when a softID token seed record file is being created. When used, this field must contain three decimal digits that control the following seed file generation characteristics: Encryption Key Type: 0, 1 or 2 Copy Protection Flag: 0 or 1 Password usage and Interpretation method: 0, 1, 2, or 3 See the documentation for the Sd_MkSoftIDExt command in the cust_admin.pdf file in the Ace Server documentation folder.
Note: Using the SoftIDParams field for AES (128 bit) tokens will cause the seed file generation to fail. For AES tokens, use the Multiple SoftToken Deployment command.
SoftIDPW
20 / 94
This field is used by the add-token commands when a softID token seed record field is being created. When used, this field supplies a password to be used for the seed file encryption. See the documentation for the Sd_MkSoftIDExt command in the cust_admin.pdf file in the Ace Server documentation folder. RemoteAlias Used to provide an alias for default logons for remote users. RealmName Used to provide a realm name for remote user maintenance. ProfileName Used to provide a profile name during user profile maintenance
The following labels are for functions implemented by ACE/Server version 5.0 and later.
AgentHostName Name of the Agent to register the user on, maximum 48 characters. Version 5.0 synonym for ClntName. AgentHostAddress IP address of AgentHost. AgentHostType Agent platform type. Version 5.0 synonym for ClntType. AgentHostFlags Agent properties. Version 5.0 synonym for ClntFlags. ActingMaster Acting master for an agentHost. ActingSlave Acting slave for an agentHost. SharedSecret
The encryption key used to establish a connection between the RADIUS Server and the Agent Host.
SecondaryNodeName Node name to be assigned to an agentHost as a secondary node. SecondaryNodeAddress IP address of a SecondaryNodeName. AgentHostKey AgentHostName or AgentHostAddress of an existing AgentHost. ParameterType Used in some functions to indicate the contents of a specific parameter. For example, a value of 1 in ParameterType would indicate that the AgentHostKey contains an AgentHostName for the SetAgentHost function.
21 / 94
ActionControl Used in some functions to indicate what action a function is to perform. Frequently, ActionControl will contain a bit field, indicating multiple actions for a function.
Input Parameter File

Input parameter files may be created and used in place of command line arguments. The file is a text file consisting of command line parameters. Formatting is not important as long as the commands are correctly formatted. Commands may be placed on one or more lines. If the ini option is used, it must be the first option on the command line. Any additional options on the command line will be ignored. tcl-sd ACEBulkAdmin.tcl ini example.ini Listing of possible Example.ini: -i input.csv -newlog m 2 o goodOldLog -p 30 -r c:/results/tokenListResults.txt
Command Reject File
Each run of ACEBulkAdmin will produce a command reject file. Its name and location are configurable through command line entries. This file will contain a copy of each input line that fails for any reason. A comment line describing the reason the command failed precedes each entry in the command reject file and includes the line number of the associated input line. If a primary command succeeds and the secondary command fails (described above) the line will be entered into this file. The purpose of this file is to provide a convenient way of correcting input errors. To correct any input errors, simply edit this file, correct any error, and supply this file as input the next update. In cases where a primary command succeeded and a secondary command failed, the secondary portion of the command should be corrected and converted to primary command. This is because the old primary command most likely would not succeed the second time and the secondary command would not be attempted. Example listing from an ACEBulkAdminRejects file:
Action,LastName,FirstName,DefLogin,DefShell,TokSerial,ReplTokSerial, . . .
22 / 94
RSA Professional Services // Line 2: Unknown Action field: "xyz" xyz,/au,xya // Line 4: Sd_AddLoginToGroup Error Group Not Found au,BigFoot2, Clem, CB1,,,,,,,BigGroup // Line 5: Sd_EnableLoginOnClient Client Not Found au,BigFoot3, Hellen, hb,,,,,,,,,,somemachine-pc.securitydynamics.com
Reporting and logging

In addition to ACE/Server logging and reporting, ACEBulkAdmin will produce an optional log and a standard command reject file. The command reject file is defined, along with an example of its contents, above. Logging functions are explained in the above command line options section. The -verbose logging function is mainly used in debugging problems. It mainly issues Info type log messages. The Boj and Eoj type log messages should need no explanation. The errMsg type is caused by application type errors such as invalid file names and directories and command line errors. Success and Failure are reserved for easy identification of the final result of a command or a secondary command. If API Return: appears in a Failure type message, it indicates that the ACE/Server API returned and error and its text follow this string. All other Failure type messages are returned by ACEBulkAdmin. Success and Failure message type also contain the line number of the associated input line. An example of each of these message types is provided here:
BOJ : Info : Info : Success: Success: Failure: Info : Info : EOJ : 2001-02-16 14:35:34 - RSA ACEBulkAdmin version 1.0, February, 2001; Input = new.csv - Log File Opened - Opening input file. Line 3 - addUser - BB1, BigFoot Line 4 - addUser - CB1, BigFoot2 Line 4 - addUserToGroup --CB1, BigGroup ; API return: Error Group Not Found; - Closing rejected actions file - Log file Closed 2001-02-16 14:35:36 - Terminating
Default File Names

If file names are not specified either by command line arguments or input parameter file statements, the following default filenames will be used:
Log filename ACEBulkAdminLog.txt Input reject filename ACEBulkAdminReject (Extension determined by input file extension.) Results filename ACEBulkAdmnResults.txt
If default file names are used, then paths (directories) have not been provided. In this instance, output files will be created in the current directory.
23 / 94
Input Template Files

Input template files can be created to assist in creating input files. (See the gta and gtc commands) A template file may be used as a base file for creating ACEBulkAdmin input files. The template file creation option is mutually exclusive of other command line options. If this option is specified, any additional options will be ignored. Example CSV template:
Action,LastName,FirstName,DefLogin,DefShell,TokSerial,ReplTokSerial,. . . <data>,<data>,<data>,<data>,<data>,<data>,<data>,<data>,<data>,<data>,<data>. . . //Replace <data> with actual data or delete it, leaving ,, then delete this comment line.
// If desired, the header labels or first line of this file may also be deleted. Example Quoted Text template:
"Action" "LastName" "FirstName" "DefLogin" "DefShell" "TokSerial" . . . "<data>" "<data>" "<data>" "<data>" "<data>" "<data>" "<data>" "<data>" . . . // Replace <data> with actual data or delete it, leaving "" then delete this comment line. // If desired, the header labels or first line of this file may also be deleted.
Note: The header and data lines of the above example files have been truncated in order to fit into this format and to avoid line wrap.
Sample CSV Format Data

(1 line header, 1 line data; no embedded cr/lf) Action,LastName,FirstName,DefLogin,DefShell,TokSerial,ReplTokSerial,TokEnabled,S etPin,CreatePin,GrpName,GrpDefLogin,GrpDefShell,ClntName,ClntDefLogin,ClntDefS hell,ExtnKey, ExtnData,ExtnTable,SiteName AUT,Smith,John,Smithj,,853618,,1,1234,,local,,,fred.securid.com
Sample Quoted Text Format Data

(1 line data) AUT Smith John Smithj 853618 1 1234 local fred.securid.com
Passwords
Passwords do not provide a high level of security. It was never intended that they be used as part of the ACE/Server system on a long-term basis. Password support is supplied as
an aid to conversion from a password system to the SecurID system. A few comments are listed here to assist in the understanding of how the ACE/Server handles passwords how various entries will affect them. Each user account may contain only one password. A password counts as one of the maximum of 3 tokens a user may have. A password entered through the ACE/Administration interface (GUI) will have a default lifetime of three years. This date is referred to in the system as the token or password death date. There is also a time of day component associated with most system dates, but it is not necessary for this discussion. When the current date is greater than or equal to the password death date, it is marked as expired and the only option available at this time is to delete the password. If the user still requires access to the system, a new password will need to be assigned. If a password is assigned using the API calls (not the ACE/Administration GUI described above), there is no default life period. The API requires an entry for both days and hours. These fields added to the current date, determine the death date of the password. If entries for days and hours are not provided, the API transaction will be rejected. ACEBulkAdmin uses the API to interface to the ACE/Server database. For the two password commands (AUP and APU), ACEBulkAdmin does not require you to enter data for the days and hours field. If you do not make an entry for days and hours, ACEBulkAdmin will supply an entry for 3 years which is the default life being supplied by the GUI interface described above. If you supply a legal value for days and hours, then that value will be used. Whenever a password is assigned by any of the above methods, it is automatically set to new pin mode by the system. There are no exceptions and there is no way to alter this behavior. New pin mode normally refers to tokens, but in the case of a password, it means that during the first logon attempt using this password, the user will be required to enter a new password. Once the new pin mode has been satisfied, the new password will be valid until the password death date, or the next new pin date. The next new pin date is determined by a system global parameter that can be selected on the ACE/Administration GUI, system screen. This value can range from 1 through 365 days and determines the number of days a password is valid until it is forced into a new pin mode state. This ACE/Administration value defaults to 90 days.
25 / 94
Function Descriptions Add Functions

Add User
Add new user and optionally add user to an existing group and/or an existing client. Action Required Fields AU LastName (24 characters maximum) DefLogin (48 characters maximum) FirstName (24 characters maximum) DefShell (256 characters maximum) GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData
Optional Fields
Add User and Token

Adds a user to the RSA ACE/Server database and assigns the token specified by TokSerial. The token is enabled, the PIN is cleared, and both BadTokenCodes and BadPINs are set to zero. Whether the user is allowed to create a new PIN, required to create a new PIN, or issued a system-generated PIN depends on the policy defined for the system. The TokEnabled field defines the Token state following successful assignment. Additionally, the PIN can be set or cleared depending on the value of the SetPin field. If the user has been added previously a FAILURE message will be generated. The user may also be assigned to an existing Group and/or an existing Client. See the Field Definitions section (above) for additional information on field values. Action Required Fields AUT LastName (24 characters maximum) DefLogin (48 characters maximum) TokSerial, TokEnabled FirstName (24 characters maximum) DefShell (256 characters maximum) SetPin, PinMode, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData, SoftIDParams, SoftIDPW
Optional Fields
26 / 94
Add User and Token Automatic

This command automates the Add User and Token command by obtaining an unassigned token of a specified type from the system and calling the Add User and Token command using the newly acquired token serial number. The field definitions and requirements are identical to those of the AUT command except for the following two exceptions: The MiscVariable field is required and is used to supply the desired token type. Acceptable values are: -1 0 1 2 4 6 First available unassigned token RSA SecurID Standard Card RSA SecurID PINPAD Card RSA SecurID Key Fob RSA SecurID Software Token (formerly SoftID) RSA SecurID modem
The TokenSerial field is not required and is ignored if present. Action Required Fields AUTA LastName (24 characters maximum) DefLogin (48 characters maximum) TokEnabled, MiscVariable (Token type) FirstName (24 characters maximum) DefShell (256 characters maximum) SetPin, PinMode, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData, SoftIDParams, SoftIDPW
Optional Fields
Essentially, this command is identical to the Add User and Token command except you will supply a token type in place of the token serial. ACEBulkAdmin will then attempt to find an unassigned token of the requested type. If successful, the newly acquired token serial will be inserted in the Token Serial field and Add User and Token command will be called. If successful, the newly assigned Token Serial will be reported in the ACEBulkAdmin transaction log.
Add User and Password

The user will be added and a static password will be assigned to the user. The SetPin field specifies the initial password. If the user has been added previously a FAILURE message will be generated. The user may also be assigned to an existing Group and/or an existing Client.
27 / 94
If the AddUser and Password function is successful, the password is automatically put into new pin mode and the user must change the password at the first login. The CreatePin field has non-standard usage and may be used to supply a validity period for the password. The expiration date then becomes the current date plus the validity period. Once a password expires, the only allowable action is to delete it and issue a new one. The format for CreatePin is d#h#. Case is not significant and both days and hours are optional. If there is no entry in the CreatePin field, ACEBulkAdmin supplies a default of 3 years which is the normal default for a hard token. See the Field Definitions section (above) for additional information on field values. Action Required Fields AUP LastName (24 characters maximum) DefLogin (48 characters maximum) SetPin - Users initial password it must conform to systemdefined standards for number of characters and whether the characters are numeric or alphanumeric
Optional Fields
FirstName (24 characters maximum) DefShell (256 characters maximum) CreatePin (Days & Hours) GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData
Add User Remote

Add user remote adds a remote user to the database. It accomplishes this by calling AddUser followed by a call to ChangeUserRemote. Consult the documentation for these two commands for additional information. If the addUser fails, the changeUserRemote will not be called. However, failures in the secondary calls from addUser (addUserToGroup, addUserToClient, and addUserExtensionData) are not considered fatal failures and the changeUserRemote will proceed. Action Required Fields AUR LastName (24 characters maximum) DefLogin (48 characters maximum)
RemoteAlias (48 characters maximum) RealmName (48 characters maximum)
Optional Fields
FirstName (24 characters maximum) DefShell (256 characters maximum) GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData
Note that there is no contact with the RSA ACE/Server in the remote realm. The only changes are made locally. The login name in the remote realm (remoteAlias) is not verified.
Add Token to User

The token to be added is specified in the ReplTokSerial field. The DefLogin field or the TokSerial field containing a token serial of a token already assigned to the user is used to identify the user. The specified Token will be assigned to the user. The TokEnabled field defines the Token state following successful assignment. If the Token is already assigned or the user already has 3 Tokens assigned a FAILURE message will be generated. PinMode may contain a value of 1 to set the token in new pin mode or a value of 0 or empty to leave the new pin mode as is. Consult the Change PIN Status command for additional information on the SetPin and PinMode options. Action Required Fields Optional Fields ATU DefLogin or TokSerial, ReplTokSerial, TokEnabled SetPin, PinMode, CreatePin, SoftIDParams, SoftIDPW
Add Token to User Automatic

This command automates the Add Token to User command by obtaining an unassigned token of a specified type from the system and calling the Add Token To User command using the newly acquired token serial number. The field definitions and requirements are identical to those of the ATU command except for the following two exceptions: The MiscVariable field is required and is used to supply the desired token type. Acceptable values are: -1. 0. 1. 2. 4. 6. First available unassigned token RSA SecurID Standard Card RSA SecurID PINPAD Card RSA SecurID Key Fob RSA SecurID Software Token (formerly SoftID) RSA SecurID modem
The ReplTokSerial filed is not required and is ignored if present. Action Required Fields
Optional Fields
ATUA DefLogin or TokSerial, TokEnabled, MiscVariable

SetPin, PinMode, CreatePin,
SoftIDParams, SoftIDPW
29 / 94
Essentially, this command is identical to the Add Token To User command except you will supply a token type in place of the replacement token serial. ACEBulkAdmin will then attempt to find an unassigned token of the requested type. If successful, the newly acquired token serial will be inserted in the ReplTokSerial field and the Add Token To User command will be called. If successful, the newly assigned Token Serial will be reported in the ACEBulkAdmin transaction log.
Add Password to User

A static password will be assigned to the user if the Token count is less than 3 and the user has not already been assigned a password. The SetPin field specifies the initial password. If the user already has 3 tokens assigned or already has a password assigned, a FAILURE message will be generated. If the AddUser and Password function is successful, the password is automatically put into new pin mode and the user must change the password at the first login. The CreatePin field has non-standard usage and may be used to supply a validity period for the password. The expiration date then becomes the current date plus the validity period. Once a password expires, the only allowable action is to delete it and issue a new one. The format for CreatePin is d#h#. Case is not significant and both days and hours are optional. If there is no entry in the CreatePin field, ACEBulkAdmin supplies a default of 3 years, which is the normal default for a hard token.
Action Required Fields Optional Fields
APU DefLogin or TokSerial, SetPin CreatePin
Add User to Group

The user associated with the specified Token or DefLogin will be added to the Group. Both the user and the group must exit. If the user is to have a different Login name or Shell within this Group it must be supplied via the optional fields, otherwise the User defaults will be used. Action Required Fields Optional Fields AUG DefLogin or TokSerial, GrpName GrpDefLogin, GrpDefShell
30 / 94
Add User to Client

The user associated with the specified Token or DefLogin will be added to the Client. Both the User and the Client must already exist. If the user is to have a different Login name or Shell for this Client it must be supplied via the optional fields, otherwise the User defaults will be used. Action Required Fields Optional Fields AUC DefLogin or TokSerial, ClntName ClntDefLogin, ClntDefShell
Add Group
The Group specified in the GrpName field will be added. Action Required Fields Optional Fields AG GrpName None
Add Group to Client

Enables a group of users on a client so that all members of the group can authenticate on that client. The function call must specify an existing group and client. The GrpName argument can include a site name separated from the group name by @ (or a different group/site separator established through Sd_SetSymbols) for example, ourgroup@oursite. Action Required Fields Optional Fields AGC GrpName, ClntName None
Add Group to Site

The Group specified in the GrpName field will be added to the Site specified in the SiteName field. The function call must specify an existing group and site. The GrpName argument can include a site name separated from the group name by @ (or a different group/site separator established through Sd_SetSymbols) for example, ourgroup@oursite. If the SiteName field is omitted, the Group will be unassigned from all sites.
31 / 94
AGS GrpName (optionally with a SiteName suffix) SiteName
Add AgentHost (Version 5.0 and later)

The AgentHost specified in the AgentHostName and/or AgentHostAddress field(s) will be added. Action AAH Required Fields Optional Fields AgentHostName and/or AgentHostAddress SiteName, AgentHostType, AgentHostEncryptionType, AgentHostFlags, ActingMaster, ActingSlave, SharedSecret
AgentHostType
The AgentHostType should be entered as a number between 0 and 4. If not specified, defaults to 0. 0 = UNIX 1 = Comm Server 2 = Single Transaction Comm Server 3 = Net OS (NT, Novell etc.) 4 = NetSP (obsolescent option for IBMs NetSP product) AgentHostEncrypti The AgentHosts Encryption type should be entered as a number 0 or onType 1. If not specified, defaults to 1. 0 = SDI Encryption 1 = DES Encryption When at all possible, DES should be selected. AgentHostFlags If not specified, defaults to 0. 0 = No flags set. 1 = Node Secret Sent 2 = AgentHost open to all 4 = Search Other Realms 8 = Require Name Lock
The only valid values for a pre 5.0 ACE/Server that can be entered for Clnt Flags in this mode are 0, 2, and 6. For 5.0 and later servers, 0, 2, 6, 8, 10, and 14 values may be entered. The reason for this is as follows:
Any value (1, 3, 5, 7) that attempts to set Flag 1 (Has the node secret been sent?) is rejected, because the client had no previous existence.
32 / 94
Flag 3 (Can the client search remote realms?) cannot be true when Flag 2 (Is the client open to all?) is false; therefore the values 4 and 5 are rejected. For version 5.0 servers, the 8 bit can be added in yielding the additional values of 8, 10 and 14
If either AgentHostName or AgentHostAddress is used, then an address or name lookup is attempted for the other. If both, fields are present, then no lookups are performed, and the values are forced.
Add Secondary Node to AgentHost (Version 5.0 and later)

A secondary node will be added to the AgentHost. Action Required Fields ASN AgentHostName, SecondaryNodeName SecondaryNodeAddress None and/or
Optional Fields
Creates a new secondary node record in the database, for the specified Agent Host. AgentHostName is the name of the Agent Host and should be the full version of the name as in the RSA ACE/Server database (for example, pc.client.server.com). SecondaryNodeName is the secondary node name to be added to the agent host. If you want the secondary node name to be resolved by the secondary node address, pass a null string (). SecondaryNodeAddress is the secondary node address to be added to the agent host. If you want the secondary node address to be resolved by the secondary node name, pass a null string (). Note: Both the secondaryNodeName and secondaryNodeAddress cannot be null strings. If both SecondaryNodeName and SecondaryNodeAddress contain values, then no name/address resolution will be preformed.
33 / 94
Add Client
The Client specified in the ClntName field will be added. Action Required Fields Optional Fields AC ClntName SiteName, ClntType, ClntEncryption, ClntFlags
ClntType
ClntEncryption
ClntFlags
The Client type should be entered as a number between 0 and 4. If not specified, defaults to 0. 0 = UNIX 1 = Comm Server 2 = Single Transaction Comm Server 3 = Net OS (NT, Novell etc.) 4 = NetSP (obsolescent option for IBMs NetSP product) The Clients Encryption type should be entered as a number 0 or 1. If not specified, defaults to 1. 0 = SDI Encryption 1 = DES Encryption The Client flags for Open to all Locally Known Users and Search Other Realms for Unknown Users are set as a bitwise value. If not specified, defaults to 0. 0 = No flags set. 1 = Node Secret Sent 2 = Client open to all 4 = Search Other Realms 8 = Require Name Lock (Ver. 5.0 and later)
The only valid values for a pre 5.0 ACE/Server that can be entered for Clnt Flags in this mode are 0, 2, and 6. For 5.0 and later servers, 0, 2, 6, 8, 10, and 14 values may be entered. The reason for this is as follows:
Any value (1, 3, 5, 7) that attempts to set Flag 1 (Has the node secret been sent?) is rejected, because the client had no previous existence. Flag 3 (Can the client search remote realms?) cannot be true when Flag 2 (Is the client open to all?) is false; therefore the values 4 and 5 are rejected. For version 5.0 servers, the 8 bit can be added in yielding the additional values of 8, 10 and 14
34 / 94
Add Client to Site

The Client specified in the ClntName field will be added to the Site specified in the SiteName field. If the SiteName field is omitted, the Client will be unassigned from all Sites. Action Required Fields Optional Fields ACU ClntName SiteName
Add Site
The Site specified in the SiteName field will be added. Action Required Fields Optional Fields AS SiteName None
Add Client Extension Data

Adds an extension field to a client record and inserts data. The function call must include a key (ExtnKey) that uniquely identifies this extension field. Action Required Fields Optional Fields ACE ClntName, ExtnKey ExtnData
Add Group Extension Data

Adds an extension field to a group record and inserts data. The GrpName argument can include a site name separated from the group name by @ (or a different group/site separator established through Sd_SetSymbols) for example, ourgroup@oursite. The function call must include a key (ExtnKey) that uniquely identifies this extension field. Action Required Fields AGE GrpName ExtnKey (maximum 48 characters)
35 / 94 Revised: June 22, 2011
Optional Fields
ExtnData (maximum 80 characters)
Add Site Extension Data

Adds an extension field to a site record and inserts data. The function call must include a key (ExtnKey) that uniquely identifies this extension field. Action Required Fields ASE SiteName ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
Add Token Extension Data

Adds an extension field to a token record and inserts data. The function call must include a key (ExtnKey) that uniquely identifies this extension field. Action Required Fields ATE TokSerial ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
Add User Extension Data

Adds a user extension record, specifying the user by token serial number or by login, and inserts data. The function call must include a key (ExtnKey) that uniquely identifies this extension field. Action Required Fields AUE TokSerial or DefLogin ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
36 / 94
Add System Extension Data

Adds an extension field to the system record and inserts data. The function call must include a key (ExtnKey) that uniquely identifies this extension field. Action Required Fields Optional Fields AYE ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Assign Profile
Assigns a profile specified by profileName to a user specified by tokenSerial or DefLogin.
AP DefLogin or TokSerial, ProfileName None
37 / 94
Change Functions
Change or Add User
This command is used to change the specified fields, however if the DefLogin is not present in the Ace Database, a new account will be created with a call to the Add User command. If the account does exist, the user data fields (LastName, FirstName and DefShell) will be modified if they are different then those in the database. If you wish to delete the FirstName or DefShell, supply a set of empty double quotes () in the input field. LastName may not be deleted. This is similar to the Update User Data Command. If a GrpDefLogin is supplied, the user will be deleted from the group and added back in. This will result in the user being a member of the group with the supplied GrpDefShell (or its default). However, if the user was a member of the group under the DefLogin, this group membership will still exist. This is also the case for ClntDefLogin. Empty double quotes are not applicable to the group and client (Agent Host) fields. Action Required Fields Optional Fields CAU DefLogin (48 characters maximum) LastName (24 characters maximum) FirstName (24 characters maximum) DefShell (256 characters maximum) GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData
Note: Although DefLogin is the only required field, at least one of the optional fields is required for anything meaningful to happen. Also, if the DefLogin does not exist in the database, the AU command is called, in which case the LastName field is also required.
Change or Add User and Token

This command has been added as a convenience to some users. It is recommended that extreme caution be used in selecting this command, as unintentional results are possible. This command is used to change the specified fields, however if the TokSerial is not assigned to a user account in the Ace Database, a new account will be created with a call to the Add User and Token command. If the TokSerial is associated with a user account, the user data fields (DefLogin, LastName, FirstName and DefShell) will be modified if they are different then those in the database. If you wish to delete a FirstName or DefShell, supply a set of empty double quotes () in the input field. DefLogin and LastName may not be deleted. This is similar to the Update User Data Command. TokEnabled, SetPin and CreatePin fields will be updated if they are present and different from that found in the token record. The SetPin field is used to set the pin state and the CreatePin field is used to set the pin create mode for this user. If a GrpDefLogin is supplied along with GrpName, the user will be deleted from the group and added back in. This will result in the user being a member of the group with the supplied GrpDefShell
38 / 94
(or its default). However, if the user was a member of the group under the DefLogin (or any other login), this group membership will still exist. This is also the case for ClntDefLogin. Empty double quotes are not applicable to the group and client (Agent Host) fields. See the Field Definitions section (above) for additional information on field values.
CAUT TokSerial DefLogin (48 characters maximum) FirstName (24 characters maximum) LastName (24 characters maximum) DefShell (256 characters maximum) TokEnabled, SetPin, PinMode, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData
Note: Although TokSerial is the only required field, at least one of the optional fields is required for anything meaningful to happen. Also, if the TokSerial is unassigned, the AUT command is called, in which case additional fields are required for a successful addition to occur (consult the AUT command for additional documentation.) The PinMode field only affects the SetPin for changes as the API command called by AUT always forces new pin mode.
Change or Add User and Password

This command is used to change the specified fields, however if the DefLogin is not present in the Ace Database, a new account will be created with a call to the Add User Password command. If the account does exist, the user data fields (LastName, FirstName and DefShell) will be modified if they are different then those in the database. If you wish to delete the FirstName or DefShell, supply a set of empty double quotes () in the input field. LastName may not be deleted. This is similar to the Update User Data Command. If a GrpDefLogin is supplied along with GrpName, the user will be deleted from the group and added back in. This will result in the user being a member of the group with the supplied GrpDefShell (or its default). However, if the user was a member of the group under the DefLogin (or any other login), this group membership will still exist. This is also the case for ClntDefLogin. Empty double quotes are not applicable to the group and client (Agent Host) fields. See the Field Definitions section (above) for additional information on field values. Action Required Fields CAUP DefLogin (48 characters maximum)
39 / 94
Optional Fields
LastName (24 characters maximum) FirstName (24 characters maximum) SetPin - Users initial password it must conform to systemdefined standards for number of characters and whether the characters are numeric or alphanumeric DefShell (256 characters maximum)
CreatePin (Days & Hours) GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData
Note: Although DefLogin is the only required field, at least one of the optional fields is required for anything meaningful to happen. Also, if the DefLogin does not exist in the database, the AUP command is called, in which case the additional fields are required for a successful addition to occur.
Change User Data

The User data associated with DefLogin will be changed to that supplied. If you desire to change the DefLogin, then TokSerial must contain an assigned token for that user or MiscVariable must contain the current DefLogin. TokSerial has precedence over MiscVaribable. If TokSerial is not supplied and MiscVaribable contains a value, ABA will attempt to obtain a TokSerial using this value. If a TokSerial can be obtained, it will be used to change the DefLogin. The API does not require all fields, however if a field is not present, the API will delete it rather than leave it unchanged. In order to understand your intent, this implementation requires all fields. To delete a field that is not required, supply a set of empty double quotes for the field. i.e., "". Of course, deleting DefLogin and/or LastName will result in an error. To modify the DefLogin field you must supply the TokSerial field or the old DefLogin in the MiscVariable field. The advantage of this command is that it is faster than the updateUserData command listed below. The disadvantage of this command is that you must know and provide entries for all fields.
CUD LastName, FirstName, DefLogin, DefShell TokSerial, MiscVariable
Change User Remote

Changes an existing local user to a remote user, or modifies an existing remote user to update the remote alias and realm information For an existing user, this function modifies
40 / 94
the user record to indicate that he or she should be authenticated in the specified remote realm using the specified login name (remoteAlias). The function requires that the user already exist in the database, that they have no administrative privileges, and no assigned tokens. Action CUR Required Fields DefLogin (48 characters maximum)
RemoteAlias (48 characters maximum) RealmName (48 characters maximum)
Optional Fields
None
Note that there is no contact with the RSA ACE/Server in the remote realm. The only changes are made locally. The login name in the remote realm (remoteAlias) is not verified.
Change PIN Status

Change PIN Status provides the following functionality: Clear the PIN associated with the specified token serial. The token will automatically be placed in new pin mode. Set the PIN associated with the specified token serial to an explicit value. Request the system to randomly generate and assign a new pin to the specified token serial. The generated pin will be returned in the log file. Force the specified token serial into new pin mode. Action Required Fields Optional Fields CPS TokSerial SetPin, PinMode
The following values are valid for SetPin: G or g or 1 Assign a randomly system generated Pin. The generated pin is returned in the log. Set PinMode equal to 1 to force the specified token serial into new pin mode. C or c or 0 Clear Pin for the specified token serial. The specified token serial is automatically forced to new pin mode. PinMode is ignored. Force specified token serial into new pin mode. option is valid only if PinMode equals 1. This
Empty
All other values
Set PIN to supplied value. Set PinMode equal to 1 to force the specified token serial into new pin mode.
41 / 94
Notes: Change PIN Status can be used to change user passwords assigned directly through ACEBulkAdmin password functions. Passwords of this type (whose token serial numbers have the prefix UPW) cannot be cleared, thus passing an empty string as the SetPin argument causes an error. Pin attributes (min/max length, alpha and/or numeric, etc) are controlled by administrative settings. If you explicitly set a PIN and receive the Invalid PIN error message, it may a result of violating one or more of these attributes. The error message will not inform you as to the specific violation. In this case it will be necessary to check with an ACE Database administrator to find out what attributes have been set in your system. Administrator PIN options allow enabling/disabling User created PINs allowed and enabling/disabling User created PINs required Using some of the set pin options above may appear to violate the selected rules but this is not the case. First of all, there is no option that disables administrative action regarding PIN changes. Secondly, any time User created PINs required is enabled and administrative action is performed on a PIN, the token will be placed in New Pin Mode requiring the user to select a new PIN during the first logon.
Change Token Status

The specified Token will be enabled or disabled according to the value of the TokEnabled parameter. Set TokEnabled to 1 in order to enable a token. Set TokEnabled to 0 (zero) in order to disable a token. Action Required Fields Optional Fields CTS TokSerial, TokEnabled None
Change Token Status eXtended

The DefLogin or TokSerial will be used to locate all tokens assigned to a specific user. All tokens assigned to the user will be enabled or disabled according to the value of the TokEnabled parameter. Set TokEnabled to 1 in order to enable a token. Set TokEnabled to 0 (zero) in order to disable a token. The MiscVariable field is used to specify the token type to enable/disable. Action Required Fields Optional Fields CTSX DefLogin or TokSerial, TokEnabled MiscVariable 0 - All tokens and passwords (Default) 1 - Tokens only (no passwords) 2 - Passwords only (no tokens)
42 / 94
Change Temporary User

Puts a user (identified by token serial number or login) in temporary mode. You can set both starting and ending times, or you can set only an ending time (.temporary mode lasts from now until this time.). Both date and hour must be specified for starting and ending times. Leaving all optional fields empty or specifying 00/00/0000 in the DefShell field will remove the user from temporary status. Action Required Fields Optional Fields CTU DefLogin or TokSerial DefShell, ClntDefLogin, GrpDefShell, GrpDefLogin
The optional fields have non-standard usage and are used to provide the following values: DefShell End Date (empty | mm/dd/yyyy | 00/00/0000) ClntDefLogin End Time (empty | h | hh) where 0 >= hours <= 23 GrpDefShell Start Date (empty | mm/dd/yyyy) GrpDefLogin Start Time (empty | h | hh) where 0 >= hours <= 23 Warning: The API does very little verification of date and time fields. If date fields contain data other than numeric or / characters, it will be forced to 0. Non-numeric data in time fields will result in the value being forced to 0.
Change Token (Immediate)

If the Token specified in the ReplTokenSerial field is currently unassigned it will immediately replace the Token specified in the TokSerial field. Action Required Fields Optional Fields CTI TokSerial, ReplTokSerial None
Change Token (on First Use of New Token)

If the Token specified in the ReplTokenSerial field is currently unassigned it will be added as a replacement Token to the User associated with the Token specified in the TokSerial field. The first time a user uses the new Token; the old Token will be disabled. The users PIN is preserved. Action
CTD
43 / 94 Revised: June 22, 2011
Required Fields Optional Fields
TokSerial, ReplTokSerial None
Change Groups Site

The Groups Site association is changed to that specified. Action Required Fields Optional Fields CGS GrpName, SiteName None
Change Clients Site

The Clients Site association is changed to that specified. Action Required Fields Optional Fields CCS ClntName, SiteName None
Change Client Extension Data

The Clients Extension Data Entry will be changed to that supplied. If the ExtnData field is not supplied, any existing data entry for the given key will be set to null (deleted.) Action Required Fields CCE ClntName ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
Change Group Extension Data

The Groups Extension Data Entry will be changed to that supplied. If the ExtnData field is not supplied, any existing data entry for the given key will be set to null (deleted.) Action CGE
44 / 94
Required Fields
GrpName ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
Change Site Extension Data

The Sites Extension Data Entry will be changed to that supplied. If the ExtnData field is not supplied, any existing data entry for the given key will be set to null (deleted.) Action Required Fields CSE SiteName ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
Change Token Extension Data

The Tokens Extension Data Entry will be changed to that supplied. If the ExtnData field is not supplied, any existing data entry for the given key will be set to null (deleted.) Action Required Fields CTE TokSerial ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
Change User Extension Data

The Users Extension Data Entry will be changed to that supplied. If the ExtnData field is not supplied, any existing data entry for the given key will be set to null (deleted.) Action Required Fields CUE TokSerial or DefLogin ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Optional Fields
Change or Add User Extension Data

This command is intended to complement the three changeOrAddUser commands. This command will first determine if a user exists for the giver DefLogin or TokSerial. If
there is a user account, it will be tested for the given extension data key. If the extension data key does not exist, addUserExtensionData is called. If the extension key does exist, then changeUserExtensionData is called. Interpretation of the ExtnData field is as defined in the addUserExtensionData and changeUserExtensionData commands respectively. Action Required Fields CAUE TokSerial or DefLogin ExtnKey (maximum 48 characters)
Optional Fields ExtnData (maximum 80 characters)
Change System Extension Data

The Systems Extension Data Entry will be changed to that supplied. If the ExtnData field is not supplied, any existing data entry for the given key will be set to null (deleted.) Action Required Fields Optional Fields CYE ExtnKey (maximum 48 characters) ExtnData (maximum 80 characters)
Set Agent Host (Version 5.0 and later)

Sets field information for an Agent Host identified by Agent Host name or IP address in the Server database. The Agent Host name, site, Agent Host type, encryption type, and several flags can be affected. Action Required Fields SAH AgentHostKey, ParameterType, ActionControl (One or more fields from the Optional Fields list) AgentHostName, AgentHostAddress, SiteName, AgentHostType, AgentHostEncryptionType, AgentHostFlags, ActingMaster, ActingSlave, SharedSecret
Optional Fields
Field Definitions: The ParameterType field must contain either a 0 or 1, indicating that the AgentHostKey filed contains an AgentHostAddress or AgentHostName respectively. These two fields determine which AgentHost to modify. The ACV column represents the ActionControl Value. The ActionControl field is a bit array
46 / 94
and determines which fields for the given agent host will be modified. The corresponding bit true in the ActionControl field indicates that this AgentHost field should be changed to the provided value. If a specific bit is not on, but the corresponding field contains a value, the value is ignored and the database is not changed. Likewise, if a bit is not on and the database contains data in the corresponding field for this agent host, the database is not changed. To change more than one value for a particular agent host, enter the sum of values for these fields in the ActionControl field and values in the corresponding fields. For example, to change the AgentHostType and AgentHostFlags, enter 10 in the ActionControl field new values in the AgentHostType and AgentHostFlags fields. Bit one of the ActionControl field on allows changing either the AgentHostName or the AgentHostAddress or both fields in the same transaction.
Label AgentHostKey ParameterType ActionControl AgentHostName AgentHostAddress AgentHostType ACV Data Value String 0 1 0 - 255 String String 0 1 2 3 4 0 1 1 2 4 8 String String String String Definition The original name of the Agent Host or IP address as in the RSA ACE/Server database. AgentHostKey is AgentHostAddress AgentHostKey is AgentHostName Bit array indicating what fields to modify. The name of the new Agent Host The IP address of the new Agent Host UNIX Agent Communication server Single-transaction comm server Net OS Agent NetSP Agent SDI DES Sent Node Secret? Open to All? Search Remote Realms? Require NameLock An existing site to which the Agent Host can be assigned The name of the Acting Master Server The name of the Acting Slave Server A string of pseudorandom data known only to the Agent and the Server.
1 1 2
AgentHostEncryptionType AgentHostFlags
4 8
SiteName ActingMaster ActingSlave SharedSecret
16 32 64 128
Note: If you are trying to modify either an AgentHostName or AgentHostAddress, supply both entries. If one cannot be resolved locally to the other, the command will fail. Supplying both entries will insure successful completion.
Set Emergency Access Fixed

Sets the status of token (identified by a token serial number) to Fixed and assigns a fixedpassword. The lifetime of the fixed password can be defined in local time by using either the dateExpire, hourExpire, or lifeTime arguments.
47 / 94
EAFXD TokSerial, SetPin CreatePin
The desired password is supplied in the SetPin field. Its acceptability is governed by system parameters. An expiration date may be supplied in the CreatePin field. If a date is given, then optionally an hour entry may be included. Additionally, an optional lifetime entry (hours) may be included in the CreatePin field. If a lifetime entry is included, any date entry will be ignored. The format for the CreatePin entry is Dmm/dd/yyyyHnLn. Any Date, Hours, and Lifetime entry must appear in that order, DHL. Acceptable entries are: Dmm/dd/yyyy Dmm/dd/yyyyHn Dmm/dd/yyyyLn HnLn Ln An hour entry is not valid unless a date entry is present. The only reason HnLn is valid, is because when a Lifetime entry is present, the Date and Hour entries are ignored. Also, the
RSA ACE/Server cannot accept fixed passwords with expiration dates of more than 210,240 hours (24 years). DHL case is not significant.
Set Emergency Access OTP

Sets the status of a token (identified by a token serial number) to lost and generates a set of one-time passwords for the token. By default, this function returns a set of two onetime passwords (default 6 digits). You can specify a larger number of passwords. These are given to the user and can be used for authentication. The lifetime of the one-time password can be defined in local time by using either the dateExpire, hourExpire, or lifeTime arguments. Action Required Fields Optional Fields EAOTP TokSerial, SetPin CreatePin
A SetPin field entry is required. The format of the SetPin entry is NnLnFn and it is used to set the followings three password parameters: Number Number of passwords to generate (Default is 2, see Note below) Length - Password length (4 8 characters) Flags - Settings for the following flags: 1 digits only 2 letters only
48 / 94
3 digits and characters only 4 punctuation only 5 digits and symbols only 6 letters and symbols only 7 letters, integers, and symbols Any combination of these three parameters is acceptable with the exception of Length only, which will generate an error. Also, any parameter combination must be in NLF order. For example, N10F3 is acceptable but L5N3 is not. NLF case is not significant.
Note: You can specify a greater number of one-time passwords to be generated, provided the maximum of 50 such passwords on file for a single user is not exceeded. If you request a number that will raise the total above 50, the request is automatically reduced to a smaller number. To clear all previously generated token codes, use the Set Emergency Access OFF command. To generate new token codes to replace the ones you have cleared, run this command again.
An expiration date may be supplied in the CreatePin field. If a date is given, then optionally an hour entry may be included. Additionally, an optional lifetime entry (hours) may be included in the CreatePin field. If a lifetime entry is included, any date entry will be ignored. The format for the CreatePin entry is Dmm/dd/yyyyHnLn. Any Date, Hours, and Lifetime entry must appear in that order, DHL. Acceptable entries are: Dmm/dd/yyyy Dmm/dd/yyyyHn Dmm/dd/yyyyLn HnLn Ln An hour entry is not valid unless a date entry is present. The only reason HnLn is valid, is because when a Lifetime entry is present, the Date and Hour entries are ignored. Also, the
RSA ACE/Server cannot accept fixed passwords with expiration dates of more than 210,240 hours (24 years). DHL case is not significant.
Set Emergency Access OFF

Switches off emergency access mode for the specified token. The users one-time password(s) is/are destroyed and the status of the original token is changed from Lost to Enabled.
EAOFF TokSerial None
Update User Data

This command is supplied as a friendlier version of the changeUserData command described above. For this command, fields that do not require modification may be omitted from the input line. To delete a field that is not required, supply a set of double quotes. i.e., "". To modify the DefLogin field, supply the TokSerial field or the old DefLogin in the MiscVariable field. TokSerial takes precedence over MiscVariable. If the TokSerial field is not present and MiscVariable contains a value, ABA will attempt to
49 / 94
obtain a TokSerial using this value. If a TokSerial is obtained, the DefLogin will be changed. The advantage of this command over the changeUserData command is that you only need to provide input for the fields you desire to change. The disadvantage of this command over the changeUserData command is that it requires a database read for each command and is therefore slower. Action Required Fields Optional Fields UUD DefLogin or TokSerial LastName, FirstName, DefShell, DefLogin (if TokSerial is present), MiscVariable
50 / 94
Delete Functions
Delete Admin Privileges
Sets a users status and level as an administrator to None (that is, the users User Type is changed to Regular User). This function is useful for resetting the status of users imported from external realms, whose administrator status is automatically imported as part of the user record. A user who is an administrator in the external realm can be made an ordinary user in the realm to which the record is imported.
Note: This
function is obsolete, and is maintained for backward compatibility. DAP TokSerial or DefLogin None
Delete User from Group

The User associated with the GrpDefLogin field will be removed from the Group. Action Required Fields Optional Fields DUG GrpDefLogin, GrpName None
Delete User from Client

The user associated with the ClntDefLogin field will be removed from the Client. Action Required Fields Optional Fields DUC ClntDefLogin, ClntName None
Delete Group from Client

The Group specified will be removed from the Client. Action
DGC
51 / 94 Revised: June 22, 2011
Required Fields Optional Fields
GrpName, ClntName None
Delete Group from Site

The Group specified will be removed from the Site. Action Required Fields Optional Fields DGS GrpName, SiteName None
Delete Client from Site

The site association will be remove form the specified Client. Action Required Fields Optional Fields DCS ClntName None
Delete Group
Deletes a specified group record from the database. For the deletion to succeed, all users must be removed from the group, and all dependent records such as extensions must be deleted, before this function is called. A group that has a group administrator cannot be deleted until the administrator is removed. (This can be done through the sdadmin utility.) The GrpName argument can include a site name separated from the group name by @ (or a different group/site separator established through Sd_SetSymbols) for example, ourgroup@oursite. Action Required Fields Optional Fields DG GrpName None
52 / 94
Delete Client
Deletes a specified client record from the database. For the deletion to succeed, all users or groups must be disabled on this client, and all dependent records such as extensions must be deleted, before the function is called. Action Required Fields Optional Fields DC ClntName None
Delete Secondary Node from AgentHost (Version 5.0 and later)

Deletes a specified secondary node record from the database. For the deletion to succeed, both the agent host and the secondary node must be valid and the secondary node must have been previously added to the agent host. Action Required Fields Optional Fields DSN AgentHostName, SecondaryNodeName None
Delete Site
Deletes a specified site record from the database. For the deletion to succeed, all associated groups and clients must be removed, and all dependent functions such as extensions must be deleted, before the function is called. A site that has a site administrator cannot be deleted. Action Required Fields Optional Fields DS SiteName None
Delete Client Extension Data

The Clients Extension Data Entry will be removed. Action Required Fields DCE ClntName, ExtnKey
53 / 94
Optional Fields
None
Delete Group Extension Data

The Groups Extension Data Entry will be removed. Action Required Fields Optional Fields DGE GrpName, ExtnKey None
Delete Site Extension Data

The Sites Extension Data Entry will be removed. Action Required Fields Optional Fields DSE SiteName, ExtnKey None
Delete Token
Deletes from the database the record of an unassigned token identified by TokSerial. For the deletion to succeed, any extension records dependent on the token record must first be deleted. Action Required Fields Optional Fields DT TokSerial None
Delete Token Extension Data

The Tokens Extension Data Entry will be removed. Action Required Fields Optional Fields
DTE TokSerial, ExtnKey None

54 / 94 Revised: June 22, 2011
Delete User Extension Data

The Users Extension Data Entry will be removed. Action Required Fields Optional Fields DUE TokSerial or DefLogin, ExtnKey None
Delete System Extension Data

The Systems Extension Data Entry will be removed. Action Required Fields Optional Fields DYE ExtnKey None
Delete User
The specified user will be deleted from the database and any associated Tokens returned to the unassigned state. The user is also removed from all other associations (Groups, Sites, etc.) Action Required Fields Optional Fields DU DefLogin or TokSerial None
Rescind Token (Version 4.0 and later)

The Token specified will be unassigned. No other action regarding this user is performed. Action Required Fields Optional Fields
RT TokSerial None
55 / 94 Revised: June 22, 2011
Unassign Profile
Unassign the currently assigned user profile. Action Required Fields Optional Fields UP DefLogin or TokSerial None
Unassign Token
Unassign a token from a user, provided that the user is not an administrator the user is not enabled on any client the user does not belong to any group the user record has no extension fields. Unless all of these requirements are met, the action is invalid and the token is not unassigned. If the action is valid and results in the users last token being unassigned, then this function also deletes the user record from the database. Action Required Fields Optional Fields UT TokSerial None
56 / 94
List Functions
The list functions provide a powerful tool for producing data that can be used as is or passed on to some other product for additional sorting, formatting or combining with data from other sources. The output of the list functions can be anything from a simple list of user default logins or token serial numbers to a full line of combined token and user information. The list functions start out by extracting data from the Ace server database based on input selection criteria. The input selection criteria can result in a list of everything from all users or tokens to a very narrow range of users or tokens. Based on additional input parameters, additional data such as all user information, extended user information, user extension data and group membership information may be reported. Token information for assigned tokens may also be included. For token-based reports, full token information and token extension data may be reported along with user and group information if the token is assigned to a user. The listTokenInfoByField command is particularly powerful in that in addition to token information it provides for option of appending user information for assigned tokens. For example, this command could be used to obtain a list of all tokens expiring in 45 days along with the user and user extension data for this token. The list could then be used to generating a mailing or to automatically email these users. Of course, this would depend on the necessary information being kept in user extension data fields. Most of the list reporting functions are also available to the multiple token assignment and multiple token replacement commands. If these commands are used to assign or replace tokens, the report functions can be used for token control or notification. The output of these commands is a comma separated variable list that can easily be processed by most scripting languages, spreadsheet programs or word processor programs. If the report is redirected to stdout or stderr, the last line of output will be the single word Done followed by a newline sequence. In this case, a report that generated no output will consist of a single line beginning with the word Done. Additional information on user and token selection is available in the cust_admin.pdf document that is part of the ACE Server installation. This document can usually be found in the ACE Server /ace/doc directory. Consult the information provided for the Sd_ListUsersByField and Sd_ListTokensByField functions. These two functions are responsible for the user and token selections for the list and multiple token ACEBulkAdmin commands.
Set Sort Order

This command is valid for Ace Server versions 5.1 and later. Sets criteria for sorting of database tables that is performed when any listing function is called to list the contents of these tables: SDToken, SDUser, SDClient (Agent Host), SDGroup, SDSite, SDProfile, SDSecondaryNode, SDSharedJob.
57 / 94
By default the RSA ACE/Server database sorts and lists the contents of these tables in chronological order according the time that each database record was created. Action Required Fields SSO MiscVariable, OutputOption
For each SSO command, supply one mnemonic name in the MiscVariable column and an appropriate value in the OutputOption column. The OutputOption (value) is not required for the Clear and Default mnemonics. Use this command to alter the output for the list and multiple token commands described below.
Database Table All All SDToken SDUser Mnemonic Name Clear Default Token User Value Ignored Ignored 0 1 0 1 2 0 1 0 1 0 1 0 1 0 1 0 1 Type of Database Sort Sets all tables to their default sort mode Sets all tables to their default sort mode Default Numerical order by token serial number Default Alphabetical order by users last name Alphabetical order by users default login Default Alphabetical order by client name Default Alphabetical order by group name Default Alphabetical order by site name Default Alphabetical order by profile name Default Numerical order by node Default Numerical order by job number
SDClient SDGroup SDSite SDProfile SDSecondaryNode SDSharedJob
Client Group Site Profile Node Job
List Token Data (Depreciated)

This function has been DEPRECIATED. Please use the LTIF (ListTokenInfobyField) command.
List and/or Delete Log Data

Lists events in the RSA ACE/Server log from the beginning to a specified date. The events can be written to a file, truncated (removed) from the log, or both. There are two ways to specify the date: Absolutely, by supplying a date (mm/dd/yyyy) in the MiscVariable field. Relatively, by supplying in the MiscVariable field a number representing the days prior to but not including the current date. Note the following:
58 / 94
The events listed include all those from the beginning of the log up to but not including the specified date. The current date is not included in the calculation.
To ensure that all the data is listed for a given time period, be sure to add an extra day to the number of days you specify or specify days rather than a specific date. For example, to list data from the beginning of the log through 06/12/2003, you would actually write 06/13/2003. If you knew this time period covered 15 days, you could use the number 16 in place of the absolute date.
LDLD LogFile and/or ActionControl MiscVariable, OutputOption
The following table shows how the LogFile and ActionControl arguments are used to determine whether log entries are written only, written and deleted, or deleted only. Value of LogFile Myfile.log Myfile.log Action Taken Copied to myfile.log Written to myfile.log and deleted from ACE log Greater than 0 Deleted from ACE log 0 No Action. Error returned. A value greater than zero for ActionControl removes the specified events permanently from the log. It does not eliminate them from the dump file. You must either use the LogFile argument to dump events to a file, use the ActionControl argument to remove events from the log, or do both. If you do neither, the function call results in an error. Depending on the number of records being truncated, the operation can take a long time to complete. To prevent problems that might otherwise occur, this function is coded with an infinite timeout interval. Value of ActionControl 0 Greater than 0
The MiscVariable argument is used to supply either a date of the format (mm/dd/yyyy) or the number of days (nnnn). For the mm/dd/yyyy format: mm - Two-digit number representing the month. The date is the first date to be exempted from the dump operation. All dates prior to it will be affected. dd - Two-digit number representing the day. yyyy - Four-digit number representing the year. For the number of days format:
59 / 94
Number of days prior to the current date to exempt from the listp operation. For example, if the value is 3, events prior to the date three days before the current date are listed. LogFile argument: If not an empty string, the selected log entries are dumped in text format to a file that is given the name specified in this argument. If LogFile is an empty string, ActionControl must have a value greater than zero. ActionControl argument: If the value is greater than zero, the selected entries are deleted permanently from the log. If the value is zero, nothing is deleted, but LogFile must specify a file to which the log entries are to be written. OutputOption argument: This value controls the number of entries accumulated before they are removed from the log table when the ActionControl argument is used. Value is an integer. Increasing OutputOption from its default of 100 to reduce the number of deletion operations can improve performance. The maximum value is 5000.
List History
Lists the events in the activity log relating to the user (identified by login or by a token serial number) that occurred between a date n days in the past (where n is the value of the MiscVariable argument) and the current date. If n days in the past is before the beginning of the log data, you will receive no warning; only data from the start of the log forward. Action Required Fields Optional Fields LH None DefLogin or TokSerial, OutputOption, MiscVariable
The OutputOption may contain the following values: [[0 | 1 | 2 | 3] [H | h] [A | a]] where: 0 The output is a CSV formatted listing. 1 The output is formatted in fixed width columns. 2 The same as option 0 except a filter is applied that filters out most events performed by administrators. 3 The same as option 1 except a filter is applied that filters out most events performed by administrators. H | h write a header record in the output file
60 / 94
A | a open results in append mode.

Note: If the filter option is enabled (2 or 3), most events performed by administrators are
filtered out, making it easier to view authentication events. If the argument is omitted, all events are listed without filtering.
The MiscVariable field is used to supply the number of days of history to list. For each event, output consists of the following information from the log (byte limitations are listed in parentheses): Event name (34) local date (10) local time (8) user login (48) affected user name (49) token serial (12) group (48) Agent Host (48) site (48) Server names (48) message number (6-prefaced with zeros if less than 6). When the user is specified by login, only records with the login passed in the argument are returned. Some users may have multiple logins (for example, special group, or Agent Host logins that differ from the default login). The only way to be sure of retrieving all log records for such users is to issue a list history command for each specific login or use the wildcard symbol described in the following note.
Note: Note: You
can use this function to list all log events for the specified period, regardless of user, if you set the value of tokenSerialOrLogin to the wildcard symbol * (asterisk). The symbol must be the only value of the argument; partial wildcards such as abc* or *123 are not accepted. If a tokenSerial or DefLogin is not provided, * (asterisk) is assumed. This feature can make ListHistory a convenient means for capturing recent history, because (unlike the above List Log Data command) the period it covers is specified by counting back from the current date rather than forward from the beginning of the log.
List Secondary Nodes for Agent Host (Version 5.0 and later)
This function will list all of the secondary nodes associated with a given agent host. The list is in comma separated variable (CSV) format and is written to the results file. (See the r command line argument for additional information on the results file.) Action Required Fields LSN AgentHostName
61 / 94
Optional Fields
None
List User Info by Field

This command will produce a list of default logins or a list of user information for each default login. The default logins selected are based on three input parameters, CompareField, CompareType, and CompareValue. Additionally, the listing is controlled by three additional parameters. The requested information is written to the ResultsFile. See the CRFN command for information on changing the results file name. Action Required Fields Optional Fields LUIF None CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable
Select the CompareField and the CompareType values from the following. Supply a value for CompareValue of the type listed in the value column. The default values for CompareField, CompareType, and CompareValue are 0, 0, and 0. If either CompareField or CompareType is 0, the other is assumed to be 0. User Listed All By last name All beginning with All matching All containing string All without a value (empty) All with any value By first name All beginning with All matching All containing string All without a value (empty) All with any value By default login All beginning with All matching All containing string All without a value (empty) All with any value By default shell All beginning with Field 0 1 Type 0 1 2 3 4 5 2 1 2 3 4 5 3 1 2 3 4 5 4 1 String String String String Ignored Ignored String String String Ignored Ignored Value Ignored String String String Ignored Ignored
62 / 94
All matching All containing string All without a value (empty) All with any value Local or remote All local All remote Permanent or Temporary All permanent All temporary By tokens assigned All with specified number of tokens All with at least one replacement pair All with passwords All with expired tokens All with lost tokens All with token type All with tokens expiring in # of days By LDAP data All beginning with All matching All containing string All without a value (empty) All with any value By profile All with a profile All without a profile All with a named profile By user extension All with extensions All without extensions All with extension keys All without extension keys * Token type values:
0 1 2 4 6 9
2 3 4 5 5 1 2 6 1 2 7 1 2 3 4 5 6 7 8 1 2 3 4 5 9 1 2 3 10 1 2 3 4
String String Ignored Ignored Ignored Ignored Ignored Ignored Number Ignored Ignored Ignored Ignored Token Type* Number String String String Ignored Ignored Ignored Ignored String Ignored Ignored String String
RSA SecurID Standard Card RSA SecurID PINPAD Card RSA SecurID Key Fob RSA SecurID Software Token (formerly SoftID) RSA SecurID modem RSA SID800 Token
The OutputOption may contain the following values:
63 / 94
Default for all versions is 0. List user information for all selected default logins; do not write a header record. For pre ACE/Server version 5.0: [[-2 | -1 | 0] [H | h] [A | a]] where: -2 produces a listing of default logins (no data) and any assigned token serial numbers (no data.) -1 produces a listing of default logins only (no data) 0 list user information for selected default logins H | h write a header record in the output file A | a open results in append mode. For ACE/Server version 5.0 and above [[-2 | -1 | 0 7 | 30 - 34] [H | h] [A | a]] where: -2 produces a listing of default logins (no data) and any assigned token serial numbers (no data.) -1 produces a listing of default logins only (no data) 0 list user information for selected default logins 1 append LDAPsource to option 0 2 append remote alias to option 0 3 append profile name to option 0 4 option 0, 1, 2, and 3 combined 5 LDAPsource only 6 remote alias only 7 profile name only 30 option 0 plus token info for assigned tokens 31 option 1 plus token info for assigned tokens 32 option 2 plus token info for assigned tokens 33 option 3 plus token info for assigned tokens 34 option 4 plus token info for assigned tokens H | h write a header record in the output file A | a open results in append mode. If the append mode is not specified, then new is assumed. Append and Header may be used simultaneously, which may result in heading lines within the file body. This choice is intentional and it is up to the user to determine which options make sense and whether or not down stream applications will be able to correctly process this file. Also, because CIF commands may be used between list commands, if the append option is used, data columns may not line up. Again, this action intentional and the user must choose the options appropriate for the desired outcome.
64 / 94
The ExtnDataOption may contain the following values: [0 | 1 | 2 . . . | 11] Where: 0 no additional data listed 1 include token extension data 2 include user extension data 3 option 1 and 2 4 include group membership group names 5 option 1 and 4 6 option 2 and 4 7 option 3 and 4 8 include group membership field values 9 option 1 and 8 10 option 2 and 8 11 option 3 and 8 Because these options may appear zero or more times, formatting tags are inserted to assist in parsing the data. If user extension data appears in the output, the first user extension data key will be preceded by *tagBUED*, followed by as many user extension key/data pairs as exist for this user. If there are no user extension key/data pairs, the tag will not appear. If group membership data appears in the output, the first group membership name (options 4 & 6) or the first group membership default login (options 8 & 10) will be preceded by the tag *tagBGM*. If there are no group membership values, the tag will not appear. If token information is requested for tokens assigned to a user, the token information will be appended after any of the above information. Each token will be listed as *tagBTOK*, token info. If token extension data has been requested, it will follow the applicable token as *tagBTED*, followed by as many token extension data key/data pairs as exist for this token. If a header record has been requested, appropriate field names are written for each option. The field names will appear only once, even though the actual data may appear more than once. When appropriate, the special identifier tag names will also appear. Header records for the ListTokenInfoByField are as follow: The following field identifiers will be included in the heading, if their associated data has been requested: User information: iUserNum, chLastName, chFirstName, chDefaultLogin, bCreatePIN, bMustCreatePIN, chDefaultShell, bTempUser, dateStart, todStart, dateEnd, todEnd
65 / 94
User extension data:: *tagBUED*,ExtnKey,ExtenData Group Membership group names: *tagBGM*,GrpName Group Membership group values: *tagBGM*,GrpDefLogin,GrpDefShell,GrpName,SiteName The options for group membership group names and group membership group values are mutually exclusive. Token information: *tagBTOK*,chSerialNum, PINClear, iNumDigits, iInterval, dateBirth, todBirth, dateDeath, todDeath, dateLastLogin, todLastLogin, iType, bHex, bEnabled, bNewPINMode, iUserNum, iNextCodeStatus, iBadTokenCodes, iBadPINs, datePIN, todPIN, dateEnabled, todEnabled, dateCountsLastModified, todCountsLastModified, bProtected, bDeployed, iCount,Reserved, softPassword Token extension data: *tagBTED*,ExtnKey,ExtnData If token information and token extension data have been requested, the data, is present, will appear in pairs for as many assigned tokens a user may have. For example, a user with two assigned tokens, each with extension data would have a listing appended to any of the above requested information something like the following:
*tagBTOK*, <token info>,*tagBTED*,extnKey1,extnData1, *tagBTOK*, <token info>,*tagBTED*,extnKey1,extnData1,extnKey2,extnData2
The MiscVariable is used to fix up extension keys and/or data that contain commas. Some users have either intentionally or unintentionally entered commas in their extension data keys or data. Because the retrieval of the extension data and keys is returned as a comma separated list, what is the key and what is the data can be next to impossible to figure out. If you are requesting extension data in this list, ACEBulkAdmin attempts to fix up key/data pairs that contain more than one comma. It does so by parsing the results, building a key with everything up to the first comma. If the key is valid, it is assumed that the remaining commas are in the data. If the key is not valid, the next section of the data (up to the next comma) is appended to the previous key and the process is repeated. Once a key if found, all extra commas in the key and data are either deleted or replaced as described below. There is no guarantee that the key is the correct one, because it is possible to build keys containing commas that will be valid as either the first portion only, or any concatenated portions. In any case, MiscVariable may be used to control the substitution. MiscVariable may contain the following values:
Delete Space <char>
delete all extra commas in the key/data pairs replace all extra commas with a space character replace all extra commas with the provided character
If the MiscVariable is either absent or empty, the default action is to replace extra commas by semi-colon. NOTE: To improve efficiency and decrease the likelihood of the ACE Server log overflowing, when using the LUIF command it is recommend that consideration be given to the loggingoff command line option. This is particularly important when a large database is involved.
List User Info for User

This command will produce user and assigned token information for one user. This command duplicates the List User Info by Field command (above) in every respect except one. The difference is that this command will supply the information for a single supplied default login or an associated user if a token serial number is supplied. If both are supplied, the token serial number is ignored. Action Required Fields Optional Fields LUI DefLogin or TokSerial OutputOption, ExtnDataOption, MiscVariable
Consult the List User Info by Field command (above) for the definition of the optional fields usage and output formatting options.
List Token Info by Field

This command will produce a list of token serial numbers or a list of token information for each token serial number. The token serial numbers selected are based on three input parameters, CompareField, CompareType, and CompareValue. Additionally, the listing is controlled by three additional parameters. The requested information is written to the ResultsFile. See the CRFN command for information on changing the results file name. If a selected token is assigned to a user, user information and group information may also be included in the output report. This make the LTIF command a fairly powerful reporting tool, as it is able to combine token and user information in a useful manner. For instance, this command can be used to report a list of users who have tokens expiring in 45 days. Because user information can be included, the report could be used to generate a mailing list or even to automatically notify users via email. Action Required Fields LTIF None
67 / 94
Optional Fields
CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable
Select the CompareField and the CompareType values from the following. Supply a value for CompareValue of the type listed in the value column. The default values for CompareField, CompareType, and CompareValue are 0, 0, and 0. If either CompareField or CompareType is 0, the other is assumed to be 0. Token Listed All By assignment All assigned tokens All unassigned tokens By token type All assigned tokens of specific type All unassigned tokens of specific type All tokens of specific type By replacement All assigned original tokens All assigned replacement tokens By expiration All expired tokens
All tokens expired already, and tokens expiring within a number of days All expired tokens and tokens expiring within a number of days All expired assigned tokens and assigned tokens set to expire All tokens set to expire
Field 0 1
Type 0 1 2
Value Ignored Ignored Ignored Token type* Token type* Token type* Ignored Ignored Ignored Ignored Number of Days
Number of days
2 1 2 3 3 1 2 4 1 2 3
4
All assigned tokens set to expire By status All assigned and disabled All assigned and enabled All with cleared Pins All in New PIN mode All in Next Token Code mode All lost tokens All with lost status expired All with lost status expired, or set to expire in a number of days All with lost status set to expire in a number of days By token extension All that have extension records
ACEBulkAdmin Guide.doc 68 / 94
5 6 5 1 2 3 4 5 6# 7# 8# 9# 6 1
Number of Days Number of Days Ignored Ignored Ignored Ignored Ignored Ignored Ignored Number of Days Number of Days
Ignored
All that do not have extension records All that have extension records with the provided key All that have extension records without a provided key * Token type values:
0 1 2 4 6 9 RSA SecurID Standard Card RSA SecurID PINPAD Card RSA SecurID Key Fob RSA SecurID Software Token (formerly SoftID) RSA SecurID modem RSA SID800 Token
2 3 4
Ignored String String
# For the LTIF command, ACEBulkAdmin uses the API ListTokensByField command.
This command was not available prior to Ace Server version 5.0. For versions prior to 5.0, ACEBulkAdmin replaces the call to ListTokensByField with actual in-line code. Although significantly slower, with few exceptions the equivalent functionality has been provided. The exceptions are indicated by # in the above table. The OutputOption may contain the following values: Default for all versions is 0. List token information for all selected tokens, do not write a header record. In the definitions below, user information and extended user information (version 5.0 and later) will be listed only if the selected token is assigned. For pre ACE/Server version 5.0: [[-1 | 0 | 10 | 20] [H | h] [A | a]] where: -1 produce a listing of token serial numbers only (no data) 0 list token information for selected token serial numbers 10 list user information 20 list both token and user information H | h write a header record in the output file For ACE/Server version 5.0 and above [[-1 | 0 | 10 17 | 20 - 27] [H | h] [A | a]] where: -1 produce a listing of token serial numbers only (no data) 0 list token information 10 list user information 11 append ldap source to option 10 12 append remote alias to option 10 13 append profile name to option 10
69 / 94
14 15 16 17 20 21 22 23 24 25 26 27 H|h A|a
option 10, 11, 12, and 13 combined list ldap source only list remote alias only list profile name only list both token and user information append ldap source to option 20 append remote alias to option 20 append profile name to option 20 option 20, 21, 22, and 23 combined token information and ldap source token information and remote alias token information and profile name write a header record in the output file open results in append mode.
If the append mode is not specified, then new is assumed. Append and Header may be used simultaneously, which may result in heading lines within the file body. This choice is intentional and it is up to the user to determine which options make sense and whether or not down stream applications will be able to correctly process this file. Also, because CIF commands may be used between list commands, if the append option is used, data columns may not line up. Again, this action intentional and the user must choose the options appropriate for the desired outcome. The ExtnDataOption may contain the following values: [0 | 1 | 2 . . . | 11] Where: 0 1 2 3 4 5 6 7 8 9 10 11 no additional data listed include token extension data include user extension data option 1 and 2 include group membership group names option 1 and 4 option 2 and 4 option 3 and 4 include group membership field values option 1 and 8 option 2 and 8 option 3 and 8
Because these options may appear zero or more times, formatting tags are inserted to assist in parsing the data. If token or user extension data appears in the output, the first extension data key will be preceded by *tagBTED* for token extension data and *tagBUED* for user extension data. The tag will be followed by as
70 / 94
many extension key/data pairs as necessary. If either or both (token or user) have no extension key/data pairs, a tag will not appear. If group membership data appears in the output, the first group membership name or the first group membership field will be preceded by the tag *tagBGM*. If there are no group membership values, the tag will not appear. If a header record has been requested, appropriate field names are written for each option. The field names will appear only once, even though the actual data may appear more than once. When appropriate, the special identifier tag names will also appear. Header records for the ListTokenInfoByField are as follow: The following field identifiers will be included in the heading, if their associated data has been requested: Token information: chSerialNum, PINClear, iNumDigits, iInterval, dateBirth, todBirth, dateDeath, todDeath, dateLastLogin, todLastLogin, iType, bHex, bEnabled, bNewPINMode, iUserNum, iNextCodeStatus, iBadTokenCodes, iBadPINs, datePIN, todPIN, dateEnabled, todEnabled, dateCountsLastModified, todCountsLastModified, bProtected, bDeployed, iCount,Reserved, softPassword User information: iUserNum,chLastName,chFirstName,chDefaultLogin,bCreatePIN, bMustCreatePIN,chDefaultShell,bTempUser,dateStart,todStart, dateEnd,todEnd Token extension data: *tagBTED*,ExtnKey,ExtnData User extension data:: *tagBUED*,ExtnKey,ExtenData Group Membership group names: *tagBGM*,GrpName Group Membership group values: *tagBGM*,GrpDefLogin,GrpDefShell,GrpName,SiteName The options for group membership group names and group membership group values are mutually exclusive. The MiscVariable is used to fix up extension keys and/or data that contains commas. Some users have either intentionally or unintentionally entered commas in their extension data keys or data. Because the retrieval of the extension data and keys is returned as a comma separated list, what is the key and what is the data can be next to impossible to
71 / 94
figure out. If you are requesting extension data in this list, ACEBulkAdmin attempts to fix up key/data pairs that contain more than one comma. It does so by parsing the results, building a key with everything up to the first comma. If the key is valid, it is assumed that the remaining commas are in the data. If the key is not valid, the next section of the data (up to the next comma) is appended to the previous key and the process is repeated. Once a key if found, all extra commas in the key and data are either deleted or replaced as described below. There is no guarantee that the key is the correct one, because it is possible to build keys containing commas that will be valid as either the first portion only, or any concatenated portion. In any case, MiscVariable may be used to control the substitution. MiscVariable may contain the following values: Delete Space <char> delete all extra commas in the key/data pairs replace all extra commas with a space character replace all extra commas with the provided character
If the MiscVariable is either absent or empty, the default action is to replace extra commas by semi-colon. NOTE: To improve efficiency and decrease the likelihood of the ACE/Server log overflowing, when using the LTIF command it is recommend that consideration be given to the loggingoff command line option. This is particularly important when a large database is involved.
List Token Info For TokenSerial

This command will produce token information and user information if the token is assigned. This command duplicates the List Token Info by Field command (above) in every respect except one. The difference is that this command will supply the information for a single supplied token serial. Action Required Fields Optional Fields LTI TokSerial OutputOption, ExtnDataOption, MiscVariable
Consult the List Token Info by Field command (above) for the definition of the optional fields usage and output formatting options.
72 / 94
Multiple Token Action

The multiple token action commands are provided as a means of assigning a token or issuing a replacement token to a large number of users. There are some limitations to these actions, but they are outweighed by the amount of effort that can be saved. If a database is properly populated with extension data, the output of these commands can be used for automated notification. Just as the above list commands, the output of these commands is a comma separated variable list that can easily be processed by most scripting languages, spreadsheet programs, or word processor programs. If the report is redirected to stdout or stderr, the last line of output will be the single word Done followed by a newline sequence. In this case, a report that generated no output will consist of a single line beginning with the word Done. As both of these commands rely heavily on the ListTokensByField command, users of versions prior to Ace Server version 5.0 should consult the note (indicated by #) immediately following the Field / Type / Value chart of the ListTokenInfoByField command (above.)
Multiple Softtoken Deployment
(ACE Server Version 5.1 and later)
Deploys software tokens in XML format. Specifies a range of software tokens and deploys them to assigned users. Prior to calling this function, all users must be in the RSA ACE/Server database, and all software tokens included in the range must be assigned to a user. The tokens can be deployed to users as specified by serial number, or default login. The following table lists acceptable values for use with rangeMode, the affect each value has on subsequent parameters, and the action taken when the function is called. Warning, if the Token deployed field is anything other than 0, the token cannot be deployed and you will receive an Invalid Token error message. Action Required Fields Optional Fields MSD rangeMode, startRange, endRange, password, fileName copyProtect, overOption, logFile, closeOption
RangeMode StartRange 0 TokSerial
EndRange Ignored
1 2
Ignored TokSerial
Ignored TokSerial
Action Taken Deploys one assigned software token specified by the serial number in the startRange parameter. Deploys all assigned software tokens. Deploys all assigned software tokens within the specified range of serial numbers.
73 / 94
DefLogin
Ignored
DefLogin
DefLogin
5 (Version 6.1 or later)
token serial number
same or
Deploys all software tokens that are assigned to a user with the default login specified in startRange. Deploys all software tokens that are assigned to a range of users specified by a default login provided with startRange and endRange. Deploys one assigned software token (even if the token was previously deployed) specified by the serial number in the startRange parameter. The endrange parameter values are as follow: same retains the token information does not retain the token information All other values return ERROR.
RangeMode
Specifies criteria used to deploy assigned software tokens either by serial number or user default login. See the above table in for details. The beginning software token serial number or user default login in a range. If rangeMode is set to .1., this argument is ignored. The ending software token serial number or user default login in a range. If rangeMode is set to either .0., .1., or .3., this argument is ignored.
startRange
endRange
passWord
Specifies that a password be provided by an administrator in order to access an RSA SecurID software token XML file. If there is no password associated with the file, an empty string may be passed.
Specifies the name of the output XML file. If left empty, the fileName defaults to softTokenDeployment.xml".
fileName
copyProtect
Specifies whether the copy protection is enabled for the software tokens in the XML file. If copy protection is
74 / 94 Revised: June 22, 2011
enabled, the Software Token record cannot be removed from the directory in which it is installed on a users computer. If 0, copy protection is disabled; if any other value, copy protection is enabled.
overOption
Overwrites the output of a previously generated XML file. If any value other than 0, the file is overwritten; if 0 is used, and a previous version of he file exists, an error is returned. The name of a log file containing the status of the deployment operation. Use one of these values when calling the function once, or repeatedly: -a: adds ranges of software tokens to an XML file resulting from each instance of the function being called repeatedly. The file is kept open and updated with each range of software tokens. -c: when the function is called once, software tokens are NOT added to an XML file, and the file is closed when the function completes. <empty>If the function is called once and an empty string is passed, the resulting range of software tokens are added to an XML file, and the file is closed when the function completes.
logFile
closeOption
Note: To generate a valid XML file, you must terminate each file with either the c or empty close option. The difference between the two options is that the c option will simply append the trailer information and close the file. The empty string option will append any softToken deployment information requested with this input line, then append the trailer information and close the file. For example:
Action, rangeMode, startRange, endRange, password, fileName, copyProtect, overOption, logFile, closeOption
msd,3,50546254,50546257,,SERegion.xml,0,1,,-a msd,3,50546354,50546472,,SERegion.xml,0,1,,-a msd,0,,,,,,,-c msd,3,45546354,45546472,,WESTRegion.xml,0,1,,-a msd,3,48546354,48546472,,WESTRegion.xml,0,1,,-a msd,3,96346354,96346472,,WESTRegion.xml,0,1,,-a msd,3,97546354,97546472,,WESTRegion.xml,0,1 The above input will create two XML files, SERegion.xml and WESTRegion.xml. The third line terminates the SERegion.xml file by appending the trailer information and proper xml closing tags. The last line accomplishes the same thing for the
75 / 94
WESTRegin.xml file in addition to adding data for token serial numbers 97546354 through 97546364.
Multiple Token Assignment

This command is used to scan the database for users that do not have a token or password currently assigned and who are not flagged as a remote user. If a user matches these conditions, a token will be assigned. The type of token to be assigned is determined by an input parameter. When the token is assigned, its PIN is cleared and the token is disabled. A listing will be generated. The list content is determined by input parameters. The listing will indicate the token serial number assigned and the user that its assigned to. The listing can be useful for automated notification or mailing label generation. Action Required Fields Optional Fields MTA None CompareField, OutputOption, ExtnDataOption, MiscVariable,Tokenabled,SetPin,PinMode, SoftIDParams, SoftIDPW
Input field definitions:

CompareField This parameter is used to indicate what type of token to assign. -1 Any unassigned token (default if empty)
There must be enough tokens of the desired type imported into the database to satisfy the number of users needing a token assigned. If there are not enough unassigned tokens in the database, the process will run until the last available token has been assigned. At that point, the process will terminate and an appropriate entry will be recorded in the log. If software tokens are being assigned, the g and gdir command line options maybe used to instruct ACEBulkAdmin to generate software token database files and place them in the specified directory. OutputOption This parameter is used to determine the information that will be included in the output report for each token assigned. If extension data fields have been appropriately initialized, they can be utilized in an automated
76 / 94
notification system or for automated mailing label generation. The report contains one line for each assigned token and is in comma separated variable format (CSV.) Most scripting languages as well as document and spreadsheet editors can parse these files and generate the desired end format. 0 - tokSerial,defLogin,FirstName,LastName 1 - Option 0 + ldap source 2 - Option 0 + remote alias 3 - Option 0 + profile name 4 - Option 0 + 1 + 2 + 3 10 - tokSerial,<userInfo> 11 - Option 10 + 1 12 - Option 10 + 2 13 - Option 10 + 3 14 - Option 10 + 1 + 2 + 3 h | H - output header line r | R - Report only a | A - Open results in append mode. If the append mode is not specified, then new is assumed. Append and Header may be used simultaneously, which may result in heading lines within the file body. This choice is intentional and it is up to the user to determine which options make sense and whether or not down stream applications will be able to correctly process this file. Also, because CIF commands may be used between list commands, if the append option is used, data columns may not line up. Again, this action intentional and the user must choose the options appropriate for the desired outcome. ExtnDataOption This parameter is used to indicate whether or not extension data should be included in the output report. 0 - No additional output 2 - Include user extension data 4 - Include group membership group names 6 Option 2 plus option 4 8 - Include group membership group fields 10 Option 2 plus option 8 MiscVariable This parameter is used to control extension data comma replacement. Many users, either intentionally or unintentionally, have included commas in extension data. The ACE Server custom API, (used by ACEBulkAdmin to interface to the database) can sometimes incorrectly parse this data because it returns the data in a comma delimited list. In certain instances, the API cannot distinguish between API list separators and commas contained in the data. This parameter can help eliminate these issues, by replacing or deleting the
77 / 94
extension data commas. The replacement, if requested, only affects the generated report and is never saved back in the database. <char> - character to replace imbedded extension key/data commas space replace commas with a space delete - delete commas If no value is supplied in MiscVariable, the default action is to replace imbedded commas with the semi-colon (;) character. For additional information on report formatting, see the ListUserInfoByField (LTIF) and ListTokenInfoByField (LTIF) commands listed above in this manual. TokEnabled This parameter is used to control the enabled/disabled state of the assigned token. 0 Disable the assigned token (default) 1 Enable the assigned token SetPin This parameter is used to initialize the PIN of the newly assigned token. This parameter has no effect on software tokens. -1 Assign a randomly generated PIN. (The new PIN will be listed in the output report.) 0 Clear PIN. (Default) This action will automatically put the token in new pin mode. ? Any other value will be will be used as the new pin. Note: Assigning a literal value here will set all newly assigned tokens to this pin. PinMode This parameter is used to control the new pin mode of the newly assigned token. This parameter has no effect on software tokens. 0 No action is taken (Default) 1 Set the newly assigned token to new PIN mode. SoftIDParams - This field is used by the add-token commands when a softID token seed record file is being created. When used, this field must contain three decimal digits that control the following seed file generation characteristics: Encryption Key Type: 0, 1 or 2 Copy Protection Flag: 0 or 1 Password usage and Interpretation method: 0, 1, 2, or 3 See the documentation for the Sd_MkSoftIDExt command in the cust_admin.pdf file in the Ace Server documentation folder.
78 / 94
SoftIDPW - This field is used by the add-token commands when a softID token seed record field is being created. When used, this field supplies a password to be used for the seed file encryption.
NOTE: To improve efficiency and decrease the likelihood of the ACE Server log overflowing, when using the MTA command it is recommend that consideration be given to the loggingoff command line option. This is particularly important when a large database is involved.
Multiple Token Disable/Rescind

This command is used to scan the database for assigned tokens that have not been used (logged on) for a specified period of time and disable or rescind them. The database is scanned for assigned tokens and the last logon date is compared with the current date cutoff date. The cutoff value is supplied in the CompareValue field. The token types scanned can be all, or a specific type determined by the CompareField value. The listing will indicate the token serial number being disabled/rescinded and the user that its assigned to. There is an optional revoke mode for rescinding software tokens. Additional listing information is available as noted below. The listing can be useful for automated notification or mailing label generation. Action Required Fields Optional Fields MTD CompareType CompareField, CompareValue, ExtnDataOption, MiscVariable OutputOption,

CompareField This optional parameter is used to indicate what type of token to scan for. -1 Any assigned token (default if empty)
CompareType This parameter designates the type of action to perform. 1 Disable inactive tokens (include last logon date of 1/1/1986) 2 Disable inactive tokens (exclude last logon date of 1/1/1986) 3 Rescind inactive tokens (include last logon date of 1/1/1986) 4 Rescind inactive tokens (exclude last logon date of 1/1/1986) 5 Option 3 + Revoke (Revoke only affects software tokens) 6 Option 4 + Revoke (Revoke only affects software tokens)
Note: When a token is imported into the system, the last logon date is initialized to 01/01/1986, the birth date of RSA. To isolate a token that has not been used yet from one that has been used but not for some period of time, use option 2 or 4. CompareValue This optional parameter is used to set the cutoff date to determine inactivity. Valid entries: 0 or empty Cutoff date is current date 90 days A number from 1 through 365 Cutoff date is set to current date number. A date of in the following format, mm/dd/yyyy. The date must be less then or equal to the current date 365 days. The cutoff date will be set to this date. OutputOption This parameter is used to determine the information that will be included in the output report for each token that is disabled. If extension data fields have been appropriately initialized, they can be utilized in an automated notification system or for automated mailing label generation. The report contains one line for each disabled/rescinded token and is in comma separated variable format (CSV.) Most scripting languages as well as document and spreadsheet editors can parse these files and generate the desired end format. 0 - tokSerial,defLogin,FirstName,LastName 1 - Option 0 + ldap source 2 - Option 0 + remote alias 3 - Option 0 + profile name 4 - Option 0 + 1 + 2 + 3 10 - tokSerial,<userInfo> 11 - Option 10 + 1 12 - Option 10 + 2 13 - Option 10 + 3 14 - Option 10 + 1 + 2 + 3 h | H - output header line r | R - Report only a | A - Open results in append mode.
If the append mode is not specified, then new is assumed. Append and Header may be used simultaneously, which may result in heading lines within the file body. This choice is intentional and it is up to the user to determine which options make sense and whether or not down stream applications will be able to correctly process this file. Also, because CIF commands may be used between list commands, if the append option is used, data columns may not line up. Again,
80 / 94
this action intentional and the user must choose the options appropriate for the desired outcome. ExtnDataOption This parameter is used to indicate whether or not extension data should be included in the output report. 0 1 2 3 4 5 6 7 8 9 10 11 no additional data listed include token extension data include user extension data option 1 and 2 include group membership group names option 1 and 4 option 2 and 4 option 3 and 4 include group membership field values option 1 and 8 option 2 and 8 option 3 and 8
Because these options may appear zero or more times, formatting tags are inserted to assist in parsing the data. If token or user extension data appears in the output, the first extension data key will be preceded by *tagBTED* for token extension data and *tagBUED* for user extension data. The tag will be followed by as many extension key/data pairs as necessary. If either or both (token or user) has no extension key/data pairs, a tag will not appear. If group membership data appears in the output, the first group membership name or the first group membership field will be preceded by the tag *tagBGM*. If there are no group membership values, the tag will not appear. If a header record has been requested, appropriate field names are written for each option. The field names will appear only once, even though the actual data may appear more than once. When appropriate, the special identifier tag names will also appear. MiscVariable This parameter is used to control extension data comma replacement. Many users, either intentionally or unintentionally, have included commas in extension data. The ACE Server custom API, (used by ACEBulkAdmin to interface to the database) can sometimes incorrectly parse this data because it returns the data in a comma delimited list. In certain instances, the API cannot distinguish between API list separators and commas contained in the data. This parameter can help eliminate these issues, by replacing or deleting the extension data commas. The replacement, if requested, only affects the generated report and is never saved back in the database. <char> - character to replace imbedded extension key/data commas space replace commas with a space delete - delete commas
81 / 94
If no value is supplied in MiscVariable, the default action is to replace imbedded commas with the semi-colon (;) character. For additional information on report formatting, see the ListUserInfoByField (LTIF) and ListTokenInfoByField (LTIF) commands listed above in this manual.
NOTE: To improve efficiency and decrease the likelihood of the ACE/Server log overflowing, when using the MTR command it is recommend that consideration be given to the loggingoff command line option. This is particularly important when a large database is involved.
Multiple Token Replacement

This command is used to scan the database for tokens that have expired, are about to expire or both. An input parameter is used to indicate whether or not the associated user can have additional tokens. If the user qualifies and is not flagged as a remote user, a replacement token is assigned. The type of token to be assigned is determined by an input parameter. When the token is assigned, its PIN is cleared and the token is disabled. A listing will be generated. The list content is determined by input parameters. The listing will indicate the token serial number assigned and the user that its assigned to. The listing can be useful for automated notification or mailing label generation. Action Required Fields Optional Fields MTR None CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable, TokenSerial, TokEnabled, SetPin, PinMode, SoftIDParams, SoftIDPW

CompareField This parameter is used to indicate what type of token to assign. -2 -1
0 1 2 4 5 6 9
Same as token being replaced Any unassigned token (default if empty)

RSA SecurID Standard Card RSA SecurID PINPAD Card RSA SecurID Key Fob RSA SecurID Software Token (formerly SoftID) RSA SecurID Software Token (128 bit AES) RSA SecurID modem RSA SID800 Token
There must be enough tokens of the desired type imported into the database to satisfy the number of users needing a token assigned. If there are not enough
82 / 94
unassigned tokens in the database, the process will run until the last available token has been assigned. At that point, the process will terminate and an appropriate entry will be recorded in the log. If software tokens are being assigned, the g and gdir command line options maybe used to instruct ACEBulkAdmin to generate software token database files and place them in the specified directory. CompareType This parameter determines the range to be used for searching for expired tokens. 0 - Replace tokens already expired (default) 1 - Replace tokens expiring in a number of days 2 - Options 0 and 1 CompareValue (time in which token will expire) 0 - (the default) days from current date mm/dd/yyyy TokenSerial 0 - unconditional replacement (default) 1 - replace if expired token is the only assigned token TokEnabled This parameter is used to control the enabled/disabled state of the assigned token. 0 Disable the assigned token (default) 1 Enable the assigned token SetPin This parameter is used to initialize the PIN of the newly assigned token. This parameter has no effect on software tokens. -1 Assign a randomly generated PIN. (The new PIN will be listed in the output report.) 0 Clear PIN. (Default) This action will automatically put the token in new pin mode. ? Any other value will be will be used as the new pin. Note: Assigning a literal value here will set all newly assigned tokens to this pin. PinMode This parameter is used to control the new pin mode of the newly assigned token. This parameter has no effect on software tokens. 0 No action is taken (Default) 1 Set the newly assigned token to new PIN mode. OutputOption This parameter is used to determine the information that will be included in the output report for each token assigned. If extension data fields have been appropriately initialized, they can be utilized in an automated notification system or for automated mailing label generation. The report contains
83 / 94
one line for each assigned token and is in comma separated variable format (CSV.) Most scripting languages as well as document and spreadsheet editors can parse these files and generate the desired end format. Base Information: chSerialNum_O, chSerialNum_R, iType, chNewPin, , chDefaultLogin, chFirstName, chLastName (These are the header names for the expired token serial number, the replacement token serial number, the replacement token type, the user default login, the user first name and the user last name) 0 Base Information only 1 - Option 0 + ldap source 2 - Option 0 + remote alias 3 - Option 0 + profile name 4 - Option 0 + 1 + 2 + 3 10 Base Information + <userInfo> 11 - Option 10 + 1 12 - Option 10 + 2 13 - Option 10 + 3 14 - Option 10 + 1 + 2 + 3 h | H - output header line r | R - Report only a | A - Open results in append mode. If the append mode is not specified, then new is assumed. Append and Header may be used simultaneously, which may result in heading lines within the file body. This choice is intentional and it is up to the user to determine which options make sense and whether or not down stream applications will be able to correctly process this file. Also, because CIF commands may be used between list commands, if the append option is used, data columns may not line up. Again, this action intentional and the user must choose the options appropriate for the desired outcome. ExtnDataOption This parameter is used to indicate whether or not extension data should be included in the output report. 0 - No additional output 2 - Include user extension data 4 - Include group membership group names 6 - Option 2 plus option 4 8 - Include group membership group fields 10 Option 2 plus option 8
84 / 94
MiscVariable This parameter is used to control extension data comma replacement. Many users, either intentionally or unintentionally, have included commas in extension data. The ACE/Server custom API (used by ACEBulkAdmin to interface to the database) can sometimes incorrectly parse this data because it returns the data in a comma delimited list. In certain instances, the API cannot distinguish between API list separators and commas contained in the data. This parameter can help eliminate these issues, by replacing or deleting the extension data commas. The replacement, if requested, only affects the generated report and is never saved back in the database. <char> - character to replace imbedded extension key/data commas space replace commas with a space delete - delete commas If no value is supplied in MiscVariable, the default action is to replace imbedded commas with the semi-colon (;) character. For additional information on report formatting, see the ListUserInfoByField (LTIF) and ListTokenInfoByField (LTIF) commands listed above in this manual. SoftIDParams - This field is used by the add-token commands when a softID token seed record file is being created. When used, this field must contain three decimal digits that control the following seed file generation characteristics: Encryption Key Type (ignored for AES tokens): 0, 1 or 2 Copy Protection Flag: 0 or 1 Password usage and Interpretation method: 0, 1, 2, or 3 For 64 bit tokens, Sd_MkSoftIDExt is called to deploy the token. For more information, see the documentation for this command in the cust_admin.pdf file in the Ace Server documentation folder. For AES Software tokens (comparefield == 5) Sd_DeployToken is called to deploy the token. Documentation can be found for this command in the in the ace_admin_toolkit.pdf (v5.1 and v5.2) or authmgr_admin_toolkit.psf (v6.0 and v6.1). SoftIDPW - This field is used by the add-token commands when a softID token seed record field is being created. When used, this field supplies a password to be used for the seed file encryption. NOTE: To improve efficiency and decrease the likelihood of the ACE/Server log overflowing, when using the MTR command it is recommend that consideration be given to the loggingoff command line option. This is particularly important when a large database is involved.
85 / 94
General Functions
Change Input Format
The change input format command may be used anywhere in the input file and as many times as desired. This command is used to override the default input file format and simplify the input file build process. It is also used to dynamically redefine the input file format at run time. This command consists of CIF in the action field followed by one or more field labels. This line is formatted in CSV or Quoted ASCII Text, depending on preceding input. If this is the first line of an input file, then it will determine the format type (CSV or Quoted ASCII Text.) The CIF command is case insensitive. The number and order of field names is arbitrary.
Action Required Field Names Optional Field Names
CIF Action
LastName, FirstName, DefLogin, DefShell, TokSerial, ReplTokSerial, TokEnabled, SetPin, CreatePin, PinMode, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData, ExtnTable, SiteName, ClntType, ClntEncryption ,ClntFlags, AgentHostName, AgentHostAddress, AgentHostType, AgentHostEncryptionType, AgentHostFlags, ActingMaster, ActingSlave, SharedSecret, SecondaryNodeName, SecondaryNodeAddress, AgentHostKey, ParameterType, ActionControl, SoftIDParams, SoftIDPW, RemoteAlias, RealmName, CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable, ProfileName The intended use of this command is to simplify the input file build process by allowing the user to define command lines unique to each users requirement. An example of this would be to define the first set of input as add group (AG), followed by add client, followed by add user. A file of this type might look something like the following:
Cif,action,defgrpname Ag,group1 Ag,group2 Ag,group3
86 / 94
. . . CIF, action,ClntName,SiteName ac,client1,site1 ac,client2,site1 ac,client3,site2 ac,client4,site2 . . . CIF,Action,LastName,DefLogin,TokSerial,TokEnabled Aut,LN1,l1,11223344,1 Aut,ln2,l2,33445677,1 . . .
Note: If a CIF command fails for any reason, all input lines are logged and ignored until a valid CIF command is processed or the end of file, which ever occurs first.
Change Results File Name

Previously, the results file name could be changed on the command line and the file name was in effect for the entire session. This command may be used to change the results file name any number of times during an ACEBulkAdmin session. The results file is opened and closed at the command level, not the session level. Therefore, this command may be used between multiple listing commands in one session. This will prevent one list command from overwriting the results of a previous list command in any one session. The result file name is supplied in the MiscVariable. This variable may include a drive, path and extension, where applicable. Leaving MiscVariable empty resets the result file name back to its default. Action Required Fields
Optional Fields
CRFN None
MiscVariable
Quit
The quit command is used to terminate the standard input file (STDIN). It is ignored if present in a disk input file. Action Required Fields Optional Fields QUIT None None
87 / 94
Run Script command

The run script command may be used to run external TCL script files. The tcl-sd interpreter is used to interpret the script file. Because ACEBulkAdmin has no prior knowledge of any returned results, it will only log returned information in the event of an error. The intent of the RUN command is to provide for customized processing; the results file for instance, and keep theses processes under control of an ACEBulkAdmin job. There is only one ACEBulkAdmin input variable for the RUN command. It may contain up to 11, space delimited variables, the first of which is the path and file name of the script file. Action Required Fields Optional Fields RUN MiscVariable None
Example: Action,MiscVariable Run /jobs/myjob/notify.tcl notifyType1 /jobs/otherjob/sometext 127.0.0.1 25 The above run command contains one variable (MiscVariable) that contains the script name (/jobs/myjob/notify.tcl) and 4 parameters, notifyType1, /jobs/otherjob/sometext, 127.0.0.1 and 25.
88 / 94
Command Table (Alphabetic listing of commands)

Command AAH Description add agent host Required Fields AgentHostName and/or AgentHostAddress Optional Fields SiteName, AgentHostType, AgentHostEncryptionThype, AgentHostFlags, ActingMaster, ActingSlave, SharedSecret SitName, ClntDefShell, ExtnKey, ExtnData ExtnData SiteName, ClntDefShell, ExtnKey, ExtnData
AC ACE ACS AG AGC AGE AGS AP APU AS ASE ASN
add client add client extension data add client to site add group add group to client add group extension data add group to site Assign profile to user add password to user add site add site extension data add secondary node to agent host add token extension data add token to user
ClntName ClntName, ExtnKey ClntName, GrpName GrpName, ClntName GrpName, ExtnKey GrpName DefLogin or TokSerial, ProfileName DefLogin or TokSerial, SetPin SiteName SiteName, ExtnKey AgentHostName, SecondaryNodeName and/or SecondaryNodeAddress TokSerial, ExtnKey DefLogin or TokSerial, ReplTokSerial, TokEnabled DefLogin or TokSerial, MiscVariable, TokEnabled LastName, DefLogin
ExtnData SiteName
CreatePin
ExtnData
ATE ATU
ExtnData SetPin, PinMode, CreatePin, SoftIDParams, SoftIDPW SetPin, PinMode, CreatePin, SoftIDParams, SoftIDPW FirstName, DefShell, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell,ExtnKey, ExtnData ClntDefLogin, ClntDefShell ExtnData GrpDefLogin, GrpDefShell
ATUA
add token to user automatic add new user and optionally add user to an existing group and/or an existing client add user to client add user extension data add user to group
AU
AUC AUE AUG
DefLogin or TokSerial, ClntName TokSerial or DefLogin, ExtnKey DefLogin or TokSerial, GrpName
89 / 94
AUP
AUR
add user with password and optionally add user to an existing group and/or an existing client Add user remote
LastName, DefLogin, SetPIn
FirstName, DefShell, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData FirstName, DefShell, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell,ExtnKey, ExtnData FirstName, DefShell, SetPin, PinMode, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData, SoftIDParams, SoftIDPW FirstName, DefShell, SetPin, PinMode, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData, SoftIDParams, SoftIDPW ExtnData LastName, FirstName, DefShell, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell,ExtnKey, ExtnData LastName, FirstName, SetPIn, DefShell, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData
DefLogin, LastName, RemoteAlias, RealmName
AUT
AUTA
add new user with token and optionally add user to an existing group and/or an existing client Add new user and assign available token form system
LastName, DefLogin, TokSerial, TokEnabled
LastName, DefLogin, TokEnabled, MiscVariable
AYE CAU
CAUP
CAUT
CCE CCS
add system extension data Change or add new user. If deflogin exists, update it. Otherwise add user (au). Change or add new user with password. If deflogin exists, update user. Otherwise add user with password (AUP). Change or add new user with token. If token already assigned, update user. Otherwise add user with token (AUT).B2 change client extension data change client's site
ExtnKey DefLogin
DefLogin
TokSerial
LastName, FirstName, DefShell, SetPin, PinMode, CreatePin, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData ExtnData
ClntName, ExtnKey ClntName, SiteName
90 / 94
CGE CGS CIF
change group extension data change group's site Change input format
GrpName, ExtnKey GrpName, SiteName Action
ExtnData
CPS CRFN CSE CTD CTE CTI CTS
change pin status Change results file name. change site extension data change token delayed change token extension data change token immediate change token status
TokSerial
LastName, FirstName, DefLogin, DefShell, TokSerial, ReplTokSerial, TokEnabled, SetPin, CreatePin, PinMode, GrpName, GrpDefLogin, GrpDefShell, ClntName, ClntDefLogin, ClntDefShell, ExtnKey, ExtnData, ExtnTable, SiteName, ClntType, ClntEncryption ,ClntFlags, AgentHostName, AgentHostAddress, AgentHostType, AgentHostEncryptionType, AgentHostFlags, ActingMaster, ActingSlave, SharedSecret, SecondaryNodeName, SecondaryNodeAddress, AgentHostKey, ParameterType, ActionControl, SoftIDParams, SoftIDPW, RemoteAlias, RealmName, CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable, ProfileName SetPin, PinMode
MiscVariable ExtnData
SiteName, ExtnKey TokSerial, ReplTokSerial TokSerial, ExtnKey TokSerial, ReplTokSerial TokSerial, TokEnabled
ExtnData
91 / 94
CTSX CTU CUD CUE CUR CAUE
CYE DAP DC DCE DCS DG DGC DGE DGS DS DSE DSN
DT DTE DU DUC DUE DUG DYE EAFXD
EAOFF EAOTP
Change token status extended. Change temporary user change user data for token change user extension data Change user remote Change or add user extension data change system extension data delete admin privileges delete client delete client extension data delete client from site delete group delete group from client delete group extension data delete group from site delete site delete site extension data delete secondary node from agent host delete token from User delete token extension data delete user delete user from client delete user extension data delete user from group delete system extension data Set emergency access fixed password Set emergency access off Set emergency
DefLogin or TokSerial, TokEnabled Deflogin or TokSerial LastName, FirstName, DefLogin, DefShell, TokSerial or DefLogin, ExtnKey DefLogin, RemoteAlias, RealmName TokSerial or DefLogin, ExtnKey ExtnKey DefLogin or TokSerial ClntName ClntName, ExtnKey ClntName GrpName GrpName, ClntName GrpName, ExtnKey GrpName, SiteName SiteName SiteName, ExtnKey AgentHostName, SecondaryNodeName TokSerial TokSerial, ExtnKey DefLogin or TokSerial ClntDefLogin, ClntName TokSerial or DefLogin, ExtnKey GrpDefLogin, GrpName ExtnKey TokSerial, SetPin
MiscVariable DefShell, ClntDefLogin, GrpDefShell, GrpDefLogin TokSerial, MiscVariable ExtnData
ExtnData
ExtnData
CreatePin
TokSerial TokSerial,SetPin
CreatePin
92 / 94
SSO LDLD LH
access one time password Set table sort order List and/or delete log data List History
MiscVariable, OutputOption
LogFile and/or ActionControl None
MiscVariable, OutputOption DefLogin or TokSerial MiscVariable OutputOption
LSN
LTIF
list secondary nodes for agent host list token information by field.
AgentHostName
None
LTI
LUIF
list token information for token serial list user information by field.
TokSerial
None
LUI
MSD
list user information for user multiple softtoken deployment
DefLogin or TokSerial
rangeMode
MTA
scan database and assign tokes to qualified users
None
MTD
MTR
scan database and disable or rescind tokens based on last login date. scan database and assign replacement tokens to qualified users
CompareType
None
CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable OutputOption, ExtnDataOption, MiscVariable CompareField, CompareType, CompareValue, OutputOption, ExtnDataOption, MiscVariable OutputOption, ExtnDataOption, MiscVariable startRange, endRange, passWord, fileName, copyProtect, overOption, logfile, closeOption CompareField, OutputOption, ExtnDataOption, MiscVariable, TokenEnabled, SetPin, PinMode, SoftIDParams, SoftIDPW CompareField, CompareValue, OutputOption, ExtnDataOption, MiscVariable CompareField, CompareType, CompareValue, TokenSerial, TokEnabled, SetPin, PinMode,
93 / 94
OutputOption, ExtnDataOption, MiscVariable, SoftIDParams, SoftIDPW RT RUN SAH rescind token run script change agent host fields TokSerial MiscVariable AgentHostKey, ParameterType, ActionControl
AgentHoatName, AgentHostAddress, SiteName, AgentHostType, AgentHostEncryptionType, AgenthostFlags, ActingMaster, ActingSlave, SharedSecret
Up
UT UUD
Unassigned the currently assigned user profile unassign token update user data
DefLogin or TokSerial
TokSerial DefLogin or TokSerial
LastName, FirstName, DefShell, DefLogin (if TokSerial is present), MiscVariable
94 / 94

ACEBulkAdmin Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ACEBulkAdmin Guide

Uploaded by

Copyright:

Available Formats

Professional Services

Custom Application Guide

Revision: Issued: Revised:

2.2.16 February 15, 2001 22, June, 2011

RSA Professional Services

Custom Application Guide.

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Operating Systems Supported

ACE/Server Versions Supported

Admin API Limitations

Common to all versions

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Installation and Operating Instructions

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Operating System Independent Requirements

Microsoft Windows Specific Requirements

UNIX Specific Requirements

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

RSA Professional Services

Custom Application Guide.

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Msg Type / Level

Boj Eoj Info Error Successful Failure

0 Yes Yes Yes Yes Yes Yes

1 Yes Yes No Yes Yes No

2 Yes Yes No Yes No Yes

3 Yes Yes No Yes Yes Yes

An example of each message type:

Failure: Line Success: Line EOJ

: 2001-02-16 14:31:18 - Terminating

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

servers for authentication, performing administrative functions only on the master.

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Input File Processing

Revised: June 22, 2011

RSA Professional Services

Custom Application Guide.

Preparing the Datafile