User Guide -- command-line tools

Intended Audience:
Developers and system administrators

  1. OpenLDAP command-line tools
    1. TLS cert valiation
    2. ldapwhoami
    3. ldapsearch
  2. Æ-DIR command-line tools
    1. ae-passwd.py
    2. ae-add-zone.py
  3. OpenSSL
    1. openssl s_client
    2. openssl verify

OpenLDAP command-line tools

Relevant OpenLDAP documentation:

TLS cert valiation

Please make sure that you fully understand how OpenLDAP command-line tools determine which trusted root CA cert to use (see section TLS_OPTIONS in ldap.conf(5)).

If in doubt simply use this to set it by environment variables (does not work on MacOSX!):

LDAPTLS_CACERT=/path/to/rootca.crt

ldapwhoami

The OpenLDAP command-line tool ldapwhoami(1) binds and sends a "Who am I?" extended operation (see RFC 4532) to the LDAP server. This is handy to test various authentication mechs and authz-ID mappings.

Check aeUser or aeService password via simple bind request with short bind-DN interactively asking for password:
ldapwhoami -x -H ldaps://demo.ae-dir.com -D "uid=lisa,ou=ae-dir" -W
Check aeHost password via simple bind request with short bind-DN and given password:
ldapwhoami -x -H ldaps://demo.ae-dir.com -D "host=bart.example.com,ou=ae-dir" -w
Check aeService authentication via SASL/EXTERNAL bind request and client cert:
LDAPTLS_CERT=/path/to/client.crt LDAPTLS_KEY=/path/to/client.key ldapwhoami -Y EXTERNAL -H ldaps://demo.ae-dir.com
On a fully installed replica the following should output the DN of the replica's aeService entry:
LDAPRC=/opt/ae-dir/etc/ldap.conf ldapwhoami -Y EXTERNAL -H ldaps://ae-dir-provider.example.com

ldapsearch

The OpenLDAP command-line tool ldapsearch(1) sends a search request to the LDAP server and outputs search results retrieved as LDIF (see RFC 2849).

Search for aeUser with username "lisa" by uid:
ldapsearch -H ldaps://demo.ae-dir.com -b ou=ae-dir -s sub "(uid=lisa)" "*" "+"
Search on behalf of an aeService (with -X):
ldapsearch -H ldaps://demo.ae-dir.com -b ou=ae-dir -s sub -X 'dn:uid=system_test-1,cn=test-servers-1,cn=test,ou=ae-dir' "*" "+"

Æ-DIR command-line tools

Various command-line tools are installed on the provider systems into directory /opt/ae-dir/bin/ which use a separate configuration file installed to /opt/ae-dir/etc/ldap.conf:

ae-passwd.py
Sets password of aeUser, aeService or aeHost
ae-add-zone.py
Adds new aeZone with the two standard aeGroup entries for the zone admins and zone auditors.

ae-passwd.py

Roles:

Especially this tool is used when boot-strapping a new Æ-DIR installation to set the password of the first Æ admin.

Example usage setting password for user account:

root@ae-dir-deb-p1:~# /opt/ae-dir/bin/ae-passwd.py bart
new password for uid=bart,cn=ae,ou=ae-dir:
repeat password:

ae-add-zone.py

Roles:

Example usage:

root@ae-dir-deb-p1:~# /opt/ae-dir/bin/ae-add-zone.py test42 IAM-42 "the definite answer"
Added cn=test42,ou=ae-dir
Added cn=test42-init,cn=test42,ou=ae-dir
Tagged cn=test42,ou=ae-dir
Added cn=test42-zone-admins,cn=test42,ou=ae-dir
Added cn=test42-zone-auditors,cn=test42,ou=ae-dir

OpenSSL command-line tools

Relevant OpenSSL documentation:

openssl s_client

The OpenSSL command-line tool s_client(1) opens a TLS connection to the server which is useful to test whether server cert validation is correct.

Open TLS connection to LDAPS port:
openssl s_client -connect demo.ae-dir.com:636 -CAfile /path/to/rootca.crt
(should display "Verify return code: 0 (ok)")

openssl verify

The OpenSSL command-line tool verify(1) is useful to validate a certificate (chain) against a locally CA certificate chain.