Util module - Platform - BlueCat Gateway - 18.6.1

Gateway Administration Guide

prodname
BlueCat Gateway
version_custom
18.6.1

Helper utilities for the BlueCat Python API. This collection of functions provide extra functionality a lot of API methods and workflows use.

classbluecat.util.QueueHandler(queue)

Queue handler

emit(message)

classutil.StackQueueModifie

Bases: Queue.Queue

Queue used for Workflow directory changes.

pop(block=True, timeout=None)

overriding pop

bluecat.util.autologin(get_autologin)

Performs autologin to BAM using provided function, which should return username and password. Logs out and cleans up the session after workflow endpoint is called.
Note: This decorator is intended for REST endpoints only and might not work if used against UI endpoints.
Parameter Description
get_autologin A function to retrieve username and password for autologin.

bluecat.util.check_and_create_path(path, base_directory='bluecat_portal')

Verifies path for storing external files and creates them if they are valid.

Parameter Description
path Path to be verified and created.
base_directory The base directory that the path must start with.

Returns: The path that was checked and created if valid, raises PortalException otherwise.

bluecat.util.check_path(path, base_directory='bluecat_portal')

Verifies Path for storing external files.

bluecat.util.cidr_to_bin(cidr)

CIDR to binary.

bluecat.util.combine_filters(validators=None)

Generates a function with a list of validator functions.

Parameter Description
validators A list of functions that take Entity object as only parameter and return bool.

Returns: A function that combines validation of the validators taken in.

bluecat.util.config_filter(config_ids=None)

A wrapped validator that returns a validator for filtering by configuration. Also an example of writing validators.

Parameter Description
config_ids  

Returns: A validator function that if an Entity’s parent Configuration is in config_ids.

bluecat.util.create_valid_api_url(url)

Parse a given URL for the BAM and ensure it is valid and add back in the extra parts to make it a valid path to the WSDL file.

Parameter Description
url The URL to be parsed.

Returns: A valid URL to the WSDL file.

bluecat.util.decrypt_key(encrypted_token, key=None)

Decrypts token using key, config.secret_key will be used, if not provided.

bluecat.util.decrypt_key_from_file(name=None, path='ps/.secret', key='one fish two fish red fish blue fish')

Decrypt the file given in path and find the key associated with the given name. Returns the key if found, otherwise will throw a PortalException.

Parameter Description
name A human readable name for the desired key that was used in the encrypt_key_to_file method for the key. If no name is provided the method will return the entire unencrypted contents of the file.
path The path (including the filename) where the encrypted file is stored.
key The secret token for decrypting the encrypted file. The default token for the Portal server will be used if nothing is provided. The token must be a URL-safe base64-encoded 32-byte string.

Returns: The found key as a string

bluecat.util.deprecated_warning(api, dep_warn)

To be used when a method, class or parameter has been deprecated and should no longer be used.

bluecat.util.encrypt_key(token, key=None)

Encrypts token using key. config.secret_key will be used, if not provided.

bluecat.util.encrypt_key_to_file(token, name=None, path='ps/.secret', key='one fish two fish red fish blue fish')

Encrypt the given name, token pair into a file specified by path. The token can later be retrieved using the name with the decrypt_key_from_file method. An optional token can be specified which is the secret used to encrypt the token and is required to decrypt it if a custom one was provided for this method.

Parameter Description
name A human readable name for the token that will be used in decrypt_key_from_file to retrieve the correct token. Cannot contain special characters such as “=”. If no name is provided the method will only write the encrypted password to the file. This will overwrite any other contents the file may have.
token Sensitive information to be encrypted such as a password.
path The path (including the filename) where the encrypted file should be stored.
key The secret token used in the encryption process. This is necessary to decrypt the encrypted file and if provided should be stored securely and must not be shared. The token must be a URL-safe base64-encoded 32-byte string.

Returns: None.

bluecat.util.exception_catcher(func)

Catches uncaught exceptions inside workflow endpoints and flashes standardized message to user.

Parameter Description
func Function being wrapped, supplied by automatically as a python decorator.

Returns: Redirect to index.

bluecat.util.filter_entities(entity_generator, filters=None)

Filter a generator of Entities with a list of filters with itertools.

Parameter Description
entity_generator A generator of entity objects.
filters A list of filters.

Returns: An filtered iterator.

bluecat.util.generate_user_css(theme, user_css_path='static/css/user_css.css', user_json_file_path='bluecat_portal/ps/ui_customizations.json')

Generates a CSS file that defines colours for customizable elements in the Gateway website.

Parameter Description
theme The color theme defined in ui_customizations.json file to use.
user_css_path Where the generated CSS file should go. The folder path must already exist.
user_json_file_path Where to find the ui_customizations.json file if it is not in its default directory.

Returns: None.

bluecat.util.get_address_space_size(cidr, subnetwork_size)

Given a CIDR address, calculate the number of subnets given the number of addresses contained within a subnet.

