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 :)
  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).


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 the first value or not. If you provide one of the following regexparts,
the filter you provide (or the default filter) will be used as-is:
that is: s//, s/^/, s/$/ and s/^$/. This way, also entries with no value for
the requested attribute will be considered in the search operation
and the replace-value will be added to the first value of the entry.
If you want to create multivalued attributes, use `ldapadd`.
Since 0.9.3-1 there is an additional -F switch that always overrides filter
tuning and will use the 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 there is a new append mode. If you provide the attribute name with
-A instead of -a, the regex is evaluated against an dummy empty value after
it was evaluated against the present attribute values. Since LDAP does not know
"empty" attribute values, the result is, that the replace value will be added
as new attribute value.
For example -A with s/^$/foo/ we will add "foo" as new value to an attribute. In
this special case no present attribute values will be modified, because as
already said, LDAP does not know "empty" values.
However, -A with s/^/foo/ will prepend every present value with "foo". After
that, a fresh value "foo" will be added as new value.

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.

Have fun!