Configuration class - Platform - BlueCat Gateway - 21.11.2

Gateway Administration Guide

Locale
English
Product name
BlueCat Gateway
Version
21.11.2

class bluecat.configuration.Configuration(api, api_entity)

Bases: bluecat.configuration.IP4SpaceConfiguration, bluecat.configuration.IP4SpaceConfigurationBlockNet, bluecat.configuration.IP4SpaceConfigurationNet, bluecat.configuration.IP6SpaceConfiguration, bluecat.configuration.IP6SpaceConfigurationBlockNet, bluecat.configuration.DNSConfiguration, bluecat.configuration.ServerConfiguration, bluecat.deployment_option.RawDeploymentOptionActionsMixin

The configuration class wraps the BAM Configuration Entity type. Generally, most API use cases start with retrieving one or more configurations from where other object types may be retrieved.

GLOBAL_UNICAST_PREFIX = '2000::/3'

MAX_COUNT = 1000

UNIQUE_LOCAL_PREFIX = 'FC00::/6'

add_ip4_block_by_cidr(cidr, properties='')

Create a new ip4 child block using CIDR.

Parameters Description
cidr the CIDR notation defining the block (for example, 10.10/16).
properties A string containing options.

Returns: Returns an APIEntity for the created IPv4 block object.

add_ip4_block_by_range(start, end, properties='')

Create a new ip4 child block by defining an address range.

Parameters Description
start An IP address defining the lowest address or start of the block.
end An IP address defining the highest address or end of the block.
properties A string containing options.

Returns: Returns an APIEntity for the created IPv4 block object.

add_mac_address(address, name='', mac_pool=None, properties='')

Adds a mac address object.

Parameters Description
address The MAC address in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn or nn:nn:nn:nn:nn:nn, where nn is a hexadecimal value.
name Name of the MAC address (optional).
mac_pool The MAC Pool object.
properties A string containing options.

Returns: The added MAC address object.

add_raw_deployment_option(option_type, raw_data, properties='')

Parameters Description
option_type the option types for Raw Deployment Options, the Three options are DNS_RAW, DHCP_RAW, DHCPV6_RAW.
raw_data the raw option value for the deployment option.
properties the properties of the raw option, if it is an DNSRawOption you need to set server in properties

Returns: Returns an instance of the type DNSOption that represents the DNS deployment option.

add_response_policy(name, policy_type, ttl=300, properties='')

Adds a response policy to the configuration.

Parameters Description
name The name of the DNS response policy.
policy_type The type of response policy. The values to be used are defined in the constants class bluecat.constants.ResponsePolicy.
ttl The time-to-live value in seconds.
properties A string containing options, including comments and user-defined fields.

Returns: The policy object that was added.

Return type: bluecat.response_policy.ResponsePolicy

Example:

from bluecat.constants import ResponsePolicy

api = g.user.get_api()                                   # get api object
configuration_id = 100001                                # configuration id
config = api.get_entity_by_id(configuration_id)

policy = config.add_response_policy('testpolicy',
                                     ResponsePolicy.WHITELIST,
                                     ttl=200, properties='test')

add_server(name, address, host_name, profile='ADONIS_1200', properties='password=bluecat|connected=true|upgrade=False')

Parameters Description
name The name of the server within Address Manager.
address The physical IP address for the server within Address Manager.
host_name The DNS FQDN by which the server is referenced.
profile The server capability profile. Defaults to ‘ADONIS_1000’
properties Defaults to ‘password=bluecat|connected=true|upgrade=False’

Returns: Server entity added.

add_tftp_group(name, properties='')

Parameters Description
name The name of the TFTP group.
properties Adds object properties, including comments and user-defined fields.

Returns: TFTPGroup entity added.

add_view(name, properties='')

Add View

Parameters Description
name The name of the view.
properties Adds object properties, including user-defined fields.

Returns: An instance of the created View

assign_ip4_address(address, mac_address, hostinfo, action, properties='')

Assign an IPv4 address (e.g. ‘192.168.0.1’).

Parameters Description
address (e.g. ‘192.168.0.1’)
mac_address (e.g. ‘“00-00-00-00-00-01’)
hostinfo A string containing host information for the address in the following format: [hostname,viewId,reverseFlag,sameAsZoneFlag, ….]. Where:
  • hostname - The Fully Qualified Domain Name (FQDN) for the host record to be added

  • viewId - The object ID of the view under which this host should be created.

  • reverseFlag - The flag indicating if a reverse record should be created. The possible values are true or false.

  • sameAsZoneFlag - The flag indicating if record should be created as same as zone record. The possible values are true or false.

