Skip to content

Commit 9ce7ba0

Browse files
williamdeswilliamdes
committed
Improved the README.md
1 parent 7ce084b commit 9ce7ba0

File tree

1 file changed

+124
-61
lines changed

1 file changed

+124
-61
lines changed

‎README.md‎

Lines changed: 124 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# osixia/openldap
22

3-
![Docker Pulls](https://img.shields.io/docker/pulls/osixia/openldap.svg)
4-
![Docker Stars](https://img.shields.io/docker/stars/osixia/openldap.svg)
5-
![](https://images.microbadger.com/badges/image/osixia/openldap.svg)
3+
[![Docker Pulls](https://img.shields.io/docker/pulls/osixia/openldap.svg)](https://hub.docker.com/r/osixia/openldap/)
4+
[![Docker Stars](https://img.shields.io/docker/stars/osixia/openldap.svg)](https://hub.docker.com/r/osixia/openldap/)
5+
[![Layers](https://images.microbadger.com/badges/image/osixia/openldap.svg)](https://hub.docker.com/r/osixia/openldap/)
66

7-
Latest release: 1.4.0 - OpenLDAP 2.4.50 - [Changelog](CHANGELOG.md) | [Docker Hub](https://hub.docker.com/r/osixia/openldap/) 
7+
Latest release: 1.4.0 - [OpenLDAP 2.4.50](https://www.openldap.org/software/release/changes.html) - [Changelog](CHANGELOG.md) | [Docker Hub](https://hub.docker.com/r/osixia/openldap/) 
88

99
**A docker image to run OpenLDAP.**
1010

11-
> OpenLDAP website : [www.openldap.org](http://www.openldap.org/)
11+
> OpenLDAP website : [www.openldap.org](https://www.openldap.org/)
1212
1313

1414
- [osixia/openldap](#osixiaopenldap)
@@ -59,15 +59,21 @@ If you find this image useful here's how you can help:
5959
## Quick Start
6060
Run OpenLDAP docker image:
6161

62-
docker run --name my-openldap-container --detach osixia/openldap:1.4.0
62+
```sh
63+
docker run --name my-openldap-container --detach osixia/openldap:1.4.0
64+
```
6365

6466
Do not forget to add the port mapping for both port 389 and 636 if you wish to access the ldap server from another machine.
6567

66-
docker run -p 389:389 -p 636:636 --name my-openldap-container --detach osixia/openldap:1.4.0
68+
```sh
69+
docker run -p 389:389 -p 636:636 --name my-openldap-container --detach osixia/openldap:1.4.0
70+
```
6771

6872
Either command starts a new container with OpenLDAP running inside. Let's make the first search in our LDAP container:
6973

70-
docker exec my-openldap-container ldapsearch -x -H ldap://localhost -b dc=example,dc=org -D "cn=admin,dc=example,dc=org" -w admin
74+
```sh
75+
docker exec my-openldap-container ldapsearch -x -H ldap://localhost -b dc=example,dc=org -D "cn=admin,dc=example,dc=org" -w admin
76+
```
7177

7278
This should output:
7379

@@ -98,8 +104,13 @@ It will create an empty ldap for the company **Example Inc.** and the domain **e
98104

99105
By default the admin has the password **admin**. All those default settings can be changed at the docker command line, for example:
100106

101-
docker run --env LDAP_ORGANISATION="My Company" --env LDAP_DOMAIN="my-company.com" \
102-
--env LDAP_ADMIN_PASSWORD="JonSn0w" --detach osixia/openldap:1.4.0
107+
```sh
108+
docker run \
109+
--env LDAP_ORGANISATION="My Company" \
110+
--env LDAP_DOMAIN="my-company.com" \
111+
--env LDAP_ADMIN_PASSWORD="JonSn0w" \
112+
--detach osixia/openldap:1.4.0
113+
```
103114

104115
#### Data persistence
105116

@@ -112,18 +123,23 @@ container and in the host, you can use build parameters
112123
`LDAP_OPENLDAP_UID` and `LDAP_OPENLDAP_GID` to set uid and gid
113124
explicitly:
114125

115-
docker build --build-arg LDAP_OPENLDAP_GID=1234 --build-arg LDAP_OPENLDAP_UID=2345 -t my_ldap_image .
116-
docker run --name my_ldap_container -d my_ldap_image
117-
# this should output uid=2345(openldap) gid=1234(openldap) groups=1234(openldap)
118-
docker exec my_ldap_container id openldap
126+
```sh
127+
docker build \
128+
--build-arg LDAP_OPENLDAP_GID=1234 \
129+
--build-arg LDAP_OPENLDAP_UID=2345 \
130+
-t my_ldap_image .
131+
docker run --name my_ldap_container -d my_ldap_image
132+
# this should output uid=2345(openldap) gid=1234(openldap) groups=1234(openldap)
133+
docker exec my_ldap_container id openldap
134+
```
119135

120136
For more information about docker data volume, please refer to:
121137

122138
> [https://docs.docker.com/engine/tutorials/dockervolumes/](https://docs.docker.com/engine/tutorials/dockervolumes/)
123139
124140
#### Firewall issues on RHEL/CentOS
125141
Docker Engine doesn't work well with firewall-cmd and can cause issues if you're connecting to the LDAP server from another container on the same machine. You can fix this by running:
126-
```
142+
```sh
127143
$ firewall-cmd --add-port=389/tcp --permanent
128144
$ firewall-cmd --add-port=636/tcp --permanent
129145
$ firewall-cmd --reload
@@ -154,34 +170,37 @@ Other `{{ * }}` substitutions are left unchanged.
154170
Since startup script modifies `ldif` files, you **must** add `--copy-service`
155171
argument to entrypoint if you don't want to overwrite them.
156172

173+
```sh
174+
# single file example:
175+
docker run \
176+
--volume ./bootstrap.ldif:/container/service/slapd/assets/config/bootstrap/ldif/50-bootstrap.ldif \
177+
osixia/openldap:1.4.0 --copy-service
157178

158-
# single file example:
159-
docker run \
160-
--volume ./bootstrap.ldif:/container/service/slapd/assets/config/bootstrap/ldif/50-bootstrap.ldif \
161-
osixia/openldap:1.4.0 --copy-service
162-
163-
#directory example:
164-
docker run \
165-
--volume ./ldif:/container/service/slapd/assets/config/bootstrap/ldif/custom \
166-
osixia/openldap:1.4.0 --copy-service
179+
# directory example:
180+
docker run \
181+
--volume ./ldif:/container/service/slapd/assets/config/bootstrap/ldif/custom \
182+
osixia/openldap:1.4.0 --copy-service
183+
```
167184

168185
#### Seed from internal path
169186

170187
This image can load ldif and schema files at startup from an internal path. This is useful if a continuous integration service mounts automatically the working copy (sources) into a docker service, which has a relation to the ci job.
171188

172-
For example: Gitlab is not capable of mounting custom paths into docker services of a ci job, but gitlab automatically mounts the working copy in every service container. So the working copy (sources) are accessible under `/builds` in every services
189+
For example: Gitlab is not capable of mounting custom paths into docker services of a ci job, but Gitlab automatically mounts the working copy in every service container. So the working copy (sources) are accessible under `/builds` in every services
173190
of a ci job. The path to the working copy can be obtained via `${CI_PROJECT_DIR}`. See also: https://docs.gitlab.com/runner/executors/docker.html#build-directory-in-service
174191

175-
This may also work with other CI services, if they automatically mount the working directory to the services of a ci job like gitlab ci does.
192+
This may also work with other CI services, if they automatically mount the working directory to the services of a ci job like Gitlab ci does.
176193

177194
In order to seed ldif or schema files from internal path you must set the specific environment variable `LDAP_SEED_INTERNAL_LDIF_PATH` and/or `LDAP_SEED_INTERNAL_SCHEMA_PATH`. If set this will copy any *.ldif or *.schema file into the default seeding
178195
directories of this image.
179196

180197
Example variables defined in gitlab-ci.yml:
181198

199+
```yml
182200
variables:
183201
LDAP_SEED_INTERNAL_LDIF_PATH: "${CI_PROJECT_DIR}/docker/openldap/ldif"
184202
LDAP_SEED_INTERNAL_SCHEMA_PATH: "${CI_PROJECT_DIR}/docker/openldap/schema"
203+
```
185204

186205
### Use an existing ldap database
187206

@@ -190,14 +209,17 @@ Assuming you have a LDAP database on your docker host in the directory `/data/sl
190209
and the corresponding LDAP config files on your docker host in the directory `/data/slapd/config`
191210
simply mount this directories as a volume to `/var/lib/ldap` and `/etc/ldap/slapd.d`:
192211

193-
docker run --volume /data/slapd/database:/var/lib/ldap \
212+
```sh
213+
docker run \
214+
--volume /data/slapd/database:/var/lib/ldap \
194215
--volume /data/slapd/config:/etc/ldap/slapd.d \
195216
--detach osixia/openldap:1.4.0
217+
```
196218

197219
You can also use data volume containers. Please refer to:
198220
> [https://docs.docker.com/engine/tutorials/dockervolumes/](https://docs.docker.com/engine/tutorials/dockervolumes/)
199221
200-
Note: By default this image is waiting an **mdb** database backend, if you want to use any other database backend set backend type via the LDAP_BACKEND environement variable.
222+
Note: By default this image is waiting an **mdb** database backend, if you want to use any other database backend set backend type via the LDAP_BACKEND environment variable.
201223

202224
### Backup
203225
A simple solution to backup your ldap server, is our openldap-backup docker image:
@@ -212,17 +234,23 @@ If you are looking for a simple solution to administrate your ldap server you ca
212234
#### Use auto-generated certificate
213235
By default, TLS is already configured and enabled, certificate is created using container hostname (it can be set by docker run --hostname option eg: ldap.example.org).
214236

215-
docker run --hostname ldap.my-company.com --detach osixia/openldap:1.4.0
237+
```sh
238+
docker run --hostname ldap.my-company.com --detach osixia/openldap:1.4.0
239+
```
216240

217241
#### Use your own certificate
218242

219243
You can set your custom certificate at run time, by mounting a directory containing those files to **/container/service/slapd/assets/certs** and adjust their name with the following environment variables:
220244

221-
docker run --hostname ldap.example.org --volume /path/to/certificates:/container/service/slapd/assets/certs \
245+
```sh
246+
docker run \
247+
--hostname ldap.example.org \
248+
--volume /path/to/certificates:/container/service/slapd/assets/certs \
222249
--env LDAP_TLS_CRT_FILENAME=my-ldap.crt \
223250
--env LDAP_TLS_KEY_FILENAME=my-ldap.key \
224251
--env LDAP_TLS_CA_CRT_FILENAME=the-ca.crt \
225252
--detach osixia/openldap:1.4.0
253+
```
226254

227255
Other solutions are available please refer to the [Advanced User Guide](#advanced-user-guide)
228256

@@ -284,12 +312,15 @@ Available levels are: `none`, `error`, `warning`, `info`, `debug` and `trace`.
284312

285313
Example command to run the container in `debug` mode:
286314

287-
docker run --detach osixia/openldap:1.4.0 --loglevel debug
315+
```sh
316+
docker run --detach osixia/openldap:1.4.0 --loglevel debug
317+
```
288318

289319
See all command line options:
290320

291-
docker run osixia/openldap:1.4.0 --help
292-
321+
```sh
322+
docker run osixia/openldap:1.4.0 --help
323+
```
293324

294325
## Environment Variables
295326
Environment variables defaults are set in **image/environment/default.yaml** and **image/environment/default.startup.yaml**.
@@ -300,7 +331,7 @@ See how to [set your own environment variables](#set-your-own-environment-variab
300331
Variables defined in this file are available at anytime in the container environment.
301332

302333
General container configuration:
303-
- **LDAP_LOG_LEVEL**: Slap log level. defaults to `256`. See table 5.1 in http://www.openldap.org/doc/admin24/slapdconf2.html for the available log levels.
334+
- **LDAP_LOG_LEVEL**: Slap log level. defaults to `256`. See table 5.1 in https://www.openldap.org/doc/admin24/slapdconf2.html for the available log levels.
304335

305336
### Default.startup.yaml
306337
Variables defined in this file are only available during the container **first start** in **startup files**.
@@ -325,7 +356,7 @@ Required and used for new ldap server only:
325356
Backend:
326357
- **LDAP_BACKEND**: Ldap backend. Defaults to `mdb` (previously hdb in image versions up to v1.1.10)
327358

328-
Help: http://www.openldap.org/doc/admin24/backends.html
359+
Help: https://www.openldap.org/doc/admin24/backends.html
329360

330361
TLS options:
331362
- **LDAP_TLS**: Add openldap TLS capabilities. Can't be removed once set to true. Defaults to `true`.
@@ -337,7 +368,7 @@ TLS options:
337368
- **LDAP_TLS_CIPHER_SUITE**: TLS cipher suite. Defaults to `SECURE256:+SECURE128:-VERS-TLS-ALL:+VERS-TLS1.2:-RSA:-DHE-DSS:-CAMELLIA-128-CBC:-CAMELLIA-256-CBC`, based on Red Hat's [TLS hardening guide](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/sec-Hardening_TLS_Configuration.html)
338369
- **LDAP_TLS_VERIFY_CLIENT**: TLS verify client. Defaults to `demand`
339370

340-
Help: http://www.openldap.org/doc/admin24/tls.html
371+
Help: https://www.openldap.org/doc/admin24/tls.html
341372

342373
Replication options:
343374
- **LDAP_REPLICATION**: Add openldap replication capabilities. Defaults to `false`
@@ -356,7 +387,7 @@ Replication options:
356387

357388
docker run --env LDAP_REPLICATION_HOSTS="#PYTHON2BASH:['ldap://ldap.example.org','ldap://ldap2.example.org']" --detach osixia/openldap:1.4.0
358389

359-
To convert yaml to python online: http://yaml-online-parser.appspot.com/
390+
To convert yaml to python online: https://yaml-online-parser.appspot.com/
360391

361392
Other environment variables:
362393
- **KEEP_EXISTING_CONFIG**: Do not change the ldap config. Defaults to `false`
@@ -376,8 +407,13 @@ Other environment variables:
376407
#### Use command line argument
377408
Environment variables can be set by adding the --env argument in the command line, for example:
378409

379-
docker run --env LDAP_ORGANISATION="My company" --env LDAP_DOMAIN="my-company.com" \
380-
--env LDAP_ADMIN_PASSWORD="JonSn0w" --detach osixia/openldap:1.4.0
410+
```sh
411+
docker run \
412+
--env LDAP_ORGANISATION="My company" \
413+
--env LDAP_DOMAIN="my-company.com" \
414+
--env LDAP_ADMIN_PASSWORD="JonSn0w" \
415+
--detach osixia/openldap:1.4.0
416+
```
381417

382418
Be aware that environment variable added in command line will be available at any time
383419
in the container. In this example if someone manage to open a terminal in this container
@@ -387,24 +423,36 @@ he will be able to read the admin password in clear text from environment variab
387423

388424
For example if your environment files **my-env.yaml** and **my-env.startup.yaml** are in /data/ldap/environment
389425

390-
docker run --volume /data/ldap/environment:/container/environment/01-custom \
426+
```sh
427+
docker run \
428+
--volume /data/ldap/environment:/container/environment/01-custom \
391429
--detach osixia/openldap:1.4.0
430+
```
392431

393432
Take care to link your environment files folder to `/container/environment/XX-somedir` (with XX < 99 so they will be processed before default environment files) and not directly to `/container/environment` because this directory contains predefined baseimage environment files to fix container environment (INITRD, LANG, LANGUAGE and LC_CTYPE).
394433

395434
Note: the container will try to delete the **\*.startup.yaml** file after the end of startup files so the file will also be deleted on the docker host. To prevent that : use --volume /data/ldap/environment:/container/environment/01-custom**:ro** or set all variables in **\*.yaml** file and don't use **\*.startup.yaml**:
396435

397-
docker run --volume /data/ldap/environment/my-env.yaml:/container/environment/01-custom/env.yaml \
436+
```sh
437+
docker run \
438+
--volume /data/ldap/environment/my-env.yaml:/container/environment/01-custom/env.yaml \
398439
--detach osixia/openldap:1.4.0
440+
```
399441

400442
#### Docker Secrets
401443

402-
As an alternative to passing sensitive information via environmental variables, _FILE may be appended to the listed variables, causing
444+
As an alternative to passing sensitive information via environmental variables, _FILE may be appended to the listed variables, causing
403445
the startup.sh script to load the values for those values from files presented in the container. This is particular usefull for loading
404446
passwords using the [Docker secrets](https://docs.docker.com/engine/swarm/secrets/) mechanism. For example:
405447

406-
docker run --env LDAP_ORGANISATION="My company" --env LDAP_DOMAIN="my-company.com" \
407-
--env LDAP_ADMIN_PASSWORD_FILE=/run/secrets/authentication_admin_pw --detach osixia/openldap:1.2.4
448+
```sh
449+
docker run \
450+
--env LDAP_ORGANISATION="My company" \
451+
--env LDAP_DOMAIN="my-company.com" \
452+
--env LDAP_ADMIN_PASSWORD_FILE=/run/secrets/ \
453+
authentication_admin_pw \
454+
--detach osixia/openldap:1.2.4
455+
```
408456

409457
Currently this is only supported for LDAP_ADMIN_PASSWORD, LDAP_CONFIG_PASSWORD, LDAP_READONLY_USER_PASSWORD
410458

@@ -420,12 +468,14 @@ If you need to add your custom TLS certificate, bootstrap config or environment
420468

421469
Dockerfile example:
422470

423-
FROM osixia/openldap:1.4.0
424-
MAINTAINER Your Name <your@name.com>
471+
```dockerfile
472+
FROM osixia/openldap:1.4.0
473+
LABEL maintainer="Your Name <your@name.com>"
425474

426-
ADD bootstrap /container/service/slapd/assets/config/bootstrap
427-
ADD certs /container/service/slapd/assets/certs
428-
ADD environment /container/environment/01-custom
475+
ADD bootstrap /container/service/slapd/assets/config/bootstrap
476+
ADD certs /container/service/slapd/assets/certs
477+
ADD environment /container/environment/01-custom
478+
```
429479

430480
See complete example in **example/extend-osixia-openldap**
431481

@@ -436,27 +486,38 @@ Warning: if you want to install new packages from debian repositories, this imag
436486

437487
Clone this project:
438488

439-
git clone https://github.com/osixia/docker-openldap
440-
cd docker-openldap
489+
```sh
490+
git clone https://github.com/osixia/docker-openldap
491+
cd docker-openldap
492+
```
441493

442494
Adapt Makefile, set your image NAME and VERSION, for example:
443495

444-
NAME = osixia/openldap
445-
VERSION = 1.1.9
496+
```makefile
497+
NAME = osixia/openldap
498+
VERSION = 1.1.9
499+
```
500+
501+
become:
446502

447-
become:
448-
NAME = cool-guy/openldap
449-
VERSION = 0.1.0
503+
```makefile
504+
NAME = cool-guy/openldap
505+
VERSION = 0.1.0
506+
```
450507

451508
Add your custom certificate, bootstrap ldif and environment files...
452509

453510
Build your image:
454511

455-
make build
512+
```sh
513+
make build
514+
```
456515

457516
Run your image:
458517

459-
docker run --detach cool-guy/openldap:0.1.0
518+
```sh
519+
docker run --detach cool-guy/openldap:0.1.0
520+
```
460521

461522
### Tests
462523

@@ -466,14 +527,16 @@ We use **Bats** (Bash Automated Testing System) to test this image:
466527
467528
Install Bats, and in this project directory run:
468529

469-
make test
530+
```sh
531+
make test
532+
```
470533

471534
### Kubernetes
472535

473536
Kubernetes is an open source system for managing containerized applications across multiple hosts, providing basic mechanisms for deployment, maintenance, and scaling of applications.
474537

475538
More information:
476-
- http://kubernetes.io
539+
- https://kubernetes.io/
477540
- https://github.com/kubernetes/kubernetes
478541

479542
osixia-openldap kubernetes examples are available in **example/kubernetes**
@@ -496,7 +559,7 @@ If you discover a security vulnerability within this docker image, please send a
496559
Please include as many details as possible.
497560

498561
### Known security issues
499-
Openldap on debian creates two admin users with the same password, if you changed admin password after bootstrap you may be concerned by issue #161.
562+
OpenLDAP on debian creates two admin users with the same password, if you changed admin password after bootstrap you may be concerned by issue #161.
500563

501564
## Changelog
502565

0 commit comments

Comments
 (0)