Backend

Usage example

from lib389.backend import Backends

backends = Backends(standalone)
backend = backends.create(properties={'nsslapd-suffix': 'o=new_suffix', # mandatory
                                      'cn': 'new_backend'})             # mandatory

# Create sample entries
backend.create_sample_entries(version='001003006')

backend.delete()

Module documentation

class lib389.backend.Backends(instance, basedn=None)[source]

DSLdapObjects that represents DN_LDBM base DN This only does ldbm backends. Chaining backends are a special case of this, so they can be subclassed off.

Parameters

instance (lib389.DirSrv) – An instance

create(rdn=None, properties=None)[source]

Create an object under base DN of our entry

Parameters

  • rdn (str) – RDN of the new entry

  • properties (dict) – Attributes for the new entry

Returns

DSLdapObject of the created entry

delete_all_dangerous()[source]

Delete all backends. This deletes from longest to shortest suffix to ensure correct delete ordering.

ensure_state(rdn=None, properties=None)[source]

Create an object under base DN of our entry, or assert it exists and update it’s properties.

Parameters

  • rdn (str) – RDN of the new entry

  • properties (dict) – Attributes for the new entry

Returns

DSLdapObject of the created entry

exists(selector=[], dn=None)[source]

Check if a child entry exists

Returns

True if it exists

export_ldif(be_names, ldif=None, use_id2entry=False, encrypted=False, min_base64=False, no_dump_uniq_id=False, replication=False, not_folded=False, no_seq_num=False, include_suffixes=None, exclude_suffixes=None)[source]

Do an export of the suffix

get(selector=[], dn=None, json=False)[source]

Get a child entry (DSLdapObject, Replica, etc.) with dn or selector using a base DN and objectClasses of our object (DSLdapObjects, Replicas, etc.)

Note that * is not a valid selector, you should use “list()” instead.

Parameters

  • dn (str) – DN of wanted entry

  • selector – An additional filter to search for, i.e. ‘backend_name’. The attributes selected are based on object type, ie user will search for uid and cn.

Returns

A child entry

import_ldif(be_name, ldifs, chunk_size=None, encrypted=False, gen_uniq_id=None, only_core=False, include_suffixes=None, exclude_suffixes=None)[source]

Do an import of the suffix

lint(spec: Union[str, None, Type[List]] = None) → Generator[Any, None, None][source]

Lint the objects returned by list method according to the spec.

lint_list(spec: Optional[str] = None) → Generator[Tuple[str, Callable], None, None][source]

Yield specs the objects returned by list method provide.

list(paged_search=None, paged_critical=True)[source]

Get a list of children entries (DSLdapObject, Replica, etc.) using a base DN and objectClasses of our object (DSLdapObjects, Replicas, etc.)

Parameters

paged_search – None for no paged search, or an int of page size to use.

Returns

A list of children entries

class lib389.backend.Backend(instance, dn=None)[source]

Backend DSLdapObject with: - must attributes = [‘cn’, ‘nsslapd-suffix’] - RDN attribute is ‘cn’

Parameters

  • instance (lib389.DirSrv) – An instance

  • dn (str) – Entry DN

add(key, value)[source]

Add an attribute with a value

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

add_encrypted_attr(attr_name)[source]

Add an encrypted attribute :param attr_name - name of the new encrypted attribute

add_index(attr_name, types, matching_rules=[], reindex=False)[source]

Add an index.

:param attr_name - name of the attribute to index :param types - a List of index types(eq, pres, sub, approx) :param matching_rules - a List of matching rules for the index :param reindex - If set to True then index the attribute after creating it.

Add a VLV search entry :param: vlvname - Name of the new VLV search entry :props - A dict of the attribute value pairs for the VLV search entry :param - reindex - Set to True to index the new attribute right away

apply_mods(mods)[source]

Perform modification operation using several mods at once

Parameters

mods (list of tuples) – [(action, key, value),] or [(ldap.MOD_DELETE, key),]

Raises

ValueError - if a provided mod op is invalid

