ldapuglist(1M)

NAME

ldapuglist — display and enumerate POSIX-like account and group entries in an LDAP directory server

SYNOPSIS

ldapuglist [options] [-t type] [-h hostname] [-p port] [-b base] [-s scope] [-n name | {-f|-F} filter] [-N maxcount] [attr...]

DESCRIPTION

ldapuglist is a command-line tool used to display and enumerate POSIX-like account and group entries that reside in an LDAP directory server.

Although ldapuglist provides similar output as compared with the ldapsearch command, it has been provided to meet a few specific feature requirements. These features allow applications to discover and evaluate account and group information stored in an LDAP directory server, without requiring intimate knowledge of the methods used retrieve and evaluate that information in the LDAP directory server.

Except for the optional trailing attr list, all parameters specified above are not positional dependent.

ldapuglist uses the existing LDAP-UX configuration, requiring minimal command-line options to discover where to search for account/group information, such as which directory server(s) to contact and proper search filters for finding accounts and groups. This tool provides command options that allow you to alter these configuration parameters.
ldapuglist uses the existing LDAP-UX authentication configuration to determine how to bind to the LDAP directory server.
ldapuglist supports attribute mapping as configured by LDAP-UX. Fields returned from ldapuglist will use a consistent format, similar to that defined by RFC2307, even when different attributes are actually used to store the information in the directory server.
Note, that although that format is similar to LDIF, it is not LDIF. Major differences include:
- Objectclasses will not be displayed.
- By default only POSIX-related attributes will be displayed by ldapuglist, unless an attribute list is specifically requested on the command line.
- Output lines will not be broken after 80 columns.

Options

-m

When -m is specified, ldapuglist will expose the names of the mapped attributes when returning results. Normally ldapuglist will return results as:

fieldname: value

where:

fieldname: is one of the pre-defined RFC2307 attribute names.
value: is the resulting value for that field, after attribute mapping has been applied.

With -m, the actual attribute name will be exposed as follows:

fieldname[attributename]: value

For example, if the RFC2307 attribute gecos has been mapped to the cn, l (location), and telephoneNumber attributes, without the -m option, the output of the gecos field would appear as:

gecos: value-of-cn,value-of-l,value-of-telephoneNumber,

When -m is used, and assuming the same conditions as above, the output representing the gecos field would appear as:

gecos[cn]: value-of-cn

gecos[l]: value-of-l

gecos[telephoneNumber]: value-of-telephoneNumber

Note that when a field has been mapped to multiple attributes, those attributes will appear in the order as defined in the LDAP-UX configuration.

The -m option does not apply if the -L option is specified.

-L

Display the password or group output in the following formats:

/etc/passwd format:

uid:userPasswd:uidNumbr:gidNumbr:gecos:homeDirectory:loginShell

/etc/group format:

cn:userPasswd:gidNumber,memberUid,...

The -m option is ignored when the -L option is specified. The attr parameter list is invalid when the -L option is specified.

-P

Prompt for the bind identity (typically LDAP DN or Kerberos principal) and bind password.

Without -P, ldapuglist will discover the bind identity and password either from the environment variables LDAP_BINDDN and LDAP_BINDCRED. If the LDAP_BINDDN or LDAP_BINDCRED environment variables have not been specified, ldapuglist will follow the bind configuration specified in the LDAP-UX configuration profile.

If LDAP-UX has specified "proxy" bind, the bind credential will be read from either the /etc/opt/ldapux/acred or /etc/opt/ldapux/pcred file. The acred file will only be used by users that have sufficient administrative privilege to read that file. Refer to Binding to the Directory Server below for additional details.

-Z

Requires an SSL connection to the directory server, even if the LDAP-UX configuration does not require the use of SSL.

Use of -Z requires either a valid directory server or CA certificate be defined in the /etc/opt/ldapux/cert8.db file. An error will occur if the SSL connection could not be established. Refer to Binding to the Directory Server below for additional details.

-ZZ

Attempt a TLS connection to the directory server, even if the LDAP-UX configuration does not require the use of TLS. If a TLS connection is unable to be established a non-TLS and non-SSL connection will be established.

