Splat Helper Modules are implemented as a Python module containing
a single subclass of
splat.plugin.Helper
. The subclass must
implement three methods: parseOptions
,
work
, and
attributes
.
For a working example, refer to the SSH public key helper located
in splat/helpers/sshPublicKeys.py
.
Example 3.1. Skeleton of Splat Helper Module
class MyHelper(splat.plugin.Helper): @classmethod def attributes(self): ... @classmethod def parseOptions(self, options): ... def work(self, context, ldapEntry, modified): ...
If an error occurs, your module must raise an exception of type
splat.plugin.SplatPluginError
, with an error
message provided as the second argument. This error will be presented
to the user by the splat daemon.
raise splat.plugin.SplatPluginError, "No such user"
Logging is provided by the standard logging module. To find the
Splat logger, use splat.LOG_NAME
:
logger = logging.getLogger(splat.LOG_NAME)
Helper-specific configuration options may be specified in the
splat.conf
configuration file. These options are
passed to the helper's parseOptions
method as
a dictionary of key/value strings. These options are not validated by
the configuration parser -- it is your responsibility to validate
these strings and convert them to the appropriate data type.
Example 3.2. Helper Module parseOptions() Method
def parseOptions(self, options): context = {} for key in options.keys(): if (key == 'minuid'): context['minuid'] = int(options[key]) continue raise splat.plugin.SplatPluginError, "Invalid options '%s' specified." % key return context
The splat daemon will perform an LDAP search on the helper's
behalf, filter based on group restrictions, and pass individual LDAP
Entry
instances to the
work
method. The following method arguments
are provided:
The opaque configuration context corresponding with the supplied entry.
An LDAP Entry
instance..
If true, the supplied LDAP entry has been modified since
the last successful helper iteration. This
can be used to avoid doing unnecessary work in the helper, such
as overwriting identical ssh keys.
modified
will also be set to
true if the modifyTimestamp
attribute was not found in an LDAP entry. This helps ensure
that helpers will still be able to function when this
attribute is not available for whatever reason.
The Entry
class provides two instance
variables: dn
and attributes
.
The dn
variable provides the corresponding LDAP
object's full DN
, while
attributes
provides a dictionary of LDAP attributes
and corresponding lists of values. The desired LDAP object attributes
must be provided by the attributes()
method
of your splat.plugin.Helper
subclass; these
LDAP attributes will used in the LDAP search and will be returned if
available.
In addition to any requested attributes, the
modifyTimestamp
operational attribute
will always be returned. This can be used by your helper to determine
if any work should be done; For example, the SSH Public Key helper
will stat()
the user's key file and compare the
two modification dates to determine whether the key should be
updated.
The helper's attributes()
method
defines the LDAP object attributes that you are interested in -- an
LDAP Entry will still be returned if it does not contain all of your
requested attributes, and/or the
modifyTimestamp
attribute. It is your
responsibility to ensure that any attributes required by your helper
are supplied.
Example 3.3. Helper Module attributes() and work() Methods
class MyHelper(splat.plugin.Helper): def attributes(self): return ('uid', 'sshPublicKey') def work(self, context, ldapEntry, modified): # If the entry has not been modified since our last run, skip it. if (not modified): return if (not ldapEntry.attributes.has_key('sshPublicKey')) return key = attributes.get('sshPublicKey')[0]