Manages the configuration settings that are stored in Active Directory and used by the password change notification service (PCNS). You must be a member of the Enterprise Admins group or the Domain Admins group to use this utility.

pcnscfg list

Displays the current PCNS configuration

Syntax

pcnscfg list

Parameters

The list command has no parameters.

Example

Sample output for the list command:

MaxQueueLength........: 0
MaxQueueAge...........: 0 seconds
MaxNotificationRetries: 0
RetryInterval.........: 90 seconds

Targets

Target Name...........: fab-dev-01
Target GUID...........: 515F9932-6332-4468-8DDA-975A74E2D337
Server FQDN or Address: fab-dev-01.usergroup.fabrikam.com
Service Principal Name: PCNSCLNT/fab-dev-01.usergroup.fabrikam.com
Authentication Service: Kerberos
Inclusion Group Name..: Fabrikam\Domain Users
Exclusion Group Name..:
Keep Alive Interval...: 15 seconds
User Name Format......: 1
Queue Warning Level...: 100
Queue Warning Interval: 30 minutes
Disabled..............: False

Total targets: 1

pcnscfg service

Configures the PCNS settings in Active Directory.

Note

This is a global command that changes settings for the overall service, not just a specific target.

Syntax

pcnscfg service [/L: MaximumQueueLength] [/A: MaximumQueueAge] [/R: MaximumNotificationRetries] [/I: RetryInterval]

Parameters

Note

If the service command is not specified, the following default values are used for the parameters:
  • MaximumQueueLength—unlimited

  • MaximumQueueAge—259200 seconds (72 hours)

  • MaximumNotificationRetries—unlimited

  • RetryInterval—60 seconds

/L: MaximumQueueLength

Specifies the maximum number of password changes to store in the queue. Must be an integer in the range from 0 to 4294967295. If a range is specified and the queue becomes full, the oldest password change requests are discarded first. Specify 0 for unlimited. Note that if passwords cannot be delivered and MaximumQueueLength is set to unlimited, the queue size increases and consumes disk resources on the domain controller as needed.

/A: MaximumQueueAge

Specifies the maximum time in seconds that an undelivered password change can remain in the queue before being discarded. Must be an integer in the range from 0 to 4294967295. Specify 0 for unlimited. Note that if passwords cannot be delivered and MaximumQueueAge is set to unlimited, the queue size increases and consumes disk resources on the domain controller as needed.

/R: MaximumNotificationRetries

Specifies the maximum number of times that an attempt is made to notify the target server of a password change. Must be an integer in the range from 0 to 1000. Specify 0 for unlimited.

/I: RetryInterval

Specifies how often in seconds before a failed notification is retried. Must be an integer in the range from 10 to 3600.

Example

To set the MaximumQueueLength and MaximumQueueAge to unlimited, and limit the number of notification retries to 500 and the retry interval to 15 seconds, type pcsncfg service /L:0 /A:0 /R:500 /I:15

pcnscfg addtarget

Creates a new target.

Syntax

pcnscfg ADDTARGET /N: Name /A: Address /S: SPN /FI: Group [/FE: [Group]] [/F: n] [/I: n] [/WL: nn] [/WI: nn] [/D: {True|False}]

Parameters

/N: Name

The user-defined, friendly name of the target server. This name becomes the value of the CN property of the object that is created in Active Directory.

/A: Address

The fully qualified domain name (FQDN) or address of the target server, for example, fab-dev-01.usergroup.fabrikam.com.

/S: SPN

Service principal name (SPN) of the target server running FIM that was specified in the setspn.exe command.

/FI: Group

Filter inclusion group name to use to permit passwords to be forwarded. Inclusion group names enclosed in quotation marks are saved with embedded spaces, for example "Password enabled users".

Note

Inclusion groups and exclusion groups must be specified by using the group name only, for example /FI:PasswordInclusionGroup. The domain specified in the /A: parameter will be used as the default domain.

/FE: Group

Filter exclusion group name to use to prevent passwords from being forwarded.

/F: n

The user name format to be delivered to the target. The specified may be either 1 or 3 (default).

Parameter User name format

1

