Commit 779d6af5 authored by Quanah Gibson-Mount's avatar Quanah Gibson-Mount
Browse files

Sync 2.4 guide with HEAD for 2.4.5

parent 368adabc
......@@ -36,9 +36,11 @@ Public License.
---
Portions Copyright 1999-2005 Howard Y.H. Chu.
Portions Copyright 1999-2005 Symas Corporation.
Portions Copyright 1999-2007 Howard Y.H. Chu.
Portions Copyright 1999-2007 Symas Corporation.
Portions Copyright 1998-2003 Hallvard B. Furuseth.
Portions Copyright 2007 Gavin Henry
Portions Copyright 2007 Suretec Systems
All rights reserved.
Redistribution and use in source and binary forms, with or without
......
......@@ -18,16 +18,19 @@ sdf-src: \
../plain.sdf \
../preamble.sdf \
abstract.sdf \
appendix-configs.sdf \
backends.sdf \
config.sdf \
dbtools.sdf \
glossary.sdf \
guide.sdf \
install.sdf \
intro.sdf \
maintenance.sdf \
master.sdf \
monitoringslapd.sdf \
overlays.sdf \
preface.sdf \
proxycache.sdf \
quickstart.sdf \
referrals.sdf \
replication.sdf \
......@@ -36,21 +39,19 @@ sdf-src: \
schema.sdf \
security.sdf \
slapdconfig.sdf \
syncrepl.sdf \
title.sdf \
tls.sdf \
troubleshooting.sdf \
tuning.sdf
sdf-img: \
../images/LDAPlogo.gif \
config_local.gif \
config_ref.gif \
config_dit.png \
config_local.png \
config_ref.png \
config_repl.gif \
config_x500fe.gif \
config_x500ref.gif \
intro_dctree.gif \
intro_tree.gif \
replication.gif
intro_dctree.png \
intro_tree.png \
guide.html: guide.sdf sdf-src sdf-img
sdf -2html guide.sdf
......@@ -62,6 +63,7 @@ admin.html: admin.sdf sdf-src sdf-img
sdf -DPDF -2html admin.sdf
guide.pdf: admin.html
htmldoc --book --duplex --bottom 36 --top 36 \
--toclevels 2 \
-f guide.pdf admin.html
htmldoc --batch guide.book
clean:
rm -f *.pdf *.html *~
# $OpenLDAP$
# Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# README.spellcheck
#
aspell.en.pws
We use aspell to spell check the Admin Guide and Man Pages.
Please move aspell.en.pws to ~/.aspell.en.pws and run:
aspell --lang=en_US -c <filename>
If you add additional words and terms, please add
them or copy them to aspell.en.pws and commit.
# $OpenLDAP$
# Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Changes Since Previous Release
The following sections attempt to summarize the new features and changes in OpenLDAP
software since the 2.3.x release and the OpenLDAP Admin Guide.
H2: New Guide Sections
In order to make the Admin Guide more thorough and cover the majority of questions
asked on the OpenLDAP mailing lists and scenarios discussed there, we have added the following new sections:
* {{SECT:When should I use LDAP?}}
* {{SECT:When should I not use LDAP?}}
* {{SECT:LDAP vs RDBMS}}
* {{SECT:Backends}}
* {{SECT:Overlays}}
* {{SECT:Replication}}
* {{SECT:Maintenance}}
* {{SECT:Monitoring}}
* {{SECT:Tuning}}
* {{SECT:Troubleshooting}}
* {{SECT:Changes Since Previous Release}}
* {{SECT:Configuration File Examples}}
* {{SECT:Glossary}}
Also, the table of contents is now 3 levels deep to ease navigation.
H2: New Features and Enhancements in 2.4
H3: Better {{B:cn=config}} functionality
There is a new slapd-config(5) manpage for the {{B:cn=config}} backend. The
original design called for auto-renaming of config entries when you insert or
delete entries with ordered names, but that was not implemented in 2.3. It is
now in 2.4. This means, e.g., if you have
> olcDatabase={1}bdb,cn=config
> olcSuffix: dc=example,dc=com
and you want to add a new subordinate, now you can ldapadd:
> olcDatabase={1}bdb,cn=config
> olcSuffix: dc=foo,dc=example,dc=com
This will insert a new BDB database in slot 1 and bump all following databases
down one, so the original BDB database will now be named:
> olcDatabase={2}bdb,cn=config
> olcSuffix: dc=example,dc=com
H3: Better {{B:cn=schema}} functionality
In 2.3 you were only able to add new schema elements, not delete or modify
existing elements. In 2.4 you can modify schema at will. (Except for the
hardcoded system schema, of course.)
H3: More sophisticated Syncrepl configurations
The original implementation of Syncrepl in OpenLDAP 2.2 was intended to support
multiple consumers within the same database, but that feature never worked and
was removed from OpenLDAP 2.3; you could only configure a single consumer in
any database.
In 2.4 you can configure multiple consumers in a single database. The configuration
possibilities here are quite complex and numerous. You can configure consumers
over arbitrary subtrees of a database (disjoint or overlapping). Any portion
of the database may in turn be provided to other consumers using the Syncprov
overlay. The Syncprov overlay works with any number of consumers over a single
database or over arbitrarily many glued databases.
H3: N-Way Multimaster Replication
As a consequence of the work to support multiple consumer contexts, the syncrepl
system now supports full N-Way multimaster replication with entry-level conflict
resolution. There are some important constraints, of course: In order to maintain
consistent results across all servers, you must maintain tightly synchronized
clocks across all participating servers (e.g., you must use NTP on all servers).
The entryCSNs used for replication now record timestamps with microsecond resolution,
instead of just seconds. The delta-syncrepl code has not been updated to support
multimaster usage yet, that will come later in the 2.4 cycle.
H3: Replicating {{slapd}} Configuration (syncrepl and {{B:cn=config}})
Syncrepl was explicitly disabled on cn=config in 2.3. It is now fully supported
in 2.4; you can use syncrepl to replicate an entire server configuration from
one server to arbitrarily many other servers. It's possible to clone an entire
running slapd using just a small (less than 10 lines) seed configuration, or
you can just replicate the schema subtrees, etc. Tests 049 and 050 in the test
suite provide working examples of these capabilities.
H3: Push-Mode Replication
In 2.3 you could configure syncrepl as a full push-mode replicator by using it
in conjunction with a back-ldap pointed at the target server. But because the
back-ldap database needs to have a suffix corresponding to the target's suffix,
you could only configure one instance per slapd.
In 2.4 you can define a database to be "hidden", which means that its suffix is
ignored when checking for name collisions, and the database will never be used
to answer requests received by the frontend. Using this "hidden" database feature
allows you to configure multiple databases with the same suffix, allowing you to
set up multiple back-ldap instances for pushing replication of a single database
to multiple targets. There may be other uses for hidden databases as well (e.g.,
using a syncrepl consumer to maintain a *local* mirror of a database on a separate filesystem).
H3: More extensive TLS configuration control
In 2.3, the TLS configuration in slapd was only used by the slapd listeners. For
outbound connections used by e.g. back-ldap or syncrepl their TLS parameters came
from the system's ldap.conf file.
In 2.4 all of these sessions inherit their settings from the main slapd configuration,
but settings can be individually overridden on a per-config-item basis. This is
particularly helpful if you use certificate-based authentication and need to use a
different client certificate for different destinations.
H3: Performance enhancements
Too many to list. Some notable changes - ldapadd used to be a couple of orders
of magnitude slower than "slapadd -q". It's now at worst only about half the
speed of slapadd -q. Some comparisons of all the 2.x OpenLDAP releases are available
at {{URL:http://www.openldap.org/pub/hyc/scale2007.pdf}}
That compared 2.0.27, 2.1.30, 2.2.30, 2.3.33, and HEAD). Toward the latter end
of the "Cached Search Performance" chart it gets hard to see the difference
because the run times are so small, but the new code is about 25% faster than 2.3,
which was about 20% faster than 2.2, which was about 100% faster than 2.1, which
was about 100% faster than 2.0, in that particular search scenario. That test
basically searched a 1.3GB DB of 380836 entries (all in the slapd entry cache)
in under 1 second. i.e., on a 2.4GHz CPU with DDR400 ECC/Registered RAM we can
search over 500 thousand entries per second. The search was on an unindexed
attribute using a filter that would not match any entry, forcing slapd to examine
every entry in the DB, testing the filter for a match.
Essentially the slapd entry cache in back-bdb/back-hdb is so efficient the search
processing time is almost invisible; the runtime is limited only by the memory
bandwidth of the machine. (The search data rate corresponds to about 3.5GB/sec;
the memory bandwidth on the machine is only about 4GB/sec due to ECC and register latency.)
H3: New overlays
* slapo-constraint (Attribute value constraints)
* slapo-dds (Dynamic Directory Services, RFC 2589)
* slapo-memberof (reverse group membership maintenance)
H3: New features in existing Overlays
* slapo-pcache
- Inspection/Maintenance
-- the cache database can be directly accessed via
LDAP by adding a specific control to each LDAP request; a specific
extended operation allows to consistently remove cached entries and entire
cached queries
- Hot Restart
-- cached queries are saved on disk at shutdown, and reloaded if
not expired yet at subsequent restart
* slapo-rwm can safely interoperate with other overlays
* Dyngroup/Dynlist merge, plus security enhancements
- added dgIdentity support (draft-haripriya-dynamicgroup)
H3: New features in slapd
* monitoring of back-{b,h}db: cache fill-in, non-indexed searches,
* session tracking control (draft-wahl-ldap-session)
* subtree delete in back-sql (draft-armijo-ldap-treedelete)
H3: New features in libldap
* ldap_sync client API (LDAP Content Sync Operation, RFC 4533)
H3: New clients, tools and tool enhancements
* ldapexop for arbitrary extended operations
* Complete support of controls in request/response for all clients
* LDAP Client tools now honor SRV records
H3: New build options
* Support for building against GnuTLS
H2: Obsolete Features Removed From 2.4
These features were strongly deprecated in 2.3 and removed in 2.4.
H3: Slurpd
Please read the {{SECT:Replication}} section as to why this is no longer in
OpenLDAP
H3: back-ldbm
back-ldbm was both slow and unreliable. Its byzantine indexing code was
prone to spontaneous corruption, as were the underlying database libraries
that were commonly used (e.g. GDBM or NDBM). back-bdb and back-hdb are
superior in every aspect, with simplified indexing to avoid index corruption,
fine-grained locking for greater concurrency, hierarchical caching for
greater performance, streamlined on-disk format for greater efficiency
and portability, and full transaction support for greater reliability.
# $OpenLDAP$
# Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Configuration File Examples
H2: slapd.conf
H2: ldap.conf
H2: a-n-other.conf
personal_ws-1.1 en 1405
nattrsets
inappropriateAuthentication
api
olcAttributeTypes
BhY
reqEnd
olcOverlayConfig
shoesize
olcTLSCACertificateFile
CGI
cdx
DCE
DAP
attributename
lsei
dbconfig
arg
kurt
authzID
authzid
authzId
DAs
ddd
userApplications
BNF
attrs
mixin
wholeSubtree
chainingRequired
ldapport
hallvard
ASN
acknowledgements
Chu
ava
monitorCounter
del
DDR
testObject
OrgPerson
IGJlZ
olcUpdateref
ECC
deleteDN
cli
ltdl
CAPI
dev
serverctrls
olcDbDirectory
xvfB
BSI
modv
nonleaf
errCode
PhotoURI
buf
cdef
monitorConnectionLocalAddress
dir
EGD
dit
retoidp
ando
edu
caseExactSubstringsMatch
bvstrdup
AUTHNAME
memrealloc
auditExtended
replog
ludp
metainformation
CRL
CRP
olcReferral
XLDFLAGS
metadirectory
csn
siiiib
stateful
olcModulePath
maxentries
authc
seeAlso
searchbase
searchBase
realnamingcontext
dn's
DNs
DN's
dns
dereference
sortKey
authzTo
lossy
gcc
CWD
lssl
organizationalRole
DSA
derefInSearching
pwdGraceUseTime
DSE
groupOfURLs
modrdn
ModRDN
modrDN
pwdFailureCountInterval
homePhone
eng
paramName
errUnsolicitedData
Heimdal
EOF
authz
XINCPATH
LTFINISH
plaintext
indices
reqAssertion
olcDbUri
dst
env
oplist
MirrorMode
mirrormode
objclass
Bint
dup
hdb
gid
stderr
caseIgnoreOrderingMatch
moduledir
gif
jpegPhoto
lsasl
judgmentday
prepend
subentry
dbcache
mkversion
objectClasses
objectclasses
searchResultReference
fmt
qdescrs
olcSuffix
supportedControl
GHz
libpath
INADDR
compareDN
sizelimit
unixODBC
APIs
blen
attrsOnly
attrsonly
slappasswd
referralsPreferred
oids
OIDs
wBDARESEhgVG
syncIdSet
olcTLSCipherSuite
username
sizeLimitExceeded
subst
idl
chroot
iff
auditDelete
numbits
ZKKuqbEKJfKSXhUbHG
reqRespControls
TLSCertificateKeyFile
olcAccess
proxyTemplates
neverDerefaliases
RootDN
rootdn
loglevel
args
caseExactOrderingMatch
olcDbQuarantine
RELEASEDATE
baseDN
basedn
argv
GSS
schemachecking
whoami
WhoAmI
syslogd
dataflow
subentries
attrpair
BerkeleyDB's
singleLevel
entryDN
dSAOperation
includedir
inplace
LDAPAPIFeatureInfo
logbase
ing
moduleload
IPC
Makefile
getpid
GETREALM
numericString
MANSECT
XXXX
domainstyle
bvarray
Choi
iscritical
subschema
slapindex
plugin
distinguishedNameMatch
derefAliases
baseObject
kdz
reqMod
ldb
srcdir
pwdExpireWarning
localstatedir
sockbuf
PENs
ipv
IPv
ghenry
hyc
multimaster
noop
DEFS
joe
testAttr
syncrepl
pwdFailureTime
timestamp
whitespaces
ISP
ldp
monitorInfo
bjensen
newPasswd
irresponsive
len
perl
dynlist
browseable
attrvalue
pers
retcode
rootpw
matchedDN
auditReadObject
idletimeout
intermediateResponse
myOID
structuralObjectClass
integerMatch
openldap
OpenLDAP
moddn
rewriteEngine
AVAs
accesslog
searchDN
reqOld
MDn
aspell
TLSCACertificateFile
mem
peername
syncUUIDs
database's
krb
bool
logins
jts
memberAttr
newpasswdfile
newPasswdFile
ucdata
LLL
confdir
BerValues
olcDbLinearIndex
Elfrink
AUTOREMOVE
countp
realloc
bsize
CThreads
structs
desc
LTCOMPILE
bindmethod
olcDbCheckpoint
modme
refreshOnly
PIII
pwdPolicySubentry
FIXME
realanonymous
caseExactMatch
olcSizeLimit
Bourne
attr
objectidentifier
objectIdentifier
refint
msgtype
OBJEXT
LRL
subtrees
realdnattr
entrymods
admittable
libtool's
dupbv
searchResultEntry
lud
modifyTimestamp
TLSEphemeralDHParamFile