Sun Java System Identity Synchronization for Windows 1 2004Q3 Installation and Configuration Guide |
Appendix A
Using the Identity Synchronization for Windows Command Line UtilitiesIdentity Synchronization for Windows enables you to perform a variety of tasks from the command line. This appendix explains how to execute the Identity Synchronization for Windows command line utilities to perform different tasks. The information is organized into the following sections:
Common FeaturesThe Identity Synchronization for Windows command line utilities share the following features:
Common Arguments
This section describes the arguments (options) that are common to most of the command line utilities. The information is organized into the following tables:
- Table A-1 Arguments Common to All Subcommands: Describes the following arguments, which are common to all of the idsync subcommands (except prepds) and migration tools.
-D <bind-DN> -w <bind-password | -> [-h <Configuration Directory-hostname>]
[-p <Configuration Directory-port-no>] [-s <rootsuffix>] [-Z] [-P <cert-db-path>]
[-m <secmod-db-path>]
- Table A-2 SSL-Related Arguments Common to All Subcommands: Describes optional arguments that provide information about securely accessing the Configuration Directory Server using Secure Socket Layer (SSL). These arguments are also common to all of the idsync subcommands and the migration tools.
- Table A-3 Configuration Directory Arguments: Describes arguments related to the configuration directory. These arguments are common to two or more idsync subcommands and migration tools.
Note
Arguments that are unique to a particular subcommand will be explained in the pertinent subcommand section.
Entering Passwords
Wherever a password argument is required (such as -w <bind-password> or
-q <configuration_password>), you can use the “-” argument to tell the password program to read the password from STDIN.If you use the “-” value for multiple password options, idsync will prompt you for passwords based on the arguments’ order.
In this case, the program would expect the <bind-password> first, and then for the <configuration-password>.
Getting Help
You can use one of the following commands to display usage information about idsync or any of its subcommands in the command Console:
For usage information
Using the idsync commandYou use the idsync command and subcommands to execute the Identity Synchronization for Windows command line utility.
Unless specifically noted otherwise, you can run the idsync command with subcommands using either of the following methods:
Table A-4 lists all of the idsync utility subcommands and their purpose:
Table A-4 idsync Subcommands Quick Reference
Subcommand
Purpose
certinfo
Displays certificate information based on your configuration and SSL settings
(see Using certinfo)changepw
Changes the Identity Synchronization for Windows configuration password
(see Using changepw)importcnf
Imports an exported Identity Synchronization for Windows version 1.0 configuration XML document (see Using importcnf)
prepds
Prepares a Sun Java System Directory Server source for use by Identity Synchronization for Windows (see Using prepds)
printstat
Displays a list of steps you must perform to complete the installation/configuration process. Also provides the status of installed connectors, the system manager, and the Message Queue (see Using printstat)
resetconn
Resets connector states in the configuration directory to uninstalled
(see Using resetconn)resync
Links and resynchronizes existing users and pre-populates directories as part of the installation process (see Using resync)
startsync
Starts synchronization (see Using startsync)
stopsync
Stops synchronization (see Using stopsync)
Using certinfo
You can use the certinfo subcommand to display certificate information based on your configuration and SSL settings. This information can help you determine which certificates must be added for each connector and/or Directory Server Plugin certificate database.
To display certificate information, open a terminal window (or Command Window) and type the idsync certinfo command as follows:
Note
Because the certinfo subcommand does not have access to the connectors’ and Directory Server’s certificate databases, some of the required steps it lists might have already been performed.
For example:
idsync certinfo -w <admin-password> -q <configuration-password>
Note
For detailed information about the certinfo arguments, review Common Arguments.
Using changepw
You can use the changepw subcommand to change the Identity Synchronization for Windows configuration password.
To change the configuration password for Identity Synchronization for Windows:
- Stop all Identity Synchronization for Windows processes (for example, System Manager, Central Logger, Connectors, Console, Installers/Uninstallers).
- After stopping all the processes, back up the ou=Services tree by exporting the configuration directory to ldif.
- Type the idsync changepw command as follows:
idsync changepw [-D <bind-DN>] -w <bind-password | -> [-h <Configuration Directory-hostname>] [-p <Configuration Directory-port-no>] [-s <rootsuffix>]
-q <configuration_password> [-Z] [-P <cert-db-path>] [-m <secmod-db-path>]
-b <new password | - > [-y]For example:
idsync changepw -w <admin password> -q <old config password> -b -q <new config password>
The following arguments are unique to changepw:
Table A-5 idsync changepw Arguments
Argument
Description
-b <password>
Specifies a new configuration password. The - value reads the password from standard input (STDIN).
[-y]
Does not prompt for command confirmation.
Note
For detailed information about other changepw arguments, review Common Arguments.
- Respond to the messages that display in the terminal window.
For example,
Are you sure that want to change the configuration password (y/n)? yes
Before restarting the system - you must edit the $PSWHOME/resources/SystemManagerBootParams.cfg file and change the ’deploymentPassword’ to the new value.
SUCCESS- You must modify the SystemManagerBootParams.cfg file before restarting the system.
The SystemManagerBootParams.cfg file in $PSWHOME\resources (where $PSWHOME is the <isw-installation directory>) contains the configuration password the system manager uses to connect to the configuration directory.
For example, you would change the password value as follows:
From: <Parameter name="manager.configReg.deploymentPassword" value="oldpassword"/>
To: <Parameter name="manager.configReg.deploymentPassword" value="newpassword"/>
- If the program reports any errors, restore the configuration directory using the ldif from Step 2 and then try again. The most likely reason for an error is that the Directory Server hosting the configuration directory became unavailable during the password change.
Using importcnf
Caution
Use idsync importcnf only when migrating from Identity Synchronization for Windows 1.0 or 1.0 SP1 to version 1 2004Q3.
After installing Core (Chapter 3, "Installing Core"), use the idsync importcnf subcommand to import your exported Identity Synchronization for Windows version 1.0 (SP1) configuration XML file, which contains Core configuration information.
To import your version 1.0 configuration XML file, open a terminal window (or Command Window) and type the idsync importcnf command as follows:
idsync importcnf [-D <bind-DN>] -w <bind-password | -> [-h <Configuration Directory-hostname>] [-p <Configuration Directory-port-no>] [-s <rootsuffix>] -q <configuration_password> [-Z] [-P <cert-db-path>] [-m <secmod-db-path>] -f <filename> [-n]
For example:
idsync importcnf -w <admin_password> -q <configuration_password> -f “MyConfig.cfg”
The following arguments are unique to importcnf:
Table A-6 idsync importcnf Arguments
Argument
Description
-f <filename>
Specifies the name of your configuration XML document.
-n
Runs in safe mode so you can preview the effects of an operation with no actual changes.
Note
For detailed information about other importcnf arguments, review Common Arguments.
After importing the version 1.0 configuration XML file, you must run prepds on all Directory Server sources configured for synchronization, (see Using prepds) and then you can install the Identity Synchronization for Windows connectors and subcomponents.
Using prepds
You use the console or prepds subcommand to prepare a Sun Java System Directory Server source for use by Identity Synchronization for Windows. You must run prepds before installing the Directory Server Connector.
Running the idsync prepds subcommand applies the appropriate ACI to the cn=changelog entry, which is the root node of the Retro-Changelog database.
The Directory Manager user is a special user on Directory Server who has full rights anywhere inside the Directory Server instance. (ACI does not apply to Directory Manager users.)
For example, only the Directory Manager can set the access control for the Retro-Changelog database, which is one of the reasons why Identity Synchronization for Windows requires Directory Manager credentials for the preferred master server.
Note
If you re-create the Retro-Changelog database for the preferred Sun directory source for any reason, the default access control settings will not allow the Directory Server Connector to read the database contents.
To restore the access control settings for the Retro-Changelog database, run idsync prepds or click the Prepare Directory Server button after selecting the appropriate Sun directory source in the Console.
Note
You can configure your system to automatically remove (or trim) Change-log entries after a specified period of time. From the command line, modify the nsslapd-changelogmaxage configuration attribute in cn=Retro Changelog Plugin, cn=plugins, cn=config:
nsslapd-changelogmaxage: IntegerTimeunit
Where:
For example, nsslapd-changelogmaxage: 2d
For more information, see the “Managing Replication” chapter in the Sun Java System Directory Server 5 2004Q2 Administration Guide.
Note
Be sure to plan your Identity Synchronization for Windows configuration before running idsync prepds because you must know which hosts and suffixes you will be using.
Running idsync prepds on a Directory Server suffix where the Directory Server Connector and Plugin are already installed, configured, and synchronizing will result in a message asking you to install the Directory Server Connector. Disregard this message.
To prepare a Sun Java System Directory Server source, open a terminal window (or a Command Window) and type the idsync prepds command as follows:
idsync prepds [-D <bind-DN>] -w <bind-password | -> [-h <preferred host>]
[-p <preferred-port>] [-s <database-suffix>] [-Z] [-P <cert-db-path>]
[-m <secmod-db-path>] [-j <secondary_host>] [-r <secondary-port>] [-E <admin DN of secondary host>] [-u <password for secondary host | ->] [-x]
For example:
idsync prepds -D “cn=Directory Manager” -w <preferred master password> -h <preferred-host> -p 389 -s dc=example,dc=com -j “secondary host” -r 389 -E “cn=Administrator” -u <secondary master password> -s dc=example,dc=com
Note
The -h, -p, -D, -w, and -s arguments are redefined (as described in the following table) for the prepds subcommand only. In addition, the -q argument does not apply.
Table A-7 describes the arguments that are unique to idsync prepds:
Table A-7 prepds Arguments
Argument
Description
-h <name>
Specifies the DNS name of the Directory Server instance serving as the preferred host.
-p <port>
Specifies port number for Directory Server instance serving as preferred host.
(Default is 389.)-j <name> (optional)
Specifies the DNS name of the Directory Server instance serving as the secondary host (applicable in a Sun Java System Directory Server 5 2004Q2 multimaster replicated (MMR) environment).
-r <port> (optional)
Specifies a port for the Directory Server serving as the secondary host (applicable in a Sun Java System Directory Server 5 2004Q2 multimaster replicated (MMR) environment). (Default is 389.)
-D <dn>
Specifies the distinguished name of the Directory Manager user for the preferred host.
-w <password>
Specifies a password for the Directory Manager user for the preferred host.
The - value reads the password from standard input (STDIN).-E <admin-DN>
Specifies the distinguished name of the Directory Manager user for the secondary host.
-u <password>
Specifies a password for the Directory Manager user for the secondary host.
The - value reads the password from standard input (STDIN).-s <rootsuffix>
Specifies the root suffix to use for adding an index (root suffix where you will be synchronizing users).
Note: The database name of the Preferred and Secondary hosts may vary, but the suffix will not. Consequently, the program can find the database name of each host and use it to add the indexes.
-x
Does not add equality and presence indexes for dspswuserlink attribute to the database.
If you are running idsync prepds in a replicated environment, (for example, where you have a preferred master, a secondary master, and two consumers), you only need to run idsync prepds once for the preferred and secondary masters.
To run idsync prepds
Running the idsync prepds command accomplishes the following:
- On M1:
- Adds indexes on M2.
Note
- Replication ensures that Identity Synchronization for Windows copies schema information and the uid=pswconnector from the preferred master to the secondary master and both consumers.
- You must install the Directory Server Connector once. You must install the Directory Server Plugin in all directories.
- Indexing is required on the preferred and the secondary masters only. (Replication does not push the indexing configuration from the preferred master to the secondary master.)
Using printstat
You can use the printstat subcommand to:
Possible status settings include:
- Uninstalled. The connector is not installed.
- Installed. The connector is installed, but not ready for synchronization because it has not received its runtime configuration yet.
- Ready. The connector is ready for synchronization, but is not synchronizing any objects yet.
- Syncing. The connector is synchronizing objects.
To print the status of installed Connectors, the System Manager, and the Message Queue open a terminal window (or a Command Window) and enter the idsync printstat command as follows:
idsync printstat [-D <bind-DN>] -w <bind-password | -> [-h <Configuration Directory-hostname>] [-p <Configuration Directory-port-no>] [-s <rootsuffix>]
-q <configuration_password> [-Z] [-P <cert-db-path>] [-m <secmod-db-path>]
For example:
idsync printstat -w <admin password> -q <configuration password>
Note
For detailed information about the printstat arguments, review Common Arguments.
Using resetconn
You can use the resetconn subcommand to reset connector states in the configuration directory to uninstalled. For example, if a hardware failure prevents you from uninstalling a connector, use resetconn to change the connector’s status to uninstalled so you can reinstall that connector.
Caution
The resetconn subcommand is intended to be used only in the event of hardware or uninstaller failures.
To reset the state of connectors from the command line, open a terminal window (or a Command Window) and type the idsync resetconn command as follows:
idsync resetconn [-D <bind-DN>] -w <bind-password> | -> [-h <Configuration Directory-hostname>] [-p <Configuration Directory-port-no>] [-s <rootsuffix>] -q <configuration_password> [-Z] [-P <cert-db-path>] [-m <secmod-db-path>] -e <directory-source-name> [-n]
For example:
idsync resetconn -w <admin password> -q <configuration_password> -e “dc=example,dc=com“
Table A-7 describes the arguments that are unique to resetconn:
Table A-8 idsync resetconn Arguments
Argument
Description
-e <dir-source>
Specifies the name of the directory source to reset.
-n
Runs in safe mode so you can preview the effects of an operation with no actual changes.
Note
idsync printstat can be used to find directoy source names.
For detailed information about the other resetconn arguments, review Common Arguments.
Using resync
You can use the resync subcommand to bootstrap deployments with existing users. This command uses administrator-specified matching rules to
- Link existing entries
- Populate an empty directory with the contents of a remote directory
- Bulk-synchronize attribute values between two existing user populations
Note
For more detailed information about linking and synchronizing users, see Synchronizing Existing Users.
To resynchronize existing users and to pre-populate directories, open a terminal window (or a Command Window) and type the idsync resync command as follows:
idsync resync [-D <bind-DN>] -w <bind-password> | -> [-h <Configuration Directory-hostname>] [-p <Configuration Directory-port-no>] [-s <rootsuffix>] -q <configuration_password> [-Z] [-P <cert-db-path>] [-m <secmod-db-path>] [-n] [-f <xml filename for linking>] [-k] [-a <ldap-filter>] [-l <sul-to-sync>] [-o Sun | Windows] [-c] [-x] [-u] [-i ALL_USERS | NEW_USERS | NEW_LINKED_USERS]
For example:
idsync resync -w <admin password> -q <configuration_password>
Table A-9 describes the arguments that are unique to resync:
Table A-9 idsync resync Usage
Argument
Meaning
-f <filename>
Creates links between unlinked user entries using one of the specified XML configuration files provided by Identity Synchronization for Windows
(see Appendix B, "LinkUsers XML Document Sample")-k
Creates links between unlinked users only (does not create users or modify existing users)
-a <ldap-filter>
Specifies an LDAP filter to limit the entries to be synchronized
The filter will be applied to the source of the resynchronization operation.
For example, if you specify idsync resync -o Sun -a “uid=*” all Directory Server users that have a uid attribute will be synchronized to Active Directory.-l <sul-to-sync>
Specifies individual Synchronization User Lists (SULs) to resynchronize
Note: You can specify multiple SUL IDs to resynchronize multiple SULs or, if you do not specify any SUL IDs, the program will resynchronize all of your SULs.
-o (Sun | Windows)
Specifies the source of the resynchronization operation
(Default is Windows.)
-c
Creates a user entry automatically if the corresponding user is not found at destination
-i (ALL_USERS | NEW_USERS | NEW_LINKED_USERS)
Resets passwords for user entries synchronized in the Sun directory sources, forcing password synchronization within the current domain for those users the next time the user password is required.
-u
Only updates the object cache. No entries are modified.
This argument updates the local cache of user entries for a Windows directory source only, which prevents pre-existing Windows users from being created in Directory Server. If you use this argument, Windows user entries are not synchronized with Directory Server user entries. This argument is valid only when the resync source is Windows.
-x
Deletes all destination user entries that do not match a source entry.
-n
Runs in safe mode so you can preview the effects of an operation with no actual changes.
Note
- Run idsync resync with no arguments to view a usage statement.
- For detailed information about the resync arguments, review Common Arguments.
- For more information about resynchronizing existing users, review Synchronizing Existing Users.
After running resync, check the resync.log file in the central audit log. If errors result, consult Chapter 9, "Troubleshooting."
Using startsync
You can use the startsync subcommand to start synchronization from the command line.
To start synchronization, open a terminal window (or a Command Window) and type the idsync startsync command as follows:
idsync startsync [-D <bind-DN>] -w <bind-password | -> [-h <Configuration Directory-hostname>] [-p <Configuration Directory-port-no>] [-s <rootsuffix>] -q <configuration_password> [-Z] [-P <cert-db-path>] [-m <secmod-db-path>]
For example:
idsync startsync -w <admin password> -q <configuration_password>
Table A-10 describes the arguments that are unique to startsync:
Table A-10 idsync startsync Arguments
Argument
Description
[-y]
Does not prompt for command confirmation.
Note
For detailed information about the other startsync arguments, review Common Arguments.
Using stopsync
You can use the stopsync subcommand to stop synchronization from the command line.
To stop synchronization, open a terminal window (or a Command Window) and type the idsync stopsync command as follows:
idsync stopsync [-D <bind-DN>] -w <bind-password | -> [-h <Configuration Directory-hostname>] [-p <Configuration Directory-port-no>] [-s <rootsuffix>] -q <configuration_password> [-Z] [-P <cert-db-path>] [-m <secmod-db-path>]
For example:
idsync stopsync -w <admin password> -q <configuration_password>
Note
For detailed information about the stopsync arguments, review Common Arguments.
Using the forcepwchg Migration UtilityUsers who change their passwords during migration will have different password in Windows NT and the Directory Server. You can use the forcepwchg utility to require a password change for users who changed their passwords during the Identity Synchronization for Windows version 1.0 to version 1 2004Q3 migration process.
Before using forcepwchg you must verify the following:
- Be sure you do not configure the 7-bit check Plugin in Directory Server to enforce 7-bit values for the userpassword attribute. Do this using the Directory Server console.
- Be sure that the client you are using for authentication translates the value from your locale to UTF-8 correctly. (For example, the -i option for the ldapsearch shipped with Directory Server).
To execute the forcepwchg command line utility,
- Open a Command Prompt window and cd to the Windows migration directory on the host where you are performing the migration. (The Identity Synchronization for Windows 1.0 NT components (connector, Change Detector DLL, Password Filter DLL) must be installed on the PDC host.)
- From the migration directory, type
Table A-11 describes the arguments that are unique to forcepwchg:
Table A-11 forcepwchg Arguments
Option
Description
-n
Specifies preview mode.
In preview mode, the utility prints out the names of all normal users except:In preview mode, any user can execute forcepwchg.
In non-preview mode, only the Administrator can execute forcepwchg.-a
Requires all users (except Administrator and Guest) to change their passwords.
You cannot use this argument if you are using the -t argument.-t <time_specification>
Forces all users who changed passwords in the past <time specification> to change their passwords. Where <time specification> can have the following form:
For example, if you specify forcepwchg -t 6h, all users who changed passwords within the last six hours will be required to change their password again.
-?
Prints out usage information.
Note
For more information about using forcepwchg, see Forcing Password Changes on Windows NT.