The comma-separated parameters may be repeated in the order shown above. The string must not end with a comma.

action MAKE_STATIC / MAKE_RESERVED / MAKE_DHCP_RESERVED
properties A string containing options.

Returns: Returns an APIEntity for the assigned IPv4 address object.

assign_ip6_address(action, address, mac_address='', hostinfo='', duid='', properties='')

Assign an IPv6 address

Parameters Description
action MAKE_STATIC / MAKE_DHCP_RESERVED
address (e.g. ‘FC01:1:1:1::/64’)
mac_address (e.g. ‘00-00-00-00-00-01’)
hostinfo A string containing host information for the address in the following format: [viewId,hostname,reverseFlag,sameAsZoneFlag, …]
  • viewId - The object ID of the view under which this host should be created.

  • hostname - The Fully Qualified Domain Name (FQDN) for the host record to be added.

  • reverseFlag - The flag indicating if a reverse record should be created. The possible values are true or false.

  • sameAsZoneFlag - The flag indicating if record should be created as same as zone record. The possible values are true or false.

The comma-separated parameters may be repeated in the order shown above. The string must not end with a comma.

duid (e.g. ‘00-01-00-01-14-77-21-A2-00-50-56-AA-5E-EE’)
properties A string containing options.

Returns: Returns the updated IPv6Address

assign_next_available_ip4_address(mac_address, hostinfo, action, properties='')

Assigns next available IPv4 address.

Parameters Description
mac_address (e.g. ‘00-00-00-00-00-01’)
hostinfo A string containing host information for the address in the following format: [hostname,viewId,reverseFlag,sameAsZoneFlag, …]. Where:
  • hostname - The Fully Qualified Domain Name (FQDN) for the host record to be added

  • viewId - The object ID of the view under which this host should be created.

  • reverseFlag - The flag indicating if a reverse record should be created. The possible values are true or false.

The comma-separated parameters may be repeated in the order shown above. The string must not end with a comma.

action MAKE_STATIC / MAKE_RESERVED / MAKE_DHCP_RESERVED
properties A string containing options. Properties include:
  • excludeDHCPRange - Specifies whether IP addresses in DHCP ranges should be excluded from assignment. The value is either true or false, default value is false.

Returns: Returns an APIEntity for the assigned IPv4 address object.

create_xha_pair(active_server, passive_server, active_server_new_ip, properties='', max_wait=1200)

Parameters Description
active_server For example, 00-00-00-00-00-01
passive_server MAKE_STATIC / MAKE_RESERVED / MAKE_DHCP_RESERVED
active_server_new_ip The new IPv4 address for the active server.
properties A string containing options.
max_wait Amount of time to wait for xHA pair to be created in seconds.

Returns: Active BDDS server entity object if successful. Exception on failure.

find_response_policy_with_item(item_name, properties='')

Get the response policies that contain an item with the specified name.

Parameters Description
item_name The Fully Qualified Domain Name (FQDN) of the response policy item.
properties Reserved for future use.

Returns: Returns an array of response policy with the item_name in them.

Example:

api = g.user.get_api()                                   # get api object
configuration_id = 100001                                # configuration id
config = api.get_entity_by_id(configuration_id)

policy_list = config.find_response_policy_with_item('testpolicy')

get_deployment_options(option_types, server)

Get deployment Option for the entity.

Parameters Description
option_types the Deployment option type you would like to search, Includes
  • DNSOption

  • DNSRawOption

  • DHCPRawOption

  • DHCPV6RawOption

  • DHCPV4ClientOption

  • DHCPV6ClientOption

  • DHCPServiceOption

  • DHCPV6ServiceOption

  • VendorClientOption

  • StartOfAuthority

server the server which the deployment option is attached to, there are 3 options:
  • >0—returns only the options that are linked to the specified server ID.

  • <0—returns all options regardless of the server ID specified.

  • =0—returns only the options that are linked to all servers.

get_entity_by_cidr(cidr, entity_type='IP4Block')

Returns an IPv4 Block object by calling the block using CIDR notation.

Parameters Description
cidr CIDR notation defining the block to be returned (for example, 10.10/16).
entity_type The type of object returned: IP4Block.

Returns: The specified IPv4 block object from the database.

get_host_records_by_ip(ip4_objects, version=1)

Use this method to find Host Records associated with a set of IPv4 addresses.

Attention: This API method requires the following:
  • BAM v9.0.0 or greater

  • Configuration of the BlueCat Gateway server IP address in the BAM Administration Console. For more information, refer to the section ‘Adding host access to the database’ in the Address Manager Administration Guide.