Fully qualified domain name (FQDN). For example, CN=MikeDan, CN=users, DC=Fabrikam, DC=com

3

NT 4.0. For example, Fabrikam\MikeDan

/I: nn

Keep alive, or heartbeat, interval specified in seconds. This sends a verification signal from PCNS to the FIM if no activity is detected within the specified time range. Must be an integer in the range from 0 to 3600. Specify 0 to disable this parameter.

/WL: nn

Logs a warning level when the number of objects in the queue reaches or exceeds nn. The default setting is 0, which disables the warning level.

/WI: nn

The interval, in minutes, that the warning level is logged. This parameter has no effect if the /WL: parameter is not specified, or is set to 0. The default value for /WI: is 30. To disable periodic notifications, set the value to 0. When the value is set to 0, notifications will still be logged whenever the level threshold defined in /WL: is crossed, either up or down.

/D: True or False

Disables the target server. Disabling the target server discards any pending password changes in the queue and stops queuing any new passwords for the target. True disables the server, and False enables the server.

Examples

To add a new target, type pcnscfg ADDTARGET /N:FIM-server-1 /A:FIM-server-1.fabrikam.com /S:FIM/FIM-server-1.fabrikam.com /FI:PasswordInclusionGroup /F:1 /I:600 /D:False /WI:60

pcnscfg modifytarget

Modifies one or more settings for an existing target.

Syntax

pcnscfg MODIFYTARGET /N: Name [/A: Address] [/S: SPN] [/FI: Group] [/FE: [Group]] [/F: n] [/I: nn] [/WL: nn] [/WI: nn] [/D: {True|False}]

Parameters

/N: Name

The user-defined, friendly name of the target server. This name becomes the value of the CN property of the object that is created in Active Directory.

/A: Address

The fully qualified domain name (FQDN) or address of the target server, for example, fab-dev-01.usergroup.fabrikam.com.

/S: SPN

Service principal name (SPN) of the target server running FIM that was specified in the setspn.exe command.

/FI: Group

Filter inclusion group name to use to permit passwords to be forwarded. Inclusion group names enclosed in quotation marks are saved with embedded spaces, for example "Password enabled users".

Note

Inclusion groups and exclusion groups must be specified by using the group name only, for example /FI:PasswordInclusionGroup. The domain specified in the /A: parameter will be used as the default domain.

/FE: Group

Filter exclusion group name to use to prevent passwords from being forwarded. If the /FE: parameter is not specified, the exclusion group specified in the current PCNS configuration for the target will not be affected. If the /FE: parameter is specified, but without a value, the exclusion group specified in the current PCNS configuration for the target will be removed. Pcnscfg.exe displays a warning when an exclusion group is being removed.

/F: n

The user name format to be delivered to the target. The specified may be either 1 or 3 (default).

Parameter User name format

1

Fully qualified domain name (FQDN). For example, CN=MikeDan, CN=users, DC=Fabrikam, DC=com

3

NT 4.0. For example, Fabrikam\MikeDan

/I: nn

Keep alive, or heartbeat, interval specified in seconds. This sends a verification signal from PCNS to the FIM if no activity is detected within the specified time range. Must be an integer in the range from 0 to 3600. Specify 0 to disable this parameter.

/WL: nn

Logs a warning level when the number of objects in the queue reaches or exceeds nn. The default setting is 0, which disables the warning level.

/WI: nn

The interval, in minutes, that the warning level is logged. This parameter has no effect if the /WL: parameter is not specified, or is set to 0. The default value for /WI: is 30. To disable periodic notifications, set the value to 0. When the value is set to 0, notifications will still be logged whenever the level threshold defined in /WL: is crossed, either up or down.

/D: True or False

Disables the target server. Disabling the target server discards any pending password changes in the queue and stops queuing any new passwords for the target. True disables the server, and False enables the server.

Examples

To modify the heartbeat interval for an existing target, type pcnscfg MODIFYTARGET /N:FIM-server-1 /I:1800

pcnscfg securetarget

Sets or modifies the inclusion and exclusion groups for the specified target server.

Syntax

pcnscfg securetarget /N: Name [/FI: Group] [/FE: [Group]]

Parameters

/N: Name

