DSML Tools Functional Specification


Summary

LDAP2DSML – takes LDAP search params and writes the results as DSML.


Description


This program takes LDAP host and search parameters on the command line, connects to the given LDAP server and performs the search. It takes the results given and, according to options set, outputs them as a DSML file to stdout or a specified file.


The command syntax is as follows. Bold indicates a mandatory option.

LDAP2DSML <outfile> -h ldap.example.com [options]


Connection options:

--host

-h

LDAP host.

--port

-p

Port on the server to connect to. Default – 389.

--username

-u

Username. Omit for anonymous login.

--password

-w

Password. Omit for anonymous login.


Search options:

--basedn

-b

The base DN (distinguished name) for the search. Default – root.

--filter

-f

An LDAP filter string, e.g. “(objectclass=person)”. Default – no filter.

--attributes

-a

A comma-separated list of attributes to return. Default – all user attributes.

--maxresults

-z

Maximum number of results to return. Default – all.

(-z for compatibility with ldapsearch).

--scope

-s

Defines the scope of the search. Followed by one of the following keywords:

base – scope includes only the base DN

one – scope includes base DN and entries one level below it

sub – scope includes base DN and entries at all levels below it. Default.

--deref

-d

Defines how alias dereferencing is done during search. Followed by one of the following keywords:

never – never dereference

always – always dereference

search – dereference during searching only. Default.

find – dereference during finding of the base DN only.


Output options:

--contains

-c

Defines the contents of the DSML file. Followed by one of the following keywords:

schema – just schema information

data – just the data

all – both schema and data. Default.

--fullschema

-e

Output the entire directory schema, not just the bits referenced by the data.

--quick

-q

Quick mode – do not validate DSML documents

--help

-?

Prints a usage message.


E.g.:

LDAP2DSML –h ldap.example.com –u “cn=Fred Bloggs” –w SecretWord

–b “ou=Sales,o=Ace Ltd,c=us” –a “cn, email” –m 50 –s One > out.dsml


Notes


All error messages will be sent to stderr.


By default, the output DSML will contain only the schema information referenced by the output data (results of the search.) This can be overridden with –e.


LDAP2DSML will return an error if the LDAP search returns no results.


Summary

DSML2LDAP – takes DSML file and makes changes to an LDAP directory based on it.


Description


This program reads in DSML, either from a file or from stdin, connects to a specified LDAP server and executes add or delete operations based on options set and the contents of the DSML file.


The command syntax is as follows. Bold indicates a mandatory option.

DSML2LDAP <infile> -h ldap.example.com [-a|-d] [options]


Connection options:


--host

-h

LDAP host.

--port

-p

Port on the server to connect to. Default – 389.

--username

-u

Username. Omit for anonymous login.

--password

-w

Password. Omit for anonymous login.


Configuration options:

--add

-a

Adds the contents of the DSML file to the directory

--delete

-d

Deletes the contents of the DSML file from the directory



You must specify one of –a or –d.

--careful

-c

In “add” mode, this means we don’t overwrite entries that are already present. In “delete” mode, this means we only delete entries that are an exact match, rather than just matching on DN.


Other options:

--quick

-q

Quick mode – do not validate DSML documents

--help

-?

Prints a usage message.


E.g.:

DSML2LDAP –h ldap.example.com –u “cn=Fred Bloggs” –w SecretWord –a –c < in.dsml


Notes


If the schema of the directory and the DSML file are different, DSML2LDAP will remove incompatible bits of the entries to get the data into the directory.


In the case of addition, if there are objectclasses or attributes in the DSML schema which do not appear in the LDAP directory schema, then DSML2LDAP will print an error message for each entry where these objectclasses or attributes are found. It will then discard any such attributes or objectclasses from those entries as they are imported.


In the case of deletion, the schema (if any) in the DSML file will be ignored.

Summary

DSMLDiff – takes two DSML files and produces two files which represent a way of turning one set of directory data into the other one.


Description


This program reads in two DSML files, X and Y and produces two more DSML files, D1 and D2, such that:

X - D1 + D2 = Y


The diff is done at the “directory entry” level, i.e. Take X, remove all the entries in D2, add/replace all the entries in D1 and you have Y. Note that this is not symmetric, i.e. it is not the case that:

Y - D2 + D1 = X Wrong!


D1 will have no schema. D2 will have a schema built up from the two schemas in X and Y.


The command syntax is as follows. Bold indicates a mandatory option.

DSMLDiff <infileA> -s <subfile> -a <addfile> <infileB> [options]


Output options:

--subtract

-s

Output file to be subtracted from A.

--add

-a

Output file to be added to (A – <subtractfile>).

--nocomments

-c

Don’t add human-readable deletion comments to addition file.

--quick

-q

Quick mode – do not validate DSML documents

--help

-?

Prints a usage message.


E.g.:

DSMLDiff Fred.dsml Bill.dsml –s Subtractme.dsml –a Addme.dsml


Notes


D2 will contain information sufficient that, on its own, a human can understand, as far as is possible, the differences between the two directories.


If one or both input files don’t exist, or don’t contain valid DSML, DSMLDiff will print an error and exit.