Read Me

ldap-preg_replace.pl README
---------------------------

This is a brief description of ldap-preg_replace.pl, a tool written in perl
that you can use to change values of attributes in a directory service online.
Because it uses regular expressions it is very powerful but remains easy.
It is able to process very much entries, and should be only limited to
the sizelimit configuration of your LDAP server.

TODOs:
- None at the moment, it should be feature complete already :)
- Maybe we should introduce some "adding" mode, so it is possible to add attributes
  based on matches of the current present values...
- Please feel free to suggest new features via ths SF-Tracker.

I. Prerequisites and installing
Installation is not neccessary. Just make the file executable
if it is not already, or run the script through `perl`.
However, before you can run this program, you need:
  * PERL installed (perl.org)
  * PERL modules 'Net::LDAP' and 'Getopt::Std'. Both should be available
    in your linux distributions package archive, otherwise fetch them from
    CPAN (this applies also for windows users)


II. General
Usage is very easy. Just call the script and provide the neccessary
command line parameters. To learn what parameters are available, call
`ldap-preg_replace.pl -h` which will print out basic usage and some extended
informations including usage examples.
Calling just ldap-preg_replace.pl without parameters gives you the
short version (usage information).
The program will only modify already present attribute values in default mode.
However, adding values is possible.


III. Internals
The tool first connects and binds to the LDAP server you provide using
parameters. Then it searches with some LDAP filter that differs wether you
provided some extra filter component or not.
If you provided some extra filter, the filter will look like this:
   (&($attribute=*)$extrafilter)
where $attribute is the value of parameter "-a" and $extrafilter the value
of parameter "-f". So for example `ldap-preg_replace.pl -a foo -f 'bar=123'`
will search with the filter '(&(foo=*)(bar=123))'.
The filter becoms more easy if you are not providing some extra filter:
  ($attribute=*)
This allows for a very flexible and performant replacement since only those
entries are considered at all, that have some values inside the attribute
you want to replace something in.

Since 0.9.3 the regex you provide will be examined to decide wether you want to
add a value or just want to operate on existing ones. To speed the search up,
this examination will be used to modify the filter you provide.
Since 0.9.3-1 there is an additional -F switch that always overrides filter
tuning and will use your provided filter (or the default one) as-is.
This might be especially useful in situations where the built in regex analysis
does not detect (see with verbose switch -v) an empty from-regex which will
happen, for example, if you use alternative regex delimeters.
Long story short, with -F you have maximun flexibility over the search filter.

After the tool performed the search, it will run through every entry.
For each entry it will loop through all values of the named attribute and
tries to apply the regular expression given by parameter "-r". If something
changed after processing all values the entry will be updated.
Then the next entry will be processed.

Since 0.9.4 it is possible to add values more flexible:
Because LDAP does not know empty value strings, we can interpret the meaning
of the /^$/ (empty string) pattern. This tool interprets it depending on
the mode it is running in (indicated by either -a or -A) and interprets it as
"replace empty attribute with something".
In normal mode (-a), you thus can add values to an empty attribute.
In append mode (-A), it is assumed, that each attribute (regardless if it has
values or not) serves an "empty string", enabling you to add values also to
multivalued attributes already having some values.
Because this attribute adding stuff is somewhat basic, we strongly suggest
you use the tool `ldapadd`.

For more information on regular expressions, feed your favorite search engine
with something like "perl regular expressions replace syntax".
Try also `ldap-preg_replace.pl -h` which gives some short examples for common tasks.

Have fun!