From 2c95a6fec528359e9db998f0ecdec7413bd7220b Mon Sep 17 00:00:00 2001 From: Will Ballantyne Date: Fri, 23 Apr 1999 23:00:44 +0000 Subject: [PATCH] openldap guide sdf files and gifs --- doc/guide/LDAPwww.gif | Bin 0 -> 2541 bytes doc/guide/config.sdf | 76 +++ doc/guide/dbtools.sdf | 702 +++++++++++++++++++++++++++ doc/guide/figure_1.gif | Bin 0 -> 3086 bytes doc/guide/figure_2.gif | Bin 0 -> 1424 bytes doc/guide/figure_3.gif | Bin 0 -> 2395 bytes doc/guide/figure_4.gif | Bin 0 -> 1667 bytes doc/guide/figure_5.gif | Bin 0 -> 3298 bytes doc/guide/figure_6.gif | Bin 0 -> 3538 bytes doc/guide/install.sdf | 268 +++++++++++ doc/guide/intro.sdf | 227 +++++++++ doc/guide/master.sdf | 20 + doc/guide/monitoringslapd.sdf | 112 +++++ doc/guide/preamble.sdf | 11 + doc/guide/quickstart.sdf | 123 +++++ doc/guide/referrals.sdf | 41 ++ doc/guide/replication.sdf | 407 ++++++++++++++++ doc/guide/runningslapd.sdf | 123 +++++ doc/guide/slapdconfig.sdf | 862 ++++++++++++++++++++++++++++++++++ doc/guide/tuning.sdf | 86 ++++ 20 files changed, 3058 insertions(+) create mode 100644 doc/guide/LDAPwww.gif create mode 100644 doc/guide/config.sdf create mode 100644 doc/guide/dbtools.sdf create mode 100644 doc/guide/figure_1.gif create mode 100644 doc/guide/figure_2.gif create mode 100644 doc/guide/figure_3.gif create mode 100644 doc/guide/figure_4.gif create mode 100644 doc/guide/figure_5.gif create mode 100644 doc/guide/figure_6.gif create mode 100644 doc/guide/install.sdf create mode 100644 doc/guide/intro.sdf create mode 100644 doc/guide/master.sdf create mode 100644 doc/guide/monitoringslapd.sdf create mode 100644 doc/guide/preamble.sdf create mode 100644 doc/guide/quickstart.sdf create mode 100644 doc/guide/referrals.sdf create mode 100644 doc/guide/replication.sdf create mode 100644 doc/guide/runningslapd.sdf create mode 100644 doc/guide/slapdconfig.sdf create mode 100644 doc/guide/tuning.sdf diff --git a/doc/guide/LDAPwww.gif b/doc/guide/LDAPwww.gif new file mode 100644 index 0000000000000000000000000000000000000000..b593bc983e33da5fc43bcf60d5c098ecca348ef1 GIT binary patch literal 2541 zcmbu)`9IT-1Hke3#+dnFj=5vYku!x)`0%OCCPQf|G|l;$`XEQH5ZX{55|N|ksO4(T zobY2>gE;{Kx-$0iXwfGgK8{OYcgA%IcBWwa?%D1=p}Iz`rW$O;t4U zpJKl%W<5k=@2lF?mGoulT&f`T)s+rBKJiC?fn9ysP`-KC=c&H>7o2D4MA#Ag2F6G+ zK1JS$Y8H~5t-S~pE>6)lfVd(HD7n0e2!Q!e; z^VOua7Rcus^Vo1OOV;v$d}_b8&4&-pG}GZf$86oNo0n&#@^RD_P@UA2W9Au*G|Fp^ z86_*xas_uFMz)5^>qNQ*NZdeDVBgM%tCRdsUdE6RlR3zQ*k4CM;P}iH0<2ic)gu}9 zE8F$YH4LL$M9!@NLsB}`fFhY*+eP8ds3lQ7lYY+zdCIpWyNaOe7{eK{)E6`8Bi3@B zL;y<-|UbyXyVD1=9kKsUM& z=x6^pYj))V@JT|3Zaf3!VTPcAah3rkA?K3VUWlaN45&NYB+7kM39 zGjhuH`60AW4^FP%i*|j|y@qhgi!E;%hQ#)kgKI--K5Aoi7Al-bwWq@qszeLz^#d)A zlM5?-y%h`#!(PWQt68Bh46ydfUetUiJ+^CUT6%tdn|vHFktDb7H!k|BJ4dhS-{WMX zrfYsz38V?1w$E+z2{b;o?|3ZyWwuOsImpHzW`xOi#8nWpolFgZB4te?ATw-c-35fx zhC6+a)P5GxsWhk~AD7BL77z0+*y0OSVIg9p$SUA*11{M`WhDK|aw-o) zc)VnaQJK)@qd8p&0W&ntp|LR6(7ox6BqESfd!4sb36uEZe{xbpX?e}|2YC1!?m!^W zjR+j_`8_x;QGc|Nc;`j?E++a`Y{t7l6|{7ZNNirlbW}AlgA)aksF}hje35RD%XG|G zL!D!mVvHPtOsACk-z^vfnOs=b=0 z2+d)o9`e{Yjdb`TH$N?81G2r{gudx;+U#GEn;sVUAgS}akb^~oT|UA zIo*dXyNCKSdxN(!9OrvO*LbNZuaBXn861GNfd8Q^=-AiNyq#jqW~mvsiNQ*ur^J!p zC!MW?=6$I`C+EJOwq+iYnMu)@`Lk9n88DAv)IRSKMj%qlz9I$49sD!9>t>z__qjn@ z;u1aHn&GzCA@{7SF3E{nV@J1#ozMJI1bHLML|xPj$}>sk^TEY4n~BI=J-FcBLPPZ!ZZ-RN&|N9hvNoG%bL6OeHxJhWE+;bh0t zLG zpsYKTlwf+t(qPKwtp8Zq!n^XWtyCk(f@M2C8^tt5Dcx#lX1^69xh?a!Oae^_6x{DYZIU(#7(xgy%LIG?BPWFu9+2 z7eGA2;etFmis6b+8&Q6U64yZMPxfHuDYu4VvREj1cBi&QbzM(AvvSz0NE)?dQe{o* z?-@@gH-Gf^y$)(}Pc)bJni~qf)JmM04=F?a@l)Jp^w!K~!nRfr=p*QBUJHz!jjg$a zudH>ZtcQ-(AM3q-XCJKCb;21XT!yElxm}DZD*4R{=MeWM)$Yl4sM|V(nt_Sjt(TW(?D8Y4!O?V*Nmh}IO4DB(8BA| z@Hrwx(+hwayk9XaW)4QXV8j$dR!@od48~j&I6&zjv(&vIdaf}@hq8?S5slOu1}dE6 z{K0hkSYZ5i?sda}M4cGqy&#ivgqJ^*PJCCe(@@%a4lad5Bjx4*Q62uuwc^PMcydGb zF{H1j2{7zh0|oV*OCVZu2Yi+Rp^j>>wYV}^hfe`tmH<)dSEs*5-g-Szoe(L@eHSRX z+u{tT+B~MeuH!OFCen%ZKuSa z677?Vwyq%PiSrmDK-#NEuR(;g-Cxe@en;L7jtAz@Wk{>rU zcve%B!+!D@j`i=?4EFN%1%;HQ;o-F!ZnQa`)dDhpYIC{b3zzTDevTT!e zWHc~7tRQD2GM;-dqj3z~;CB!VCj1a+w??&APRT6IYL2jtQnq}J_h~J(i4ji6PBUkJ hL-F?Ek2$H%e_0m}1o?+QS1)vapWqy + +As described in the preceding section, this option says what +entries are to be held by this database. You should set this +to the DN of the root of the subtree you are trying to create. +For example + +E: suffix "o=University of Michigan, c=US" + +You should be sure to specify a directory where the index +files should be created: + +E: directory + +For example: + +E: directory /usr/local/openldap/slapd + +You need to make it so you can connect to slapd as +somebody with permission to add entries. This is done +through the following two options in the database definition: + +E: rootdn +E: rootpw + +These options specify a DN and password that can be used +to authenticate as the "superuser" entry of the database (i.e., +the entry allowed to do anything). The DN and password +specified here will always work, regardless of whether the +entry named actually exists or has the password given. This +solves the chicken-and-egg problem of how to authenticate +and add entries before any entries yet exist. + +Finally, you should make sure that the database definition +contains the index definitions you want: + +E: index { | default} [pres,eq,approx,sub,none] + +For example, to index the cn, sn, uid and objectclass +attributes the following index configuration lines could be +used. + +E: index cn,sn,uid +E: index objectclass pres,eq +E: index default none + +See Section 4 on the configuration file for more details on +this option. Once you have configured things to your liking, +start up slapd, connect with your LDAP client, and start +adding entries. For example, to add a the U of M entry +followed by a Postmaster entry using the {{I:ldapadd}} tool, you +could create a file called {{EX:/tmp/newentry}} with the contents: + + +E: o=University of Michigan, c=US +E: objectClass=organization +E: o=University of Michigan +E: description=University of Michigan at Ann Arbor +E: cn=Postmaster, o=University of Michigan, c=US +E: objectClass=organizationalRole +E: cn=Postmaster +E: description=U of M postmaster - postmaster@umich.edu + +and then use a command like this to actually create the +entry: + +E: ldapadd -f /tmp/newentry -D "cn=Manager, o=University of +E: Michigan, c=US" -w secret + +The above command assumes that you have set {{EX: rootdn}} to +"cn=Manager, o=University of Michigan, c=US" and {{EX: rootpw}} +to "secret". + +H2: Creating a database off-line + +The second method of database creation is to do it off-line, +using the index generation tools described below. This +method is best if you have many thousands of entries to +create, which would take an unacceptably long time using +the LDAP method described above. These tools read the +slapd configuration file and an input file containing a text +representation of the entries to add. They produce the LDBM +index files directly. There are several important configuration +options you will want to be sure and set in the config file +database definition first: + +E: suffix + +As described in the preceding section, this option says what +entries are to be held by this database. You should set this +to the DN of the root of the subtree you are trying to create. +For example + +E: suffix "o=University of Michigan, c=US" + +You should be sure to specify a directory where the index +files should be created: + +E: directory + +For example: + +E: directory /usr/local/openldap-slapd + +Next, you probably want to increase the size of the in-core +cache used by each open index file. For best performance +during index creation, the entire index should fit in memory. If +your data is too big for this, or your memory too small, you +can still make it pretty big and let the paging system do the +work. This size is set with the following option: + +E: dbcachesize + +For example: + +E: dbcachesize 50000000 + +This would create a cache 50 MB big, which is pretty big (at +U-M, our database has about 125K entries, and our biggest +index file is about 45 MB). Experiment with this number a bit, +and the degree of parallelism (explained below), to see what +works best for your system. Remember to turn this number +back down once your index files are created and before you +run slapd. + +Finally, you need to specify which indexes you want to build. +This is done by one or more index options. + +E: index { | default} [pres,eq,approx,sub,none] + +For example: + +E: index cn,sn,uid pres,eq,approx +E: index default none + +This would create presence, equality and approximate +indexes for the cn, sn, and uid attributes, and no indexes for +any other attributes. See the configuration file section for +more information on this option. + +H3: The {{EX: ldif2ldbm}} program + +Once you've configured things to your liking, you create the +indexes by running the ldif2ldbm program: + +E: ldif2ldbm -i -f +E: [-d ] [-j ] +E: [-n ] [-e ] + +The arguments have the following meanings: + +E: -i + +Specifies the LDIF input file containing the entries to add in +text form (described below in Section 8.3). + +E: -f + +Specifies the slapd configuration file that tells where to +create the indexes, what indexes to create, etc. + +E: -d + +Turn on debugging, as specified by {{EX: }}. The +debug levels are the same as for slapd (see Section 6.1). + +E: -j + +An optional argument that specifies that at most {{EX: }} +processes should be started in parallel when building the +indexes. The default is 1. If set to a value greater than one, +{{I: ldif2ldbm}} will create at most that many subprocesses at a +time when building the indexes. A separate subprocess is +created to build each attribute index. Running these +processes in parallel can speed things up greatly, but +beware of creating too many processes, all competing for +memory and disk resources. + +E: -n + +An optional argument that specifies the configuration file +database for which to build indices. The first database listed +is "1", the second "2", etc. By default, the first ldbm database +in the configuration file is used. + +E: -e + +An optional argument that specifies the directory where +{{EX: ldif2ldbm}} can find the other database conversion tools it +needs to execute ({{EX: ldif2index}} and friends). The default is the +installation {{EX: ETCDIR}}. + +The next sections describe the programs invoked by +{{I: ldif2ldbm}} when it is building indexes. Normally, these +programs are invoked for you, but occasionally you may +want to invoke them yourself. + + + +H3: The {{EX: ldif2index}} program + +Sometimes it may be necessary to create a new attribute +index file without disturbing the rest of the database. This is +possible using the {{EX: ldif2index}} program. {{EX: ldif2index}} is invoked +like this + +E: ldif2index -i -f +E: [-d ] [-n ] + +Where the -i, -f, -d, and -n options are the same as for the +{{I: ldif2ldbm}} program. {{EX: }} is the attribute to build an index for. +Which indexes are built (e.g., equality, substring, etc.) is +controlled by the corresponding index line in the slapd +configuration file. + +You can use the ldbmcat program to create a suitable LDIF +input file from an existing LDBM database. + + + +H3: The {{EX: ldif2id2entry}} program + +The {{EX: ldif2id2entry}} program is normally invoked from {{EX: ldif2ldbm}}. +It is used to convert an LDIF text file into an {{EX: id2entry}} index. +It is unlikely that you would need to invoke it yourself, but if +you do it works like this + +E: ldif2id2entry -i -f +E: [-d ] [-n ] + +The arguments are the same as for the {{EX: ldif2ldbm}} program. + + + +H3: The {{EX: ldif2id2children}} program + +The {{EX: ldif2id2children}} program is normally invoked from +{{EX: ldif2ldbm}}. It is used to convert an LDIF text file into +{{EX: id2children}} and {{EX: dn2id}} indexes. Occasionally, it may be +necessary to run this program yourself, for example if one of +these indexes has become corrupted. {{EX: ldif2id2children}} is +invoked like this + +E: ldif2id2children -i -f +E: [-d ] [-n ] + +The arguments are the same as for the {{EX: ldif2ldbm}} program. +You can use the ldbmcat program to create a suitable LDIF +input file from an existing LDBM database. + + + +H3: The {{EX: ldbmcat}} program + +The {{EX: ldbmcat}} program is used to convert an {{EX: id2entry}} index +back into its LDIF text format. This can be useful when you +want to make a human-readable backup of your database, +or as an intermediate step in creating a new index using the +{{EX: ldif2index}} program. The program is invoked like this: + +E: ldbmcat [-n] + +where {{EX: }} is the name of the {{EX: id2entry}} index file. The +corresponding LDIF output is written to standard output. + +The -n option can be used to prevent the printing of entry +IDs in the LDIF format. If you are creating an LDIF format for +use as input to {{EX: ldif2index}} or anything by {{EX: ldif2ldbm}}, you +should not use the -n option (because the entry IDs must +match those already in the id2entry file). If you are just +making a backup of your data, you can use the -n option to +save space. + + + +H3: The {{EX: ldif}} program + +The ldif program is used to convert arbitrary data values to +LDIF format. This can be useful when writing a program or +script to create the LDIF file you will feed into the ldif2ldbm +program, or when writing a SHELL backend. ldif takes an +attribute name as an argument, and reads the attribute +value(s) from standard input. It produces the LDIF formatted +attribute line(s) on standard output. The usage is: + +E: ldif [-b] + +where {{EX: }} is the name of the attribute. Without the +-b option, ldif considers each line of standard input to be a +separate value of the attribute. + +The -b option can be used to force ldif to interpret its input +as a single raw binary value. This option is useful when +converting binary data such as a {{EX: jpegPhoto}} or {{EX: audio}} +attribute. + + +H2: The LDIF text entry format + +The LDAP Data Interchange Format (LDIF) is used to +represent LDAP entries in a simple text format. The basic +form of an entry is: + +E: [] +E: dn: +E: : +E: : +E: +E: ... + +where {{EX: }} is the optional entry ID (a positive decimal +number). Normally, you would not supply the {{EX: }}, allowing +the database creation tools to do that for you. The ldbmcat +program, however, produces an LDIF format that includes +{{EX: }} so that new indexes created will be consistent. + +A line may be continued by starting the next line with a +single space or tab character. e.g., + +E: dn: cn=Barbara J Jensen, o=University of Michigan, c=US + +Multiple attribute values are specified on separate lines. e.g., + +E: cn: Barbara J Jensen +E: cn: Babs Jensen + +If an {{EX: }} contains a non-printing character, or +begins with a space or a colon `:', the {{EX: }} is followed +by a double colon and the value is encoded in base 64 +notation. e.g., the value " begins with a space" would be +encoded like this: + +E: cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U= + +Multiple entries within the same LDIF file are separated by +blank lines. Here's an example of an LDIF file containing +three entries. + +E: dn: cn=Barbara J Jensen, o=University of Michigan, c=US +E: cn: Barbara J Jensen +E: cn: Babs Jensen +E: objectclass: person +E: sn: Jensen +E: +E: +E: dn: cn=Bjorn J Jensen, o=University of Michigan, c=US +E: cn: Bjorn J Jensen +E: cn: Bjorn Jensen +E: objectclass: person +E: sn: Jensen +E: +E: dn: cn=Jennifer J Jensen, o=University of Michigan, c=US +E: cn: Jennifer J Jensen +E: cn: Jennifer Jensen +E: objectclass: person +E: sn: Jensen +E: jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD +E: A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ +E: ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG +E: +E: ... + +Notice that the {{EX: jpegPhoto}} in Jennifer Jensen's entry is +encoded using base 64. The {{EX: ldif}} program (described in +Section 8.2.6) can be used to produce the LDIF format. + +Note: Trailing spaces are not trimmed from values in an +LDIF file. Nor are multiple internal spaces compressed. If +you don't want them in your data, don't put them there. + + +H2: Converting from QUIPU EDB format to LDIF format + +If you have directory data that is or was held in a QUIPU +DSA (available as part of the ISODE package), you will want +to convert the EDB files used by QUIPU into an LDIF file. +The edb2ldif program is provided to do most of the +conversion for you. Once you have an LDIF file, you should +follow the steps outlined in section 6.2 above to build an +LDBM database for slapd. + + + +H3: The {{EX: edb2ldif}} program + +The edb2ldif program is invoked like this: + +E: edb2ldif [-d] [-v] [-r] [-o] [-b ] +E: [-a ] [-f ] +E: [-i ] [] + +The LDIF data is written to standard output. The arguments +have the following meanings: + +E: -d + +This option enables some debugging output on standard +error. + +E: -v + +Enable verbose mode that writes status information to +standard error, such as which EDB file is being processed, +how many entries have been converted so far, etc. + +E: -r + +Recurse through child directories, processing all EDB files +found. + +E: -o + +Cause local .add file definitions to override the global addfile +(see -a below) + +E: -b + +Specify the Distinguished Name that all EDB file entries +appear below. + +E: -a + +The LDIF information contained in this file will be appended +to each entry. + +E: -f + +Specify a single directory where all file-based attributes +(typically sounds and images) can be found. If this option is +not given, file attributes are assumed to be located in the +same directory as the EDB file that refers to them. + +E: -i + +Specify an attribute that should not be converted. You can +include as many -i flags as necessary. + +E: + +Specify a particular EDB file (or files) to read data from. By +default, the EDB.root (if it exists) and EDB files in the current +directory are used. + +When {{EX: edb2ldif}} is invoked, it will also look for files named +.add in the directories where EDB files are found and append +the contents of the .add file to each entry. Typically, this +feature is used to include inherited attribute values (e.g., +{{EX: objectClass}}) that do not appear in the EDB files. + + + +H3: Step-by-step EDB to LDIF conversion + +The basic steps to follow when converting your EDB format +data to an LDIF file are: + +^ Locate the directory at the top of the EDB file hierarchy +.that your QUIPU DSA masters. The EDB file located there +.should contain the entries for the first level of your +.organization or organizational unit. If you are using an +.indexed database with QUIPU, you may need to create EDB +.files from your index files (using the synctree or qb2edb +.tools). +. + ++If you do not have a file named EDB.root in the same +.directory that contains your organizational or organizational +.unit entry, create it now by hand. Its contents should look +.something like this: +. +.{{EX: MASTER}} +.{{EX: 000001}} +.{{EX: }} +.{{EX: o=University of Michigan}} +.{{EX: objectClass= top & organization & domainRelatedObject &\}} +.{{EX: quipuObject & quipuNonLeafObject}} +.{{EX: l= Ann Arbor, Michigan}} +.{{EX: st= Michigan}} +.{{EX: o= University of Michigan & UMICH & UM & U-M & U of M}} +.{{EX: description= The University of Michigan at Ann Arbor}} +.{{EX: associatedDomain= umich.edu}} +.{{EX: masterDSA= c=US@cn=Woolly Monkey}} +.{{EX: }} + ++ (Optional) Create a global add file and/or local .add files to +.take care of adding any attribute values that do not appear in +.the EDB files. For example, if all entries in a particular EDB +.are person entries and you want to add the appropriate +.objectClass attribute value for them, create a file called .add +.in the same directory as the person EDB that contains the +.single line: +. +.{{EX: objectClass: person }} +. + ++ Run the edb2ldif program to do the actual conversion. +.Make sure you are in the directory that contains the root of +.the EDB hierarchy (the one where the EDB.root file resides). +.Include a -b flag with a base DN one level above your +.organizational entry, and include -i flags to ignore any +.attributes that are not useful to slapd. E.g., the command: +. +.{{EX: edb2ldif -v -r -b "c=US" -i iattr -i acl -i xacl -i sacl}} +.{{EX: -i lacl -i masterDSA -i slaveDSA > ldif}} +. +.will convert the entire EDB hierarchy to LDIF format and +.write the result to a file named ldif. Some attributes that are +.not useful when running slapd are ignored. The EDB +.hierarchy is assumed to reside logically below the base DN +."c=US". +. + ++ Follow the steps outlined in section 8.2 above to produce +.an LDBM database from your new LDIF file. + + + +H2: The ldbmtest program + +Occasionally you may find it useful to look at the LDBM +database and index files directly (i.e., without going through +slapd). The {{EX: ldbmtest}} program is provided for this purpose. It +gives you raw access to the database itself. {{EX: ldbmtest}} should +be run line this: + +E: ldbmtest [-d ] [-f ] + +The default configuration file in the {{EX: ETCDIR}} is used if you +don't supply one. By default, ldbmtest operates on the last +database listed in the config file. You can specify an +alternate database, or see the current database with the +following commands. + +E: b specify an alternate backend database +E: B print out the current backend database + +The {{EX: b}} command will prompt you for the suffix associated with +the database you want. The database you select can be +viewed and modified using a set of two-letter commands. +The first letter selects the command function to perform. +Possible commands and their meanings are as follows. + +E: l lookup (do not follow indirection) +E: L lookup (follow indirection) +E: t traverse and print keys and data +E: T traverse and print keys only +E: x delete an index item +E: e edit an index item +E: a add an index item +E: c create an index file +E: i insert an entry into an index item + +The second letter indicates which index the command +applies to. The possible index selections are as follows. + +E: c id2children index +E: d dn2id index +E: e id2entry index +E: f arbitrary file name +E: i attribute index + +Each command may require additional arguments which +ldbmtest will prompt you for. + +To exit {{EX: ldbmtest}}, type {{EX: control-D}} or {{EX: control-C}}. + +Note that this is a very raw interface originally developed +when testing the database format. It is provided and +minimally documented here for interested parties, but it is not +meant to be used by the inexperienced. See the next section +for a brief description of the LDBM database format. + + + +H2: The LDBM database format + +In normal operation, it is not necessary for you to know much +about the LDBM database format. If you are going to use the +ldbmtest program to look at or alter the database, or if you +want a deeper understanding of how indexes are maintained, +some knowledge of how it works could be useful. This +section gives an overview of the database format and how +slapd makes use of it. + + + +H3: Overview + +The LDBM database works by assigning a compact +four-byte unique identifier to each entry in the database. It +uses this identifier to refer to entries in indexes. The +database consists of one main index file, called id2entry, +which maps from an entry's unique identifier (EID) to a text +representation of the entry itself. Other index files are +maintained, for each indexed attribute for example, that map +values people are likely to search on to lists of EIDs. + +Using this simple scheme, many LDAP queries can be +answered efficiently. For example, to answer a search for +entries with a surname of "Jensen", slapd would first consult +the surname attribute index, look up the value "Jensen" and +retrieve the corresponding list of EIDs. Next, slapd would +look up each EID in the id2entry index, retrieve the +corresponding entry, convert it from text to LDAP format, and +return it to the client. + +The following sections give a very brief overview of each +type of index and what it contains. For more detailed +information see the paper "An X.500 and LDAP Database: +Design and Implementation," available in postscript format +from + +{{CMD[jump="ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps"]ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps}} + + + +H3: Attribute index format + +The LDBM backend will maintain one index file for each +attribute it is asked to index. Several sets of keys must +coexist in this file (e.g., keys for equality and approximate +equality), so the keys are prefixed with a character to ensure +uniqueness. The prefixes are given in the table below + +E: = equality keys +E: ~ approximate equality keys +E: * substring equality keys +E: \ continuation keys + +Key values are also normalized (e.g., converted to upper +case for case ignore attributes). So, for example, to look up +the surname equality value in the example above using the +ldbmtest program, you would look up the value "{{EX: =JENSEN}}". + +Substring indexes are maintained by generating all possible +N-character substrings for a value (N is 3 by default). These +substrings are then stored in the attribute index, prefixed by +"*". Additional anchors of "^" and "$" are added at the +beginning and end of words. So, for example the surname of +Jensen would cause the following keys to be entered in the +index: {{EX: ^JE, JEN, ENS, NSE, SEN, EN$}}. + +Approximate values are handled in a similar way, with +phonetic codes being generated for each word in a value +and then stored in the index, prefixed by "~". + +Large blocks in the index are split into smaller ones. The +smaller blocks are accessed through a level of indirection +provided by the original block. They are stored in the index +using the continuation key prefix of "\". + + + +H3: Other indexes + +In addition to the {{EX: id2entry}} and attribute indexes, LDBM +maintains a number of other indexes, including the {{EX: dn2id}} +index and the {{EX: id2children}} index. These indexes provide the +mapping between a DN and the corresponding EID, and the +mapping between an EID and the EIDs of the corresponding +entry's children, respectively. + +The {{EX: dn2id}} index stores normalized DNs as keys. The data +stored is the corresponding EID. + +The {{EX: id2children}} index stores EIDs as keys. The data stored +is a list of EIDs, just as for the attribute indexes. + + +PB: + + + diff --git a/doc/guide/figure_1.gif b/doc/guide/figure_1.gif new file mode 100644 index 0000000000000000000000000000000000000000..9fdfaf71b7d4b1e581f90599ffa2b0b253ea02e5 GIT binary patch literal 3086 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 b!6A-8E}mfurg{dPj8B9a7%EwT8O$00X81dZ literal 0 HcmV?d00001 diff --git a/doc/guide/figure_3.gif b/doc/guide/figure_3.gif new file mode 100644 index 0000000000000000000000000000000000000000..c986d865e14689a034b9f684e3854a09c9c16b8a GIT binary patch literal 2395 zcmeH@`9Bj10Klg_XGxCUBZL=bq^Ege#6!(kujd*$Hdn)pk=$}b8gn%=N5)LdopbJ- z%N2R%+9q?8^m#>z#NO-gczu8Tet-L#TR`>n-H!mNfDeHG-~o6%r2~FG0N?~b^Sk(7 z@ZSTE_wD52ck_cE2mWUVgm{3Tgydj#l->j(Ns!A>U2#8NT=GONte(n9`2~zh9jY%G z%uqBV$PL$f#AN|(D_w>g)nBZMw?iMW|3u8lfi(3@q#Bf8d4<*GMmQeB$VdQv($>t(nMparF zCwta>!A;0$(;crKleC!frfb#{D|9ZzEf6TiQY0Ac0Dlcv)|y?mlK>qMGv=?cva?|~ z)Yr`H*myLFk4;yx0PpOt1sP)Wy|BIwVXFC?HNp~EK`(^Wyn{${>v5qA2e%8w{}u+O z#i;80m_@yq+aM?7Smo5jkuV@NOH0b@nZ-3wX_=)~r3{U1zco>stDp`tqof}c6(I}r zbE?j!@qq8D(S0CdjsKDprPic$qzc!)Af;*DFXFt7Y*NK8)e9c@mJtK#k=%lD`=2!{ zN<}OSVB_|13N1at0Mw$L3|DF`ip1vGED~vR?L%Fn@_GGK=cn!4eY%%BlGotK%Jp_f z(31g_UO@Qq-plhec3-|y)Ad^R1-y6%kl8!fR`w4zLw7rnbPX|`<1A{#s&SVqkqZds z?Va=Kk&1uC8j#FE?>gL}b81ocm#V>i^?h=UuP#>v?~a)-yU-@gB>g`z#kYKj&&V@Q znj{)gbLVmNm7{{eK@a($bn7VKVw)RSRQkysxIdjRi@-Fq!%Xx)6RU!vTZ(%KJe5mt z#>D&-8c^p`FD$AE8?`P?O%n913H{BrHy#-r>)G#lb!@MVqtn&9WA7L3$n(rSKAZd{FL4F6m>rmd{6?@7eXaIUr{j%5N{hxn zrT4Air+?qEgclt;FgpA_zwl#?m1cxR+S(69NEcr0bFyj`4x2gxw7;#4av?`b9`LVk z_Z={?2}icl?^Y!{0Sh#b9$_+HQE9b+4emjKh9du8jBep&9PZpy;R$dOMB=Vhq{27K z2Qjt2vtG|0s$NtQF>f{9x2Q`@k1yUw0sF0{ts-yJG=vcl(8%oCe7{}5+757&7Or&v!CXH4L`>~(|P1Ffjsgn4!AhzlHTD3+Vz zMCx1CxQT1iFL}tLAf09U|=eHAVdFMr>CPv1wySfyXfeqtPWFccHu3! zU=+THoE4lUnA+aB3Ry6D?KFdB`(yQ@*JAm7%bEr7d3Xj|D`a&XsT*3;v%27-rs2S_ znQ0({{6I`8tH%vN#>jzp=w9{f)sGMeuzw9ya0G_FqQGpXAZ1m$e;I=A(4+TCYEU15 kF1pKmDvY(f!x-mg9n~BPrqkZnHp`A~^$|6FS_ok9FCZr}m;e9( literal 0 HcmV?d00001 diff --git a/doc/guide/figure_4.gif b/doc/guide/figure_4.gif new file mode 100644 index 0000000000000000000000000000000000000000..916a26eae3241b5002231d5a03538e2a09e376e1 GIT binary patch literal 1667 zcmZ?wbhEHbRA&}Udi;wp!ICsf-Zd!73vPST#n3n<#rbm{(VdEV{+Tc`u$&iJpHOJ6WCj7dfA)fUb$T5 z^U9^y^3R+UO~_;pS`yQo87sc9?Jnnw+l}SC>{0Q;VeXfzZ?v{uPM)55G_jqvj$>wr zfl;VZtJ*?|sa+?&W-QGAU-{xjhQ!Msk9)bhQl2z!`Fdkfw?N*D#BP73G>J)`ZCg|( z{MqT&M(`@*xrERIgr&D*f3&;IWF zl*_L7OrIX@y>0PuTJv?w3$xe0-Zbk?SlqA9<>q!)?l-xt-n{16&sTkZ6E}CD1B2p! c?%)u|AQ#Ut1yel(PR1-b28K!&V3}eK0E8FKUjP6A literal 0 HcmV?d00001 diff --git a/doc/guide/figure_5.gif b/doc/guide/figure_5.gif new file mode 100644 index 0000000000000000000000000000000000000000..d0b70bba487284a136af930d9aeb36869eacd40f GIT binary patch literal 3298 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 () + +This attribute identifies the slapd server software by name, +version, and build date, e.g., {{EX: slapd 3.3 (Thu May 21 14:19:03 +EDT 1996)}} + +E: threads: + +This attribute indicates the number of threads (operations) +currently outstanding in slapd. + +E: connection: : : : +E: : : [ ] + +This multi-valued attribute summarizes information for each +open connection. The information given is {{EX: }}, the file +descriptor; {{EX: }}, the time the connection was opened +in UTC format; {{EX: }}, the number of operations +initiated over the connection; {{EX: }}, the number +of operations completed over the connection; {{EX: }}, the +DN currently bound to the connection; and optionally {{EX: }}, +indicating whether the connection is currently blocked for +read or write.. + +E: currentconnections: + +The current number of connections. + +E: totalconnections: + +The total number of connections handled by slapd since it +started. + +E: dtablesize: + +The size of slapd's file descriptor table. + +E: writewaiters: + +The number of threads blocked waiting to write data to a +client. + +E: readwaiters: + +The number of threads blocked waiting to read data from a +client. + +E: opsinitiated: + +The total number of operations initiated by slapd since it +started. + +E: opscompleted: + +The total number of operations completed by slapd since it +started. + +E: entriessent: + +The total number of entries sent to clients by slapd since it +started. + +E: bytessent: + +The total number of bytes sent to clients by slapd since it +started. + +E: currenttime: + +Slapd's idea of the current time. + +E: starttime: + +The time slapd was started. + +E: nbackends: + +The number of backends currently being served by slapd. + +E: concurrency: + +Under Solaris 2.x only, an indication of the current level of +thread concurrency. + +Note that slapd takes a snapshot of this information and +returns it to you. No attempt is made to ensure that the +information is consistent (i.e., if an operation thread is +modifying one of these things when the monitor thread is +reading it, strange results could be returned). + +You should be able to use any LDAP client to retrieve this +information. Here's how you might do it using the +{{I: ldapsearch}}(1) client: + +E: ldapsearch -s base -b cn=monitor 'objectclass=*' + +PB: + + + diff --git a/doc/guide/preamble.sdf b/doc/guide/preamble.sdf new file mode 100644 index 0000000000..2ccda413db --- /dev/null +++ b/doc/guide/preamble.sdf @@ -0,0 +1,11 @@ +# file: guide.sdf +# + +!define DOC_NAME "OpenLDAP Administrators Guide" +!define DOC_AUTHOR "OpenLDAP" +!define DOC_LOGO "LDAPwww.gif" +!define DOC_LOF_TITLE "Figures" +!define DOC_LOF +!build_title + + diff --git a/doc/guide/quickstart.sdf b/doc/guide/quickstart.sdf new file mode 100644 index 0000000000..4d97407a73 --- /dev/null +++ b/doc/guide/quickstart.sdf @@ -0,0 +1,123 @@ + +H1: A Quick-Start Guide to Running slapd + +This section provides a quick step-by-step guide to building, +installing and running {{I:slapd}}. It is intended to provide users with a +simple and quick way to get started only. If you intend to run slapd +seriously, you should read the rest of this guide. + + +^ {{B:Get the software}}. {{I:Slapd}} is part of the OpenLDAP distribution, which +you can retrieve using this URL: +. +.{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}} +. +.If you are reading this guide, you have probably already done this. +. + ++ {{B:Untar the distribution}}. Pick a place for the LDAP source to live, cd +there, and untar it. For example: +. +.{{EX: cd /usr/local/src}} +.{{EX: gunzip -c openldap-release.tgz | tar xvfB -}} +.{{EX: cd ldap}} ++{{B: Configure the software}}. +. +.You will have to edit two files to configure things for your site. +. +.{{EX: vi Make-common}} +.{{EX:vi include/ldapconfig.h.edit}} +. +.Read the comments in Make-common and configure things +.appropriately. If you have the Berkeley DB package installed, or the +.GDBM package, you should set the LDBMBACKEND variable +.accordingly. Otherwise, the defaults should be OK to get you started. +. +.In the include/ldapconfig.h.edit file, be sure to set the DEFAULT_BASE +.and LDAPHOST variables to something appropriate for your site. +.Other than that, the defaults should work OK. + + ++{{B:Install the software}}. From the top level LDAP source directory, +type: +. +.{{EX: su}} +.{{EX: make install}} +. +.Examine the output of this command carefully to ensure everything is +.installed properly. +. + + ++{{B:Make a configuration file}}. Create a file called myslapd.conf and +.enter the following lines into it. See Section 5 for more details on this +.file. +. +.{{EX:referral ldap://ldap.itd.umich.edu}} +.{{EX:database ldbm}} +.{{EX:suffix "o=, c=US"}} +.{{EX:rootdn "cn=, o=, c=US"}} +.{{EX:rootpw secret}} +. +.Be sure to replace "" with the name of your +.organization and "" with your name. If you are not in +.the US, replace "US" with your two-letter country code. The rootdn +.and rootpw lines are only required if later you want to easily add or +.modify entries via LDAP. +. + + ++{{B:Create a database}}. This is a two-step process. Step A is to create +.a file (we'll call it myldif) containing the entries you want your database +.to contain. Use the following example as a guide, or see Section 7.3 for +.more details. +. +.{{EX:dn: o=, c=US}} +.{{EX:o: }} +.{{EX:objectclass: organization}} +. +.{{EX:dn: cn=, o=, c=US}} +.{{EX:cn: }} +.{{EX:sn: }} +.{{EX:mail: }} +.{{EX:objectclass: person}} +. +.You can include additional entries and attributes in this file if you want, +.or add them later via LDAP. +. +.Step B is to run this file through a tool to create the slapd database. +. +.{{EX:$(ETCDIR)/ldif2ldbm -f myslapd.conf -i myldif}} +. +.Where myslapd.conf is the configuration file you made in step 6, and +.myldif is the file you made in step 7A above. By default, the database +.files will be created in /usr/tmp. You may specify an alternate directory +.via the directory option in the slapd.conf file. +. + + ++{{B:See if it works}}.You can use any LDAP client to do this, but our +.example uses the ldapsearch tool. +. +.{{EX:ldapsearch -h 127.0.0.1 'objectclass=*'}} +. +.This command will search for and retrieve every entry in the database. +.Note the use of single quotes around the filter, which prevents the "*" +.from being interpreted by the shell. +. +.You are now ready to add more entries (e.g., using {{I:ldapadd}}(3) or +.another LDAP client), experiment with various configuration options, +.backend arrangements, etc. Note that by default, the {{I:slapd}} database +.grants {{EX:READ}} access to everybody. So if you want to add or modify +.entries over LDAP, you will have to bind as the rootdn specified in the +.config file (see Section 5.2.2), or change the default access control +.(see Section 5.3). +. + + +The following sections provide more detailed information on making, +installing, and running slapd. + +PB: + + diff --git a/doc/guide/referrals.sdf b/doc/guide/referrals.sdf new file mode 100644 index 0000000000..00477e9c37 --- /dev/null +++ b/doc/guide/referrals.sdf @@ -0,0 +1,41 @@ +H1: Distributing {{I: slapd}} DATA + +For many sites, running one or more {{I: slapds}} that hold an +entire subtree of data is sufficient. But sometimes it may be +desirable to have one slapd refer to other {{I: slapds}} for a +certain part of the tree. This can be accomplished by +creating a referral entry in one {{I:slapd}}'s database pointing +to another {{I: slapd}}. For those familiar with X.500, a {{I:slapd}} +{{I: referral}} entry is similar to an X.500 knowledge reference. + +The referral entry acts as a mount point, glueing two slapd +databases together. A referral entry has an {{I: objectclass}} of +"referral" and is named by a {{I: ref}} attribute containing a URL +pointing to the slapd holding the data below the mount +point. This mechanism is very general and allows slapd +databases that are not normally hierarchical to be grafted +together. + +An example should help illustrate things. Suppose your +company is running a slapd and just purchased a new +company, also running a slapd. You can easily connect +the two databases by creating an entry like this in your +slapd's database. + +E: dn: ref="ldap://new.host/o=New Company,c=US", o=Your + +company, c=US + +E: objectclass: referral + +Now any subtree search that has this entry in its scope +will return a referral to the new company, in addition to any +entries matched in your database. Referral-aware clients +will continue the search at the new company's server. + +A mechanism similar to this is used to support distributed +indexing, described in Appendix C. + + +PB: + diff --git a/doc/guide/replication.sdf b/doc/guide/replication.sdf new file mode 100644 index 0000000000..b25b89e5a6 --- /dev/null +++ b/doc/guide/replication.sdf @@ -0,0 +1,407 @@ +H1: Replication with slurpd + +In certain configurations, a single slapd instance may be +insufficient to handle the number of clients requiring +directory service via LDAP. It may become necessary to +run more than one slapd instance. At the University of +Michigan, for instance, there are four slapd servers, one +master and three slaves. A DNS lookup of the name +ldap.itd.umich.edu returns the IP addresses of those four +servers, distributing the load among them. This +master/slave arrangement provides a simple and effective +way to increase capacity, availability and reliability. + +Slurpd provides the capability for a master slapd to +propagate changes to slave slapd instances, +implementing the master/slave replication scheme +described above. Slurpd runs on the same host as the +master slapd instance. + + + +H2: Overview + +Slurpd provides replication services "in band". That is, it +uses the LDAP protocol to update a slave database from +the master. Perhaps the easiest way to illustrate this is +with an example. In this example, we trace the propagation +of an LDAP modify operation from its initiation by the LDAP +client to its distribution to the slave slapd instance. + + +{{B: Sample replication scenario:}} + +* Step 1: An LDAP client starts up and connects to a slave +slapd. + +* Step 2: The LDAP client submits an LDAP modify +. operation to the slave slapd. + +* Step 3: The slave slapd returns a referral to the LDAP +. client, which causes the client to send the modify +. operation to the master slapd. + +* Step 4: The master slapd performs the modify operation, +. writes out the change to its replication log file and returns +. a success code to the client. + +* Step 5: The slurpd process notices that a new entry has +. been appended to the replication log file, reads the +. replication log entry, and sends the change to the slave +. slapd via LDAP. + +* Step 6: The slave slapd performs the modify operation and +. returns a success code to the slurpd process. + +Note: if the LDAP client happened to connect to the +master slapd to begin with, Step 3 is omitted, but the rest +of the scenario remains the same. + + + +H2: Replication Logs + +When slapd is configured to generate a replication logfile, +it writes out a file in a format which is a variant of the LDIF +format. The replication log gives the replication site(s), a +timestamp, the DN of the entry being modified, and a series +of lines which specify the changes to make. In the +example below, "Barbara Jensen" has replaced a line of +her multiLineDescription. The change is to be propagated +to the slapd instance running on truelies.rs.itd.umich.edu. +The lastModifiedBy and lastModified Time attributes are +also propagated to the slave slapd. + +E: replica: truelies.rs.itd.umich.edu:389 +E: time: 809618633 +E: dn: cn=Barbara Jensen, ou=People, o=University of Michigan,c=US +E: changetype: modify +E: delete: multiLineDescription +E: multiLineDescription: I enjoy sailing in my spare time +E: - +E: add: multiLineDescription +E: multiLineDescription: A dreamer... +E: - +E: delete: lastModifiedBy +E: - +E: add: lastModifiedBy +E: lastModifiedBy: cn=Barbara Jensen, ou=People, o=University of Michigan, c=US +E: - +E: delete: lastModifiedTime +E: - +E: add: lastModifiedTime +E: lastModifiedTime: 950825073308Z +E: - + +The modifications to {{EX: lastModifiedBy}} and {{EX: lastModifiedTime}} +were initiated by the master {{I: slapd}}. + + + +H2: Command-Line Options + +Slurpd supports the following command-line options. + +E: -d | ? + +This option sets the slurpd debug level to {{EX: }}. When +level is a `?' character, the various debugging levels are +printed and slapd exits, regardless of any other options +you give it. Current debugging levels (a subset of slapd's +debugging levels) are + + +E: 4 heavy trace debugging +E: 64 configuration file processing +E: 65535 enable all debugging + +Debugging levels are additive. That is, if you want heavy +trace debugging and want to watch the config file being +processed, you would set level to the sum of those two +levels (in this case, 68). + +E: -f + +This option specifies an alternate slapd configuration file. +Slurpd does not have its own configuration file. Instead, all +configuration information is read from the slapd +configuration file. + +E: -r + +This option specifies an alternate slapd replication log file. +Under normal circumstances, slurpd reads the name of +the slapd replication log file from the slapd configuration +file. However, you can override this with the -r flag, to +cause slurpd to process a different replication log file. See +section 10.5, Advanced slurpd Operation, for a discussion +of how you might use this option. + +E: -o + +Operate in "one-shot" mode. Under normal +circumstances, when slurpd finishes processing a +replication log, it remains active and periodically checks to +see if new entries have been added to the replication log. +In one-shot mode, by comparison, slurpd processes a +replication log and exits immediately. If the -o option is +given, the replication log file must be explicitly specified +with the -r option + +E: -t + +Specify an alternate directory for slurpd's temporary +copies of replication logs. The default location is /usr/tmp. + +E: -k + +When slurpd uses kerberos to authenticate to slave slapd +instances, it needs to have an appropriate srvtab file for +the remote slapd. This option allows you to specify an +alternate filename containing kerberos keys for the remote +slapd. The default filename is /etc/srvtab. You can also +specify the srvtab file to use in the slapd configuration +file's replica option. See the documentation on the srvtab +directive in section 5.2.2, General Backend Options. A +more complete discussion of using kerberos with slapd +and slurpd may be found in Appendix D. + + + +H2: Configuring slurpd and a slave slapd instance + +To bring up a replica slapd instance, you must configure +the master and slave slapd instances for replication, then +shut down the master slapd so you can copy the +database. Finally, you bring up the master slapd instance, +the slave slapd instance, and the slurpd instance. These +steps are detailed in the following sections. You can set +up as many slave slapd instances as you wish. + + +H3: Set up the master slapd + +Follow the procedures in Section 4, Building and Installing +slapd. Be sure that the slapd instance is working properly +before proceeding. Be sure to do the following in the +master slapd configuration file. + +^ Add a replica directive for each replica. The binddn= +. parameter should match the updatedn option in the +. corresponding slave slapd configuration file, and should +. name an entry with write permission to the slave database +. (e.g., an entry listed as rootdn, or allowed access via +. access directives in the slave slapd configuration file). + ++ Add a replogfile directive, which tells slapd where to log +. changes. This file will be read by slurpd. + + + +H3: Set up the slave slapd + +Install the slapd software on the host which is to be the +slave slapd server. The configuration of the slave server +should be identical to that of the master, with the following +exceptions: + +^ Do not include a replica directive. While it is possible to +. create "chains" of replicas, in most cases this is +. inappropriate. + ++ Do not include a replogfile directive. + ++ Do include an updatedn line. The DN given should +. match the DN given in the {{EX: binddn=}} parameter of the +. corresponding {{EX: replica=}} directive in the master slapd +. config file. + ++ Make sure the DN given in the {{EX: updatedn}} directive has +. permission to write the database (e.g., it is listed as rootdn +. or is allowed access by one or more access directives). + + + +H3: Shut down the master slapd + +In order to ensure that the slave starts with an exact copy +of the master's data, you must shut down the master +slapd. Do this by sending the master slapd process an +interrupt signal with {{EX: kill -TERM }}, where {{EX: }} is the +process-id of the master slapd process. + +If you like, you may restart the master slapd in read-only +mode while you are replicating the database. During this +time, the master slapd will return an "unwilling to perform" +error to clients that attempt to modify data. + + + +H3: Copy the master slapd's database to the slave + +Copy the master's database(s) to the slave. For an +LDBM-based database, you must copy all index files as +well as the "NEXTID" file. Index files will have a different +suffix depending on the underlying database package +used. The current possibilities are + +* {{EX: dbb}} Berkeley DB B-tree backend +* {{EX: dbh}} Berkeley DB hash backend +* {{EX: gdbm}} GNU DBM backend +* {{EX: pag}} UNIX NBDM backend +* {{EX: dir}} UNIX NBDM backend + +You should copy all files with such a suffix that are located +in the index directory specified in your slapd config file. + + + +H3: Configure the master slapd for replication + +To configure slapd to generate a replication logfile, you +add a "{{EX: replica}}" configuration option to the master slapd's +config file. For example, if we wish to propagate changes +to the slapd instance running on host +truelies.rs.itd.umich.edu: + +E: replica host=truelies.rs.itd.umich.edu:389 +E: binddn="cn=Replicator, o=U of M, c=US" +E: bindmethod=simple credentials=secret + +In this example, changes will be sent to port 389 (the +standard LDAP port) on host truelies. The slurpd process +will bind to the slave slapd as +"cn=Replicator, o=U of M, c=US" +using simple authentication with password "secret". +Note that the entry given by the binddn= directive must +exist in the slave slapd's database (or be the rootdn +specified in the slapd config file) in order for the bind +operation to succeed. + + + +H3: Restart the master slapd and start the slave slapd + +Restart the master slapd process. To check that it is +generating replication logs, perform a modification of any +entry in the database, and check that data has been +written to the log file. + + + +H3: Start slurpd + +Start the slurpd process. Slurpd should immediately send +the test modification you made to the slave slapd. Watch +the slave slapd's logfile to be sure that the modification +was sent. + +{{EX: slurpd -f }} + + + +H2: Advanced slurpd Operation + +H3: Replication errors + +When slurpd propagates a change to a slave slapd and +receives an error return code, it writes the reason for the +error and the replication record to a reject file. The reject +file is located in the same directory with the per-replica +replication logfile, and has the same name, but with the +string ".rej" appended. For example, for a replica running +on host truelies.rs.itd.umich.edu, port 389, the reject file, if it +exists, will be named + +E: /usr/tmp/truelies.rs.itd.umich.edu:389. + +A sample rejection log entry follows: + +E: ERROR: No such attribute +E: replica: truelies.rs.itd.umich.edu:389 +E: time: 809618633 +E: dn: cn=Barbara Jensen, ou=People, o=University of Michigan, c=US +E: changetype: modify +E: delete: multiLineDescription +E: multiLineDescription: I enjoy sailing in my spare time +E: - +E: add: multiLineDescription +E: multiLineDescription: A dreamer... +E: - +E: delete: lastModifiedBy +E: - +E: add: lastModifiedBy +E: lastModifiedBy: cn=Barbara Jensen, ou=People, o=University of Michigan, c=US +E: - +E: delete: lastModifiedTime +E: - +E: add: lastModifiedTime +E: lastModifiedTime: 950825073308Z +E: - + +Note that this is precisely the same format as the original +replication log entry, but with an ERROR line prepended to +the entry. + + + +H3: {{I:Slurpd}}'s one-shot mode and reject files + +It is possible to use slurpd to process a rejection log with +its "one-shot mode." In normal operation, slurpd watches +for more replication records to be appended to the +replication log file. In one-shot mode, by contrast, slurpd +processes a single log file and exits. Slurpd ignores +ERROR lines at the beginning of replication log entries, so +it's not necessary to edit them out before feeding it the +rejection log. + +To use one-shot mode, specify the name of the rejection +log on the command line as the argument to the -r flag, +and specify one-shot mode with the -o flag. For example, +to process the rejection log file +/usr/tmp/replog.truelies.rs.itd.umich.edu:389 and exit, use the +command + +E: slurpd -r /usr/tmp/truelies.rs.itd.umich.edu:389 -o + + +H2: Replication from a slapd directory server to an X.500 DSA + +In mixed environments where both X.500 DSAs and slapd +are used, it may be desirable to replicate changes from a +slapd directory server to an X.500 DSA. This section +discusses issues involved with this method of replication, +and describes the currently-available facilities. + +To propagate changes from a slapd directory server to an +X.500 DSA, slurpd runs on the master slapd host, and +sends changes to an ldapd which acts as a gateway to +the X.500 DSA: + +!import "figure_1.gif"; align="center"; title="Replication from slapd to an X.500 DSA" +FT: Figure 6: Replication from slapd to an X.500 DSA + +Note that the X.500 DSA must be a read-only copy. Since +the replication is one-way, updates from DAP clients +connecting to the X.500 DSA simply cannot be handled. + +A problem arises where attribute names differ between the +slapd directory server and the X.500 DSA. At present, +slapd and slurpd do not support selective replication of +attributes, nor do they support translation of attribute +names and values. For example, slurpd will attempt to +update the "modifiersName" and "modifyTimeStamp" +attributes on the slave it connects to. However, the X.500 +DSA may expect these attributes to be named +"lastModifiedBy" and "lastModifiedTime". + +A solution to this attribute naming problem is to have the +ldapd read oidtables that map "modifiersName" to the +objectID (OID) for the "lastModifiedBy" attribute and +"modifyTimeStamp" to the OID for the "lastModifiedTime" +attribute. Since attribute names are carried as OIDs over +DAP, this should perform the appropriate translation of +attribute names. + + diff --git a/doc/guide/runningslapd.sdf b/doc/guide/runningslapd.sdf new file mode 100644 index 0000000000..f591f92d72 --- /dev/null +++ b/doc/guide/runningslapd.sdf @@ -0,0 +1,123 @@ +H1: Running slapd + +Slapd can be run in two different modes, stand-alone or from +inetd(8). Stand-alone operation is recommended, especially if you +are using the LDBM backend. This allows the backend to take +advantage of caching and avoids concurrency problems with the +LDBM index files. If you are running only a PASSWD or SHELL +backend, running from inetd is an option. How to do this is +described in the next section, after the command-line options and +stand-alone daemon operation are described. + + + +H2: Command-Line Options + +{{I:Slapd}} supports the following command-line options. + +E: -d | ? + +This option sets the slapd debug level to . When level is a +`?' character, the various debugging levels are printed and slapd +exits, regardless of any other options you give it. Current +debugging levels are + +E: 1 trace function calls +E: 2 debug packet handling +E: 4 heavy trace debugging +E: 8 connection management +E: 16 print out packets sent and received +E: 32 search filter processing +E: 64 configuration file processing +E: 128 access control list processing +E: 256 stats log connections/operations/results +E: 512 stats log entries sent +E: 1024 print communication with shell backends +E: 2048 print entry parsing debugging +E: 65535 enable all debugging + +Debugging levels are additive. That is, if you want to trace function +calls and watch the config file being processed, you would set +level to the sum of those two levels (in this case, 65). Consult +{{EX: }} for more details. + +Note: slapd must have been compiled with {{EX:-DLDAP_DEBUG}} +defined for any debugging information beyond the two stats levels +to be available. + +E: -f + +This option specifies an alternate configuration file for slapd. + +E: -i + +This option tells slapd that it is running from inetd instead of as a +stand-alone server. See the next section on running slapd from +inetd for more details. + +E: -p + +This option specifies an alternate TCP port on which slapd should +listen for connections. The default port is 389. + + + +H2: Running slapd as a Stand-Alone Daemon + +In general, slapd is run like this: + +E: $(ETCDIR)/slapd [