7.2. How setpin Works

The PIN Generator generates PINs for user entries in an LDAP directory and updates the directory with these PINs. To run the setpin command, the following five options are required:

The host name (host) and port number (port) of the LDAP server
The bind DN (binddn) and password (bindpw)
An LDAP filter (filter) for filtering out the user entries that require PINs

The setpin command looks like the following:

setpin host=csldap port=19000 binddn="CN=Directory Manager" bindpw=redhat filter="(ou=employees)" \
	basedn="o=example.com"

This example queries the directory for all the entries in the employees organizational unit (ou). For each entry matching the filter, information is printed out to standard error and to the standard output.

Note

Because the PIN Generator makes a lot of changes to the directory, it is important to use the correct filter, or the wrong entries are modified. Using the write option is a safeguard because no changes are made to the directory unless that option is used. This allows the PINs to be verified before any entries are modified.

The information can be written to a different output file by using the output option; see Section 7.2.2, “Output File” for more information. The entries returned by the LDAP search filter can be further restricted by using an ASCII input file which lists the entry DNs; only entries matching those in the file are updated. The input file is set with the input option. The input file is not a substitute for the LDAP directory entries; the filter attribute must still be provided. For more information about the input file, refer to Section 7.2.1, “Input File”. Figure 7.1, “Using an Input and Output File When Generating PINs” shows how the input and output files work with the setpin tool.

Figure 7.1. Using an Input and Output File When Generating PINs

The output file contains the entry and PIN information from running setpin, as shown in the following example:

Processing: cn=QA Managers,ou=employees,o=example.com
Adding new pin/password
dn:cn=QA Managers,ou=employees,o=example.com
pin:lDWynV
status:notwritten

Processing: cn=PD Managers,ou=employees,o=example.com
Adding new pin/password
dn:cn=PD Managers,ou=employees,o=example.com
pin:G69uV7
status:notwritten

The output also contains the status of each entry in the directory. The status values are listed in Table 7.2, “PIN Generator Status ”.

Exit Code	Description
`notwritten`	The PINs were not written to the directory because the `write` option was not used.
`writefailed`	The tool tried to modify the directory, but the write operation was unsuccessful.
`added`	The tool added the new PIN to the directory successfully.
`replaced`	The tool replaced an old PIN with a new one; this means the `clobber` option was used.
`notreplaced`	The tool did not replace the old PIN with a new one; this means the `clobber` option was not used.

Table 7.2. PIN Generator Status

If a PIN already exists for a user, it is not changed if the setpin command is run a second time. This allows new PINs to be created for new users without overwriting PINs for users who have already received a PIN. To overwrite a PIN, use the clobber option.

After making sure that the filter is matching the right users, run the setpin command again with the write option and with output set to the name of the file to capture the unhoused PINs. For details about the output file, refer to Section 7.2.2, “Output File”.