Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Identity Synchronization for Windows Installation and Configuration Guide

Appendix A  
Command Line Utilities

Identity Synchronization for Windows includes a number of command line utilities that are useful in installing the product. This Appendix explains command line usage and lists these utilities in the following sections:


Using idsync

All Identity Synchronization for Windows command line utilities are executed with the idsync script. Use the idsync script as follows:

idsync <subcommand> <subcommand-arg1> <subcommand-arg2> ...

The first argument is a sub command followed by its arguments. Identity Synchronization for Windows sub commands include:

Entering Passwords

Anywhere that a <bind password> or <configuration password> value is required, the value “-” can be used to read the password from STDIN or console. When “-” is the value of multiple password options, the idsync program will prompt for passwords in the order of the arguments.

Accessing the Configuration Directory Server Via SSL

All of the sub commands list the following options, which provide information about securely accessing the configuration Directory Server via SSL:

[-Z] [-P <cert db path>] [-m <secmod db path>]

Getting Help

Enter any of the following three help options following a sub command:

-help --help -?

The usage for the sub command is listed to the command console. If no sub command is specified, usage for idsync is listed, including a list of sub commands.


Using changepw

The script changepw changes the configuration password for Identity Synchronization for Windows. Before running the script, stop the console, any running installers, and all other system processes. Export the ou=Services tree in the Configuration Registry to ldif as backup.

Arguments

The script changepw uses the following arguments:

Table A-1  changepw Arguments

Argument

Description

-h

Configuration registry hostname

-p

Configuration registry port no

-D

bind distinguished name

-w

bind password

-s

This is the name of the configuration registry rootsuffix. A rootsuffix is a distinguished name such as dc=example,dc=com.

-q

configuration password

-b

new configuration password

Usage

To change the configuration password for Identity Synchronization for Windows:

  1. Stop all of the Identity Synchronization processes (for example, System Manager, Central Logger, Connectors, Console, Installers/Uninstallers)
  2. After stopping all the processes, make a backup of the ou=Services tree by exporting the configuration registry to ldif.
  3. Enter the following command.
  4. idsync changepw -h hostname -p <port no> -D <bind DN> -w <bind password> -s <rootsuffix> -q <configuration password> -b <new configuration>

    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

  5. Modify the SystemManagerBootParams.cfg file that appears in $PSWHOME\resources before restarting the system. This file contains the configuration password that the SystemManager uses to connect to the configuration registry. For example a password ’oldpassword’ - change the line:
  6. <Parameter name="manager.configReg.deploymentPassword" value="oldpassword"/>

    to:

    <Parameter name="manager.configReg.deploymentPassword" value="newpassword"/>

  7. If there were any errors reported, restore the configuration registry 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 registry goes down during the password change.


Using importcnf

The administrator has the alternative to provide configuration information via a command line interface as opposed to using the Console; this interface is called idsync importcnf. The directory deployment’s topology can be documented in an XML Document that we shall name the Configuration XML Document. It contains enough information to configure a Identity Synchronization for Windows installation.

Run idsync importcnf after installing core. idsync importcnf can be run multiple times following core installation, but should not be run following the installation of connectors or connector sub-components.

Any error detected in the command line input configuration file results in a fatal error that will abort the command and provide necessary information to correct the mistakes. Possible errors can be caused by:

Arguments

importcnf accepts the following arguments:

Table A-2  importcnf Arguments

Argument

Description

-h

Configuration Registry hostname

-p

Configuration Registry LDAP port no

-D

Configuration Registry bind DN

-w

Configuration Registry bind password

-s

Configuration Registry rootsuffix. A rootsuffix is a distinguished name such as dc=example,dc=com.

-q

Configuration password

-n

