xref: /PHP-8.0/ext/ldap/tests/README.md (revision 38f388fb) 
1# The ldap extension tests
2
3To ease testing LDAP-Setups we've created a vagrant-setup.
4
5## Prerequisites
6
7You will need [vagrant](https://www.vagrantup.com) on your box.
8
9## Usage
10
11To use it follow these steps:
12
13* Create a `Vagrantfile` with the following content.
14* Go to that directory and run "vagrant up"
15
16```Vagrantfile
17$setup = <<<SETUP
18apt-get update
19
20DEBIAN_FRONTEND=noninteractive aptitude install -q -y slapd ldap-utils
21
22export SLAPPASS=`slappasswd -s password`
23
24echo "dn: olcDatabase={1}hdb,cn=config
25changetype: modify
26replace: olcSuffix
27olcSuffix: dc=nodomain
28-
29replace: olcRootDN
30olcRootDN: dc=admin,dc=nodomain
31-
32replace: olcRootPW
33olcRootPW: ${SLAPPASS}" | ldapmodify -Y EXTERNAL -H ldapi:///
34
35echo "dn: dc=nodomain
36objectClass: dcObject
37objectClass: organization
38o: Example
39dc: example
40
41dn: ou=extldap,dc=nodomain
42objectClass: organizationalUnit
43ou: extldap" | ldapadd -c -x -H ldap://localhost:389 -D "dc=admin,dc=nodomain" -w password
44SETUP
45
46Vagrant.configure(2) do |config|
47  config.vm.box = "ubuntu/trusty64"
48  config.vm.network "private_network", ip: "192.168.33.10"
49  config.vm.provision "shell", inline: $setup
50end
51```
52
53Now you will have a virtual machine up and running on IP-Address `192.168.10.33`
54listening on port 369 for incoming LDAP-connections. The machine is already
55configured to execute the LDAP-Tests.
56
57The next step is to go into the PHP-Source-directory. Configure and make the
58source as appropriate.
59
60Before running the LDAP-Tests you need to set some environment-variables:
61
62```bash
63export LDAP_TEST_PASSWD="password"
64export LDAP_TEST_BASE="ou=extldap,dc=nodomain"
65export LDAP_TEST_USER="dc=admin,dc=nodomain"
66export LDAP_TEST_HOST=192.168.33.10
67```
68
69Now you can run the test-suite by calling `make test`. To test only the
70LDAP-Tests, run `make test TESTS=ext/ldap`.
71
72CAVEAT: The current setup does not (yet) test secure connections.
73
74## Old README
75
76Most tests here rely on the availability of an LDAP server configured with TLS.
77
78### Client/Server configuration
79
80OpenLDAP 2.4.31 has been used with the configuration below.
81
82Notes:
83
841. A self signed certificate can be generated using:
85
86    ```bash
87    openssl req -newkey rsa:1024 -x509 -nodes -out server.pem -keyout server.pem -days 3650
88    ```
89
90    It is used for testing ldap_start_tls(), which also requires
91    `TLS_REQCERT never` in client configuration.
92
932. An empty LDAP structure is required for the tests to be PASSed (except for
94    base and admin)
95
96If you use a debian based distribution, prefer the use of `dpkg-reconfigure`.
97Otherwise you may alter these configuration files:
98
99#### (/etc/openldap/)slapd.conf
100
101```txt
102TLSCACertificateFile /etc/openldap/ssl/server.pem
103TLSCertificateFile /etc/openldap/ssl/server.pem
104TLSCertificateKeyFile /etc/openldap/ssl/server.pem
105TLSVerifyClient never
106
107# hdb is used instead of bdb as it enables the usage of referrals & aliases
108database        hdb
109suffix          "dc=my-domain,dc=com"
110checkpoint      32      30
111rootdn          "cn=Manager,dc=my-domain,dc=com"
112rootpw          secret
113directory       /var/lib/openldap-data
114index   objectClass     eq
115
116authz-regexp
117    uid=Manager,cn=digest-md5,cn=auth
118    cn=Manager,dc=my-domain,dc=com
119```
120
121#### (/etc/openldap/)ldap.conf
122
123```txt
124TLS_REQCERT never
125```
126
127#### Tests configuration
128
129The following environment variables may be defined:
130
131```txt
132LDAP_TEST_HOST (default: localhost)                        Host to connect to
133LDAP_TEST_PORT (default: 389)                              Port to connect to
134LDAP_TEST_BASE (default: dc=my-domain,dc=com)              Base to use. May be the ldap root or a subtree. (ldap_search_variation6 will fail if a subtree is used)
135LDAP_TEST_USER (default: cn=Manager,dc=my-domain,dc=com)   DN used for binding
136LDAP_TEST_SASL_USER (default: Manager)                     SASL user used for SASL binding
137LDAP_TEST_PASSWD (default: secret)                         Password used for plain and SASL binding
138LDAP_TEST_OPT_PROTOCOL_VERSION (default: 3)                Version of LDAP protocol to use
139LDAP_TEST_SKIP_BIND_FAILURE (default: true)                Whether to fail the test or not in case binding fails
140```
141
142## Credits
143
144* Davide Mendolia (idaf1er@gmail.com)
145* Patrick Allaert (patrick.allaert@gmail.com)
146* Côme Bernigaud (mcmic@php.net)
147