Parameter Description
cidr CIDR Address. For example, “10.0.0.0/16”
subnetwork_size Number of addresses contained in each subnet.

Returns: Number of addresses available.

bluecat.util.get_configurations(default_val=False)

Get a list of configurations for display in a dropdown box.

Returns: List of configuration ID, configuration name tuples.

bluecat.util.get_password_from_file(password_path_option, default_path)

Extracting encoded password from file and with key that defined in configuration file.

Parameter Description
password_path_option Name of option in config file that define file path.
default_path Default path to a password file, when password_path_option not defined in config file.

Returns: Password.

bluecat.util.get_portal_mongo_db()

Returns Database pointer

bluecat.util.get_secret(secret='one fish two fish red fish blue fish')

Encodes secret using Base64.

bluecat.util.get_text(workflow_dir, language)

Get text of given language from workflow_dir.

Returns: Dictionary of text results.

bluecat.util.has_response(response)

Check for none response for anything that you would normally expect to return an entity.

Parameter Description
response API response from BAM.

Returns: True if response contains an object represanting a valid found entity in BAM, otherwise False.

bluecat.util.int2ip4(addr)

Turn a 32-bit integer into an IPv4 address string.

bluecat.util.ip42int(addr)

Turn an IP address string into a 32-bit integer.

bluecat.util.is_valid_domain_name(address)

Verifies if provided string is a valid string to be a domain name.

bluecat.util.is_valid_ipv4_address(address)

Figure out if a string is a valid IPv4 address.

bluecat.util.is_valid_ipv6_address(address)

Figure out if a string is a valid IPv6 address.

bluecat.util.load_group_settings(default_keys=True, logger=<module 'logging' from '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/logging/__init__.pyc'>)

Loads the group settings.

Parameter Description
default_keys Default non-existing keys to the default_group_settings.

Returns: Dictionary containing groups and their settings.

bluecat.util.map_to_properties(properties)

Turn a dictionary of properties into a BAM property string.

bluecat.util.parse_properties(properties)

Parses property input that is in a list or dictionary form and converts it to a string of property=value separated by ‘|’ pipe characters.

Parameter Description
properties List or dictionary containing properties.

Returns: Properties in form of a string with property=value separated by ‘|’ pipe characters format.

bluecat.util.properties_to_map(properties)

Turn a string of BAM properties into a dictionary of name->value.

Parameter Description
properties String in the form ‘a=b|c=d|…’

bluecat.util.remove_from_bam_control(ip, username='', password='')

Not tested! Removes a BDDS from BAM control.

Parameter Description
username The administrator username of the BDDS.
password The administrator password of the BDDS.
ip IP address of the BDDS.

Returns: False if there is an error removing from control. True otherwise.

bluecat.util.rest_exception_catcher(func)

Catches uncaught exceptions inside workflow endpoints and raises 500 HTTP error with standardized message.

Parameter Description
func Function being wrapped, supplied by automatically as a python decorator.

Returns: HTTP error.

bluecat.util.rest_workflow_permission_required(workflow)

Checks that the user has permission for the view that was called. Returns a 401 to the user if they do not have permission.

Parameter Description
workflow The name of the workflow the view is in and that permission was set for.

bluecat.util.run_ssh_cmd(hostname, username='', password='', cmd='', timeout=30, **kwargs)

Execute a single SSH command.

Parameter Description
hostname Hostname or IPv4/IPv6 address of the remote server.
username Username to login to remote server if no key found.
password Password to login to remote server if no key found.
cmd One-liner command to execute on remote system via SSH.
timeout Time to wait for command to execute.
kwargs Additional keyword arguments supported by paramiko.SSHClient.connect().

Returns: A tuple: stdout, stderr.

bluecat.util.safe_str(obj)

Return the byte string representation of obj.

bluecat.util.save_group_settings(group_settings_data, logger=<module 'logging' from '/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/logging/__init__.pyc'>)

Given a dictionary containing the group settings, save it to the file specified in the config :param group_settings_data: A dictionary where the keys are the group names and the value is another dictionary containing the group data.

bluecat.util.setup_mongo_db()

Configure parameters for MongoDB, and prepare Database pointer.

bluecat.util.spawn_child_logger(parent_logger, child_name, handler_type, handler_args, level, log_format, timestamp_format

Spawn a child logger from a logger object with a specific handler and name.

Parameter Description
parent_logger Typically from app.logger base object.
child_name Name of the child logger, will be displayed in the logs as “<PARENT>.<CHILD_NAME>”.
handler_type Type of handler to attach to the child logger.
handler_args List of args to pass into the obtained handler.
level The level of messages the handler will log, messages below this level will be ignored.
log_format Custom format of the log messages.
timestamp_format Custom format of the log messages.

bluecat.util.validate_partial_ipv4_address(address)

Check if provided string is a valid partial IPv4 address.

bluecat.util.workflow_permission_required(workflow)

Checks that the user has permission for the view that was called. Returns user to index if they do not have permission.

Parameter Description
workflow The name of the workflow the view is in and that permission was set for.