Parameters Description
ip4_objects(List) List of IPv4 address objects.
version(int, optional) Version of API. Current version support: 1

Returns: Returns a generator that yields tuples, where each tuple contains an IPv4 address object and the list of Host Records objects associated with it.

Raises:
  • BAMException – If there is an exception in retrieving host records.

  • PortalException – If BAM version is lower than 9.0.0.

  • PortalException – If version is not supported

Example:

api = g.user.get_api()                          # get api object
configuration = api.get_configuration('config') # get configuration object
ip4_address = api.get_entity_by_id(101873)      # IP4 address objects to search

for ip_address in configuration.get_host_records_by_ip([ip4_address]):
    for host in ip_address[1]:
        print(host)

get_ip4_address(address)

Get an IPv4 address by IP (e.g. ‘192.168.0.1’).

Parameters Description
address the IPv4 address string.

Returns: Returns the requested APIEntity of IPv4 Address object.

get_ip4_blocks()

Get the IPv4 blocks directly underneath the current configuration or block. Note that blocks form the nodes of a tree with networks being the leaves.

Returns: Returns an iterator of DHCPv4 range objects from the database.

get_ip4_networks_by_hint(ip_prefix)

Search for IPv4 networks using their ip prefix in the configuration or block. Returns an array of IPv4 networks found under the container object. Currently only allows hints using ip prefix.

Parameters Description
ip_prefix The beginning ip prefix of the networks you wish to find. ex. ‘172’, ‘192.27’, ‘100.100.100.’

Returns: Returns an array of IPv4 networks based on the input argument or returns an empty list if no results are found.

get_ip6_address(address)

Get an IPv6 Address

Parameters Description
address Address to be retrieved

get_ip6_global_unicast_block()

Return the IPv6 global unicast address space block

get_ip6_objects_by_hint(hint, access_right='', count=10)

Gets an array of IPv6 objects.

Parameters Description
hint The partial or full name of the IPv6 objects.
access_right The access right of the requested objects.
count The number of elements to return.

Example:

from bluecat.constants import AccessRightValues

api = g.user.get_api()                                   # get api object
configuration_id = 100001                                # configuration id
config = api.get_entity_by_id(configuration_id)

ip6_networks = config.get_ip6_objects_by_hint('2001', access_right=AccessRightValues.AddAccess,
                                             count=10)
for network in ip6_networks:
    print(network)

get_ip6_unique_local_block()

Return the IPv6 unique local address space block

get_ip_range_by_ip(entity_type, address)

Warning: This method has been deprecated, use get_ip_ranged_by_ip instead.

Use this method to find the Configuration, IPv4 Block, IPv6 Block, IPv4 Network, IPv6 Network, DHCP Range, or DHCPv6 range containing a specified address. You can specify the type of object to be returned, or you can leave the type of object empty to find the most direct container for the object.

Parameters Description
entity_type The type of object containing the IPv4 or IPv6 address. Specify EntityType.IP4Block, EntityType.IP4Network, or EntityType.DHCP4Range to find the block, network, or range containing the IPv4 address. Specify EntityType.IP6Block, EntityType.IP6Network, or EntityType.DHCP6Range to find the block, network, or range containing the IPv6 address. Specify an empty string (“”) to return the most direct container for the IPv4 address or IPv6 address.
address An IPv4 address or Ipv6 address.

Returns: Returns an APIEntity for the object containing the specified address. If EntityType.IP4Block, EntityType.IP6Block, EntityType.IP4Network, EntityType.IP6Network, EntityType.DHCP4Range, or EntityType.DHCP6Range is specified as the type parameter, returns an object of the specified type. If an empty string (“”) is specified as the type parameter, returns the most direct container for the IPv4 address or IPv6 address.

Raises: PortalException – if no object matching the entity_type and address is found.

get_ip_ranged_by_ip(entity_type, address)

Use this method to find the Configuration, IPv4 Block, IPv6 Block, IPv4 Network, IPv6 Network, DHCP Range, or DHCPv6 range containing a specified address. You can specify the type of object to be returned, or you can leave the type of object empty to find the most direct container for the object.

Parameters Description
entity_type(str) The type of object containing the IPv4 or IPv6 address. Specify EntityType.IP4Block, EntityType.IP4Network, or EntityType.DHCP4Range to find the block, network, or range containing the IPv4 address. Specify EntityType.IP6Block, EntityType.IP6Network, or EntityType.DHCP6Range to find the block, network, or range containing the IPv6 address. Specify an empty string (“”) to return the most direct container for the IPv4 address or IPv6 address.
address(str) An IPv4 address or Ipv6 address.