The unique name of the target server.

/FI: Group

Filter inclusion group name to use to permit passwords to be forwarded. Inclusion group names enclosed in quotation marks are saved with embedded spaces, for example "Password enabled users".

Note

Inclusion groups and exclusion groups must be specified by using the group name only, for example /FI:PasswordInclusionGroup. The domain specified in the /A: parameter will be used as the default domain.

/FE: Group

Filter exclusion group name to use to prevent passwords from being forwarded. If the /FE: parameter is not specified, the exclusion group specified in the current PCNS configuration for the target will not be affected. If the /FE: parameter is specified, but without a value, the exclusion group specified in the current PCNS configuration for the target will be removed. Pcnscfg.exe displays a warning when an exclusion group is being removed.

Examples

To specify a new inclusion group and remove the existing exclusion group, type pcnscfg securetarget /N:FIM-server-1 /FI:NewPasswordInclusionGroup /FE:

pcnscfg deletetarget/enabletarget/disabletarget

Use to delete, enable, or disable an existing target. When you delete or disable a target, all pending password changes in the queue are discarded, and in the case of disable, no further password changes are added to the queue. A disabled target can be enabled again with this command. A deleted target can only be recreated by using the ADDTARGET command.

Syntax

pcnscfg deletetarget /N: Name

pcnscfg disabletarget /N: Name

pcnscfg enabletarget /N: Name

  • deletetarget—Use this command when you need to completely flush the password queue and recreate the target.

  • disabletarget—Use this command when you need to temporarily turn off synchronization to the target without reconfiguring.

  • enabletarget—Use this command to restart a disabled target.

Parameters

/N: Name

The user-defined, friendly name of the target server.

Examples

pcnscfg deletetarget /N:FIM-server-1

Remote operation

All commands for pcnscfg.exe may be run remotely.

Syntax

pcnscfg user specified command and parameters [/Server: Name] [/User: Name] [/Password: {password | *}]

Parameters

/Server: Name

The remote server or domain name.

/User: Name

The account name to use when authenticating to the remote server or domain.

/Password: password or *

The password to use when authenticating to the remote server or domain. Specify * to be prompted for the password.

Examples

To delete a target remotely and be prompted for your password, type pcnscfg deletetarget /N:FIM-server-1 /Server:fabrikam.com /User:Fabrikam\MikeDan /Password:*

Remarks

  • Pcnscfg.exe is located in the \Program Files\Microsoft Password Change Notification folder on each domain controller where the pcns.msi installation package is run.

  • The number of configured targets is limited to 50.

  • Changes to the PCNS configuration can affect passwords already in the queue:

    • Changes to inclusion and exclusion groups applied to target servers does not affect passwords already in the queue. Changes are effective for any new password synchronization events.

    • Deleting or disabling a target server discards all passwords in the queue, and no new passwords are stored in the queue for that target.

    • The recommended method for purging all passwords from the queue is to delete the target and then add it again as a new target with the same name.

Registry settings

  • There are four logging levels for PCNS that are controlled by adding the EventLogLevel (REG_DWORD) entry to the following registry subkey:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\PCNSSVC\Parameters

    • 0 = Minimal Logging

    • 1 = Normal logging (default)

    • 2 = High logging

    • 3 = Verbose logging

  • If you are running PCNS on a computer with a slow boot cycle, or through a Virtual PC connection, PCNS startup may timeout with an error. The default timeout is 3 minutes (180 seconds), and can be controlled by adding the ServiceStopWaitTime (REG_DWORD) entry to the following registry subkey:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\PCNSSVC\Parameters

  • The value is measured in seconds and can range from 20 to 600. If the value cannot be read, the default value of 180 will be used. If the value is less than 20, the value will be set to 20, and if the value is greater than 600, the value will be set to 600.

Formatting legend

Format Meaning

Italic

Information that the user must supply

Bold

Elements that the user must type exactly as shown

Ellipsis (...)

Parameter that can be repeated several times in a command line

Between brackets ([])

Optional items

Between braces ({}); choices separated by pipe (|). Example: {even|odd}

Set of choices from which the user must choose only one

 
Courier font

Code or program output

See Also