Use of -ZZ is not recommended unless alternative methods are used to protect from network eavesdropping. Use of -ZZ requires either a valid server or CA certificate be defined in the /etc/opt/ldapux/cert8.db file. Refer to Binding to the Directory Server below for additional details.

-ZZZ

Requires a TLS connection to the directory server, even if the LDAP-UX configuration does not require the use of TLS.

Use of -ZZZ requires either a valid directory server or CA certificate be defined in the /etc/opt/ldapux/cert8.db file. An error will occur if the TLS connection could not be established. Refer to Binding to the Directory Server below for additional details.

Arguments

-t type

Specifies which service type ldapuglist will use to display or enumerate entries. The service type can be either passwd or group, where:

passwd: implies posixAccount-type entries and,
group: implies posixGroup-type entries.

Specification of the type parameter indicates how to handle processing of search filters (-f) and attribute mapping. If the -t option is not specified, ldapuglist will assume the passwd type.

-h hostname

Specifies the host name and optional port number (hostname:port) of the directory server. This option overrides the server list configured by LDAP-UX.

This field supports specification of IPv4 and IPv6 addresses. Note that when a port is specified for an IPv6 address, the IPv6 address must be specified in square-bracketed form. If the optional port is unspecified, the port number is assumed to be 389 or 636 for SSL connections (-Z). Refer to Binding to the Directory Server below for additional details.

-p port

Specifies the port number of the directory server to contact. This option is ignored if the port number is specified in the hostname as part of the -h option. Refer to Bindinding to the Directory Server below for additional details.

-n name

Provides a simplified method for discovering a single account or group. Use of -n is the same as -f"(uid=name)" for accounts and -f"(cn=cname)" for groups.

-F and -f may not be specified on the command line if -n is used.

-b base

This option overrides the search base as defined in the LDAP-UX configuration. base is a distinguished name (DN) that describes the highest location in the directory tree where to start the search. If unspecified, ldapuglist will use the defaultSearchBase as defined in the LDAP-UX configuration profile.

-s scope

This option overrides the search scope as defined in the LDAP-UX configuration. scope specifies how deep in the directory tree ldapuglist should search. scope may be one of base, one, or sub, where:

base: only performs a search on the base specified above,
one: searches all entries that are child entries of the base, and
sub: searches all entries below, including the base.

-f filter

Specifies an LDAP-style search filter, filter, used to select specific entries from the LDAP directory. When -f is used, the filter specified by filter is assumed to apply to either POSIX-style users or groups (depending on if the -t passwd or -t group option is specified). This means the filter specified with -f will be amended with the default LDAP-UX search filter for either the user or group object types.

In addition, when -f is used, if a known attribute for the particular service (see the lists defined under OUTPUT FORMAT), has been mapped as defined by the LDAP-UX configuration profile, then the mapped attribute name will be substituted in the search filter.

Using an example with the following command:

ldapuglist -t passwd -f "(uidNumber=52345)"

And assuming the LDAP-UX product has been configured as follows:

The configuration profile defines the search filter for the passwd service as (objectclass=posixAccount)
The uidNumber attribute for the passwd service has been mapped to the employeeNumber attribute.

Then the actual search filter used by ldapuglist would be:

(&(objectclass=posixAccount)(employeeNumber=52345))

The -f option also supports generation of search filters for multi-mapped attributes, gecos and memberUid. In the case of gecos, each mapped attribute would be used in the search filter using the LDAP and operation (&). And in the case of memberUid, each mapped attribute would be used in the search filter using the LDAP or operation (|).

For an example using gecos: assume gecos has been mapped to cn, l, and telephoneNumber. If the argument to -f is (gecos=Jane Smith,BLD-5D,555-1212), then the resulting search filter presented to the LDAP directory server would be:

(&(objectclass=posixAccount)(&(cn=Jane Smith)

(l=BLD-5D)(telephoneNumber=555-1212)))

Using an example for memberUid, assume memberUid has been mapped to member and memberUid. If the argument to -f is (memberUid=jsmith), then the resulting search filter presented to the LDAP directory server would be:

(&(objectclass=posixGroup)(|(member=

cn=Jane Smith,ou=people,ou=myorg,dc=myco,dc=com)

(memberUid=jsmith)))

NOTES:

When -f is used and any of the attributes specified in the search filter have been mapped to *NULL*, ldapuglist will return an error.
Attributes that are not part of the LDAP-UX configuration profile mapping will not be modified. Refer to RFC2307: An Approach for Using LDAP as a Network Information Service for the list of attributes that may be mapped.
Specifying -n and -f on the same command line will result in an error.

-F filter

Similar to -f, except that filter is assumed to be immutable, and neither the LDAP-UX user nor group filter from the configuration profile will be amended to the specified filter, nor will attribute mapping apply to the filter.

NOTES:

When -F is used, the specified filter should still apply to either user or group entries and match the -t passwd or -t group option. In other words, ldapuglist will produce unpredictable results if the search filter specified with -F discovers group entries, but the -t passwd option was specified.
Specifying -n and -F on the same command line will result in an error.

-N maxcount

This option specifies the maximum number of entries to be returned. If this option is not specified, the maximum number of entries to be returned is 200 by default.

Some directory servers will limit the number of entries returned for a particular search request, regardless of how many entries are requested. If the maxcount limit is set too high, it may not be possible to determine if a search has returned complete results, since the directory server may have truncated the number of returned entries before reaching the requested maximum count.

Although some directory servers will indicate if a specified search exceeds an enumeration limit, if maxcount is above the directory servers internal configured limit, it is not always possible to determine if all results have been returned. However a reasonable assumption is that if maxcount entries have been returned, additional entries are likely still available that match the search criteria than just those displayed.

attr

Specifies additional LDAP attributes to display aside from the pre-defined RFC2307 attributes for users or groups.

attr may not be used if the -L option is specified. Attributes specified in the attr list are assumed to not be part of RFC2307 and thus will not be mapped.

When the -m option is specified, the output format for a value specified by an attr will always be in the form:

attributename[attributename]: value

Note: ldapuglist does not allow use of the attr parameter when ldapuglist binds to the directory server using the LDAP-UX proxy user. This limitation prevents regular HP-UX users from discovering LDAP data that was previously not displayed by LDAP-UX. Use of the attr parameter requires either that the user has permission to use the LDAP-UX Administrator Credential (/etc/opt/ldapux/acred) or that the user specifies an identity using the -P or LDAP_BINDDN and LDAP_BINDCRED environment variables when running ldapuglist.

Binding to the Directory Server

ldapuglist has been designed to take advantage of the existing LDAP-UX configuration for determining to which directory server to bind and how to perform the bind operation. ldapuglist will consult the LDAP-UX configuration profile for the following information:

The list of LDAP directory server hosts.
The authentication method (simple passwords, SASL Digest MD5, etc.).

If either of the environment variables LDAP_BINDDN and LDAP_BINDCRED have not been specified, ldapuglist will also consult the LDAP-UX configuration for additional information:

The type of credential (user, proxy or anonymous) to use.
The credential used for binding as a proxy user (either /etc/opt/ldapux/acred for administrative users or /etc/opt/ldapux/pcred for non-privileged users.)

ldapuglist will display an error message if LDAP_BINDDN has been specified and LDAP_BINDCRED has not, unless the -P option has been specified.

As with LDAP-UX, ldapuglist will attempt to contact the first available directory server as defined in the LDAP-UX host list. As soon as a connection is established, further directory servers on the host list will not be contacted.

Once connected, ldapuglist will first determine if the environment variables LDAP_BINDDN and LDAP_BINDCRED have been specified. If so, then ldapuglist will attempt to bind to the directory server using the specified credentials and configured LDAP-UX authentication method.

If the above mentioned environment variables have not been specified, then ldapuglist will determine if the configured credential type is "proxy" and if so, attempt to bind to the directory server using the configured LDAP-UX proxy credential. If configured, the acred proxy credential will be used for administrative users (determined if the user running ldapuglist has enough privilege to read the /etc/opt/ldapux/acred file). Otherwise the credential configured in /etc/opt/ldapux/pcred will be used.