Returns: Returns an APIEntity for the object containing the specified address. If EntityType.IP4Block, EntityType.IP6Block, EntityType.IP4Network, EntityType.IP6Network, EntityType.DHCP4Range, or EntityType.DHCP6Range is specified as the type parameter, returns an object of the specified type. If an empty string (“”) is specified as the type parameter, returns the most direct container for the IPv4 address or IPv6 address.

Raises: PortalException – if no object matching the entity_type and address is found.

get_mac_address(address)

Retrieves a MAC address object by MAC address.

Parameters Description
address The MAC address in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn or nn:nn:nn:nn:nn:nn, where nn is a hexadecimal value.

Returns: The MAC address object.

get_next_available_ip4_address()

Gets next available IPv4 address in current configuration

Returns: Returns the next available IPv4 address in an existing network as a string.

get_next_available_ip4_network(size, is_larger_allowed=False, auto_create=True)

Returns the next available (unused) network within a configuration or block.

Parameters Description
size The size of the network, expressed as a power of 2
is_larger_allowed indicates whether to return larger networks than those specified with the size parameter
auto_create indicates whether the next available network should be created if it does not exist.

Returns: Returns the next available (unused) network or None.

get_next_available_ip_range(size, entity_type, properties='')

Returns the existing next available IPv4 range or, if the next available IP range does not exist and autoCreate

  • was set to true, the newly created IPv4 range.

Parameters Description
size The size of the range, expressed as a power of 2.
entity_type The type of the range object to be fetched. Currently IPv4 block and network are supported.
properties A string containing options.

Returns: Returns the next available (unused) block or network within a configuration or block.

get_next_available_ip_ranges(size, max_results, properties='')

Finds or creates unused IPv4 Networks of the specified size.

Parameters Description
size The size of the range, expressed as a power of 2.
max_results The number of networks to be found or created.
properties A string containing options.

Returns: A list of newly created IPv4Networks.

get_next_ip4_address(exclude=None)

Get the next available IPv4 address (as a string) optionally excluding a given list of addresses.

Parameters Description
exclude(str, optional) which addresses (as a list of strings) to exclude.

get_next_ip4_address_string(exclude=None)

Warning: This method has been deprecated, use get_next_ip4_address instead.

Get the next available IPv4 address (as a string) optionally excluding a given list of addresses.

Parameters Description
exclude which addresses (as a list of strings) to exclude.

get_server(name)

Get a named server. Returns None if the server wasn’t found.

get_servers()

Get a list of all the servers in a configuration.

get_tsig_keys(start:Optional[int]=0, count:Optional[int]=100)

List TSIG keys defined within the configuration.

Attention: This API method requires the following:
  • BAM v9.1.0 or greater.

Parameters Description
start(int, optional) Indicates where in the list of objects to start returning objects. The list begins at an index of 0. Defaults to 0.
count(int, optional) The maximum number of elements to be returned. Defaults to 100.

Returns: An iterable of instances of TSIGKey.

Return type: Iterable[TSIGKey]

Example:

api = g.user.get_api()     # a user-aware bluecat.api.API instance
configuration_id = 100001  # ID of a Configuration
configuration = api.get_entity_by_id(configuration_id)

keys = configuration.get_tsig_keys(start=0, count=10)

for key in keys:
    print(key.name)

New in version 20.3.1.

get_view(name)

Get a named view (ref: split horizon DNS) out of a configuration. An exception is raised if the view doesn’t exist.

get_views()

Get an Iterator for all child views (ref: split horizon DNS) of the configuration.

Returns: Iterator for View entities

get_zones_by_hint(hint)

Get an array of accessible zones under the configuration.

Parameters Description
hint The partial or full name of the zone.

Returns: Returns an array of any zones (the FQDN of the zone) that match the given hint as data in JSON, using the result template format. The array contains a maximum of 10 elements.

is_address_allocated(address, mac_address)

Checks if an IPv4 address is allocated in the current configuration.

Parameters Description
address(str) The IPv4 address string.
mac_address(str) The MAC address associated with the IPv4 DHCP allocated address. The MAC address can be specified in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn or nn:nn:nn:nn:nn:nn, where nn is a hexadecimal value.

Returns: True/False

is_ip4_address_allocated(address, mac_address)

Warning: This method has been deprecated, use is_address_allocated instead.

Checks if an IPv4 address is allocated in the current configuration.

Parameters Description
address The IPv4 address string.
mac_address The MAC address associated with the IPv4 DHCP allocated address. The MAC address can be specified in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn or nn:nn:nn:nn:nn:nn, where nn is a hexadecimal value.

Returns: True/False