1# $OpenLDAP$ 2# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Database Creation and Maintenance Tools 6 7This section tells you how to create a slapd database from scratch, 8and how to do trouble shooting if you run into problems. There are 9two ways to create a database. First, you can create the database 10on-line using {{TERM:LDAP}}. With this method, you simply start up slapd 11and add entries using the LDAP client of your choice. This method 12is fine for relatively small databases (a few hundred or thousand 13entries, depending on your requirements). This method works for 14database types which support updates. 15 16The second method of database creation is to do it off-line using 17special utilities provided with {{slapd}}(8). This method is best if you 18have many thousands of entries to create, which would take an 19unacceptably long time using the LDAP method, or if you want to 20ensure the database is not accessed while it is being created. Note 21that not all database types support these utilities. 22 23 24H2: Creating a database over LDAP 25 26With this method, you use the LDAP client of your choice (e.g., 27the {{ldapadd}}(1)) to add entries, just like you would once the 28database is created. You should be sure to set the following 29options in the configuration file before starting {{slapd}}(8). 30 31> suffix <dn> 32 33As described in the {{SECT:General Database Directives}} section, 34this option defines which entries are to be held by this database. 35You should set this to the DN of the root of the subtree you are 36trying to create. For example: 37 38> suffix "dc=example,dc=com" 39 40You should be sure to specify a directory where the index files 41should be created: 42 43> directory <directory> 44 45For example: 46 47> directory /usr/local/var/openldap-data 48 49You need to create this directory with appropriate permissions such 50that slapd can write to it. 51 52You need to configure slapd so that you can connect to it as a 53directory user with permission to add entries. You can configure 54the directory to support a special {{super-user}} or {{root}} user 55just for this purpose. This is done through the following two 56options in the database definition: 57 58> rootdn <dn> 59> rootpw <passwd> 60 61For example: 62 63> rootdn "cn=Manager,dc=example,dc=com" 64> rootpw secret 65 66These options specify a DN and password that can be used to 67authenticate as the {{super-user}} entry of the database (i.e., 68the entry allowed to do anything). The DN and password specified 69here will always work, regardless of whether the entry named actually 70exists or has the password given. This solves the chicken-and-egg 71problem of how to authenticate and add entries before any entries 72yet exist. 73 74Finally, you should make sure that the database definition contains 75the index definitions you want: 76 77> index {<attrlist> | default} [pres,eq,approx,sub,none] 78 79For example, to index the {{EX:cn}}, {{EX:sn}}, {{EX:uid}} and 80{{EX:objectclass}} attributes, the following {{EX:index}} directives 81could be used: 82 83> index cn,sn,uid pres,eq,approx,sub 84> index objectClass eq 85 86This would create presence, equality, approximate, and substring 87indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and 88an equality index for the {{EX:objectClass}} attribute. Note that 89not all index types are available with all attribute types. See 90{{SECT:The slapd Configuration File}} section for more information 91on this option. 92 93Once you have configured things to your liking, start up slapd, 94connect with your LDAP client, and start adding entries. For 95example, to add an organization entry and an organizational role 96entry using the {{I:ldapadd}} tool, you could create an {{TERM:LDIF}} 97file called {{EX:entries.ldif}} with the contents: 98 99> # Organization for Example Corporation 100> dn: dc=example,dc=com 101> objectClass: dcObject 102> objectClass: organization 103> dc: example 104> o: Example Corporation 105> description: The Example Corporation 106> 107> # Organizational Role for Directory Manager 108> dn: cn=Manager,dc=example,dc=com 109> objectClass: organizationalRole 110> cn: Manager 111> description: Directory Manager 112 113and then use a command like this to actually create the entry: 114 115> ldapadd -f entries.ldif -x -D "cn=Manager,dc=example,dc=com" -w secret 116 117The above command assumes settings provided in the above examples. 118 119 120H2: Creating a database off-line 121 122The second method of database creation is to do it off-line, using 123the slapd database tools described below. This method is best if 124you have many thousands of entries to create, which would take an 125unacceptably long time to add using the LDAP method described above. 126These tools read the slapd configuration file and an input file 127containing a text representation of the entries to add. For database 128types which support the tools, they produce the database files 129directly (otherwise you must use the on-line method above). Also, 130the input file must be completely valid, as these tools do fewer 131consistency checks than the on-line method. 132 133Note: this Guide is not meant to provide exhaustive documentation 134on the software. The tool descriptions here only list a few of the 135available options for each command. Read the associated manpages for 136complete documentation on all of the available options. 137 138There are several important configuration options you will want to be 139sure and set in the config file database definition first: 140 141> suffix <dn> 142 143As described in the {{SECT:General Database Directives}} section, 144this option defines which entries are to be held by this database. 145You should set this to the DN of the root of the subtree you are 146trying to create. For example: 147 148> suffix "dc=example,dc=com" 149 150You should be sure to specify a directory where the index files 151should be created: 152 153> directory <directory> 154 155For example: 156 157> directory /usr/local/var/openldap-data 158 159Finally, you need to specify which indices you want to build. This 160is done by one or more index options. 161 162> index {<attrlist> | default} [pres,eq,approx,sub,none] 163 164For example: 165 166> index cn,sn,uid pres,eq,approx,sub 167> index objectClass eq 168 169This would create presence, equality, approximate, and substring 170indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and 171an equality index for the {{EX:objectClass}} attribute. Note that 172not all index types are available with all attribute types. See 173{{SECT:The slapd Configuration File}} section for more information 174on this option. 175 176H3: The {{EX:slapadd}} program 177 178Once you've configured things to your liking, you create the primary 179database and associated indices by running the {{slapadd}}(8) 180program: 181 182> slapadd -l <inputfile> -f <slapdconfigfile> 183> [-d <debuglevel>] [-n <integer>|-b <suffix>] 184 185The arguments have the following meanings: 186 187> -l <inputfile> 188 189Specifies the {{TERM:LDIF}} input file containing the entries to 190add in text form (described below in the {{SECT:The LDIF text entry 191format}} section). 192 193> -f <slapdconfigfile> 194 195Specifies the slapd configuration file that tells where to create 196the indices, what indices to create, etc. 197 198> -F <slapdconfdirectory> 199 200Specifies a config directory. If both {{EX:-f}} and {{EX:-F}} are specified, 201the config file will be read and converted to config directory format and 202written to the specified directory. If neither option is specified, an attempt 203to read the default config directory will be made before trying to use the 204default config file. If a valid config directory exists then the default 205config file is ignored. If dryrun mode is also specified, no conversion will occur. 206 207> -d <debuglevel> 208 209Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug 210levels are the same as for slapd. See the {{SECT:Command-Line 211Options}} section in {{SECT:Running slapd}}. 212 213> -n <databasenumber> 214 215An optional argument that specifies which database to modify. The 216first database listed in the configuration file is {{EX:1}}, the 217second {{EX:2}}, etc. By default, the first database in the 218configuration file is used. Should not be used in conjunction with 219{{EX:-b}}. 220 221> -b <suffix> 222 223An optional argument that specifies which database to modify. The 224provided suffix is matched against a database {{EX:suffix}} directive 225to determine the database number. Should not be used in conjunction 226with {{EX:-n}}. 227 228 229H3: The {{EX:slapindex}} program 230 231Sometimes it may be necessary to regenerate indices (such as after 232modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8) 233program. {{slapindex}} is invoked like this 234 235> slapindex -f <slapdconfigfile> 236> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>] [attr...] 237 238Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options 239are the same as for the {{slapadd}}(1) program. If no specific 240attributes are listed, {{slapindex}} rebuilds all indices based 241upon the current database contents. 242 243 244H3: The {{EX:slapcat}} program 245 246The {{EX:slapcat}} program is used to dump the database to an 247{{TERM:LDIF}} file. This can be useful when you want to make a 248human-readable backup of your database or when you want to edit 249your database off-line. The program is invoked like this: 250 251> slapcat -l <filename> -f <slapdconfigfile> 252> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>] 253 254where {{EX:-n}} or {{EX:-b}} is used to select the database in the 255{{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding 256{{TERM:LDIF}} output is written to standard output or to the file 257specified using the {{EX:-l}} option. 258 259 260!if 0 261H3: The {{EX:ldif}} program 262 263The {{ldif}}(1) program is used to convert arbitrary data values 264to {{TERM:LDIF}} format. This can be useful when writing a program 265or script to create the LDIF file you will feed into the {{slapadd}}(8) 266or {{ldapadd}}(1) program, or when writing a SHELL backend. 267{{ldif}}(1) takes an attribute description as an argument and reads 268the attribute value(s) from standard input. It produces the LDIF 269formatted attribute line(s) on standard output. The usage is: 270 271> ldif [-b] <attrdesc> 272 273where {{EX:<attrdesc>}} is an attribute description. Without the 274{{EX-b}} option, the {{ldif}} program will consider each line of 275standard input to be a separate value of the attribute. 276 277> ldif description << EOF 278> leading space 279> # leading hash mark 280> EOF 281 282The {{EX:-b}} option can be used to force the {{ldif}} program to 283interpret its input as a single raw binary value. This option is 284useful when converting binary data such as a {{EX:jpegPhoto}} or 285{{EX:audio}} attribute. For example: 286 287> ldif -b jpegPhoto < photo.jpeg 288!endif 289 290 291H2: The LDIF text entry format 292 293The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries 294in a simple text format. This section provides a brief description 295of the LDIF entry format which complements {{ldif}}(5) and the 296technical specification {{REF:RFC2849}}. 297 298The basic form of an entry is: 299 300> # comment 301> dn: <distinguished name> 302> <attrdesc>: <attrvalue> 303> <attrdesc>: <attrvalue> 304> 305> ... 306 307Lines starting with a '{{EX:#}}' character are comments. An 308attribute description may be a simple attribute type like {{EX:cn}} 309or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated 310with an attribute type) or may include options such as {{EX:cn;lang_en_US}} 311or {{EX:userCertificate;binary}}. 312 313A line may be continued by starting the next line with a {{single}} 314space or tab character. For example: 315 316> dn: cn=Barbara J Jensen,dc=example,dc= 317> com 318> cn: Barbara J 319> Jensen 320 321is equivalent to: 322 323> dn: cn=Barbara J Jensen,dc=example,dc=com 324> cn: Barbara J Jensen 325 326Multiple attribute values are specified on separate lines. e.g., 327 328> cn: Barbara J Jensen 329> cn: Babs Jensen 330 331If an {{EX:<attrvalue>}} contains non-printing characters or begins 332with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'), 333the {{EX:<attrdesc>}} is followed by a double colon and the base64 334encoding of the value. For example, the value "{{EX: begins with 335a space}}" would be encoded like this: 336 337> cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U= 338 339You can also specify a {{TERM:URL}} containing the attribute value. 340For example, the following specifies the {{EX:jpegPhoto}} value 341should be obtained from the file {{F:/path/to/file.jpeg}}. 342 343> jpegPhoto:< file:///path/to/file.jpeg 344 345Multiple entries within the same LDIF file are separated by blank 346lines. Here's an example of an LDIF file containing three entries. 347 348> # Barbara's Entry 349> dn: cn=Barbara J Jensen,dc=example,dc=com 350> cn: Barbara J Jensen 351> cn: Babs Jensen 352> objectClass: person 353> sn: Jensen 354> 355> # Bjorn's Entry 356> dn: cn=Bjorn J Jensen,dc=example,dc=com 357> cn: Bjorn J Jensen 358> cn: Bjorn Jensen 359> objectClass: person 360> sn: Jensen 361> # Base64 encoded JPEG photo 362> jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD 363> A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ 364> ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG 365> 366> # Jennifer's Entry 367> dn: cn=Jennifer J Jensen,dc=example,dc=com 368> cn: Jennifer J Jensen 369> cn: Jennifer Jensen 370> objectClass: person 371> sn: Jensen 372> # JPEG photo from file 373> jpegPhoto:< file:///path/to/file.jpeg 374 375Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded 376and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the 377location indicated by the URL. 378 379Note: Trailing spaces are not trimmed from values in an LDIF file. 380Nor are multiple internal spaces compressed. If you don't want them 381in your data, don't put them there. 382 383
