ldap-filter: Filter out entries and attributes from an LDIF file
The rules file is written in YAML, a flexible, human-readable data encoding. Each filter is a map. The "index" of a rule is the position of the rule within the file.
The following fields are allowed in every filter:
nameA human-readable name to use in informational and error messages.
descriptionA longer description of what the rule does. So far this is not used for anything.
enabledA boolean value that indicates whether the rule is enabled or not. This allows you to easily disable a filter rule by simply adding this attribute. When this attribute is not supplied, the rule is considered enabled.
target [required]Indicates to what this rule applies. Must be one of the following:
ENTRYThe rule affects the entire entry. The entry as a whole is either accepted or dropped.
ATTRIBUTEThe rule affects only an attribute.
Specified attributes will be accepted (see ACCEPT QUICK below) or dropped.
actionThe action that will be triggered when the rule matches. Possible values are:
DROPWhen target is ENTRY then the entry is dropped immediately.
When target is ATTRIBUTE then the relevant attribute is removed from the entry (which is considered neither dropped nor accepted).
For example, the following rules will (1) delete any attributes called "dropme" or "deleteme", and (2) drop any entries that have "c=us", "c=ca", or "c=mx" in their DN.
--- target: ATTRIBUTE action: DROP rule: attr_exists attributes: - dropme - deleteme --- target: ENTRY action: DROP rule: dn_match segment: c values: - us - ca - mx
ACCEPTPlace the entry in the acceptance chain. An entry in the acceptance chain can be dropped at any time if a subsequent rule triggers the DROP action. If the entry is never dropped after all rules have been processed, then it will be emitted.
ACCEPT QUICKImmediately accept the entry or attribute. This means that no further rules can affect the same target. As a result, the order of the rules in the file become very important; it's possible to do something like the following:
--- target: ATTRIBUTE action: ACCEPT QUICK rule: attr_exists attributes: - keepme - ok --- target: ATTRIBUTE action: DROP rule: attr_exists attributes: - '*'
This example will remove all attributes except for "keepme" and "ok". If we had used an action of ACCEPT rather than ACCEPT QUICK then all attributes would have been removed, including "keepme" and "ok".
ruleIndicates the rule logic to follow. There are several available, see Rules below for more information.
A rule is essentially a predicate that is used to test some condition of the current LDAP entry. If a rule succeeds, then the action is applied. If not, then nothing happens. Rules are predefined; the complete list is below.
All rules are applied (in the order they are found in the rules file) to each entry. If a rule succeeds, then the action is set. For any DROP action, the entry is immediately dropped and the process continues with the next entry. For any ACCEPT action, the entry enters the acceptance chain. If any subsequent rule triggers the DROP action for that entry, it is dropped; otherwise after all rules are processed, the entry is emitted. Any entry that never triggers either a DROP or an ACCEPT action (i.e. no rules match) is implicitly dropped.
dn_exactMatches the full DN of the entry. The following additional fields are used:
values [required]A list of the values to match on. These are literal strings that the entry's DN must precisely equal.
dn_matchMatches the DN of the entry. The following additional fields are used:
segment [required]Indicates the name of the DN component to use for the matching. For example, specifying ou means that the DN has to contain an organizational unit that matches one of the given values.
values [required]A list of values to match on. These are literal strings, not regular expressions.
attr_existsChecks the presence of an attribute. The following additional fields are used:
classesA list of object classes for which this rule is in effect. This is used to remove certain attributes from entries that belong to certain object classes.
invertWhen true, indicates that the matching should be inverted.
target: ENTRY action: ACCEPT rule: attr_exists invert: true attributes: - foo - bar
The above will accept any entry which has neither "foo" nor "bar" in its attributes.
target: ATTRIBUTE action: DROP rule: attr_exists invert: true attributes: - abc - def
This will drop all attributes except "foo" and "bar" from the entry.
match_styleHow the attributes listed in attributes should be matched against the actual attribute names in the LDAP data. When exact, precise string comparisons are used. When glob, Unix shell glob patterns are used. When regexp, Perl regular expressions are used. The default value is exact.
attributes [required]A list of attribute names, each of which is removed if found.
attribute_valueCheck the value of an attribute. The following additional fields are used:
classesA list of object classes for which this rule is in effect. This is used to remove certain attributes from entries that belong to certain object classes.
invertWhen true, indicates that the matching should be inverted.
target: ENTRY action: ACCEPT rule: attribute_value invert: true attribute: lastName values: - Harrison - Lennon - McCartney - Starr
This will accept any entry that has an attribute called "lastName" which does not have a value that belongs to one of the Beatles.
target: ATTRIBUTE action: DROP rule: attribute_value invert: true attribute: someAttr values: - abcd - efgh
This will remove the "someAttr" attribute from any entry where it holds a value of either "abcd" or "efgh".
scopeIndicates the scope of the action. For the sake of examples, let's assume the following entry:
dn: cn=taylor,o=Metasyntax firstName: Taylor lastName: Venable pastResidence: Fort Wayne pastResidence: West Lafayette pastResidence: Chicago pastResidence: New York
The following values are accepted:
matchingThe action only affects the attribute with a value that matches. For example:
target: ATTRIBUTE action: DROP scope: matching attribute: pastResidence values: - Chicago - New York - Las Vegas
With the above rule, the example entry turns into the following:
dn: cn=taylor,o=Metasyntax firstName: Taylor lastName: Venable pastResidence: Fort Wayne pastResidence: West Lafayette
Because the attribute had some of the specified values, those values were removed from that attribute in the entry.
allThe action affects all the values of that attribute. For example:
target: ATTRIBUTE action: DROP scope: all attribute: pastResidence values: - Chicago - New York - Las Vegas
With the above rule, the example entry turns into the following:
dn: cn=taylor,o=Metasyntax firstName: Taylor lastName: Venable
As you can see, because the attribute had one of the specified values, the attribute was completely removed from the entry.
The default value is matching.
match_styleHow the attributes listed in attributes should be matched against the actual attribute names in the LDAP data. When exact, precise string comparisons are used. When glob, Unix shell glob patterns are used. When regexp, Perl regular expressions are used. The default value is exact.
Note that regexp is not yet implemented and will cause an error.
attribute [required]The attribute to affect.
values [required]A list of values, which when matched according to match_style, cause the action to execute.
The following format is used to log information:
DATE TIME LEVEL [LOGGER] <RULE> ACTION TARGET ...
Note that in log messages, the rule is a zero-based index indicating the position of the rule as defined within the filter file. This is done to conserve space in the log output. The rule name is used in error messages.