1# OpenLDAP: pkg/openldap-guide/admin/dbtools.sdf,v 1.24.2.7 2009/01/22 00:00:47 kurt Exp 2# Copyright 1999-2009 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). There 130are several important configuration options you will want to be 131sure and set in the config file database definition first: 132 133> suffix <dn> 134 135As described in the {{SECT:General Database Directives}} section, 136this option defines which entries are to be held by this database. 137You should set this to the DN of the root of the subtree you are 138trying to create. For example: 139 140> suffix "dc=example,dc=com" 141 142You should be sure to specify a directory where the index files 143should be created: 144 145> directory <directory> 146 147For example: 148 149> directory /usr/local/var/openldap-data 150 151Finally, you need to specify which indices you want to build. This 152is done by one or more index options. 153 154> index {<attrlist> | default} [pres,eq,approx,sub,none] 155 156For example: 157 158> index cn,sn,uid pres,eq,approx,sub 159> index objectClass eq 160 161This would create presence, equality, approximate, and substring 162indices for the {{EX:cn}}, {{EX:sn}}, and {{EX:uid}} attributes and 163an equality index for the {{EX:objectClass}} attribute. Note that 164not all index types are available with all attribute types. See 165{{SECT:The slapd Configuration File}} section for more information 166on this option. 167 168H3: The {{EX:slapadd}} program 169 170Once you've configured things to your liking, you create the primary 171database and associated indices by running the {{slapadd}}(8) 172program: 173 174> slapadd -l <inputfile> -f <slapdconfigfile> 175> [-d <debuglevel>] [-n <integer>|-b <suffix>] 176 177The arguments have the following meanings: 178 179> -l <inputfile> 180 181Specifies the {{TERM:LDIF}} input file containing the entries to 182add in text form (described below in the {{SECT:The LDIF text entry 183format}} section). 184 185> -f <slapdconfigfile> 186 187Specifies the slapd configuration file that tells where to create 188the indices, what indices to create, etc. 189 190> -F <slapdconfdirectory> 191 192Specifies a config directory. If both {{EX:-f}} and {{EX:-F}} are specified, 193the config file will be read and converted to config directory format and 194written to the specified directory. If neither option is specified, an attempt 195to read the default config directory will be made before trying to use the 196default config file. If a valid config directory exists then the default 197config file is ignored. If dryrun mode is also specified, no conversion will occur. 198 199> -d <debuglevel> 200 201Turn on debugging, as specified by {{EX:<debuglevel>}}. The debug 202levels are the same as for slapd. See the {{SECT:Command-Line 203Options}} section in {{SECT:Running slapd}}. 204 205> -n <databasenumber> 206 207An optional argument that specifies which database to modify. The 208first database listed in the configuration file is {{EX:1}}, the 209second {{EX:2}}, etc. By default, the first database in the 210configuration file is used. Should not be used in conjunction with 211{{EX:-b}}. 212 213> -b <suffix> 214 215An optional argument that specifies which database to modify. The 216provided suffix is matched against a database {{EX:suffix}} directive 217to determine the database number. Should not be used in conjunction 218with {{EX:-n}}. 219 220 221H3: The {{EX:slapindex}} program 222 223Sometimes it may be necessary to regenerate indices (such as after 224modifying {{slapd.conf}}(5)). This is possible using the {{slapindex}}(8) 225program. {{slapindex}} is invoked like this 226 227> slapindex -f <slapdconfigfile> 228> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>] 229 230Where the {{EX:-f}}, {{EX:-d}}, {{EX:-n}} and {{EX:-b}} options 231are the same as for the {{slapadd}}(1) program. {{slapindex}} 232rebuilds all indices based upon the current database contents. 233 234 235H3: The {{EX:slapcat}} program 236 237The {{EX:slapcat}} program is used to dump the database to an 238{{TERM:LDIF}} file. This can be useful when you want to make a 239human-readable backup of your database or when you want to edit 240your database off-line. The program is invoked like this: 241 242> slapcat -l <filename> -f <slapdconfigfile> 243> [-d <debuglevel>] [-n <databasenumber>|-b <suffix>] 244 245where {{EX:-n}} or {{EX:-b}} is used to select the database in the 246{{slapd.conf}}(5) specified using {{EX:-f}}. The corresponding 247{{TERM:LDIF}} output is written to standard output or to the file 248specified using the {{EX:-l}} option. 249 250 251!if 0 252H3: The {{EX:ldif}} program 253 254The {{ldif}}(1) program is used to convert arbitrary data values 255to {{TERM:LDIF}} format. This can be useful when writing a program 256or script to create the LDIF file you will feed into the {{slapadd}}(8) 257or {{ldapadd}}(1) program, or when writing a SHELL backend. 258{{ldif}}(1) takes an attribute description as an argument and reads 259the attribute value(s) from standard input. It produces the LDIF 260formatted attribute line(s) on standard output. The usage is: 261 262> ldif [-b] <attrdesc> 263 264where {{EX:<attrdesc>}} is an attribute description. Without the 265{{EX-b}} option, the {{ldif}} program will consider each line of 266standard input to be a separate value of the attribute. 267 268> ldif description << EOF 269> leading space 270> # leading hash mark 271> EOF 272 273The {{EX:-b}} option can be used to force the {{ldif}} program to 274interpret its input as a single raw binary value. This option is 275useful when converting binary data such as a {{EX:jpegPhoto}} or 276{{EX:audio}} attribute. For example: 277 278> ldif -b jpegPhoto < photo.jpeg 279!endif 280 281 282H2: The LDIF text entry format 283 284The {{TERM[expand]LDIF}} (LDIF) is used to represent LDAP entries 285in a simple text format. This section provides a brief description 286of the LDIF entry format which complements {{ldif}}(5) and the 287technical specification {{REF:RFC2849}}. 288 289The basic form of an entry is: 290 291> # comment 292> dn: <distinguished name> 293> <attrdesc>: <attrvalue> 294> <attrdesc>: <attrvalue> 295> 296> ... 297 298Lines starting with a '{{EX:#}}' character are comments. An 299attribute description may be a simple attribute type like {{EX:cn}} 300or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated 301with an attribute type) or may include options such as {{EX:cn;lang_en_US}} 302or {{EX:userCertificate;binary}}. 303 304A line may be continued by starting the next line with a {{single}} 305space or tab character. For example: 306 307> dn: cn=Barbara J Jensen,dc=example,dc= 308> com 309> cn: Barbara J 310> Jensen 311 312is equivalent to: 313 314> dn: cn=Barbara J Jensen,dc=example,dc=com 315> cn: Barbara J Jensen 316 317Multiple attribute values are specified on separate lines. e.g., 318 319> cn: Barbara J Jensen 320> cn: Babs Jensen 321 322If an {{EX:<attrvalue>}} contains non-printing characters or begins 323with a space, a colon ('{{EX::}}'), or a less than ('{{EX:<}}'), 324the {{EX:<attrdesc>}} is followed by a double colon and the base64 325encoding of the value. For example, the value "{{EX: begins with 326a space}}" would be encoded like this: 327 328> cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U= 329 330You can also specify a {{TERM:URL}} containing the attribute value. 331For example, the following specifies the {{EX:jpegPhoto}} value 332should be obtained from the file {{F:/path/to/file.jpeg}}. 333 334> cn:< file:///path/to/file.jpeg 335 336Multiple entries within the same LDIF file are separated by blank 337lines. Here's an example of an LDIF file containing three entries. 338 339> # Barbara's Entry 340> dn: cn=Barbara J Jensen,dc=example,dc=com 341> cn: Barbara J Jensen 342> cn: Babs Jensen 343> objectClass: person 344> sn: Jensen 345> 346> # Bjorn's Entry 347> dn: cn=Bjorn J Jensen,dc=example,dc=com 348> cn: Bjorn J Jensen 349> cn: Bjorn Jensen 350> objectClass: person 351> sn: Jensen 352> # Base64 encoded JPEG photo 353> jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD 354> A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ 355> ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG 356> 357> # Jennifer's Entry 358> dn: cn=Jennifer J Jensen,dc=example,dc=com 359> cn: Jennifer J Jensen 360> cn: Jennifer Jensen 361> objectClass: person 362> sn: Jensen 363> # JPEG photo from file 364> jpegPhoto:< file:///path/to/file.jpeg 365 366Notice that the {{EX:jpegPhoto}} in Bjorn's entry is base 64 encoded 367and the {{EX:jpegPhoto}} in Jennifer's entry is obtained from the 368location indicated by the URL. 369 370Note: Trailing spaces are not trimmed from values in an LDIF file. 371Nor are multiple internal spaces compressed. If you don't want them 372in your data, don't put them there. 373 374
