Built-In Extensions¶
Description Attributes¶
Support for structured description fields.
This implements the common pattern of storing arbitrary key=value data in description fields, but presents an attribute-like interface to access and change them.
Example:
from laurelin.ldap import LDAP
LDAP.activate_extension('laurelin.extensions.descattrs')
with LDAP() as ldap:
result = ldap.base.get_child('cn=someObject')
result.add_desc_attrs({'foo':['one', 'two']})
print(result.format_ldif())
# ...
# description: foo=one
# description: foo=two
# ...
attr_vals = result.desc_attrs().get_attr('foo')
print(attr_vals)
# ['one', 'two']
result.replace_desc_attrs({'foo':['one','two','three']})
result.delete_desc_attrs({'foo':['two']})
attr_vals = result.desc_attrs().get_attr('foo')
print(attr_vals)
# ['one', 'three']
print(result.format_ldif())
# ...
# description: foo=one
# description: foo=three
# ...
-
class
laurelin.ldap.
LDAPObject
[source] The following new methods get bound to
laurelin.ldap.LDAPObject
upon extension activation:-
desc_attrs
()¶ Query the description attribute if unknown and return an
AttrsDict
representing the data stored in the description.Returns: An AttrsDict
representing the data stored in the description.Return type: AttrsDict
-
add_desc_attrs
(attrs_dict)¶ Add new description attributes.
Parameters: attrs_dict (dict(str, list[str]) or AttrsDict) – Dictionary of description attributes to add Return type: None
-
NIS Netgroups¶
Extension adding netgroup support to laurelin.
Includes schema definitions.
You should begin by tagging the base object which all netgroups are below, and defining the RDN attribute and scope. If
the structure is flat there is a performance advantage by setting relative_search_scope=Scope.ONE
:
from laurelin.ldap import LDAP, Scope
netgroups_extension = LDAP.activate_extension('laurelin.extensions.netgroups')
with LDAP() as ldap:
netgroups = ldap.base.obj('ou=netgroups',
tag=netgroups_extension.TAG,
relative_search_scope=Scope.ONE,
rdn_attr='cn')
Member Lists¶
This extension module allows a shortcut to specify members of netgroups. Any function with a members
argument uses
this feature.
The function name will tell you whether it expects users (e.g., LDAP.add_netgroup_users()
) or hosts (e.g.
LDAP.add_netgroup_hosts()
). If you just specify a string in your member list, it will be assumed to be either a
user or a host accordingly.
You can also specify a tuple with up to 3 elements for any member list entry. These fields must correspond to the
nisNetgroupTriple
fields: host, user, and domain. For user functions, at least the first 2 tuple elements must be
specified. For host functions, only the first is required, the 2nd (user) field will be assumed as an empty string. In
all cases, the domain can be specified for all members by passing the domain
argument to the function (it defaults
to an empty string).
The third option for member list entries is to specify the full nisNetgroupTriple
yourself in a string.
Finally, you can specify a memberNisNetgroup
by prefixing the entry with a +
symbol. For example: +users
.
Examples:
users = [
'alice',
'bob',
('dir.example.org', 'admin'),
'(dir.example.org,manager,example.org)',
]
ldap.add_netgroup_users('cn=managers,ou=netgroups,dc=example,dc=org', users, domain='example.org')
# Adds the following nisNetgroupTriples:
# (,alice,example.org)
# (,bob,example.org)
# (dir.example.org,admin,example.org)
# (dir.example.org,manager,example.org)
# Does not add any memberNisNetgroups
hosts = [
'dir1.example.org',
'dir2.example.org',
'(dir3.example.org,,)',
('dir4.example.org',),
'+aws_backup_dir_servers',
]
ldap.add_netgroup_hosts('cn=dir_servers,ou=netgroups,dc=example,dc=org', hosts)
# Adds the following nisNetgroupTriples:
# (dir1.example.org,,)
# (dir2.example.org,,)
# (dir3.example.org,,)
# (dir4.example.org,,)
# Adds the following memberNisNetgroup:
# aws_backup_dir_servers
-
netgroups.
TAG
= 'netgroup_base'¶
-
netgroups.
NETGROUP_ATTRS
= ['cn', 'nisNetgroupTriple', 'memberNisNetgroup', 'objectClass']¶
-
netgroups.
OBJECT_CLASS
= 'nisNetgroup'¶
-
class
laurelin.ldap.
LDAP
[source] The following new methods get bound to
laurelin.ldap.LDAP
upon extension activation:-
get_netgroup
(cn, attrs=NETGROUP_ATTRS)¶ Find a specific netgroup object.
This depends on the base object having been tagged and configured properly. See
laurelin.extensions.netgroups
.Parameters: Returns: The netgroup object
Return type: Raises: TagError – if the base object has not been tagged.
-
netgroup_search
(filter, attrs=NETGROUP_ATTRS)¶ Search for netgroups.
This depends on the base object having been tagged and configured properly. See
laurelin.extensions.netgroups
.Parameters: Returns: An iterator over matching netgroup objects, yielding instances of
LDAPObject
.Return type: Raises: TagError – if the base object has not been tagged.
-
get_netgroup_users
(cn, recursive=True)¶ Get a list of all user entries for a netgroup.
This depends on the base object having been tagged and configured properly. See
laurelin.extensions.netgroups
.Parameters: Returns: A list of usernames
Return type: Raises: TagError – if the base object has not been tagged.
-
get_netgroup_hosts
(cn, recursive=True)¶ Query a list of all host entries for a netgroup.
This depends on the base object having been tagged and configured properly. See
laurelin.extensions.netgroups
.Parameters: Returns: A list of hostnames
Return type: Raises: TagError – if the base object has not been tagged.
-
get_netgroup_obj_users
(ng_obj, recursive=True)¶ Get a list of netgroup users from an already queried object, possibly querying for memberNisNetgroups if
recursive=True
(the default).Parameters: - ng_obj (LDAPObject) – A netgroup LDAP object
- recursive (bool) – Set to False to only consider members of this group directly
Returns: A list of usernames
Return type:
-
get_netgroup_obj_hosts
(ng_obj, recursive=True)¶ Get a list of netgroup hosts from an already queried object, possibly querying for memberNisNetgroups if
recursive=True
(the default).Parameters: - ng_obj (LDAPObject) – A netgroup LDAP object
- recursive (bool) – Set to False to only consider members of this group directly
Returns: A list of hostnames
Return type:
-
add_netgroup_users
(dn, members, domain='')¶ Add new users to a netgroup.
Parameters: Return type:
-
add_netgroup_hosts
(dn, members, domain='')¶ Add new hosts to a netgroup.
Parameters: Return type:
-
replace_netgroup_users
(dn, members, domain='')¶ Set new users on a netgroup.
Parameters: Return type:
-
replace_netgroup_hosts
(dn, members, domain='')¶ Set new hosts on a netgroup.
Parameters: Return type:
-
delete_netgroup_users
(dn, members, domain='')¶ Delete users from a netgroup.
Parameters: Return type:
-
delete_netgroup_hosts
(dn, members, domain='')¶ Delete hosts from a netgroup.
Parameters: Return type:
-
-
class
laurelin.ldap.
LDAPObject
[source] The following new methods get bound to
laurelin.ldap.LDAPObject
upon extension activation:-
get_netgroup_users
(recursive=True)¶ Get all users in this netgroup object.
Parameters: recursive (bool) – Set to False to ignore any memberNisNetgroups defined for this object. Returns: A list of usernames Return type: list[str] Raises: RuntimeError – if this object is missing the netgroup object class
-
get_netgroup_hosts
(recursive=True)¶ Get all hosts in this netgroup object.
Parameters: recursive (bool) – Set to False to ignore any memberNisNetgroups defined for this object. Returns: A list of hostnames Return type: list[str] Raises: RuntimeError – if this object is missing the netgroup object class
-
add_netgroup_users
(members, domain='')¶ Add new user netgroup entries to this netgroup object.
Parameters: - members (list or str or tuple) – A Member List (see
laurelin.extensions.netgroups
doc) or single member list entry - domain (str) – The default domain to use in nisNetgroupTriples where not already specified
Return type: Raises: RuntimeError – if this object is missing the netgroup object class
- members (list or str or tuple) – A Member List (see
-
add_netgroup_hosts
(members, domain='')¶ Add new host netgroup entries to this netgroup object.
Parameters: - members (list or str or tuple) – A Member List (see
laurelin.extensions.netgroups
doc) or single member list entry - domain (str) – The default domain to use in nisNetgroupTriples where not already specified
Return type: Raises: RuntimeError – if this object is missing the netgroup object class
- members (list or str or tuple) – A Member List (see
-
replace_netgroup_users
(members, domain='')¶ Set new user netgroup entries on this netgroup object.
Parameters: - members (list or str or tuple) – A Member List (see
laurelin.extensions.netgroups
doc) or single member list entry - domain (str) – The default domain to use in nisNetgroupTriples where not already specified
Return type: Raises: RuntimeError – if this object is missing the netgroup object class
- members (list or str or tuple) – A Member List (see
-
replace_netgroup_hosts
(members, domain='')¶ Set new host netgroup entries on this netgroup object.
Parameters: - members (list or str or tuple) – A Member List (see
laurelin.extensions.netgroups
doc) or single member list entry - domain (str) – The default domain to use in nisNetgroupTriples where not already specified
Return type: Raises: RuntimeError – if this object is missing the netgroup object class
- members (list or str or tuple) – A Member List (see
-
delete_netgroup_users
(members, domain='')¶ Delete user netgroup entries from this netgroup object.
Parameters: - members (list or str or tuple) – A Member List (see
laurelin.extensions.netgroups
doc) or single member list entry - domain (str) – The default domain to use in nisNetgroupTriples where not already specified
Return type: Raises: RuntimeError – if this object is missing the netgroup object class
- members (list or str or tuple) – A Member List (see
-
delete_netgroup_hosts
(members, domain='')¶ Delete host netgroup entries from this netgroup object.
Parameters: - members (list or str or tuple) – A Member List (see
laurelin.extensions.netgroups
doc) or single member list entry - domain (str) – The default domain to use in nisNetgroupTriples where not already specified
Return type: Raises: RuntimeError – if this object is missing the netgroup object class
- members (list or str or tuple) – A Member List (see
-
Paged Results¶
RFC 2696 Simple Paged Results Manipulation
This adds a control to support paging results. Use the control keyword paged
with search methods. Returns a cookie
on the page_cookie
response attribute which can be found on the results handle after all paged results have been
received. See example below.
Note: Do not use this extension to simply limit the total number of results. The search methods accept a limit
keyword out of the box for this purpose.
Example usage:
from laurelin.ldap import LDAP
LDAP.activate_extension('laurelin.extensions.pagedresults')
with LDAP() as ldap:
search = ldap.base.search(paged=10)
page1_results = list(search)
search = ldap.base.search(paged=(10, search.page_cookie))
page2_results = list(search)
# ...
if not search.page_cookie:
print('Got all pages')
Note: When getting pages in a loop, you may set the cookie value to an empty string on the first iteration, e.g.:
ldap.base.search(paged=(10, ''))