| Previous | Next | Contents | Index |
Each DIRBOT needs to know what to do with each LDIF file it might be
sent, as well as the secret it needs to sign directories and check
signatures on directories. It also needs to know the e-mail address of
a responsible person so that if it runs into difficulties it can send
for help. All this information is held in the SYNC_DIRBOT channel
option file; since the channel name is typically sync_dirbot_local,
this file is typically
/pmdf/table/sync_dirbot_local_option (unix) or
PMDF_TABLE:sync_dirbot_local_option. (OpenVMS) or
C:\pmdf\table\sync_dirbot_local_option (NT).
Since the channel option file contains the shared secret used for verifying and constructing signatures on directory information, note that it should be protected against world access.
The format of this option file is similar to that of the PMDF Dispatcher configuration file, in that it is an option file with subsections marked by
[DIRECTORY=directory-name] |
directory-name is a directory name, one
such section for each directory that the SYNC_DIRBOT channel (DIRBOT)
must handle. The options within a directory section are specific to
that directory, telling the SYNC_DIRBOT channel how to handle that
directory. Global options are specified at the top of the option file
before any of the directory specific sections.
The following options are global options (that can appear at the top of the file):
DIRECTORY_MASTER (RFC 822 address)
This specifies the e-mail address of the person to receive exception reports from the DIRBOT.LEAVE_TEMPS (0 or 1)
Setting this option to 1 causes the DIRBOT not to delete temporary files, which can be useful for debugging purposes. The default value is 0, meaning that temporary files are deleted.REQUIRED_DIRECTORIES (comma-separated list of directory names)
This specifies the directories that must be present in order to perform differencing and generate an authoritative directory snapshot; until all the specified directories are present, differencing will not occur. If more directories are required than is convenient to specify on one line, additional REQUIRED_DIRECTORIES_n options can be used to complete the list of required directories.REQUIRED_DIRECTORIES_n (comma-separated list of directory names)
REQUIRED_DIRECTORIES_1, REQUIRED_DIRECTORIES_2, etc., options can be used to extend the list of required directories beyond those specified with the REQUIRED_DIRECTORIES option.SECRET (string)
This specifies the shared secret for verifying and constructing signatures.SEND_BULK_LOAD_TO (comma-separated list of directory names)
This specifies the list of directories which need to receive a copy of the current entire authoritative directory each time the DIRBOT generates an authoritative directory snapshot. That is, this option lists the directories which require a complete copy (an absolute bulk load rather than delta differences) of the authoritative directory.
The following options are directory specific options (that can appear only in directory sections):
BEST_WITHIN (integer)
The DIRBOT's differencing and merging processes leave a.oldLDIF file for each directory after performing their processing. In some setups, some directories can not send updates as frequently as other directories; in such cases, rather than having all processing wait for the updates of the "infrequent" directory, it can be more useful to go ahead and use the "stale".oldinformation for the "infrequent" directory when more frequent directories have supplied their update information. Also on some occasions, as for testing or recovering from problems, it can be useful to reprocess.olddirectory LDIF files, even for directories that normally send frequent updates, as if they were new. If BEST_WITHIN is specified in a directory section then, when a directory is needed for differencing or merging, and if a new LDIF file for it isn't present but a.oldfile is present, then the.oldwill be used for the differencing or merging. The BEST_WITHIN value is interpreted as a number of hours; if the.oldfile is older than this, then a warning message will be logged in the log file warning of the health risks of using stale data. See also the related DISCARD_AFTER option.BULK_LOAD (next-process or next-process|dirbot-address)
The BULK_LOAD option tells the DIRBOT where to send a copy of the entire authoritative directory snapshot, and how to mark this entire authoritative directory snapshot for further processing, (the required processing usually being SERVE). If no address is specified, then this very DIRBOT performs the specified processing on the entire authoritative directory snapshot; if an address is specified, then it is the address of theDIRBOTto which to send the entire authoritative directory snapshot. For instance,
means to send the entire authoritative directory snapshot to
BULK_LOAD=SERVE|dirbot@dirsync.example.comdirbot@dirsync.example.com, marked as requiring serving (changing from canonical form to directory specific form). Normally each particular directory section will specify one or the other ofDIFForBULK_LOAD, not both, according to the capabilities of the directory -- whether the directory can handle delta updates (the result of differencing), or can only handle absolute updates (a complete authoritative directory snapshot).COOK (file-spec|next-process or file-spec|next-process|dirbot-address)
TheCOOKoption specifies a recipe file containing cooking instructions (the instructions for how to turn a directory specific LDIF file into a canonical LDIF file), and the next process to perform after cooking the information (usually DIFF), and optionally the address of anotherDIRBOTto which to send the cooked file and process instruction. If aDIRBOTaddress is not specified, this veryDIRBOTperforms that next processing. For instance,
specifies that cooking instructions can be found in the file
COOK=/pmdf/table/ccmail.rcp|DIFF|dirbot@dirsync.example.com/pmdf/table/ccmail.rcpand that after cooking, the cooked (canonical form) LDIF file should be sent to dirbot@dirsync.fibula.org with instructions to perform differencing on the cooked file. See Table 37-1 for a list of which next process values are valid in a COOK option.COPY (name1,proc1;...;nameN,procN|nex tproc or
The current directory is copied to the specified output directories, name1,..., nameN. Each of the new output directories also has a next process specified, proc1, ..., procN. The original directory's next process is nextproc and a DIRBOT to execute that next process can optionally be specified as nextdirbot. For instance, to make three copies of a Lotus Notes directory, and specify that the next process for the original Lotus Notes directory should be a
name1,proc1;...;nameN,procN|next proc|nextdirbot)MERGEsent todirbot@dirsync.example.com, one might use:
In this example, the STOP process is used for each of the new directory copies on the assumption that some other processing is already awaiting the creation of these copies---for instance, some other directories might be waiting to MERGE the Lotus Notes directory copies with their own data.
COPY=ln2,STOP;ln3,STOP;ln4,STOP|MERGE|dirbot@dirsync.example.comDIFF (next-process or next-process|dirbot-address)
The DIFF option tells the DIRBOT where to send the output of the differencing step and how to mark that output for further processing (the required processing usually being SERVE). If no address is specified, then this very DIRBOT performs the specified processing on the differencing output; if an address is specified, then it is the address of the DIRBOT to which to send the differencing output. For instance,
means to send the output of differencing to dirbot@host2.dirsync.example.com, marked as requiring serving (changing from canonical form to directory specific form). Normally each particular directory section will specify one or the other of DIFF or BULK_LOAD, not both, according to the capabilities of the directory -- whether the directory can handle delta updates (the result of differencing), or can only handle absolute updates (a complete authoritative directory snapshot).
DIFF=SERVE|dirbot@dirsync.example.comDISCARD_AFTER (integer)
When BEST_AFTER is specified in a directory section, then the DIRBOT will use.oldLDIF data for that directory for differencing or merging rather than insisting upon new LDIF data for the processing. DISCARD_AFTER can be used to specify the maximum age, in hours, of such.oldlike that can be used. If the.oldfile is older than this age, the differencing or merging will not proceed until a new LDIF file for the directory is received.EXCLUDE (comma-separated list of attributes)
The EXCLUDE option is optional. It tells the differencer to use all but the specified attributes during the differencing. This can be useful if you are trying to synchronize directories of mixed ability, for instance X.500, Lotus Notes and cc:Mail. You likely want to keep many attributes in the authoritative directory for the benefit of X.500 and Notes, but you want to ignore most of them when working on the cc:Mail directory. Normally, each particular directory section would specify at most one of EXCLUDE or INCLUDE, not both. By default, if neither EXCLUDE nor INCLUDE is specified, all attributes are using during differencing.INCLUDE (comma-separated list of attributes)
The INCLUDE option is optional. It tells the differencer to use only the specified attributes during the differencing. This can be useful if you are trying to synchronize directories of mixed ability, for instance X.500, Lotus Notes and cc:Mail. You likely want to keep many attributes in the authoritative directory for the benefit of X.500 and Notes, but you want to ignore most of them when working on the cc:Mail directory. Normally, each particular directory section would specify at most one of EXCLUDE or INCLUDE, not both. By default, if neither EXCLUDE nor INCLUDE is specified, all attributes are using during differencing.MERGE (other-dirname,new-dirname|next-process or
The MERGE option specifies that for entries already in the current directory, any additional attributes for those entries found in other-dirname, are to be added to them (though entirely new entries will not be added) and a new directory, new-dirname, created. next-process specifies the next process to perform after the merge, that is, the process to apply to the new (merged) directory. Note that new-dirname must be a new directory name: one must not attempt to MERGE into an existing directory name, since the subsequent processing (the next-process step) is triggered by the presence of a new-dirname directory. If one were to attempt to MERGE into an old directory name, the next-process step would be performed when the old directory first arrived, rather than being performed on the newly created, merged directory. Note that the current directory and the other-dirname directory are deleted by the MERGE processing; if you want to retain an original directory, first use the COPY option to copy the original directory to a new directory and then merge that new directory.
other-dirname,new-dirname|next-process|ne xt-dirbot)SERVE (file-spec|next-process or file-spec|next-process|dirbot-address)
This specifies a recipe file containing serving instructions (the instructions for how to turn a canonical LDIF file back into a directory specific LDIF file), and the next process to perform after serving the information back to directory specific form (usually APPLY), and optionally the address of another DIRBOT to which to send the cooked file and process instruction. If a DIRBOT address is not specified, this very DIRBOT performs that next processing. For instance,
specifies that serving instructions can be found in the file
SERVE=/pmdf/table/ccserve.rcp|APPLY|dirbot@dirsync.carrot.example.com/pmdf/table/ccserve.rcpand that after serving, the served (directory specific form) LDIF file should be sent to dirbot@dirsync.carrot.example.com with instructions to apply the directory update.SERVE_TO_STALE (0 or 1)
For a directory for which BEST_AFTER has been set, the SERVE_TO_STALE option controls whether directory updates will be served back to the directory in question when "stale" information for it is being used during the differencing processing. The default is SERVE_TO_STALE=0, meaning that directory updates will only be sent back to the directory in question when new directory information is available from the directory. Setting SERVE_TO_STALE=1 will cause directory update information to be sent even if "stale" information is being used as input from the directory in question.RENAME (dirname|next-process)
This option changes the name associated with a directory. This option can be useful with the MERGE option: after merging, a new directory can be renamed back to the original directory name.
| Next Process | ||||||||
|---|---|---|---|---|---|---|---|---|
| Option | COOK | SERVE | DIFF | MERGE | RENAME | COPY | STOP | APPLY |
| COOK | Yes | Yes | Yes | Yes | ||||
| SERVE | Yes | Yes | ||||||
| DIFF | Yes | Yes | Yes | |||||
| MERGE | Yes | Yes | Yes | Yes | ||||
| RENAME | Yes | Yes | ||||||
| COPY | Yes | Yes | Yes | Yes | ||||
37.5.2.1 Examples of DIRBOT Work Orders
Example 37-1 shows a sample SYNC_DIRBOT channel option file on unix.
This example corresponds to a site example.com with three directories
to synchronize, cc:Mail, X.500, and Lotus Notes. The X.500 and Lotus
Notes directories can accept delta updates (the result of
differencing); the cc:Mail directory can only accept absolute updates
(bulk loads).
| Example 37-1 Sample SYNC_DIRBOT Channel Option File on unix |
|---|
DIRECTORY_MASTER=postmaster@example.com SEND_BULK_LOAD_TO=ccmail SECRET=secret REQUIRED_DIRECTORIES=x500,lotusnotes,ccmail ! [DIRECTORY=x500] COOK=/pmdf/table/x500_cook.rcp|DIFF DIFF=SERVE EXCLUDE=maildomain SERVE=/pmdf/table/x500_serve.rcp|APPLY|dirbot@dirsync.x500.example.com ! [DIRECTORY=lotusnotes] COOK=/pmdf/table/ln_cook.rcp|DIFF DIFF=SERVE EXCLUDE=maildomain SERVE=/pmdf/table/ln_serve.rcp|APPLY|dirbot@ln.example.com ! [DIRECTORY=ccmail] COOK=/pmdf/table/cc_cook.rcp|DIFF BULK_LOAD=SERVE SERVE=/pmdf/table/cc_serve.rcp|APPLY|dirbot@dirsync.carrot.example.com |
A typical complete processing cycle for the SYNC_DIRBOT channel whose option file is shown in Example 37-1 would be:
/pmdf/table/ln_cook.rcp. After
cooking (canonicalization) of the LDIF file, the SYNC_DIRBOT channel
performs sifting automatically---generating an additional file
containing authoritative records extracted from the cooked Lotus Notes
LDIF file.
/pmdf/dirsync.
/pmdf/table/x500_cook.rcp. After cooking
(canonicalization) of the LDIF file, the SYNC_DIRBOT channel performs
sifting automatically---generating an additional file containing
authoritative records extracted from the cooked X.500 LDIF file.
/pmdf/dirsync.
/pmdf/table/cc_cook.rcp. After cooking
(canonicalization) of the LDIF file, the SYNC_DIRBOT channel performs
sifting automatically---generating an additional file containing
authoritative records extracted from the cooked cc:Mail LDIF file.
/pmdf/table/x500_serve.rcp recipe file, and the served
result sent with an APPLY instruction to
dirbot@dirsync.x500.example.com.
/pmdf/table/ln_serve.rcp recipe file, and the served
result sent with an APPLY instruction to dirbot@ln.example.com.
Example 37-2 shows a sample SYNC_DIRBOT channel option file on OpenVMS. This example corresponds to a site example.com with three "directories" to synchronize, where two are "real" directories, X.500 and Lotus Notes, and the third "directory" is the PMDF alias database. The X.500 and Lotus Notes directories can accept delta updates (the result of differencing). The PMDF alias database is a directory data sink (destination) only; information garnered from the X.500 and Lotus Notes directories will be used to update the alias database. Comparing with the similar Example 37-2 but where the third directory is cc:Mail which is used as a information source, note that in this example with the alias database as the third directory that the alias database is neither listed on the REQUIRED_DIRECTORIES line, nor does it have a COOK line -- the alias database is not a source of information.
| Example 37-2 Sample SYNC_DIRBOT Channel Option File on OpenVMS |
|---|
DIRECTORY_MASTER=postmaster@example.com SEND_BULK_LOAD_TO=aliasdb SECRET=secret REQUIRED_DIRECTORIES=x500,lotusnotes ! [DIRECTORY=x500] COOK=PMDF_TABLE:x500_cook.rcp|DIFF DIFF=SERVE EXCLUDE=maildomain SERVE=PMDF_TABLE:x500_serve.rcp|APPLY|dirbot@dirsync.x500.example.com ! [DIRECTORY=lotusnotes] COOK=PMDF_TABLE:ln_cook.rcp|DIFF DIFF=SERVE EXCLUDE=maildomain SERVE=/pmdf/table/ln_serve.rcp|APPLY|dirbot@ln.example.com ! [DIRECTORY=aliasdb] BULK_LOAD=SERVE SERVE=PMDF_TABLE:alias_serve.rcp|APPLY|dirbot@dirsync.carrot.example.com |
A typical complete processing cycle for the SYNC_DIRBOT channel whose option file is shown in Example 37-2 would be:
/pmdf/table/ln_cook.rcp. After
cooking (canonicalization) of the LDIF file, the SYNC_DIRBOT channel
performs sifting automatically---generating an additional file
containing authoritative records extracted from the cooked Lotus Notes
LDIF file.
/pmdf/dirsync.
/pmdf/table/x500_cook.rcp. After cooking
(canonicalization) of the LDIF file, the SYNC_DIRBOT channel performs
sifting automatically---generating an additional file containing
authoritative records extracted from the cooked X.500 LDIF file.
Example 37-3 shows a sample SYNC_DIRBOT channel option file on unix involving merging two directories. This example involves three main directories. A cc:Mail and Lotus Notes directory require delta updates; a GroupWise directory requires absolute updates. The GroupWise directory, however, contains additional attributes that should be added to any already existing cc:Mail or Lotus Notes entries.
| Example 37-3 Sample SYNC_DIRBOT Option File with MERGE |
|---|
DIRECTORY_MASTER=dirmaster@example.com SEND_BULK_LOAD_TO=groupwise SECRET=secret REQUIRED_DIRECTORIES=ccmailplus,notesplus ! [DIRECTORY=groupwise] COOK=/pmdf/table/cook_groupwise.rcp|COPY COPY=groupwise2,STOP|STOP BULK_LOAD=SERVE EXCLUDE=notesname,ccmailname SERVE=/pmdf/table/serve_groupwise.rcp|APPLY|dirbot@gw.spinach.example.com ! [DIRECTORY=notes] COOK=/pmdf/table/cook_notes.rcp|MERGE MERGE=groupwise2,notesplus|DIFF SERVE=/pmdf/table/serve_notes.rcp|APPLY|dirbot@ln.example.com ! [DIRECTORY=notesplus] DIFF=RENAME RENAME=notes,SERVE ! [DIRECTORY=ccmail] COOK=/pmdf/table/cook_ccmail.rcp|MERGE MERGE=groupwise|ccmailplus|DIFF SERVE=/pmdf/table/serve_ccmail.rcp|APPLY|dirbot@ccsync.carrot.example.com ! [DIRECTORY=ccmailplus] DIFF=RENAME RENAME=ccmail|SERVE |
A typical complete processing cycle for the SYNC_DIRBOT channel whose option file is shown in Example 37-2 would be:
/pmdf/table/cook_notes.rcp. After
cooking (canonicalization) of the LDIF file, the SYNC_DIRBOT channel
performs sifting automatically---generating an additional file
containing authoritative records extracted from the cooked Lotus Notes
LDIF file.
groupwise2 directory) required for the merge with the
Lotus Notes directory is yet present; since it is not, the cooked and
sifted Lotus Notes LDIF files remain in the PMDF-DIRSYNC work directory.
/pmdf/table/cook_groupwise.rcp. After
cooking (canonicalization) of the LDIF file, the SYNC_DIRBOT channel
performs sifting automatically---generating an additional file
containing authoritative records extracted from the cooked GroupWise
LDIF file.
groupwise, has
its cooked LDIF file and its sifted LDIF file copied to a new (and in
this setup, temporary) directory named groupwise2. Note
that there are two files for each copy; that is, the new
groupwise2 directory has both a cooked LDIF file (a copy
of the original GroupWise directory's cooked LDIF file) and a sifted
LDIF file (a copy of the original GroupWise directory sifted cooked
LDIF file). The new directory (two new files) will be used to merge
attributes coming from GroupWise into the existing entries from Lotus
Notes. Similarly, the original groupwise directory will be
used to merge attributes into existing entries coming from cc:Mail. The
STOP process is specified for both the new copy and the original
GroupWise directory copy, since these directories need no further
processing of their own; they will simply be used as input in the MERGE
options for the Lotus Notes and cc:Mail directories.
groupwise2
directories are indeed now present, so for any existing entries in the
Lotus Notes directory, additional attributes present in the
groupwise2 directory are added to create a new, Lotus
Notes plus extra attributes directory named notesplus.
More specifically, the cooked LDIF groupwise2 file is
merged into the cooked LDIF notes file to result in a
cooked LDIF notesplus file, and the sifted LDIF
groupwise2 file is merged into the sifted LDIF
notes file to result in a sifted LDIF
notesplus file. The original cooked and sifted Lotus Notes
notes, LDIF files and the groupwise2. cooked
and sifted LDIF files are deleted by this MERGE processing. No other
merging can yet be performed, since the cc:Mail directory is not yet
present.
notesplus, directory is present, the
ccmailplus directory has not yet been generated, so
differencing can not yet be performed.
/pmdf/table/cook_ccmail.rcp. After
cooking (canonicalization) of the LDIF file, the SYNC_DIRBOT channel
performs sifting automatically---generating an additional file
containing authoritative records extracted from the cooked cc:Mail LDIF
file.
groupwise directory) required for the merge with the
cc:Mail directory is yet present. It is indeed present, so for any
existing entries in the cc:Mail directory, additional attributes
present in the groupwise directory are added to create a
new, cc:Mail plus extra attributes directory named
ccmailplus. Note that, as with any MERGE operation, MERGE
actually operates on two files per directory, the cooked LDIF file and
the sifted LDIF file, to result in two new files for a new directory.
The old cc:Mail cooked LDIF and sifted LDIF files, and the
groupwise cooked LDIF and sifted LDIF files, are all
deleted. There is no other merging to perform, since the other
directories required for merging, Lotus Notes and
groupwise2 are no longer present---they were present, but
processed and deleted at an earlier step.
notesplus and
ccmailplus directories are indeed both now present, so the
SYNC_DIRBOT channel performs differencing on the two input directories.
Differencing generates an absolute update (suitable for bulk loads) by
concatenating the two sifted LDIF files. Differencing also generates a
delta update by comparing each of the two cooked LDIF files with the
absolute update (the concatenation of all the sifted LDIF files). (A
delta update is only generated if there exists at least one directory
with a DIFF option.)
ccmailplus directory's DIFF option specfies a
RENAME as the next processing step. So the ccmailplus
directory is accordingly renamed to ccmail -- the name of
the original cc:Mail directory---and SERVE processing is requested.
/pmdf/table/serve_ccmail.rcp,
SERVE recipe file, and the served delta directory update is sent with
an APPLY instruction to dirbot@ccsync.carrot.example.com.
notesplus directory's DIFF option specfies a
RENAME as the next processing step. So the notesplus
directory is accordingly renamed to notes -- the name of
the original Lotus Notes directory---and SERVE processing is requested.
/pmdf/table/serve_notes.rcp,
SERVE recipe file, and the served delta directory update is sent with
an APPLY instruction to dirbot@ln.example.com.
| Previous | Next | Contents | Index |