[Validate the configuration file, but do not update the configuration registry.

-f <filename>

Names the Configuration XML Document input file

importcnf XML Document

The importcnf script uses as input an XML document that contains the same information that an administrator would provide via the Console’s UI, namely information about Directory Sources, Directory Globals, and Synchronization User Lists.


Note

Complete, commented samples are provided in the isw-hostname/samples directory where you installed Identity Synchronization for Windows.


Configuration XML Document Usage Samples

Following are usage samples for defining Creation/Significant Attributes, Creation/Modification Synchronization Settings, and Attribute Maps in the Configuration XML Document used by importcnf.

Defining Directory Sources

Single Master Sun, Single AD Domain with Single Synchronized User List

This example assumes the synchronization settings have been set to synchronize modifications and creations from Windows to Sun.

The SunDirectorySource synchronized user list Synchronization Scope Definition Sets (SSDS) is either the Windows or the Sun Directory Source side of a Synchronization User List. A Sychronization User List will always have one SSDS for a Windows Directory Source and one SSDS for a Sun Directory Source.

SSDS definition includes a creation expression (to define the parent DN and naming attribute) for when new entries are propagated from AD to Sun.


Note

The XML will not work with out the surrounding ActiveConfiguration> ... </ActiveConfiguration> tags.


<SunDirectorySource displayName="dc=example,dc=com">

  <SynchronizationHost hostname="ds-host.example.com" port="389"/>

  <SyncScopeDefinitionSet sulid="SUL1"

    location="ou=people,dc=example,dc=com"

    creationExpression="cn=%cn%,ou=people,dc=example,dc=com"/>

</SunDirectorySource>

The AD synchronization host requires credentials, the Sun one does not.

<ActiveDirectorySource displayName="example.com">

  <SynchronizationHost hostname="ad-host.example.com">

    <Credentials userName="cn=Administrator,cn=users, dc=example,
       dc=com" cleartextPassword="examplePassword"/>

  </SynchronizationHost>

  <SyncScopeDefinitionSet sulid="SUL1"

    location="cn=Users,dc=example,dc=com"/>

</ActiveDirectorySource>

Single Master Sun, Single AD Domain, Single NT Domain with Multiple SULs

This example assumes the synchronization settings have been set to synchronize modifications and creations from Sun to Windows.

The ActiveDirectorySource synchronized user list SSDS definition includes a creation expression (to define the parent DN and naming attribute) for when new entries are propagated from Sun to AD; NT does not require creation expressions.

<SunDirectorySource displayName="dc=example,dc=com">

  <SynchronizationHost hostname="ds-host.example.com" port="389"/>

  <SyncScopeDefinitionSet sulid="SULAD"

    location="ou=people,dc=example,dc=com"

    creationExpression="cn=%cn%,ou=people,dc=example,dc=com"

    index=1/>

  <SyncScopeDefinitionSet sulid="SULNT"

    location="ou=ntpeople,dc=example,dc=com"

    creationExpression="cn=%cn%,ou=ntpeople,dc=example,dc=com"

    index=2/>

</SunDirectorySource>

<ActiveDirectorySource displayName="example.com">

  <SynchronizationHost hostname="ad-host.example.com">

    <Credentials userName="cn=Administrator,cn=users,dc=example,dc=com"       cleartextPassword="examplePassword"/>

  </SynchronizationHost>

  <SyncScopeDefinitionSet sulid="SULAD" location="cn=Users,dc=example,dc=com"/>

</ActiveDirectorySource>

<NTDirectorySource displayName="ntexample1">

  <SynchronizationHost hostname="NTHOST1"/>

  <SyncScopeDefinitionSet sulid="SULNT"/>

</NTDirectorySource>

Single Master Sun, Single AD Domain, with Multiple SULs using filters

This example assumes the synchronization settings have been set to synchronize modifications and creations between Sun and Windows.

The ActiveDirectorySource and the SunDirectorySource synchronized user list SSDS definition both include creation expressions (to define the parent DN and naming attribute) for when new entries are propagated between Sun and AD.

<ActiveDirectorySource displayName="example.com">

  <SynchronizationHost hostname="ad-host.example.com">

  <Credentials userName="cn=Administrator,cn=users,dc=example,dc=com"

    cleartextPassword="examplePassword"/>

  </SynchronizationHost>

  <SyncScopeDefinitionSet sulid="SUL_SALES"

    location="cn=Users,dc=example,dc=com"

    filter="(department=sales)"

    index="1"/>

  <SyncScopeDefinitionSet sulid="SUL_FINANCE"

    location="cn=Users,dc=example,dc=com"

    filter="(department=finance)"

    index="2"/>

</ActiveDirectorySource>

<SunDirectorySource displayName="dc=example,dc=com">

  <SynchronizationHost hostname="ds-host.example.com" port="389"/>

  <SyncScopeDefinitionSet sulid="SUL_SALES"

    location="ou=sales,dc=example,dc=com"

    creationExpression="cn=%cn%,ou=sales,dc=example,dc=com"

    index=1/>

  <SyncScopeDefinitionSet sulid="SUL_FINANCE"

    location="ou=finance,dc=example,dc=com"

    creationExpression="cn=%cn%,ou=finance,dc=example,dc=com"

    index=2/>

Defining SULs Using Filters and Indices


Note

For more information about using filters and indices, see "Synchronization User List Definitions and Configuration".


Following are two usage samples for using filters and indices.

Using filters to differentiate same Base DNs

Reversing the indices is not valid because the filter on SUL_MANAGER is more specific than the filter on SUL_PEOPLE.

<SunDirectorySource ...>

  ...

<SyncScopeDefinitionSet sulid="SUL_MANAGER"

    location="ou=people,dc=example,dc=com"

    creationExpression="cn=%cn%,ou=people,dc=example,dc=com"

    filter="(employeeType=manager)"

    index=1/>

<SyncScopeDefinitionSet sulid="SUL_PEOPLE"

    location="ou=people,dc=example,dc=com"

    creationExpression="cn=%cn%,ou=people,dc=example,dc=com"

    index=2/>

</SunDirectorySource>

Defining Synchronization Settings, Significant/Creation Attributes, and Attribute Maps

Attribute flow settings, significant and creation attributes, and attribute maps are only specified once for each directory source type as Directory Globals.

Synchronizing Creates and Modifies from Sun to Windows

In a Sun/Active Directory deployment

When synchronizing creates from Sun to Active Directory, the Active Directory Source’s mandatory creation attributes must be mapped to attributes in the Sun Directory Source; the maps are used during creation of a new User in Active Directory. Modifications are synchronized for employeeNumber only; note that employeeNumber will also be synchronized from Sun to Active Directory during creation.

<SunDirectoryGlobals

  FlowInboundCreates="TRUE"

  FlowInboundModifies="TRUE"

  FlowOutboundCreates="FALSE"

  FlowOutboundModifies="FALSE"

  userObjectClass="inetOrgPerson">

  <AttributeDescription parent.attr="SignificantAttribute"

                        name="employeeNumber"/>

</SunDirectoryGlobals>

<ActiveDirectoryGlobals

  FlowInboundCreates="FALSE"

  FlowInboundModifies="FALSE"

  FlowOutboundCreates="TRUE"

  FlowOutboundModifies="TRUE">

  <AttributeDescription parent.attr="SignificantAttribute"

                        name="employeeID"/>

The following maps are required from the you to satisfy Active Directory mandatory creation attributes:

<AttributeMap parent.attr="AttributeMap">

  <AttributeDescription parent.attr="SunAttribute"

                        name="cn"/>

  <AttributeDescription parent.attr="WindowsAttribute"

                        name="cn"/>

</AttributeMap>

<AttributeMap parent.attr="AttributeMap">

  <AttributeDescription parent.attr="SunAttribute"

                        name="uid"/>

  <AttributeDescription parent.attr="WindowsAttribute"

                        name="samaccountname"/>

</AttributeMap>

 

The following map is required to synchronize modifications to employeeNumber:

<AttributeMap parent.attr="AttributeMap">

  <AttributeDescription parent.attr="SunAttribute"

                        name="employeeNumber"/>

  <AttributeDescription parent.attr="WindowsAttribute"

                        name="employeeID"/>

</AttributeMap>

 

In a Sun/NT deployment

When synchronizing creates from Sun to NT this Directory Source’s mandatory creation attributes must be mapped to attributes in the Sun Directory Source; the maps are used during creation of a new User in NT. Modifications are synchronized for comments only; note that comments will also be synchronized from Sun to NT during creation.

<SunDirectoryGlobals

  FlowInboundCreates="TRUE"

  FlowInboundModifies="TRUE"

  FlowOutboundCreates="FALSE"

  FlowOutboundModifies="FALSE"

  userObjectClass="inetOrgPerson">

  <AttributeDescription parent.attr="SignificantAttribute"

                        name="description"/>

</SunDirectoryGlobals>

 

<NTDirectoryGlobals

  FlowInboundCreates="FALSE"

  FlowInboundModifies="FALSE"

  FlowOutboundCreates="TRUE"

  FlowOutboundModifies="TRUE">

  <AttributeDescription parent.attr="SignificantAttribute"

                        name="USER_COMMENT"/>

  <AttributeMap parent.attr="AttributeMap">

    <AttributeDescription parent.attr="SunAttribute"

                          name="uid"/>

    <AttributeDescription parent.attr="WindowsAttribute"

                          name="USER_NAME"/>

  </AttributeMap>

 

The following map is required to synchronize modifications to description.

The following map is required for the NT mandatory creation attribute:

  <AttributeMap parent.attr="AttributeMap">

  <AttributeDescription parent.attr="SunAttribute"

                        name="description"/>

  <AttributeDescription parent.attr="WindowsAttribute"

                        name="USER_COMMENT"/>

  </AttributeMap>

</NTDirectoryGlobals>

Synchronizing Creates from Windows to Sun

In these examples the Directory Server userObjectclass is inetorgperson; therefore, cn and sn must be defined as a creation attributes on the Directory Server side, and have maps on the Active Directory side. Modifications are synchronized for telephonenumber and password only; note that telephonenumber (by default) will also be synchronized from Active Directory to Directory Server during creation.

In a Sun/AD deployment

<SunDirectoryGlobals

  FlowInboundCreates="FALSE"

  FlowInboundModifies="FALSE"

  FlowOutboundCreates="TRUE"

  FlowOutboundModifies="TRUE"

  userObjectClass="inetOrgPerson">

 

The cn and sn creation attributes are required to successfully create user entries of type inetorgperson; cn is set as creation “only,” while “sn” is set as a significant, which implies inclusion in “both” creates and modifies.

  <AttributeDescription parent.attr="CreationAttribute"

                        name="cn"/>

  <AttributeDescription parent.attr="SignificantAttribute"

                        name="sn"/>

  <AttributeDescription parent.attr="SignificantAttribute"

                        name="telephonenumber"/>

</SunDirectoryGlobals>

<ActiveDirectoryGlobals

  FlowInboundCreates="TRUE"

  FlowInboundModifies="TRUE"

  FlowOutboundCreates="FALSE"

  FlowOutboundModifies="FALSE">

  <AttributeDescription parent.attr="SignificantAttribute"

                        name="telephonenumber"/>

 

The following maps are required to match the Sun objectclass inetorgperson creation syntax:

<AttributeMap parent.attr="AttributeMap">

  <AttributeDescription parent.attr="SunAttribute"

                        name="cn"/>

  <AttributeDescription parent.attr="WindowsAttribute"

                        name="cn"/>

</AttributeMap>

<AttributeMap parent.attr="AttributeMap">

  <AttributeDescription parent.attr="SunAttribute"

                        name="sn"/>

  <AttributeDescription parent.attr="WindowsAttribute"

                        name="sn"/>

</AttributeMap>

The following map is required to synchronize modifications to telephonenumber:

<AttributeMap parent.attr="AttributeMap">

  <AttributeDescription parent.attr="SunAttribute"

                        name="telephonenumber"/>

  <AttributeDescription parent.attr="WindowsAttribute"

                        name="telephonenumber"/>

</AttributeMap>

</ActiveDirectoryGlobals>

The following map is required to synchronize modifications to description:

<AttributeMap parent.attr="AttributeMap">

<AttributeDescription parent.attr="SunAttribute" name="description"/>

<AttributeDescription parent.attr="WindowsAttribute" name="USER_COMMENT"/>

</AttributeMap>

</ActiveDirectoryGlobals>


Using startsync

Start synchronization from the command line.

Arguments

startsync accepts the following arguments:

Table A-3  startsync Arguments

Argument

Description

-h

Configuration Registry hostname

-p

Configuration Registry LDAP port no

-D

Configuration Registry bind DN

-w

Configuration Registry bind password

-s

Configuration Registry rootsuffix. A rootsuffix is a distinguished name such as dc=example,dc=com.

-q

Configuration password

-Z

Specify that SSL be used to provide certificate-based client authentication.

-N

Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".

-P <cert db path>

Specify the path and filename of the client’s certificate database.

This file may be the same as the certificate database for an SSL-enabled version of Directory Server. When using the command on the same host as the Directory Server you may use the server’s own certificate database, for example:

-P <installDir>/alias/slapd-<serverId>-cert7.db

If -Z is specified and -P is not, the <cert db path> defaults to <current working directory>/cert7.db.

Note: If the certificate database file is not found in the specified directory, an *empty* database will be created in that directory. The database consists of three files: cert7.db, key3.db, and secmod.db.

-m <secmod db path>

Specify the path to the security module database. For example:

/var/Sun/MPS/slapd-<serverID>/secmod.db

You need to specify this option only if the security module database is in a different directory from the certificate database itself.


Using stopsync

Stops synchronization from the command line.

Arguments

stopsync accepts the following arguments:

Table A-4  stopsync Arguments

Argument

Description

-h

Configuration Registry hostname

-p

Configuration Registry LDAP port no

-D

Configuration Registry bind DN

-w

Configuration Registry bind password

-s

Configuration Registry rootsuffix. A rootsuffix is a distinguished name such as dc=example,dc=com.

-q

Configuration password

-Z

Specify that SSL be used to provide certificate-based client authentication.

-N

Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".

-P <cert db path>

Specify the path and filename of the client’s certificate database.

This file may be the same as the certificate database for an SSL-enabled version of Directory Server. When using the command on the same host as the Directory Server you may use the server’s own certificate database, for example:

-P <installDir>/alias/slapd-<serverId>-cert7.db

If -Z is specified and -P is not, the <cert db path> defaults to <current working directory>/cert7.db.

Note: If the certificate database file is not found in the specified directory, an *empty* database will be created in that directory. The database consists of three files: cert7.db, key3.db, and secmod.db.

-m <secmod db path>

Specify the path to the security module database. For example:

/var/Sun/MPS/slapd-<serverID>/secmod.db

You need to specify this option only if the security module database is in a different directory from the certificate database itself.


Using certinfo

Displays certificate information, which includes the certificates that must be added to each connector or Directory Server plug-in certificate database.

Arguments

certinfo accepts the following arguments:

Table A-5  certinfo Arguments

Argument

Description

-h

Configuration Registry hostname

-p

Configuration Registry LDAP port no

-D

Configuration Registry bind DN

-w

Configuration Registry bind password

-s

Configuration Registry rootsuffix. A rootsuffix is a distinguished name such as dc=example,dc=com.

-q

Configuration password

-Z

Specify that SSL be used to provide certificate-based client authentication.

-N

Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".

-P <cert db path>

Specify the path and filename of the client’s certificate database.

This file may be the same as the certificate database for an SSL-enabled version of Directory Server. When using the command on the same host as the Directory Server you may use the server’s own certificate database, for example:

-P <installDir>/alias/slapd-<serverId>-cert7.db

If -Z is specified and -P is not, the <cert db path> defaults to <current working directory>/cert7.db.

Note: If the certificate database file is not found in the specified directory, an *empty* database will be created in that directory. The database consists of three files: cert7.db, key3.db, and secmod.db.

-m <secmod db path>

Specify the path to the security module database. For example:

/var/Sun/MPS/slapd-<serverID>/secmod.db

You need to specify this option only if the security module database is in a different directory from the certificate database itself.


Using printstat

Prints out the status of the installed connectors, the system manager, and the message queue. The status can be any of the following:

Arguments

printstat accepts the following arguments:

Table A-6  printstat Arguments

Argument

Description

-h

Configuration Registry hostname

-p

Configuration Registry LDAP port no

-D

Configuration Registry bind DN

-w

Configuration Registry bind password

-s

Configuration Registry rootsuffix. A rootsuffix is a distinguished name such as dc=example,dc=com.

-q

Configuration password

-Z

Specify that SSL be used to provide certificate-based client authentication.

-N

Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".

-P <cert db path>

Specify the path and filename of the client’s certificate database.

This file may be the same as the certificate database for an SSL-enabled version of Directory Server. When using the command on the same host as the Directory Server you may use the server’s own certificate database, for example:

-P <installDir>/alias/slapd-<serverId>-cert7.db

If -Z is specified and -P is not, the <cert db path> defaults to <current working directory>/cert7.db.

Note: If the certificate database file is not found in the specified directory, an *empty* database will be created in that directory. The database consists of three files: cert7.db, key3.db, and secmod.db.

-m <secmod db path>

Specify the path to the security module database. For example:

/var/Sun/MPS/slapd-<serverID>/secmod.db

You need to specify this option only if the security module database is in a different directory from the certificate database itself.


Using resetconn

Resets the state of connectors in the Configuration Directory to uninstalled. resetconn provides two options:

Arguments

resetconn accepts the following arguments:

Table A-7  resetconn Arguments

Argument

Description

-h

Configuration Registry hostname

-p

Configuration Registry LDAP port no

-D

Configuration Registry bind DN

-w

Configuration Registry bind password

-s

Configuration Registry rootsuffix. A rootsuffix is a distinguished name such as dc=example,dc=com.

-q

Configuration password

-Z

Specify that SSL be used to provide certificate-based client authentication.

-N

Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".

-P <cert db path>

Specify the path and filename of the client’s certificate database.

This file may be the same as the certificate database for an SSL-enabled version of Directory Server. When using the command on the same host as the Directory Server you may use the server’s own certificate database, for example:

-P <installDir>/alias/slapd-<serverId>-cert7.db

If -Z is specified and -P is not, the <cert db path> defaults to <current working directory>/cert7.db.

Note: If the certificate database file is not found in the specified directory, an *empty* database will be created in that directory. The database consists of three files: cert7.db, key3.db, and secmod.db.

-m <secmod db path>

Specify the path to the security module database. For example:

/var/Sun/MPS/slapd-<serverID>/secmod.db

You need to specify this option only if the security module database is in a different directory from the certificate database itself.



Previous      Contents      Index      Next     


Copyright 2003 Sun Microsystems, Inc. All rights reserved.