classmethod compare(obj1, obj2)[source]

Compare if two RDN objects have same attributes and values.

This comparison is a loose comparison, not a strict one i.e. “this object is this other object” It will just check if the attributes are same. ‘nsUniqueId’ attribute is not checked intentionally because we want to compare arbitrary objects i.e they may have different ‘nsUniqueId’ but same attributes.

Example:

cn=user1,ou=a
cn=user1,ou=b

Comparision of these two objects should result in same, even though their ‘nsUniqueId’ attribute differs.

Parameters

  • obj1 (lib389._mapped_object.DSLdapObject) – An entry to check

  • obj2 (lib389._mapped_object.DSLdapObject) – An entry to check

Returns

True if objects have same attributes else returns False

Raises

ValueError - if obj1 or obj2 don’t inherit DSLdapObject

create(dn=None, properties=None, basedn='cn=ldbm database,cn=plugins,cn=config', create_mapping_tree=True)[source]
Add a new backend entry, create mapping tree,

and, if requested, sample entries

Parameters

  • dn (str) – DN of the new entry

  • properties (dict) – Attributes and parameters for the new entry

  • basedn (str) – Base DN of the new entry

  • create_mapping_tree (bool) – If a related mapping tree node should be created

Returns

DSLdapObject of the created entry

create_sample_entries(version)[source]

Creates sample entries under nsslapd-suffix value

Parameters

version (str) – Sample entries version, i.e. 001003006

del_encrypted_attr(attr_name)[source]

Delete encrypted attribute :param attr_name - Name of the encrypted attribute to delete

delete()[source]

Deletes the backend, it’s mapping tree and all related indices. This can be changed with the self._protected flag!

Raises

  • UnwillingToPerform - if backend is protected

  • UnwillingToPerform - if nsslapd-state is not ‘backend’

display(attrlist=['*'])[source]

Get an entry but represent it as a string LDIF

Returns

LDIF formatted string

display_attr(attr)[source]

Get all values of given attribute - ‘attr: value’

Returns

Formatted string

property dn

Get an object DN

Returns

DN

ensure_attr_state(state)[source]

Given a dict of attr-values, ensure they are in the same state on the entry. This is a stateful assertion, generally used by things like PATCH in a REST api.

The format is:
{

‘attr_1’: [‘value’, ‘value’], ‘attr_2’: [],

}

If a value is present in the list, but not in the entry it is ADDED. If a value is NOT present in the list, and is on the entry, it is REMOVED. If a value is an empty list [], the attr is REMOVED from the entry. If an attr is not named in the dictionary, it is not altered.

This function is atomic - all changes are applied or none are. There are no partial updates.

This function is idempotent - submitting the same request twice will cause no action to be taken as we are ensuring a state, not listing actions to take.

Parameters

state (dict) – The entry ava state

ensure_present(attr, value)[source]

Ensure that an attribute and value are present in a state, or add it.

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

ensure_removed(attr, value)[source]

Ensure that a attribute and value has been removed and not present or remove it.

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

ensure_state(rdn=None, properties=None, basedn=None)[source]

Ensure an entry exists with the following state, created if necessary.

Parameters

  • rdn (str) – RDN of the new entry

  • properties (dict) – Attributes for the new entry

  • basedn – Base DN of the new entry

Returns

DSLdapObject of the created entry

exists()[source]

Check if the entry exists

Returns

True if it exists

export_ldif(ldif=None, use_id2entry=False, encrypted=False, min_base64=False, no_uniq_id=False, replication=False, not_folded=False, no_seq_num=False, include_suffixes=None, exclude_suffixes=None)[source]

Do an export of the suffix

get_all_attrs(use_json=False)[source]

Get a dictionary having all the attributes of the entry

Returns

Dict with real attributes and operational attributes

get_all_attrs_utf8(use_json=False)[source]

Get a dictionary having all the attributes of the entry

Returns

Dict with real attributes and operational attributes

get_attr_val_bytes(key, use_json=False)[source]