Note: to prevent discovery of the LDAP administrator's credentials, the LDAP user DN and password may not be specified as command-line options to the ldapuglist utility.

Security Considerations

In order to support non-interactive use of the ldapuglist command, specification of the LDAP administrator's credentials is required through use of the LDAP_BINDDN and LDAP_BINDCRED environment variables. To prevent exposure of these environment variables, they should be unset after use.

Note also that shells command history log may contain copies of the executed commands that show setting of these variables. Access to a shell's history file must be protected. Specification of the LDAP administrator's credentials on the command line is not allowed since information about the currently running processes can be exposed externally from the session.

Use of the -P eliminates the need to set the mentioned environment variables by interactively prompting for the required credentials.

LDAP-UX PROFILE

ldapuglist makes use of the LDAP-UX configuration profile to determine the information model used in the directory server to store POSIX attributes. Please refer to the LDAP-UX Client Services Administrator's Guide for additional information about the configuration profile.

OUTPUT FORMAT

Output from ldapuglist will follow a consistent format, regardless of which attributes are used to define information in an LDAP directory. The output format is:

dn: dn1
field1: value1
field2: value2
field3:: base64-encodeded-value3

dn: dn2
field1: value1
field2: value2

Each entry will be preceded by a DN, followed by one or more field-value pairs. The DN and each field-value pair will be on a separate line, separated by a carriage-return and line-feed character. The field and value will be separated by a colon and space character. And each entry will be separated by a blank line.

In the case when an unencodable character is encountered (carriage-return or line-feed for example) in a value string, the whole value will be base64 encoded and the field-value separator will change to two colons and a space character. See Unencodable Characters below. When the -t passwd option is specified, the following fields will be returned:

cn 
uid 
userPassword 
uidNumber 
gidNumber 
homeDirectory 
loginShell 
gecos 

When the -t group option is specified, the following fields will be returned:

cn 
userPassword 
gidNumber 
memberUid 

Note that when the -m option is specified, the output format will change (for both users and groups) to:

dn: dn1
field1[attribute1]: value1
field2[attribute2]: value2
field3[attribute3]:: base64-encodeded-value3

Special Considerations for Output Format

Multi-Valued Attributes

Although some of the attributes used in LDAP directory servers are considered multi-valued attributes, the ldapuglist tool will only display the first value discovered for each RFC2307 attribute for each entry, since these fields appear only once in a POSIX account or group.

For non-RFC2307 attributes (those specified via the attr argument list), if the attribute is multi-valued, multiple values will be displayed. Also note that this rule does not apply to the memberUid field since POSIX groups may have multiple members.

Since the gecos attribute can be mapped to multiple attributes, the gecos field may appear multiple times in an entry if the -m option is used, once for each mapped attribute. Example:

gecos[cn]: Bill Smith
gecos[l]: Building 6A
gecos[telephoneNUmber]: +1-555-555-4321

Non-POSIX Accounts & Groups

With the -F option, ldapuglist can be used to display users and groups that are not posixAccounts or posixGroups. Thus, these entries may not contain the required fields that store POSIX account and group information (such as the uidNumber). When displaying these entries, the specified fields will be missing from the output.

As non-POSIX accounts and groups are not required to contain POSIX attributes, use of the -L option may result in unexpected output. Data between the : characters may be empty, such as ::x:::.

UTF-8

Since LDAP directories require data be stored according to the UTF-8 (RFC3629) character encoding method, all characters displayed by ldapuglist will be UTF-8, and assumed to be part of the ISO-10646 character set. ldapuglist will not perform conversion of the locale character set to/from the UTF-8 character set.

Unencodable Characters (Base64 Encoding)

In the output format of ldapuglist each displayed field will be delimited by a new line (carriage-return and line-feed). In order to assure that ldapuglist displays only printable and LDIF encodable characters, all characters less than 32 (ASCII space), except for 9 (ASCII horizontal tab) and the character 127 (ASCII delete) will result in the value being converted into a base-64 encoded string. Characters above 127 are assumed be from the UTF-8 character set, and assumed printable. If the output lines are long, the data will not be broken into multiple lines.

