Usage example

standalone.ldif2db(bename, suffixes, excludeSuffixes, encrypt, import_file)
standalone.db2ldif(bename, suffixes, excludeSuffixes, encrypt, repl_data, outputfile)
standalone.db2index(bename=None, suffixes=None, attrs=None, vlvTag=None)
standalone.dbscan(bename=None, index=None, key=None, width=None, isRaw=False)

# Generate a simple ldif file using the dbgen.pl script, and set the ownership and permissions to match the user that the server runs as
standalone.buildLDIF(number_of_entries, path_to_ldif, suffix='dc=example,dc=com')

Module documentation

Utilities for DirSrv.

TODO put them in a module!

lib389.utils.assert_c(condition, msg='Assertion Failed')[source]

This is the same as assert, but assert is compiled out when optimisation is enabled. This prevents compiling out.


Return True if current version of ns-slapd is older than provided version


convert special characters in a DN into LDAPv3 escapes for use in search filters


convert special characters in a DN into LDAPv3 escapes.


“dc=example,dc=com” -> “dc=example,dc=com”


Return the .inf data for a silence setup via setup-ds.pl.

args = {

# new instance values newhost, newuserid, newport, SER_ROOT_DN, newrootpw, newsuffix,

# The following parameters require to register the new instance # in the admin server have_admin, cfgdshost, cfgdsport, cfgdsuser,cfgdspwd, admin_domain

InstallLdifFile, AddOrgEntries, ConfigFile, SchemaFile, ldapifilepath

# Setup the o=NetscapeRoot namingContext setup_admin,


@see https://access.redhat.com/site/documentation/en-US/
Red_Hat_Directory_Server/8.2/html/Installation_Guide/ Installation_Guide-Advanced_Configuration-Silent.html

[General] FullMachineName= dir.example.com SuiteSpotUserID= nobody SuiteSpotGroup= nobody AdminDomain= example.com ConfigDirectoryAdminID= admin ConfigDirectoryAdminPwd= admin ConfigDirectoryLdapURL= ldap://dir.example.com:389/o=NetscapeRoot

[slapd] SlapdConfigForMC= Yes UseExistingMC= 0 ServerPort= 389 ServerIdentifier= dir Suffix= dc=example,dc=com RootDN= cn=Directory Manager RootDNPwd= password ds_bename=exampleDB AddSampleEntries= No

[admin] Port= 9830 ServerIpAddress= ServerAdminID= admin ServerAdminPwd= admin


Format the subprocess command list to the quoted shell string

lib389.utils.generate_ds_params(inst_num, role=<Replica role.STANDALONE: 4>)[source]

Generate a host, port, secure port, server ID and replica ID for the selected role and instance number. I.e. inst_num=1, role=”master”.

@param inst_num - an instance number in a range from 1 to 99 @param role - ReplicaRole.STANDALONE, ReplicaRole.MASTER, ReplicaRole.HUB, ReplicaRole.CONSUMER @return - the dict with next keys: host, port, secure port, server id and replica id


Return the date and time:

2016-04-21 21:21:00
lib389.utils.get_bin_dir(sroot=None, prefix=None)[source]

Return the sbin directory (default /usr/bin).


Return the shared data directory (default /usr/share/dirsrv/data).


Return version of ns-slapd installed on this system. This is determined by the defaults.inf file, so is correct for the built and installed ns-slapd binary. This function works without root permissions.

returns a string of the form:


Take an instance name, and get the host/port/protocol from dse.ldif and return a LDAP URL to use in the CLI tools (dsconf)

Parameters:instance – The server ID of a server instance

:return tuple of LDAPURL and certificate directory (for LDAPS)


Return the plugin directory (default /usr/lib64/dirsrv/plugins). This should be 64/32bit aware.

lib389.utils.get_sbin_dir(sroot=None, prefix=None)[source]

Return the sbin directory (default /usr/sbin).


Return the unix username used from the server inspecting the following keys in args.

‘newuserid’, ‘admconf’, ‘sroot’ -> ssusers.conf
lib389.utils.getadminport(cfgconn, cfgdn, args)[source]

Return a 2-tuple (asport, True) if the admin server is using SSL, False otherwise.

Get the admin server port so we can contact it via http. We get this from the configuration entry using the CFGSUFFIX and cfgconn. Also get any other information we may need from that entry.


Returns a 3-tuple consisting of the host, port, and cfg suffix.

new_instance_arguments = {
‘cfgdshost’: ‘cfgdsport’: ‘new_style’:


We need the host and port of the configuration directory server in order to create an instance. If this was not given, read the dbswitch.conf file to get the information. This method will raise an exception if the file was not found or could not be open. This assumes new_instance_arguments contains the sroot parameter for the server root path.

lib389.utils.getcfgdsuserdn(cfgdn, args)[source]

Return a DirSrv object bound anonymously or to the admin user.

If the config ds user ID was given, not the full DN, we need to figure out the full DN.

Try in order to:
1- search the directory anonymously; 2- look in ldap.conf; 3- try the default DN.

This may raise a file or LDAP exception.


Use the new style prefix /etc/dirsrv/admin-serv/adm.conf.

new_instance_arguments = {‘admconf’: obj } where obj.ldapurl != None


Use the old style sroot/shared/config/dbswitch.conf to get the info

lib389.utils.getserverroot(cfgconn, isLocal, args)[source]

Grab the serverroot from the instance dir of the config ds if the user did not specify a server root directory


True if host_name points to a local ip.

Uses gethostbyname()

lib389.utils.is_a_dn(dn, allow_anon=True)[source]

Returns True if the given string is a DN, False otherwise.


Return a filter matching any possible suffix form.

eg. normalized, escaped, spaced…

lib389.utils.update_admin_domain(isLocal, args)[source]

Get the admin domain to use.


Replace args[SER_HOST] with its fqdn and returns True if local.

One of the arguments to createInstance is newhost. If this is specified, we need to convert it to the fqdn. If not given, we need to figure out what the fqdn of the local host is. This method sets newhost in args to the appropriate value and returns True if newhost is the localhost, False otherwise

lib389.utils.valgrind_check_file(results_file, *patterns)[source]

Check the valgrind results file for the all the patterns @param result_file - valgrind results file (must be read after server is

@param patterns - A plain text or regex pattern string args that should
be searched for
@return True/False - Return true if one if the patterns match a stack

@raise IOError


Restore the ns-slapd binary to its original state - the server instances are expected to be stopped.

Note - selinux is enabled at the end of this process.

:param sbin_dir - the location of the ns-slapd binary (e.g. /usr/sbin) :raise ValueError :raise EnvironmentError: If script is not run as ‘root’

lib389.utils.valgrind_enable(sbin_dir, wrapper=None)[source]

Copy the valgrind ns-slapd wrapper into the /sbin directory (making a backup of the original ns-slapd binary).

The script calling valgrind_enable() must be run as the ‘root’ user as selinux needs to be disabled for valgrind to work

The server instance(s) should be stopped prior to calling this function. Then after calling valgrind_enable(): - Start the server instance(s) with a timeout of 60 (valgrind takes a

while to startup)
  • Run the tests
  • Stop the server
  • Get the results file
  • Run valgrind_check_file(result_file, “pattern”, “pattern”, …)
  • Run valgrind_disable()
  • sbin_dir – the location of the ns-slapd binary (e.g. /usr/sbin)
  • wrapper – The valgrind wrapper script for ns-slapd (if not set, a default wrapper is used)
  • IOError – If there is a problem setting up the valgrind scripts
  • EnvironmentError – If script is not run as ‘root’

Return the valgrind results file for the dirsrv instance.