1.\" $OpenBSD: ldapd.conf.5,v 1.28 2023/03/02 17:09:53 jmc Exp $ 2.\" 3.\" Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se> 4.\" Copyright (c) 2008 Janne Johansson <jj@openbsd.org> 5.\" Copyright (c) 2009 Jacek Masiulaniec <jacekm@dobremiasto.net> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.\" 20.Dd $Mdocdate: March 2 2023 $ 21.Dt LDAPD.CONF 5 22.Os 23.Sh NAME 24.Nm ldapd.conf 25.Nd LDAP daemon configuration file 26.Sh DESCRIPTION 27.Nm 28is the configuration file for the LDAP daemon 29.Xr ldapd 8 . 30.Pp 31The current line can be extended over multiple lines using a backslash 32.Pq Sq \e . 33Comments can be put anywhere in the file using a hash mark 34.Pq Sq # , 35and extend to the end of the current line. 36Care should be taken when commenting out multi-line text: 37the comment is effective until the end of the entire block. 38.Pp 39Argument names not beginning with a letter, digit, or underscore 40must be quoted. 41Arguments containing whitespace should be surrounded by double quotes 42.Pq \&" . 43.Pp 44Macros can be defined that will later be expanded in context. 45Macro names must start with a letter, digit, or underscore, 46and may contain any of those characters. 47Macro names may not be reserved words (for example 48.Ar listen , 49.Ar namespace , 50.Ar port ) . 51Macros are not expanded inside quotes. 52.Pp 53For example: 54.Bd -literal -offset indent 55wan_if = "fxp0" 56listen on $wan_if 57listen on $wan_if tls 58.Ed 59.Pp 60Additional configuration files can be included with the 61.Ic include 62keyword, for example: 63.Bd -literal -offset indent 64include "/etc/ldap/sub.namespace.conf" 65.Ed 66.Pp 67Additional schema files can be included with the 68.Ic schema 69keyword, for example: 70.Bd -literal -offset indent 71schema "/etc/ldap/inetorgperson.schema" 72.Ed 73.Pp 74The syntax of 75.Nm 76is described below. 77.Sh GLOBAL CONFIGURATION 78.Bl -tag -width Ds 79.It Xo 80.Ic listen on Ar interface 81.Op Ic port Ar port 82.Op Ic legacy 83.Op Ic tls | ldaps | secure 84.Op Ic certificate Ar name 85.Xc 86Specify an 87.Ar interface 88and 89.Ar port 90to listen on. 91An IP address, domain name or absolute path may be used in place of 92.Ar interface . 93An absolute path is used to listen on a unix domain socket. 94.Pp 95Secured connections are provided either using STARTTLS 96.Pq Ic tls , 97by default on port 389, 98or LDAPS 99.Pq Ic ldaps , 100by default on port 636. 101.Ic tls 102and 103.Ic ldaps 104connections will use the defaults from libtls. 105If compatibility with the insecure TLSv1.0 and TLSv1.1 106protocols and ciphers is required, 107they can be enabled with the 108.Ic legacy 109keyword. 110Creation of certificates is documented in 111.Xr starttls 8 . 112If no certificate 113.Ar name 114is specified, the 115.Pa /etc/ldap/certs 116directory is searched for a file named by joining 117the interface name with a .crt extension, e.g.\& 118.Pa /etc/ldap/certs/fxp0.crt . 119.Pp 120If the certificate name is an absolute path, a .crt and .key extension 121are appended to form the certificate path and key path respectively. 122.Pp 123Only secured connections accept plain text password authentication. 124Connections using TLS or unix domain sockets are always considered secured. 125The 126.Ic secure 127keyword can be used to mark an otherwise insecure connection 128secured, e.g. if IPsec is used. 129.It referral Ar URL 130Specify a default referral. 131If no namespace matches the base DN in a request, the request is 132delegated to another LDAP server instead of returning an error. 133.Pp 134This option can be given multiple times, in which case the URLs are 135considered equal. 136Clients may choose to follow any of the referral URLs. 137.Pp 138The URL has the following format: 139.Bd -literal -offset indent 140ldap://ldap.example.com 141ldaps://ldap.example.com:3890 142.Ed 143.It rootdn Ar dn 144Specify the distinguished name of the root user for all namespaces. 145The root user is always allowed to read and write entries in all 146local namespaces. 147.It rootpw Ar password 148Password for the root user. 149Specified either in plain text, or in hashed format. 150See AUTHENTICATION in 151.Xr ldapd 8 . 152.It schema Ar filename 153Add schema definitions from the specified file. 154For a description of the schema file syntax see 155.Sx SCHEMA 156below. 157.El 158.Sh NAMESPACES 159A namespace is a subtree of the global X.500 DIT (Directory Information Tree), 160also known as a naming context. 161All entries' distinguished names (DN) have the same suffix, which is used to 162identify the namespace. 163The suffix should consist of the domain components, in reverse order, of your 164domain name, as recommended by RFC 2247. 165.Bd -literal -offset indent 166namespace "dc=example,dc=com" { 167 rootdn "cn=admin,dc=example,dc=com" 168 rootpw "secret" 169} 170.Ed 171.Pp 172When matching requests against namespace suffixes, the most specific 173match is used. 174Each namespace stores data in a separate database file. 175.Pp 176A namespace has the following configuration properties: 177.Bl -tag -width Ds 178.It referral Ar URL 179Specify a referral to return for requests matching the suffix. 180.It rootdn Ar dn 181Specify the distinguished name of the root user for the namespace. 182The root user is always allowed to read and write entries in the namespace. 183The distinguished name must have the same suffix as the namespace. 184.It rootpw Ar password 185Password for the root user. 186Specified either in plain text, or in hashed format. 187See AUTHENTICATION in 188.Xr ldapd 8 . 189.It index Ar attribute 190Maintain an index on the specified attribute. 191This index can be used for equality, presence, prefix substring and range searches. 192.Xr ldapd 8 193will update the index on each modification. 194If you add an index to an existing namespace, you need to run 195.Xr ldapctl 8 196to index the existing entries. 197.It fsync Ar on | off 198If 199.Ar off , 200data will not be forced to disk after each commit. 201Disabling fsync can increase write speed substantially, but may lead to data 202loss. 203The default value is on. 204.It cache-size Ar size 205Set the cache size for data entries. 206The 207.Ar size 208is specified in number of pages. 209Note that more than the configured number of pages may exist in the cache, as 210dirty pages and pages referenced by cursors are excluded from cache expiration. 211.Pp 212Cached pages are expired in a least recently used (LRU) order. 213.It index-cache-size Ar size 214Set the cache size for the index database. 215.It relax schema 216Disables checking of required and optional object attributes against schema. 217All attributes and values are matched as case-insensitive strings. 218All attributes are considered multi-valued. 219.It strict schema 220Enables checking of required and optional object attributes against schema. 221This is the default. 222.It Ic allow | deny 223Allow or deny access to parts of the namespace. 224.Pp 225Each request to the 226.Xr ldapd 8 227daemon evaluates the filter rules in sequential order, from first to last. 228The last matching rule decides what action is taken. 229If no rule matches the request, the default action is to allow the request. 230The root DN is always allowed to perform any request. 231.Pp 232The allow/deny statement operates on all access types by default. 233This can be restricted by an access type specification: 234.Bl -tag -width Ds 235.It read access 236Restricts the filter rule to search operations. 237.It write access 238Restricts the filter rule to add, delete and modify operations. 239.It bind access 240Restricts the filter rule to bind operations. 241.El 242.Pp 243The scope of the filter rule can be restricted by the 244.Em to 245keyword: 246.Bl -tag -width Ds 247.It to subtree Ar DN 248The filter rule applies to the distinguished name, 249as well as for all its descendants. 250.It to children of Ar DN 251The filter rule applies to all the direct children of the distinguished name. 252.It to Ar DN 253The filter rule applies to the distinguished name only. 254.It to any 255The filter rule applies to any distinguished name in the namespace. 256This is the default if no scope is specified. 257.It to root 258The filter rule applies to the root DSE. 259.El 260.Pp 261The scope can be restricted to an optional attribute: 262.Bl -tag -width Ds 263.It attribute Ar name 264The filter rule applies to the specified attribute. 265.El 266.Pp 267Finally, the filter rule can match a bind DN: 268.Bl -tag -width Ds 269.It by any 270The filter rule matches by any bind dn, including anonymous binds. 271.It by Ar DN 272The filter rule matches only if the requestor has previously performed 273a bind as the specified distinguished name. 274.It by self 275The filter rule matches only if the requestor has previously performed 276a bind as the distinguished name that is being requested. 277Typically used to allow users to modify their own data. 278.El 279.It use compression Op level Ar level 280Enable compression of entries and optionally specify compression level (0 - 9). 281By default, no compression is used. 282.El 283.Sh SCHEMA 284Schema files define the structure and format of entries in the directory tree. 285There are three types of definitions in a schema file: 286.Bl -tag -width Ds 287.It attributetype 288.Po 289.Ar oid 290.Op NAME name 291.Op DESC description 292.Op OBSOLETE 293.Op SUP oid 294.Op EQUALITY oid 295.Op ORDERING oid 296.Op SUBSTR oid 297.Op SYNTAX oid 298.Op SINGLE-VALUE 299.Op COLLECTIVE 300.Op NO-USER-MODIFICATION 301.Op USAGE Brq userApplications | directoryOperation | distributedOperation | dSAOperation 302.Pc 303.Pp 304An attribute type definition specifies the syntax of attribute values, whether 305it allows multiple values and how it can be compared in search requests. 306For a complete description of attribute type definitions, see section 3074.1.2 in RFC 4512. 308.It objectclass 309.Po 310.Ar oid 311.Op NAME name 312.Op DESC description 313.Op OBSOLETE 314.Op SUP oids 315.Op Brq ABSTRACT | STRUCTURAL | AUXILIARY 316.Op MUST oids 317.Op MAY oids 318.Pc 319.Pp 320An object class definition specifies which attributes are required 321and which are allowed. 322For a complete description of object class definitions, see section 3234.1.1 in RFC 4512. 324.It objectidentifier Ar symbolic-name Ar OID 325Defines a symbolic name for the object identifier. 326A symbolic name can be used in place of a numeric OID in definitions 327of attribute types, object classes and other symbolic OIDs. 328A descendant OID can be defined in terms of another symbolic OID by appending 329a numeric OID after a colon, for example: 330.Bd -literal -offset indent 331objectidentifier MyOidRoot 1.2.3.4 332objectidentifier MyOidAttributes MyOidRoot:5.6 333objectidentifier MyOidObjects MyOidRoot:7 334.Ed 335.Pp 336This would define MyOidAttributes as a symbolic name for the OID 3371.2.3.4.5.6, and MyOidObjects for 1.2.3.4.7. 338.El 339.Sh FILES 340.Bl -tag -width /etc/examples/ldapd.conf -compact 341.It Pa /etc/ldapd.conf 342Default 343.Xr ldapd 8 344configuration file. 345.It Pa /etc/examples/ldapd.conf 346Example configuration file. 347.It Pa /etc/ldap/*.schema 348Default schema definition files. 349.It Pa /etc/ldap/certs/ 350Default directory for TLS certificates. 351.El 352.Sh SEE ALSO 353.Xr ldapctl 8 , 354.Xr ldapd 8 355.Sh STANDARDS 356.Rs 357.%A K. Zeilenga 358.%D June 2006 359.%R RFC 4512 360.%T Lightweight Directory Access Protocol (LDAP): Directory Information Models 361.Re 362.Sh HISTORY 363The 364.Nm 365file format first appeared in 366.Ox 4.8 . 367