Get a single attribute value from the entry in bytes type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_val_int(key, use_json=False)[source]

Get a single attribute value from the entry in int type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_val_utf8(key, use_json=False)[source]

Get a single attribute value from the entry in utf8 type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_val_utf8_l(key, use_json=False)[source]

Get a single attribute value from the entry in utf8 type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_bytes(key, use_json=False)[source]

Get attribute values from the entry in bytes type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_int(key, use_json=False)[source]

Get attribute values from the entry in int type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_utf8(key, use_json=False)[source]

Get attribute values from the entry in utf8 type

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_attr_vals_utf8_l(key, use_json=False)[source]

Get attribute values from the entry in utf8 type and lowercase

Parameters

key (str) – An attribute name

Returns

A single bytes value

Raises

ValueError - if instance is offline

get_basedn()[source]

Get the suffix this entry belongs to

get_compare_attrs(use_json=False)[source]

Get a dictionary having attributes to be compared i.e. excluding self._compare_exclude

get_encrypted_attrs(just_names=False)[source]

Get a list of the excrypted attributes :param just_names - If True only the encrypted attribute names are returned (instead of the full attribute entry) :returns - a list of attributes

get_indexes()[source]

Get an Indexes(DSLdapObject) for the backend

get_monitor()[source]

Get a MonitorBackend(DSLdapObject) for the backend

get_sub_suffixes()[source]

Return a list of Backend’s returns: a List of subsuffix entries

get_vlv_searches(vlv_name=None)[source]

Return the VLV seaches for this backend, or return a specific search :param vlv_name - name of a VLV search entry to return :returns - A list of VLV searches or a single VLV sarch entry

import_ldif(ldifs, chunk_size=None, encrypted=False, gen_uniq_id=None, only_core=False, include_suffixes=None, exclude_suffixes=None)[source]

Do an import of the suffix

lint(spec: Union[str, None, Type[List]] = None) → Generator[Any, None, None][source]

Lint the object according to the spec.

lint_list(spec: Optional[str] = None) → Generator[Tuple[str, Callable], None, None][source]

Yield specs the object provides.

This yields from each lint method yielding all specs it can provide.

present(attr, value=None)[source]

Assert that some attr, or some attr / value exist on the entry.

Parameters

  • attr (str) – an attribute name

  • value (str) – an attribute value

Returns

True if attr is present

property rdn

Get an object RDN

Returns

RDN

reindex(attrs=None, wait=False)[source]

Reindex the attributes for this backend :param attrs - an optional list of attributes to index :param wait - Set to true to wait for task to complete

remove(key, value)[source]

Remove a value defined by key

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

remove_all(key)[source]

Remove all values defined by key (if possible).

If an attribute is multi-valued AND required all values except one will be deleted.

Parameters

key (str) – an attribute name

rename(new_rdn, newsuperior=None, deloldrdn=True)[source]

Renames the object within the tree.

If you provide a newsuperior, this will move the object in the tree. If you only provide a new_rdn, it stays in the same branch, but just changes the rdn.

Note, if you use newsuperior, you may move this object outside of the scope of the related DSLdapObjects manager, which may cause it not to appear in .get() requests.

Parameters

  • new_rdn (str) – RDN of the new entry

  • newsuperior (str) – New parent DN

replace(key, value)[source]

Replace an attribute with a value

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

replace_many(*args)[source]

Replace many key, value pairs in a single operation. This is useful for configuration changes that require atomic operation, and ease of use.

An example of usage is replace_many((key, value), (key, value))

No wrapping list is needed for the arguments.

Parameters

*args –

tuples of key,value to replace.

set(key, value, action=2)[source]

Perform a specified action on a key with value

Parameters

  • key (str) – an attribute name

  • value (str) – an attribute value

  • action (int) –

    • ldap.MOD_REPLACE - by default

    • ldap.MOD_ADD

    • ldap.MOD_DELETE

Returns

result of modify_s operation

Raises

ValueError - if instance is not online