You use the idsync command and subcommands to execute the Identity Synchronization for Windows command line utility.
The idsync command converts all DN-valued arguments (such as bind DN or suffix name) from the character set specified for that window to UTF-8 before sending the arguments to Directory Server.
Do not use backslashes as escape characters in suffix names.
To specify UTF-8 characters on Solaris and on Linux, your terminal window must have a locale based on UTF-8. Make sure that the environmental variable’s LC_CTYPE and LANG.are set correctly.
Unless specifically noted otherwise, you can run the idsync command with subcommands using either of the following methods:
From Solaris:
From Linux:
From Windows:
Open a Command Window and cd to the install_path\isw-hostname\bin directory.
Type the idsync command with one subcommand, as follows
Using the idsync command lists all of the idsync utility subcommands and their purpose:
Subcommand |
Purpose |
---|---|
Displays certificate information based on your configuration and SSL settings (see Using certinfo) |
|
Changes the Identity Synchronization for Windows configuration password (see Using changepw) |
|
Imports an exported Identity Synchronization for Windows version 1.0 configuration XML document (see Using importcnf) |
|
Prepares a Sun Java System Directory Server source for use by Identity Synchronization for Windows (see Using prepds) |
|
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) |
|
Resets connector states in the configuration directory to uninstalled (see Using resetconn) |
|
Links and resynchronizes existing users or groups and pre-populates directories as part of the installation process (see Using resync) |
|
groupsync |
Synchronizes group information between users and groups from one directory source to another (see Using groupsync) |
accountlockout |
Synchronizes account lockout and unlockout between Directory Server and Active Directory sources (see Using accountlockout) |
dspluginconfig |
Configures and unconfigures Directory Server plugin on a specified host (see Using dspluginconfig) |
Starts synchronization (see Using startsync) |
|
stopsync |
Stops synchronization (see Using stopsync) |
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 Plug-in certificate database.
To display certificate information, open a terminal window (or Command Window) and type the idsync certinfo command as follows:
idsync certinfo [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]
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.
idsync certinfo -w admin-password -q configuration-password
For detailed information about the certinfo arguments, review Common Arguments to the Idsync Subcommands.
You can use the changepw subcommand to change the Identity Synchronization for Windows configuration password.
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 toldif.
Type theidsync 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]
idsync changepw -w admin password -q old config password -b -q new config password |
The following arguments are unique to changepw:
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. |
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 Using changepw 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.
After installing Core (Chapter 3, Installing Core), use the idsync importcnf subcommand to import your exported Identity Synchronization for Windows version 1.0 or 1.1 (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]
idsync importcnf -w admin_password -q configuration_password -f “MyConfig.cfg”
The following arguments are unique to importcnf:
Table A–5 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. |
For detailed information about other importcnf arguments, review Common Arguments to the Idsync Subcommands.
After importing the version 1.0 configuration XML file, you must run prepds on all Directory Server sources configured for synchronization, (see Using prepds connectors and subcomponents.
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.
If you are preparing a preferred master Directory Server for use by Identity Synchronization for Windows, you must provide Directory Manager credentials.
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.
If you recreate 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.
You can configure your system to automatically remove (or trim) Changelog entries after a specified period of time. From the command line, modify the nsslapd-changelogmaxage configuration attribute in cn=Retro Changelog Plug-in, cn=plugins, cn=config:
nsslapd-changelogmaxage: IntegerTimeunit
Where:
Integer is a number.
Timeunit is s for seconds, m for minutes, h for hours, d for days, or w for weeks. (There should be no space between the Integer and Timeunit variables.)
For example, nsslapd-changelogmaxage: 2d
For more information, see the “Managing Replication” chapter in the Sun Java System Directory Server 5 2004Q2 Administration Guide.
You can use Administrative credentials to prepare a secondary server.
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 Plug-in 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:
For single host:
idsync prepds [-h <hostname>] [-p <port>] [-D <Directory Manager DN>] -w <password> -s <database suffix> [-x] [-Z] [-P <cert db path>] [-m <secmod db path>]
For multiple hosts:
idsync prepds -F <filename of Host info> -s <root suffix> [-x] [-Z] [-P <cert db path>][-m <secmod db path>] [-3]
isw-hostname\bin>idsync prepds -F isw-hostname\samples\Hosts.xml \ -s ou=isw_data
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.
Using prepds describes the arguments that are unique to idsync prepds.
Table A–6 prepds Arguments
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.
Ensure that Directory Server replication is up and running (if applicable.)
Run idsync prepds from the Console or from the command line, for example:
idsync prepds -h M1.example.com -p 389 -j M2.example.com -r 389. |
Running the idsync prepds command on M1 accomplishes the following:
Enables and extends the RCL to capture more attributes ( dspswuserlink and so forth)
RCL is required on M1 only.
Extends schema.
Adds uid=pswconnector,suffix user with ACIs.
Adds indexes to the dspswuserlink attribute, which puts Directory Server in read-only mode temporarily until the indexing is done.
You can add indexes later to avoid downtime, but you must add indexes before installing the Directory Server Connector.
Adds indexes on M2.
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 Plug-in 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.)
You can use the printstat subcommand to:
Display a list of the remaining steps you have to perform to complete the installation and configuration process.
Print the status of installed connectors, the system manager, and the Message Queue.
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]
idsync printstat -w admin password -q configuration password
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.
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]
idsync resetconn -w admin password -q configuration_password -e “dc=example,dc=com“
Using prepds describes the arguments that are unique to resetconn:
Table A–7 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. |
idsync printstat can be used to find directory source names.
For detailed information about the other resetconn arguments, review Common Arguments to the Idsync Subcommands.
You can use the resync subcommand to bootstrap deployments with existing users. This command uses administrator-specified matching rules to
Populate an empty directory with the contents of a remote directory
Bulk-synchronize attribute values between two existing user populations
Bulk-synchronize existing groups and the users associated with the groups (when the group synchronization feature is enabled).
For more detailed information about linking and synchronizing users, see Chapter 1, Understanding the Product.
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]
idsync resync -w admin password -q configuration_password
Using resync describes the arguments that are unique to resync:
Table A–8 idsync resync Usage
Argument | |
---|---|
-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, Identity Synchronization for Windows 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
|
-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. |
Run idsync resync with no arguments to view a usage statement.
For detailed information about the resync arguments, review Common Arguments to the Idsync Subcommands.
For more information about resynchronizing existing users, review Chapter 1, Understanding the Product.
After running resync, check the resync.log file in the central audit log. If errors result, consult Chapter 7, Troubleshooting Identity Synchronization for Windows, in Sun Directory Server Enterprise Edition 7.0 Troubleshooting Guide.
You can use the groupsync subcommand to synchronize groups between Active Directory and Directory Server.
To enable or disable the Group Synchronization, type idsync groupsync command.
For example:
idsync groupsync -{e/d} -D <bind DN> -w <bind password> [-h <CD hostname>] [-p <CD port no>] -s <rootsuffix> [-Z] -q <configuration password> -t <AD group type>Table A–9 groupsync arguments
Argument |
Meaning |
---|---|
-{e/d} |
Select e for enabling , and d for disabling the group synchronization. |
-t |
Specifies the group type at Active Directory. For example, it can be selected as either of "distribution" or "security" |
You can use the accountlockout subcommand to synchronize account lockout and unlockout between Active Directory and Directory Server.
To enable or disable the account lockout, type idsync accountlockout command.
For example:
idsync accountlockout -{e/d} -D <Directory Manager DN> -w <bind-password> -h <Configuration Directory-hostname> -p <Configuration Directory-port-no> -s <rootsuffix> [-Z] [-P <cert db path>] [-m <secmod db path>] -q <configuration password> -t <max lockout attempts>Table A–10 accountlockout arguments
Argument |
Meaning |
---|---|
-{e/d} |
Select e for enabling , and d for disabling the account lockout synchronization. |
-t |
Specifies the maximum number of lockout attempts that Active Directory Connector performs. |
You can use the dspluginconfig subcommand to configure or unconfigure Directory Server plugin on a specified Directory Server data source.
To configure or unconfigure the Directory Server plugin, type idsync dspluginconfigcommand.
For example:
idsync dspluginconfig -{C/U} -D <bind DN> -w <bind password | -> [-h <CD hostname>] [-p <CD port no>] [-s <configuration suffix>] [-Z] [-P <cert db path>] [-m <secmod db path> ] [-d <ds plugin hostname>] [-r <ds plugin port>] [-u <ds plugin user>] [-x <ds plugin user password>] [-o <database suffix>] [-q <configuration password | ->]Table A–11 dspluginconfig arguments
Argument |
Meaning |
---|---|
-{C/U} |
Select C for configuring and U for unconfiguring the Directory Server plugin. |
-d |
Host name of the Directory Server data source where the plugin needs to be configured |
-r |
Port number of the Directory Server data source where the plugin needs to be configured |
-u |
Administrator of the Directory Server data source where the plugin needs to be configured |
-x |
Password of the administrator of the Directory Server data source where the plugin needs to be configured |
-o |
Data suffix of the Directory Server data source. |
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]
idsync startsync -w admin password -q configuration_password
Using startsync describes the arguments that are unique to startsync.
Table A–12 idsync startsync Arguments
Argument |
Description |
---|---|
[-y] |
Does not prompt for command confirmation. |
For detailed information about the other startsync arguments, review Common Arguments to the Idsync Subcommands.
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]
idsync stopsync -w admin password -q configuration_password
For detailed information about the stopsync arguments, review Common Arguments to the Idsync Subcommands.