PingFederate provides a command-line interface (CLI) to help manage automated outbound provisioning at IdP sites. Administrators can use this tool to view the status of user provisioning, either globally or one provisioning channel at a time, and to rectify unusual situations where provisioning at the service provider may get out of sync with the enterprise user store.

The CLI tool, provmgr.bat or provmgr.sh, is located in the directory <pf_install>/pingfederate/bin. The tool interacts with the internal datastore PingFederate uses to maintain provisioning synchronization between the LDAP user store and the target service.

Note that the tool creates its own log file, provmgr.log, located in the directory <pf_install>/pingfederate/log. You can control settings for this log, as needed, in the file provmgr.log4j2.xml, located in the <pf_install>/pingfederate/bin directory.

The following table describes the available global and channel-specific command arguments.

Command argument Description
Global options
--help Describes the available options. The help is also displayed if the command is run with no arguments.
--show-channels Lists all channels in a table format, showing for each:
  • ID: A numeric channel ID (channel-specific commands need this ID)
  • Name: The channel name
  • Connection ID
  • Status: active | inactive (both the connection and the channel status are shown)
  • User count/dirty-user-record count (for example, 5000/12 means 5000 users and 12 dirty records)
  • Source (as LDAP URL)
  • Target code
--show-nodes Shows all the provisioning-server nodes with their status and the last timestamp (applicable only when failover provisioning is configured in the <pf_install>/pingfederate/bin/run.properties file).
--force-node-backup

Use with node number: -n <node ID>

Sets the provisioner mode to FAILOVER for the associated PingFederate server node.
Channel-specific options
Note:

With each command, specify the channel with the -c <channel-id-number> argument; for example:

provmgr -c 1 --show-source

You can determine channel ID numbers by using the global command: provmgr --show-channels

--reset-group-timestamp Deletes the user-group timestamp, which forces the provisioner to process the provisioning group on the next cycle, even if the timestamp on that group did not actually change.
Depending on your LDAP server and administrative practices, you may want to schedule this command to run periodically to catch up with any users that may have been deleted (rather than deactivated) in the directory server: some directory servers do not update the group timestamp for deleted users.
Important:

This option should seldom be needed if users are deactivated rather than deleted. If it is needed, you may wish to schedule it when other network activity is low.

--reset-attribute-sync Sets the attribute sync timestamp to 1, which forces the provisioner to look at all users for changes, not only those that have a newer timestamp on their LDAP entry.
Important:

This option should be needed rarely and may consume considerable network resources, depending on the number of users. If it is needed, you may wish to schedule it when other network activity is low.

--reset-values-hash Removes the values hash for all users. (The database stores a hash of attribute values for users to determine whether any values have been changed.)

This argument forces users that have a newer timestamp on their LDAP entry to be updated at the service provider, regardless of the actual field values. Note, however, that users whose recorded timestamp is unchanged are not updated.

--reset-all Equivalent to using all three of the arguments above.
--show-dirty-records Lists all users or groups that have not been provisioned or updated at the service-provider site. This option should be needed rarely if ever and may consume considerable network resources, depending on the number of users. If it is needed, you may wish to schedule it when other network activity is low.
--show-dirty-group-records List groups that have not been provisioned or updated at the service-provider site.
--show-dirty-user-records List all users that have not been provisioned or updated at the service-provider site.
--show-group

--show-user

Use with:

-u <provider name>

Or:

-g <LDAP GUID>

Shows all internal database fields related to the specified user or group, including transitory mapping fields (fields waiting to be pushed to the service provider); for a user, shows all LDAP attributes retrieved from the directory server.
Note:

You can obtain user or group names and GUIDs for dirty records, as needed, using any of the --show-dirty-* options (described above).

The LDAP GUID, if used and if it is binary, should be entered in hexadecimal format (as shown in log files).

Examples:

provmgr.sh --show-user -u user@example.com
provmgr.sh --show-user -g ffd448643f812b43a0bee2504173f0
--clear-dirty-records Clears the dirty flag on all records.
--clear-dirty-group-records Clears the dirty flag on all group records.
--clear-dirty-user-records Clears the dirty flag on all user records.
--delete-dirty-records Removes all dirty records from the internal store.
--delete-dirty-group-records Removes all dirty group records from the internal store.
--delete-dirty-user-records Removes all dirty user records from the internal store.
--delete-all

--delete-all-users

The delete-all parameter removes all users and groups from the internal store and deletes the provisioning group timestamp and the last attribute-sync timestamp. The delete-all-users parameter deletes users and timestamps but retains groups.
The effect of either command is to reset the channel to its initial state for user provisioning. All user metadata is lost and provisioning for the channel will start from the beginning, picking up all users (and groups if deleted) and pushing them to the service provider when the synchronization frequency interval (defined on the System > Protocol Settings > Outbound Provisioning screen) has expired.
Important:

These options should be needed rarely if ever. If needed, you may wish to schedule the operation when other network activity is low.

--show-target Displays the target configuration.
--show-source Displays all source LDAP configuration parameters, including settings and location.