Encoding of the DN

ldapuglist will display DN strings according to the encoding rules defined in RFC4514. The escape character (\) will precede special characters, which may be the character itself or a 2 digit hex representation of the character.

Passwords

In many cases, ldapuglist will not be able to access the user or group password fields. This can occur when:

ldapuglist has insufficient privilege to access the password field
The passwords are not used to authenticate users (such as when X.500 certificates).
The password is not stored in the LDAP directory server. The password might be stored in a third-party repository such as a Kerberos KDC.
The password is stored in a format un-parsable by HP-UX (such as SSHA, the Salted Secure Hash Algorithm).

If the password is not available to ldapuglist, the userPassword field will not be displayed. If the -L option is specified, the password field will contain the "x" character. Existence or lack of the password field can not be used to determine if an account is active or inactive.

RETURN VALUE

Upon exit, ldapuglist returns the following:

0

Success. ldapuglist exits with no errors or with one or more warnings.

<>0

ldapuglist returns with a non-zero exit status if it encounters an error, and messages will be logged to stderr.

Messages will follow the below format:

ERROR:

code

message

WARNING:

code

message

Leading extra white space may be inserted to improve readability and follow 80 column screen formatting.

code: will be a programmatically parsable error key-string, while
message: will be human-readable. Refer to the LDAP-UX Client Services Administrator's Guide for a list of possible error codes generated by the LDAP user and group management tools.

EXTERNAL INFLUENCES

Environment Variables

LDAP_BINDDN: Specified the DN of a user with sufficient directory server privilege to discover and enumerate users and/or groups in the LDAP directory server. While this variable is optional, if LDAP_BINDDN is specified, LDAP_BINDCRED must also be specified.
LDAP_BINDCRED: A password or other type of credential used for the user specified by LDAP_BINDDN. While this variable is optional, if LDAP_BINDCRED is specified, LDAP_BINDDN must also be specified.

Refer to Security Considerations for important security impacts when these environment variables are used.

EXAMPLES

Specifying LDAP_BINDDN and LDAP_BINDCRED:

# export LDAP_BINDDN="cn=Directory Manager"
# export LDAP_BINDCRED="password"
# ldapuglist -f "(uid=apierce)" sn
dn: cn=Alan Pierce,ou=people,ou=IT,dc=FutureWidget,dc=com
cn: Alan Pierce
uid: apierce
uidNumber: 22014
gidNumber: 318
homeDirectory: /home/apierce
loginShell: /usr/bin/ksh
gecos: Alan Pierce,San Francisco,+1 505-555-6525
sn: Pierce

Using the -m option on the same entry, assuming that the uidNumber has been mapped to employeeNumber and gecos has been mapped to cn, l, and telephoneNumber.

# export LDAP_BINDDN="cn=Directory Manager"
# export LDAP_BINDCRED="password"
# ldapuglist -u -m -f "(uidd=apierce)"
dn: cn=Alan Pierce,ou=people,ou=IT,dc=FutureWidget,dc=com
cn[cn]: Alan Pierce
uid[uid]: apierce
uidNumber[employeeNumber]: 22014
gidNumber[gidNumber]: 318
homeDirectory[homeDirectory]: /home/apierce
loginShell: /usr/bin/ksh
gecos[cn]: Alan Pierce
gecos[l]: San Francisco
gecos[telephoneNumber]: +1 505-555-6525

Listing all POSIX accounts held by users in San Francisco.

# ldapuglist -f "(l=Sann Francisco)"
dn: cn=Alan Pierce,ou=people,ou=IT,dc=FutureWidget,dc=com
cn: Alan Pierce
uid: apierce
uidNumber: 22014
gidNumber: 318
homeDirectory: /home/apierce
loginShell: /usr/bin/ksh
gecos: Alan Pierce,San Francisco,+1 505-555-6525

