Utils

Usage example

standalone.ldif2db(bename, suffixes, excludeSuffixes, encrypt, import_file)
standalone.db2ldif(bename, suffixes, excludeSuffixes, encrypt, repl_data, outputfile)
standalone.bak2db(archive_dir)
standalone.db2bak(archive_dir)
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')

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

lib389.utils.cmp(self, x, y)

Replacement for built-in function cmp that was removed in Python 3

Compare the two objects x and y and return an integer according to the outcome. The return value is negative if x < y, zero if x == y and strictly positive if x > y.

lib389.utils.copy_with_permissions(source, target)

Copy a file while preserving all permissions

lib389.utils.ds_is_newer(*ver, instance=None)

Return True if the current version of ns-slapd is newer than a provided version

lib389.utils.ds_is_older(*ver, instance=None)

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

lib389.utils.ds_is_related(relation, *ver, instance=None)

Return a result of a comparison between the current version of ns-slapd and a provided version.

lib389.utils.ds_supports_new_changelog()

Return True if the current version of ns-slapd supports changelogs under cn=changelog,cn=<backend>,cn=ldbm..

lib389.utils.escapeDNFiltValue(dn)

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

lib389.utils.escapeDNValue(dn)

convert special characters in a DN into LDAPv3 escapes.

e.g.

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

lib389.utils.formatInfData(args)

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= 111.11.11.11 ServerAdminID= admin ServerAdminPwd= admin

lib389.utils.format_cmd_list(cmd)

Format the subprocess command list to the quoted shell string

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

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

lib389.utils.gentime_to_datetime(gentime)

Convert Generalized time to datetime object

Parameters

gentime – Time in the format - YYYYMMDDHHMMSSZ (20170126120000Z)

Returns

datetime.datetime object

lib389.utils.gentime_to_posix_time(gentime)

Convert Generalized time to POSIX time format

Parameters

gentime – Time in the format - YYYYMMDDHHMMSSZ (20170126120000Z)

Returns

Epoch time int

lib389.utils.getDateTime()

Return the date and time:

2016-04-21 21:21:00

lib389.utils.get_bin_dir(sroot=None, prefix=None)

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

lib389.utils.get_data_dir(prefix=None)

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

lib389.utils.get_ds_version(paths=None)

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: 1.3.4.8

lib389.utils.get_ldapurl_from_serverid(instance)

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)

lib389.utils.get_plugin_dir(prefix=None)

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

lib389.utils.get_sbin_dir(sroot=None, prefix=None)

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

lib389.utils.get_server_user(args)

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)

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.

lib389.utils.getcfgdsinfo(new_instance_arguments)

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)

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.

lib389.utils.getnewcfgdsinfo(new_instance_arguments)

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

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

lib389.utils.getoldcfgdsinfo(args)

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

lib389.utils.getserverroot(cfgconn, isLocal, args)

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

lib389.utils.isLocalHost(host_name)

True if host_name points to a local ip.

Uses gethostbyname()

lib389.utils.is_a_dn(dn, allow_anon=True)

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

lib389.utils.is_dn_parent(parent_dn, child_dn)

check if child_dn is a really a child of parent_dn :return True - if child directly under parent, otherwise False

lib389.utils.print_nice_time(seconds)

Convert seconds to a pretty format

lib389.utils.search_filter_escape_bytes(bytes_value)

Convert a byte sequence to a properly escaped for LDAP (format BACKSLASH HEX HEX) string

lib389.utils.selinux_label_port(port, remove_label=False)

Either set or remove an SELinux label(ldap_port_t) for a TCP port

Parameters

• port (str) – The TCP port to be labeled

• remove_label (boolean) – Set True if the port label should be removed

Raises

ValueError: Error message

lib389.utils.selinux_present()

Determine if selinux libraries are on a system, and if so, if we are in a state to consume them (enabled, disabled).

Returns

bool

lib389.utils.selinux_restorecon(path)

Relabel a filesystem rooted at path.

Parameters

path (str:) – The filesystem path to recursively relabel

lib389.utils.socket_check_open(host, port)

Check if a socket can be opened. Need to handle cases where IPv6 is completely disabled.

lib389.utils.suffixfilt(suffix)

Return a filter matching any possible suffix form.

eg. normalized, escaped, spaced…

lib389.utils.update_admin_domain(isLocal, args)

Get the admin domain to use.

lib389.utils.update_newhost_with_fqdn(args)

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)

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

stopped)

@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

trace

@raise IOError

lib389.utils.valgrind_disable(sbin_dir)

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)

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()

Parameters

• 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)

Raises

• IOError – If there is a problem setting up the valgrind scripts

• EnvironmentError – If script is not run as ‘root’

lib389.utils.valgrind_get_results_file(dirsrv_inst)

Return the valgrind results file for the dirsrv instance.