ldapuglist(1M)ldapuglist(1M)NAMEldapuglist - display and enumerate POSIX-like account and group entries
in an LDAP directory server
SYNOPSIS
[options] type] hostname] port] base] scope] name | filter] maxcount]
[attr...]
DESCRIPTION
is a command-line tool used to display and enumerate POSIX-like account
and group entries that reside in an LDAP directory server.
Although provides similar output as compared with the command, it has
been provided to meet a few specific feature requirements. These fea‐
tures allow applications to discover and evaluate account and group
information stored in an LDAP directory server, without requiring inti‐
mate knowledge of the methods used retrieve and evaluate that informa‐
tion in the LDAP directory server.
Except for the optional trailing attr list, all parameters specified
above are not positional dependent.
· uses the existing ldapux(5) configuration, requiring minimal com‐
mand-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 parame‐
ters.
· uses the existing ldapux(5) authentication configuration to deter‐
mine how to bind to the LDAP directory server.
· supports attribute mapping as configured by ldapux(5). Fields
returned from 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
unless an attribute list is specifically requested on the command
line.
· Output lines will not be broken after 80 columns.
Options
When is specified, will expose the names of the mapped attributes
when returning results. Normally will return results as:
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 the actual attribute name will be exposed as follows:
For example, if the RFC2307 attribute gecos has been mapped to
the cn, l (location), and telephoneNumber attributes, without
the option, the output of the gecos field would appear as:
When is used, and assuming the same conditions as above, the
output representing the gecos field would appear as:
Note that when a field has been mapped to multiple attributes,
those attributes will appear in the order as defined in the
ldapux(5) configuration.
The option does not apply if the option is specified.
Display the password or group output in the following formats:
format:
format:
The option is ignored when the option is specified. The attr
parameter list is invalid when the option is specified.
Prompt for the bind identity (typically LDAP DN or Kerberos principal)
and bind password.
Without will discover the bind identity and password either
from the environment variables and If the or environment vari‐
ables have not been specified, will follow the bind configura‐
tion specified in the ldapux(5) configuration profile.
If ldapux(5) has specified "proxy" bind, the bind credential
will be read from either the or file. The file will only be
used by users that have sufficient administrative privilege to
read that file. Refer to below for additional details.
Requires an SSL connection to the directory server, even if the
ldapux(5) configuration does not require the use of SSL.
Use of requires either a valid directory server or CA certifi‐
cate be defined in the file. An error will occur if the SSL
connection could not be established. Refer to below for addi‐
tional details.
Attempt a TLS connection to the directory server, even if the
ldapux(5) 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 is not recommended unless alternative methods are used
to protect from network eavesdropping. Use of requires either
a valid server or CA certificate be defined in the file. Refer
to below for additional details.
Requires a TLS connection to the directory server, even if the
ldapux(5) configuration does not require the use of TLS.
Use of requires either a valid directory server or CA certifi‐
cate be defined in the file. An error will occur if the TLS
connection could not be established. Refer to below for addi‐
tional details.
Arguments
Specifies which service type
will use to display or enumerate entries. The service
type can be either or where:
implies posixAccount-type entries and,
implies posixGroup-type entries.
Specification of the type parameter indicates how to
handle processing of search filters and attribute map‐
ping. If the option is not specified, will assume the
type.
Specifies the host name and optional port number
of the directory server. This option overrides the
server list configured by ldapux(5).
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 unspeci‐
fied, the port number is assumed to be 389 or 636 for
SSL connections Refer to below for additional details.
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 option. Refer to below
for additional details.
Provides a simplified method for discovering a single account or group.
Use of is the same as for accounts and for groups.
and may not be specified on the command line if is used.
This option overrides the search base as defined in the
ldapux(5) configuration. base is a distinguished name
(DN) that describes the highest location in the direc‐
tory tree where to start the search. If unspecified,
will use the defaultSearchBase as defined in the LDAP-UX
configuration profile.
This option overrides the search scope as defined in the
ldapux(5) configuration. scope specifies how deep in
the directory tree should search. scope may be one of
or where:
only performs a search on the
base specified above,
searches all entries that are child entries of the
base, and
searches all entries below, including the
base.
Specifies an LDAP-style search filter,
filter, used to select specific entries from the LDAP
directory. When is used, the filter specified by filter
is assumed to apply to either POSIX-style users or
groups (depending on if the or option is specified).
This means the filter specified with will be amended
with the default ldapux(5) search filter for either the
user or group object types.
In addition, when is used, if a known attribute for the
particular service (see the lists defined under has been
mapped as defined by the ldapux(5) configuration pro‐
file, then the mapped attribute name will be substituted
in the search filter.
Using an example with the following command:
And assuming the LDAP-UX product has been configured as
follows:
· The configuration profile defines the search filter
for the service as
· The uidNumber attribute for the service has been
mapped to the employeeNumber attribute.
Then the actual search filter used by would be:
The 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 operation And in the
case of memberUid, each mapped attribute would be used
in the search filter using the LDAP operation
For an example using gecos: assume gecos has been mapped
to cn, l, and telephoneNumber. If the argument to is
then the resulting search filter presented to the LDAP
directory server would be:
Using an example for memberUid, assume memberUid has
been mapped to member and memberUid. If the argument to
is then the resulting search filter presented to the
LDAP directory server would be:
NOTES:
· When is used and any of the attributes specified in
the search filter have been mapped to will return an
error.
· Attributes that are not part of the LDAP-UX configu‐
ration profile mapping will not be modified. Refer
to for the list of attributes that may be mapped.
· Specifying and on the same command line will result
in an error.
Similar to except that filter is assumed to be immutable, and nei‐
ther the ldapux(5) user nor group filter from the con‐
figuration profile will be amended to the specified fil‐
ter, nor will attribute mapping apply to the filter.
NOTES:
· When is used, the specified filter should still apply
to either user or group entries and match the or
option. In other words, will produce unpredictable
results if the search filter specified with discovers
group entries, but the option was specified.
· Specifying and on the same command line will result
in an error.
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 direc‐
tory server may have truncated the number of returned
entries before reaching the requested maximum count.
Although some directory servers will indicate if a spec‐
ified 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 dis‐
played.
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 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 option is specified, the output format for a
value specified by an attr will always be in the form:
Note: does not allow use of the attr parameter when
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 Adminis‐
trator Credential or that the user specifies an identity
using the or and environment variables when running
Binding to the Directory Server
has been designed to take advantage of the existing ldapux(5) configu‐
ration for determining to which directory server to bind and how to
perform the bind operation. will consult the ldapux(5) 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 and have not been specified,
will also consult the ldapux(5) configuration for additional informa‐
tion:
· The type of credential (user, proxy or anonymous) to use.
· The credential used for binding as a proxy user (either for adminis‐
trative users or for non-privileged users.)
will display an error message if has been specified and has not, unless
the option has been specified.
As with ldapux(5), will attempt to contact the first available direc‐
tory server as defined in the ldapux(5) host list. As soon as a con‐
nection is established, further directory servers on the host list will
not be contacted.
Once connected, will first determine if the environment variables and
have been specified. If so, then will attempt to bind to the directory
server using the specified credentials and configured LDAP-UX authenti‐
cation method.
If the above mentioned environment variables have not been specified,
then 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 has
enough privilege to read the file). Otherwise the credential config‐
ured in 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 utility.
Security Considerations
In order to support non-interactive use of the command, specification
of the LDAP administrator's credentials is required through use of the
and environment variables. To prevent exposure of these environment
variables, they should be unset after use.
Note also that shells(4) 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 exter‐
nally from the session.
Use of the eliminates the need to set the mentioned environment vari‐
ables by interactively prompting for the required credentials.
LDAP-UX PROFILE
makes use of the LDAP-UX configuration profile to determine the infor‐
mation model used in the directory server to store POSIX attributes.
Please refer to the for additional information about the configuration
profile.
OUTPUT FORMAT
Output from will follow a consistent format, regardless of which
attributes are used to define information in an LDAP directory. The
output format is:
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 below. When the option is speci‐
fied, the following fields will be returned:
cn
uid
userPassword
uidNumber
gidNumber
homeDirectory
loginShell
gecos
When the option is specified, the following fields will be returned:
cn
userPassword
gidNumber
memberUid
Note that when the option is specified, the output format will change
(for both users and groups) to:
Special Considerations for Output Format
Although some of the attributes used in LDAP directory servers are con‐
sidered multi-valued attributes, the 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 dis‐
played. 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 option is
used, once for each mapped attribute. Example:
gecos[cn]: Bill Smith
gecos[l]: Building 6A
gecos[telephoneNUmber]: +1-555-555-4321
With the option, 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 option may result in unexpected output. Data
between the characters may be empty, such as Since LDAP directories
require data be stored according to the UTF-8 (RFC3629) character
encoding method, all characters displayed by will be UTF-8, and assumed
to be part of the ISO-10646 character set. will not perform conversion
of the locale character set to/from the UTF-8 character set. In the
output format of each displayed field will be delimited by a new line
(carriage-return and line-feed). In order to assure that 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. 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. In many
cases, will not be able to access the user or group password fields.
This can occur when:
· 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 pass‐
word 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 the userPassword field will not be
displayed. If the 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, returns the following:
0 Success. exits with no errors or with one or more warnings.
<>0 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:
code
message
or
code
message
Leading extra white space may be inserted to improve readabil‐
ity and follow 80 column screen formatting.
code will be a programmatically parsable error key-string,
while
message will be human-readable. Refer to the for a list of
possible error codes generated by the LDAP user and
group management tools.
EXTERNAL INFLUENCES
Environment Variables
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 is specified, must also be
specified.
A password or other type of credential used for the user specified
by While this variable is optional, if is specified, must also
be specified.
Refer to for important security impacts when these environment vari‐
ables are used.
EXAMPLES
Specifying and
# 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 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
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 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 as a member defined using mem‐
berUid 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 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 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
· will not support enumeration of members of a dynamic group, such as
those defined by the attributes: memberUrl, nxSearchFilter, msDS-
AzLDAPQuery, etc.
· will not perform conversion of the locale character set to/from the
UTF-8 character set.
· will not display attributes to which it does not have access rights
in the LDAP directory server. Be sure to specify administrator cre‐
dentials with sufficient privileges in the LDAP directory to view
the requested attributes.
SEE ALSOldapcfinfo(1M), ldapugadd(1M), ldapugdel(1M), ldapugmod(1M), ldapux(5).
ldapuglist(1M)