dn: cn=Manuel Wolters,ou=people,ou=IT,dc=FutureWidget,dc=com
cn: Manuel Wolters
uid: mwolters
uidNumber: 2284
gidNumber: 212
homeDirectory: /home/mwolters
loginShell: /usr/bin/ksh
gecos: Manuel Wolters,San Francisco,+1 505-555-5072

dn: cn=Joanie Lin,ou=people,ou=IT,dc=FutureWidget,dc=com
cn: Joanie Lin
uid: jlin
uidNumber: 2840
gidNumber: 229
homeDirectory: /home/jlin
loginShell: /usr/bin/ksh
gecos: Joanie Lin,San Francisco,+1 505-555-1111
...

Listing an account that does not contain POSIX attributes.

# ldapuglist -m -F "(uid=apierce)"
dn: cn=Alan Pierce,ou=people,ou=IT,dc=FutureWidget,dc=com
cn[cn]: Alan Pierce
uid[uid]: apierce
gecos[cn]: Alan Pierce
gecos[l]: San Francisco
gecos[telephoneNumber]: +1 505-555-6525

Listing an account that does not contain POSIX attributes using the -L option.

# ldapuglist -m -L -F "(uid=apierce)"
apierce:x:::Alan Pierce,San Francisco,+1 505-555-6525::

Listing a posixGroup which has its members defined using the X.500-style syntax. Note that ldapuglist will map DN-style membership to account names.

# ldapuglist -t group -f "(cn=mygroup1)"
dn: cn=mygroup1,ou=groups,ou=IT,dc=FutureWidges,dc=com
cn: mygroup1
gidNumber: 542
memberUid: mdiaz
memberUid: apierce
memberUid: bjones
...

Listing posixGroups which have Mike Diaz (uid=mdiaz) as a member defined using memberUid syntax.

# ldapuglist -t group -f "(memberUid=mdiaz)"
dn: cn=mygroup1,ou=groups,ou=IT,dc=FutureWidges,dc=com
cn: mygroup1
gidNumber: 542
memberUid: mdiaz
memberUid: apierce
memberUid: bjones
...

dn: cn=mygroup2,ou=groups,ou=IT,dc=FutureWidges,dc=com
cn: mygroup1
gidNumber: 542
memberUid: lsmith
memberUid: bjones
memberUid: mdiaz
...

Listing all posixGroups which have Mike Diaz (uid=mdiaz) as a member defined using the X.500-style (member or uniqueMember) syntax.

# ldapuglist -t group -m \
-f "(member=cn=Mike Diaz,ou=People,ou=IT,dc=FutureWidget,dc=com)"
dn: cn=mygroup1,ou=groups,ou=IT,dc=FutureWidges,dc=com
cn[cn]: mygroup1
gidNumber[gidNumber]: 542
memberUid[member]: mdiaz
memberUid[member]: apierce
memberUid[member]: bjones
...

dn: cn=mygroup2,ou=groups,ou=IT,dc=FutureWidges,dc=com
cn: mygroup1
gidNumber: 542
memberUid: lsmith
memberUid: bjones
memberUid: mdiaz
...

Listing regular posixGroups which have Mike Diaz (uid=mdiaz) as a member:

# ldapuglist -t group -f "(cn=mygroup1)"
dn: cn=mygroup1,ou=groups,ou=IT,dc=FutureWidges,dc=com
cn: mygroup1
gidNumber: 542
memberUid: mdiaz
memberUid: apierce
memberUid: bjones
...

Listing a group that does not have the required posixGroup attributes.

# ldapuglist -t group \
  -F "((cn=mygroup2)(objectclass=groupOfUniqueNames))"
dn: cn=mygroup2,ou=groups,ou=IT,dc=FutureWidges,dc=com
cn: mygroup2

LIMITATIONS

ldapuglist will not support enumeration of members of a dynamic group, such as those defined by the attributes: memberUrl, nxSearchFilter, msDS-AzLDAPQuery, etc.
ldapuglist will not perform conversion of the locale character set to/from the UTF-8 character set.
ldapuglist will not display attributes to which it does not have access rights in the LDAP directory server. Be sure to specify administrator credentials with sufficient privileges in the LDAP directory to view the requested attributes.