Client class - Platform - BlueCat Gateway - 24.1

Gateway Administration Guide
Locale
English
Product name
BlueCat Gateway
Version
24.1

Click a link to jump to the indicated section.

class bluecat_libraries.address_manager.api.Client(url, *, verify=True)

Bases: object

A client for calling BAM REST API v1 endpoints.

This client tracks authentication tokens and sends them with subsequent requests.

This client can be used as a context manager to automatically release used resources. Doing so does not automatically call the logout method. If not used as a context manager, we recommend you call the close method a single time.

Parameters Description
url (str)

URL with a scheme that indicates how to connect to the BlueCat Address Manager.
verify (Union[bool, str])

If true (the default), BAM’s TLS certificate is verified when using HTTPS communications. If a string, it is treated as a path to the CA bundle to use. This parameter mirrors the use of the parameter with the same name in the methods in the requests Python library.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    data = client.get_system_info()
    client.logout()

for key, value in data.items():
    print('{}: {}'.format(key, value))

Sample protocol and certificate validation scenarios:

# Use HTTP
Client("http://bam.example.com")

# Use HTTPS and the certificate must be valid and trusted by the default CAs.
Client("https://bam.example.com")

# Use HTTPS, but ignore certificate verification errors. Not recommended, but useful
# in case of self-signed certificates.
Client("https://bam.example.com", verify=False)

# Use HTTPS with the expectation that the certificate that BAM sends is either the same
# as the one in the specified file, or signed by the CA certificate in it.
# Typically, this scenario applies when using self-signed certificates.
Client("https://bam.example.com", verify="/path/to/file")

# Use HTTPS with the expectation that the certificate that BAM sends is either the same
# as the one in the specified directory, or signed by a CA certificate in it.
# The directory must have been processed with the ``c_rehash`` utility provided by OpenSSL.
Client("https://bam.example.com", verify="/path/to/dir")

New in version 21.5.1.

Note: Changed in version 22.4.1: Use https as fallback if the passed BAM URL does not have a scheme. Previously, http was used.

add_access_right(entity_id, user_id, value, overrides=None, properties=None)

Add an access right to an object.

Parameters Description
entity_id (int)

The object ID of the entity to which the access right is being added. Set to zero (0) if you are adding the access right to the root level default access rights.
user_id (int)

The object ID of the user to whom this access right applies.
value (str)

The value of the access right being added. This value must be one of the following items:

  • ADD

  • CHANGE

  • FULL

  • HIDE

  • VIEW
overrides (dict, optional)

A dictionary of type-specific overrides.
properties (dict, optional)

A dictionary including the following options:

  • workflowLevel - valid values for this option are:

    • NONE - changes made by the user or group take effect immediately.

    • RECOMMEND - changes made by the user or group are saved as change requests and must be reviewed and approved before they take effect.

    • APPROVE - changes made by the user or group take effect immediately and the user or group can approve change requests from other users or groups.

  • deploymentAllowed - A boolean value indicating whether or not the user or group can perform a full deployment of data from the configuration to a managed server.

  • quickDeploymentAllowed - A boolean value indicating whether or not the user or group can instantly deploy changed DNS resource records.

  • selectiveDeploymentAllowed - A boolean value indicating whether a user or group can perform a selective deployment of data to a managed server, and dynamically deploy resource records that are added, updated, and deleted within a DNS zone that has the dynamicUpdate parameter enabled. This property is supported from Address Manager v9.4.0

Note:

  • All of these properties are optional.

  • The deploymentAllowed property applies only to configuration, server, or root entities with Full access rights.

  • The selectiveDeploymentAllowed property can only be configured at the root level.

  • The workflowLevel property applies only to Change, Add, or Full access rights.

Returns: The object ID of the new access right.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import AccessRightValues

value = AccessRightValues.FullAccess
overrides = {"AliasRecord": "ADD", "Configuration": "VIEW"}
properties = {"deploymentAllowed": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    access_right_id = client.add_access_right(
        0, <user_id>, value, overrides, properties
    )
print(access_right_id)

New in version 21.8.1.

add_acl(entity_id, name, properties)

Add an Access Control List (ACL).

Parameters Description
entity_id (int)

The object ID of the configuration in which an ACL need to be added.
name (str)

The name of the ACL.
properties (list[str])

List of options. Use an exclamation mark to exclude a certain option.

Returns: The object ID of the newly created ACL.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>
name = "ACl_name"
properties = ["127.0.0.13", "!127.0.0.14"]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    acl_id = client.add_acl(entity_id, name, properties)
print(acl_id)

New in version 21.8.1.

add_additional_ip_addresses(server_id, ips, properties=None)

Add additional IPv4 addresses and loopback addresses to the Service interface for DNS service.

Parameters Description
server_id (int)

The object ID of the server to which the additional IP addresses is being added.
ips (list[str])

A list of the IPs addresses to add. The supported format is [“IP,serviceType”, “IP,serviceType”].
properties (dict, optional)

Object properties. This is reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

ips = ["10.0.0.10/32,loopback", "11.0.0.3/24,service"]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.add_additional_ip_addresses(<server_id>, ips)

Return type: None

New in version 21.11.1.

add_alias_record(view_id, absolute_name, linked_record_name, ttl=-1, properties=None)

Add an alias record.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
absolute_name (str)

The FQDN of the alias record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
linked_record_name (str)

The name of the record to which the alias is being linked.
ttl (int, optional)

The time-to-live (TTL) value of the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new alias resource record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "alias.example.com"
linked_record_name = "host.example.com"
ttl = 3000

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    alias_record_id = client.add_alias_record(<view_id>, absolute_name, linked_record_name, ttl)
print(alias_record_id)

New in version 21.8.1.

add_bulk_host_record(view_id, network_id, absolute_name, start_address, number_of_addresses, ttl=-1, properties=None)

Add a bulk of host records using auto-increment from the specific starting address.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
network_id (int)

The object ID of The network receiving the available IP addresses. Each address is used for one host record.
absolute_name (str)

The FQDN of the bulk host record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
start_address (str)

The starting IPv4 address for getting the available addresses.
number_of_addresses (int)

The number of addresses.
ttl (int, optional)

The time-to-live (TTL) value for the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including user-defined fields and excludeDHCPRange option. If excludeDHCPRange is true, then IP addresses within a DHCP range will be skipped.

Returns: A list of host record APIEntity objects based on available addresses and number of IP addresses required. If no addresses are available, an error will be shown.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "example.com"
start_address = "10.0.0.10"
number_of_addresses = 5
ttl = 3000

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    bulk_host_records = client.add_bulk_host_record(
        <view_id>, <network_id>, absolute_name, start_address, number_of_addresses, ttl
    )
for bulk_host_record in bulk_host_records:
    print(bulk_host_record)

New in version 21.8.1.

add_custom_option_definition(configuration_id, code, name, type, allow_multiple=False, properties=None)

Add a custom deployment option.

Parameters Description
configuration_id (int)

The object ID of the configuration.
code (int)

The option code for the custom deployment option. This value must be within the range of 151 to 174, 178 to 207, 212 to 219, 222 to 223, or 224 to 254.
name (str)

The name of the custom deployment option.
type (str)

The type of custom deployment option. This type must be one of the constants listed for DHCP custom option types.
allow_multiple (bool, optional)

This parameter determines whether or not the custom option requires multiple values. The default value is false.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new option defined.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DHCPCustomOptionType

configuration_id = <configuration_id>
code = 151
name = "test-custom-option"
type = DHCPCustomOptionType.TEXT

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    custom_option_id = client.add_custom_option_definition(
        configuration_id, code, name, type
    )
print(custom_option_id)

New in version 21.8.1.

add_device(configuration_id, device_name, device_type_id=0, device_subtype_id=0, ip4_addresses=None, ip6_addresses=None, properties=None)

Add a device to a configuration.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the device is to be located.
device_name (str)

The name of the device.
device_type_id (int, optional)

The object ID of the device type with which the device is associated. The value can be 0 if you do not wish to associate a device type to the device.
device_subtype_id (int, optional)

The object ID of the device sub-type with which the device is associated. The value can be 0 if you do not wish to associate a device sub-type to the device.
ip4_addresses (list[str], optional)

One or more IPv4 addresses to which the device is assigned.
ip6_addresses (list[str], optional)

One or more IPv6 addresses to which the device is assigned.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new device.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

configuration_id = <configuration_id>
device_name = "device_name"
device_type_id = <device_type_id>
device_subtype_id = <device_subtype_id>
ip4_addresses = ["127.0.0.13", "127.0.0.26"]
ip6_addresses = ["2001:DB8::1322:33FF:FE44:5566"]
properties = {<UDF_name>: <UDF_value>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    device_id = client.add_device(
        configuration_id,
        device_name,
        device_type_id,
        device_subtype_id,
        ip4_addresses,
        ip6_addresses,
        properties
    )
print(device_id)

New in version 21.8.1.

add_device_subtype(device_type_id, name, properties=None)

Add a device sub-type to Address Manager.

Parameters Description
device_type_id (int)

The object ID of the parent device type.
name (str)

The descriptive name for the device sub-type.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new device sub-type.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

device_type_id = <device_type_id>
name = "device_subtype_name"
properties = {<UDF_name>: <UDF_value>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    device_subtype_id = client.add_device_subtype(device_type_id, name, properties)
print(device_subtype_id)

New in version 21.8.1.

add_device_type(name, properties=None)

Add a device type to Address Manager.

Parameters Description
name (str)

The descriptive name for the device type.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new device type.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {<UDF_name>: <UDF_value>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    device_type_id = client.add_device_type("device_type_name", properties)
print(device_type_id)

New in version 21.8.1.

add_dhcp4_range(network_id, start_address, end_address, properties=None)

Add an IPv4 DHCP range.

Parameters Description
network_id (int)

The object ID of the IPv4 network in which the DHCP range is located.
start_address (str)

An IP address defining the lowest address or start of the range.
end_address (str)

An IP address defining the highest address or end of the range.
properties (dict, optional)

Object properties, including the object name and user-defined fields.

Returns: The object ID of the new DHCPv4 range.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

network_id = <network_id>
start_address = "10.0.0.10"
end_address = "10.0.0.13"
properties = {"name": "ip4-dhcp-range"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcp4_range_id = client.add_dhcp4_range(network_id, start_address, end_address, properties)
print(dhcp4_range_id)

New in version 21.8.1.

add_dhcp4_range_by_size(network_id, offset, size, properties=None)

Add an IPv4 DHCP range by offset and percentage.

Parameters Description
network_id (int)

The object ID of the IPv4 network in which the DHCP range is being located.
offset (int)

An integer value specifying the point where the range should begin.

  • A positive value indicate the starting IP address of the range will be counted from the IPv4 Network first IP address and forward in the range.

  • A negative value indicate the starting IP address of the range will be counted from the IPv4 Network Broadcast Address last IP address and backward in the range.
size (int)

The size of the range.

  • If the value of defineRangeBy is “OFFSET_AND_SIZE”, this value specify the number of addresses in the range.

  • If the value of defineRangeBy is “OFFSET_AND_PERCENTAGE”, this value specify the range size in a relative size proportional to the parent network size.
properties (dict, optional)

Object properties, including the object name, user-defined fields, and the value of defineRangeBy.

  • The possible values for defineRangeBy are “OFFSET_AND_SIZE” and “OFFSET_AND_PERCENTAGE”.

  • The default value for defineRangeBy is “OFFSET_AND_SIZE”.

Returns: The object ID of the new DHCPv4 range.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DHCPDefineRange

network_id = <ip4_network_id>
offset = <offset_number>
size = 4
properties = {"defineRangeBy": DHCPDefineRange.OFFSET_AND_PERCENTAGE}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcp4_range_id = client.add_dhcp4_range_by_size(network_id, offset, size, properties)
print(dhcp4_range_id)

New in version 21.8.1.

add_dhcp6_client_deployment_option(entity_id, option_name, value, properties=None)

Add a DHCPv6 client option and return the database object ID of the new option object.

Note:

DHCPv6 Client Deployment options can be assigned from the following levels:

  • Configuration

  • Server Group

  • Server

  • IPv6 Block

  • IPv6 Network

  • DHCPv6 Range

Parameters Description
entity_id (int)

The object ID of the entity to which the deployment option is being added.
option_name (str)

The name of the DHCPv6 client option being added. The name must be one of the following values:

  • dns-servers

  • domain-search-list

  • information-refresh-time

  • sntp-servers

  • unicast

  • wpad-url
value (list[str])

The value assigned to the option.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new DHCPv6 client object.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>
option_name = "information-refresh-time"
value = ["9669"]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    object_id = client.add_dhcp6_client_deployment_option(entity_id, option_name, value)
print(object_id)

New in version 21.8.1.

add_dhcp6_range(network_id, start_address, end_address, properties=None)

Add an IPv6 DHCP range.

Parameters Description
network_id (int)

The object ID of the network in which this DHCPv6 range is being located.
start_address (str)

An IP address defining the lowest address or start of the range.
end_address (str)

An IP address defining the highest address or end of the range.
properties (dict, optional)

Object properties, including the object name and user-defined fields.

Returns: The object ID of the new DHCPv6 range.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

network_id = <network_id>
start_address = "2000::1"
end_address = "2000::64"
properties = {"name": "test-dhcp6-range"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    object_id = client.add_dhcp6_range(network_id, start_address, end_address, properties)
print(object_id)

New in version 21.8.1.

add_dhcp6_range_by_size(ip6_network_id, start, size, properties=None)

Add an IPv6 DHCP range by size.

Parameters Description
ip6_network_id (int)

The object ID of the network in which the DHCP range is being located.
start (str)

An empty string, an positive integer, or IPv6 address specifying the point where the range should begin.

Note:

  • If defineRangeBy is set with the AUTOCREATE_BY_SIZE value in the property field, the start field must contain an empty string (“”).

  • If defineRangeBy is set with the OFFSET_AND_SIZE value in the property field, the start field must contain a positive integer value that indicates the starting IP address of the range will be counted from Network address and forward in the range.

  • If defineRangeBy is set with the START_ADDRESS_AND_SIZE value in the property field, the start field must contain a valid IPv6 address that will be used as the starting address of the DHCP range.
size (int)

The size of the range. Currently, the range size is only specified in a relative size proportional to the parent network size.
properties (dict, optional)

Object properties, including the following options: the object name, the value of defineRangeBy, and user-defined fields. The possible values for defineRangeBy are AUTOCREATE_BY_SIZE, OFFSET_AND_SIZE, and START_ADDRESS_AND_SIZE.

Note:

If the defineRangeBy value isn’t specified, the DHCP range will be created using AUTOCREATE_BY_SIZE by default.

Returns: The object ID of the new DHCPv6 range.

Return type: int

Example: 

from bluecat_libraries.address_manager.constants import DHCPDefineRange
from bluecat_libraries.address_manager.api import Client

start = "2"
size = 3
properties = {"name": "dhcp6-range", "defineRangeBy": DHCPDefineRange.OFFSET_AND_SIZE}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity_id = client.add_dhcp6_range_by_size(<ip6_network_id>, start, size, properties)
print(entity_id)

New in version 21.8.1.

add_dhcp6_service_deployment_option(entity_id, option_name, value, properties=None)

Add a DHCPv6 service option. DHCPv6 Service Deployment options can be assigned from the following levels:

  • Configuration

  • Server Group

  • Server

  • IPv6 block

  • IPv6 network

  • DHCPv6 range

Parameters Description
entity_id (int)

The object ID of the entity to which the service option is being added.
option_name (str)

The name of the DHCPv6 service option. The name must be one of the following values:

  • client-updates

  • ddns-domainname

  • ddns-dual-stack-mixed-mode

  • ddns-guard-id-must-match

  • ddns-hostname

  • ddns-other-guard-is-dynamic

  • ddns-ttl

  • ddns-updates

  • ddns-update-style

  • default-lease-time

  • do-reverse-updates

  • limit-addresses-per-ia

  • preferred-lifetime

  • rapid-commit

  • server-preference

  • update-conflict-detection
value (Union[str, list[str], list[list[str]]])

The value assigned to the option.
properties (dict, optional)

Object properties, including user-defined fields.

Return type: int

Returns: The object ID of the new option.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    option_id = client.add_dhcp6_service_deployment_option(<configuration_id>, "ddns-updates", ["true"])
print(option_id)

New in version 21.8.1.

add_dhcp_client_deployment_option(entity_id, option_name, value, properties=None)

Add a DHCP client option.

Parameters Description
entity_id (int)

The object ID of the entity to which the client option is added.
option_name (str)

The name of the DHCPv4 client option being added. This name must be one of the constants listed for DHCP client options.
value (Union[str, list[str], list[list[str]]])

The value assigned to the option.

Note:

Depending on the type of added DHCPv4 client option, the format of the value might differ.
properties (dict, optional)

Object properties, including user-defined fields.

Return type: int

Returns: The object ID of the new DHCPv4 client option object.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcpv4_client_id = client.add_dhcp_client_deployment_option(<ip4_block_id>, "time-offset", ['3600'])
print(dhcpv4_client_id)

New in version 21.8.1.

add_dhcp_deployment_role(entity_id, server_interface_id, type, properties=None)

Add a DHCP deployment role to an object.

Parameters Description
entity_id (int)

The object ID of the object to which the deployment role is being added.
server_interface_id (int)

The object ID of the server interface to which the role is being added.
type (str)

The type of DHCP role to add. The type must be one of the DHCPDeploymentRoleType constant.
properties (dict, optional)

A dictionary containing options including:

  • inherited - either true or false, indicates whether or not the deployment role was inherited.

  • secondaryServerInterfaceId - the object ID of the secondary server interface for a DHCP failover.

Returns: The object ID of the new DHCP server role object.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DHCPDeploymentRoleType

type = DHCPDeploymentRoleType.MASTER
properties = {"secondaryServerInterfaceId": <secondary_server_interface_id>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_role_id = client.add_dhcp_deployment_role(
        <ip4_network_id>, <server_interface_id>, type, properties
    )
print(deployment_role_id)

New in version 21.8.1.

add_dhcp_match_class(configuration_id, name, type, properties=None)

Add a DHCP match class to Address Manager.

Parameters Description
configuration_id (int)

The object ID of the configuration to which the DHCP match class is being added.
name (str)

The name of the DHCP match class.
type (str)

The type of the match criteria. This type must be one of the constants listed for DHCP match class criteria.
properties (dict, optional)

Object properties, following properties and values:

  • description - A description of the match class.

  • matchOffset - The Match Offset value for the MatchClass. It refers to the point where the match should begin.

  • matchLength - The Match Length value for the MatchClass. It refers to the number of characters to match.

  • customMatchRawString - A raw string that maps directly to a data or boolean expression for DHCP_CLASS_CUSTOM_MATCH and DHCP_CLASS_CUSTOM_MATCH_IF constants.

Note:

  • matchOffset and matchLength only apply to the following five constants:

    • DHCP_CLASS_HARDWARE

    • DHCP_CLASS_CLIENT_ID

    • DHCP_CLASS_VENDOR_ID

    • DHCP_CLASS_AGENT_CIRCUIT_ID

    • DHCP_CLASS_AGENT_REMOTE_ID

  • matchOffset and matchLength must be specify together.

Returns: The object ID of the new DHCP match class.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DHCPMatchClass

configuration_id = <configuration_id>
name = "dhcp-match-class-name"
type = DHCPMatchClass.DHCP_CLASS_VENDOR_ID
properties = {"matchOffset": 0, "matchLength": 256}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity_id = client.add_dhcp_match_class(configuration_id, name, type, properties)
print(entity_id)

New in version 21.8.1.

add_dhcp_service_deployment_option(entity_id, option_name, value, properties=None)

Add a DHCP service option.

Parameters Description
entity_id (int)

The object ID of the entity to which the service option is being added.
option_name (str)

The name of the DHCPv4 service option being added. This name must be one of the constants listed for DHCP service options.

Note:

If we do not configure the DDNS_UPDATE_STYLE service option, the default value is interim.
value (Union[str, list[str], list[list[str]]])

The value assigned to the option.

Note:

Depending on the type of deployment option, the format of the value input might differ.
properties (dict, optional)

Object properties, including user-defined fields.

Return type: int

Returns: The object ID of the new DHCPv4 service option.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import (
    DHCPServiceOption,
    DHCPServiceOptionConstant
)
entity_id = <ip4_network_id>
option_name = DHCPServiceOption.DDNS_HOSTNAME
value = [
    DHCPServiceOptionConstant.DDNS_HOSTNAME_TYPE_IP,
    DHCPServiceOptionConstant.DDNS_HOSTNAME_POSITION_APPEND,
    "10.0.0.10",
]
properties = {"inherited": "false"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcp_service_option_id = client.add_dhcp_service_deployment_option(
        entity_id, option_name, value, properties
    )
print(dhcp_service_option_id)

New in version 21.8.1.

add_dhcp_sub_class(match_class_id, value, properties=None)

Add a DHCP match class value.

Parameters Description
match_class_id (int)

The object ID of the match class in which the DHCP match class value is being added.
value (str)

The value of the DHCP match value to be matched with the match class. The length of the match value must be equal to the length, in bytes, specified in the match class.
properties (dict, optional)

Object properties, a dictionary including the following options:

  • description - a description of the match class.

Returns: The object ID of the new DHCP match class value.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

match_class_id = <match_class_id>
# The length value must be equal to the length of the match class
value = <dhcp_match_class_value>
properties = {"description": "description about sub class"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity_id = client.add_dhcp_sub_class(match_class_id, value, properties)
print(entity_id)

New in version 21.8.1.

add_dhcp_vendor_deployment_option(entity_id, option_id, value, properties=None)

Add a DHCP vendor deployment option to an object.

Parameters Description
entity_id (int)

The object ID of the entity to which the DHCP vendor deployment option is added. This must be the ID of a Configuration, IP4Block, IP4Network, IP4NetworkTemplate, IPv4Address, IP4DHCPRange, Server, MACAddress, or MACPool.
option_id (int)

The object ID of the vendor option definition.
value (Union[str, list[str], list[list[str]]])

The value for the option. The value should be appropriate for its option type.
properties (dict, optional)

Object properties, including user-defined fields. This value can be empty. If the DHCP vendor client deployment option is intended for use with a specific server, the object ID of the server must be specified in the properties.

Return type: int

Returns: The ID of the added DHCP vendor deployment option object.

Example: 

from bluecat_libraries.address_manager.api import Client

configuration_id = <configuration_id>
vendor_option_id = <vendor_option_id>
value = ['10.244.140.123']

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcp_vendor_option_id = client.add_dhcp_vendor_deployment_option(
        configuration_id, vendor_option_id, value
    )
print(dhcp_vendor_option_id)

New in version 21.8.1.

add_dns_deployment_option(entity_id, option_name, value, properties=None)

Add a DNS deployment option.

Parameters Description
entity_id (int)

The object ID of the entity to which the DNS deployment option is being added.
option_name (str)

The name of the DNS option being added. This name must be one of the constants listed listed in DNS options.
value (Union[str, list[str], list[list[str]]])

The list of raw option values. The list is processed before it is sent to Address Manager. The total length of the result (all values and a separator between each of them) should not exceed 65,536 characters. Depending on the type of deployment option added, the format of the values might differ.

Note:

If adding a Reverse Zone Name Format, the following values are supported:

  • ReverseZoneFormatType.STARTIP_NETMASK_NET or “[start-ip]-[net-mask].[net].inaddr.arpa”

  • ReverseZoneFormatType.STARTIP_ENDIP_NET or “[start-ip]-[end-ip].[net].in-addr.arpa”

  • ReverseZoneFormatType.STARTIP_SLASH_NETMASK_NET or “[start-ip]/[netmask].[net].in-addr.arpa”

  • ReverseZoneFormatType.STARTIP_SLASH_ENDIP_NET or “[start-ip]/[end-ip].[net].inaddr.arpa”

  • ReverseZoneFormatType.CUSTOM + ReverseZoneFormatType.SEPARATOR + “[customformat-value]” or “custom:<custom-format-value>”
properties (dict, optional)

Object properties, including comments and user-defined fields.

Return type: int

Returns: The ID of the added DNS deployment option.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <zone_id>
option_name = 'update-policy'
value = [
    ["grant", "test", "subdomain", "sub.domain.com", "ANY"],
    ["deny", "test2", "self", "test2", "ANY"],
]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_option_id = client.add_dns_deployment_option(entity_id, option_name, value)
print(deployment_option_id)

New in version 21.8.1.

add_dns_deployment_role(entity_id, server_interface_id, type, properties=None)

Add a DNS deployment role to an object.

Parameters Description
entity_id (int)

The object ID of the entity to which the deployment role is added.
server_interface_id (int)

The object ID of the server interface to which the role is added.
type (str)

The type of DNS role is to be added. The type must be one of those listed in DNS deployment role type.
properties (dict, optional)

Object properties, including the View associated with this DNS deployment role and user-defined fields.

Returns: The ID of the added DNS deployment role object.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DNSDeploymentRoleType

entity_id = <entity_id>
server_interface_id = <server_interface_id>
type = DNSDeploymentRoleType.MASTER
properties = {"view": <view_id>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dns_deployment_role_id = client.add_dns_deployment_role(
        entity_id, server_interface_id, type, properties
    )
print(dns_deployment_role_id)

New in version 21.8.1.

add_entity(parent_id, entity)

Add an entity object.

Parameters Description
parent_id (int)

The ID of the object that will be parent to the added entity.
entity (APIEntity)

The entity to add. Its fields should be structured as per

Returns: The ID of the added entity object.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIEntity

props = {
    udf1_name: 'udf1_value',
    udf2_name: 'udf2_value',
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = APIEntity(name='config', type='Configuration', properties=props)
    client.add_entity(<parent_id>, entity)

New in version 21.5.1.

add_enum_number(enum_zone_id, number, properties)

Add an ENUM number.

Parameters Description
enum_zone_id (int)

The object ID of an ENUM zone.
number (int)

The ENUM number.
properties (dict)

Object properties and user-defined fields. The dictionary should contain the following key:

  • data - The value is a comma-separated list of values for service, URI, comment, and ttl.

Returns: The object ID of the new ENUM number.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

number = 100
properties = {"data": "H323,example,a comment,300"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    enum_number_id = client.add_enum_number(<enum_zone_id>, number, properties)
print(enum_number_id)

New in version 21.8.1.

add_enum_zone(entity_id, prefix, properties=None)

Add an ENUM zone.

Parameters Description
entity_id (int)

The object ID of the parent object of the ENUM zone.
prefix (int)

The number prefix for the ENUM zone.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new ENUM zone.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    enum_zone_id = client.add_enum_zone(<entity_id>, 100)
print(enum_zone_id)

New in version 21.8.1.

add_external_host_record(view_id, absolute_name, properties=None)

Add an external host record.

Parameters Description
view_id (int)

The object ID of the view to which the external host record is being added.
absolute_name (str)

The FQDN of the external host record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new external host record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    external_host_record_id = client.add_external_host_record(<view_id>, "example.com")
print(external_host_record_id)

New in version 21.8.1.

add_generic_record(view_id, absolute_name, type, rdata, ttl=-1, properties=None)

Add a generic record.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
absolute_name (str)

The FQDN of the generic record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
type (str)

The type of record. Valid settings for this parameter are the generic resource record types supported in Address Manager: A, A6, AAAA, AFSDB, APL, CAA, CERT, DHCID, DNAME, DNSKEY, DS, ISDN, KEY, KX, LOC, MB, MG, MINFO, MR, NS, NSAP, PX, RP, RT, SINK, SSHFP, TLSA, WKS, TXT, and X25.
rdata (str)

The data of the resource record, in BIND format.
ttl (int, optional)

The time-to-live (TTL) value for the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new generic resource record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "example.com"
type = <record_type>
rdata = <record_data>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    generic_record_id = client.add_generic_record(<view_id>, absolute_name, type, rdata)
print(generic_record_id)

New in version 21.8.1.

add_hinfo_record(view_id, absolute_name, cpu, os, ttl=-1, properties=None)

Add a HINFO record.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
absolute_name (str)

The FQDN of the HINFO record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
cpu (str)

A string providing central processing unit information.
os (str)

A string providing operating system information.
ttl (int, optional)

The time-to-live (TTL) value of the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new HINFO resource record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "example.com"
cpu = "INTEL-386"
os = "WIN32"
ttl = 300

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    hinfo_record_id = client.add_hinfo_record(<view_id>, absolute_name, cpu, os, ttl)
print(hinfo_record_id)

New in version 21.8.1.

add_host_record(view_id, absolute_name, addresses, ttl=-1, properties=None)

Add a host record.

Parameters Description
view_id (int)

The object ID of the view to which this record is being added.
absolute_name (str)

The FQDN of the host record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
addresses (list)

A list of IP addresses.
ttl (int, optional)

The time-to-live value for the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Return type: int

Returns: The object ID of the new host resource record.

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "example.com"
addresses = ["10.0.0.3", "10.0.0.4"]
ttl = 3000
properties = {"reverseRecord": "false"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    host_record_id = client.add_host_record(<view_id>, absolute_name, addresses, ttl, properties)
print(host_record_id)

New in version 21.8.1.

add_ip4_block_by_cidr(entity_id, cidr, properties=None)

Add a new IPv4 Block using CIDR notation.

Parameters Description
entity_id (int)

The object ID of the target object’s parent object.
cidr (str)

The CIDR notation defining the block. For example: 172.0/16
properties (dict, optional)

Object properties. For more information about the available options, refer to Property Options Reference.

Returns: The object ID of the new IPv4 block.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>
cidr = "172.0/16"
properties = {"name": "ipv4-block-name", "allowDuplicateHost": "enable"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_block_id = client.add_ip4_block_by_cidr(entity_id, cidr, properties)
print(ip4_block_id)

New in version 21.8.1.

add_ip4_block_by_range(entity_id, start_address, end_address, properties=None)

Add a new IPv4 block defined by an address range. The address range must conform to CIDR boundaries.

Parameters Description
entity_id (int)

The object ID of the target object’s parent object.
start_address (str)

An IP address defining the lowest address or start of the block.
end_address (str)

An IP address defining the highest address or end of the block.
properties (dict, optional)

Object properties.

Returns: The object ID of the new IPv4 block.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {"name": <ipv4_block_name>, "inheritDefaultView": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_block_id = client.add_ip4_block_by_range(
        <configuration_id>, "10.0.0.1", "10.0.0.10", properties
    )
print(ip4_block_id)

New in version 21.8.1.

add_ip4_ip_group_by_range(ip4_network_id, name, start_address, end_address, properties=None)

Add an IPv4 IP group by range bound.

Parameters Description
ip4_network_id (int)

The object ID of the network in which the IP group is being added.
name (str)

The name of the IP group.
start_address (str)

A start IPv4 address of the IP group range.
end_address (str)

An end IPv4 address of the IP group range.
properties (dict, optional)

Object properties, including the user-defined fields.

Returns: The object ID of the new IPv4 IP group.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

ip4_network_id = <ip4_network_id>
name = <ip_group_name>
start_address = "10.0.0.1"
end_address = "10.0.0.20"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip_group_id = client.add_ip4_ip_group_by_range(
        ip4_network_id, name, start_address, end_address
    )
print(ip_group_id)

New in version 21.8.1.

add_ip4_ip_group_by_size(ip4_network_id, name, size, position_range_by=None, position_value=None, properties=None)

Add an IPv4 IP group by size.

Parameters Description
ip4_network_id (int)

The object ID of the network in which the IP group is being added.
name (str)

The name of the IP group.
size (int)

The number of addresses in the IP group.
position_range_by (str, optional)

A string specifying the position of the IP group range in the parent network. This is optional. The value must be one of the constants listed for IP group range position.
position_value (str, optional)

The offset value when using START_OFFSET or END_OFFSET. The start address of the IP group in the network when using START_ADDRESS. This is required only if position_range_by is specified.
properties (dict, optional)

Object properties, including the user-defined fields.

Returns: The object ID of the new IPv4 IP group.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import IPGroupRangePosition

ip4_network_id = <ip4_network_id>
name = <ip_group_name>
size = 10
position_range_by = IPGroupRangePosition.START_ADDRESS
position_value = "10.0.0.20"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip_group_id = client.add_ip4_ip_group_by_size(
        ip4_network_id, name, size, position_range_by, position_value
    )
print(ip_group_id)

New in version 21.8.1.

add_ip4_network(ip4_block_id, cidr, properties=None)

Add an IPv4 network using CIDR notation.

Parameters Description
ip4_block_id (int)

The object ID of the IPv4 block in which the IPv4 network is being added.
cidr (str)

The CIDR notation defining the network, for example: 10.10.10/24.
properties (dict, optional)

Object properties. For more information about the available options, refer to IPv4 objects.

Returns: The object ID of the new IPv4 network.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

ip4_block_id = <ip4_block_id>
cidr = "10.10.10/24"
properties = {"name": "ip4-network-name", "defaultView": <existing_view_id>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_network_id = client.add_ip4_network(ip4_block_id, cidr, properties)
print(ip4_network_id)

New in version 21.8.1.

add_ip4_reconciliation_policy(parent_id, name, properties)

Add an IPv4 reconciliation policy.

Parameters Description
parent_id (int)

The object ID of the parent object of the policy. The IPv4 reconciliation policies can be created at the configuration, IPv4 block, and IPv4 network levels.
name (str)

The name of the IPv4 reconciliation policy.
properties (dict)

Object properties and values listed in Reconciliation properties and values.

Note:

The hour specified for schedule must be in 12-hour clock format.

Returns: The object ID of the new reconciliation policy.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DiscoveryType, SNMPVersion

parent_id = <configuration_id>
name = "reconciliation-policy-name"
properties = {
    "discoveryType": DiscoveryType.SNMP,
    "seedRouterAddress": "10.244.140.124",
    "snmpVersion": SNMPVersion.V1,
    "snmpPortNumber": 161,
    "snmpCommunityString": "public",
    "networkBoundaries": "10.0.0.0/8",
    "schedule": "09:59AM,01 Nov 2021,ONCE",
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    policy_id = client.add_ip4_reconciliation_policy(parent_id, name, properties)
print(policy_id)

New in version 21.11.1.

add_ip4_template(configuration_id, template_name, properties=None)

Add an IPv4 template to a configuration.

Parameters Description
configuration_id (int)

The object ID of the configuration where you wish to add the IPv4 template
template_name (str)

The name of the IPv4 template
properties (dict, optional)

A dictionary defining the IPv4 template properties. It includes the following keys:

  • gateway: An integer specifying which address to assign an IPv4 gateway. If it’s a negative value, it counts from the end of the range.

  • reservedAddresses: A string specifying the reserved addresses details

Returns: The object ID of the new IPv4 template.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

template_name = <ip4_template_name>
reserved_addresses = (
    '{RESERVED_DHCP_RANGE,OFFSET_AND_PERCENTAGE,'
    '50,20,FROM_START,reserved_addresses_name,true}'
)
template_prop = {'gateway': 1, 'reservedAddresses': reserved_addresses}
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_template_id = client.add_ip4_template(<configuration_id>, template_name, template_prop)
print(ip4_template_id)

New in version 21.5.1.

add_ip6_address(entity_id, address, type, name=None, properties=None)

Add an IPv6 address to an IPv6 Network.

Parameters Description
entity_id (int)

The object ID of the entity where the IPv6 address is being added. This can be the object ID of a Configuration, IPv6 Block, or IPv6 Network.
address (str)

The IPv6 address. Address and type must be consistent.
type (str)

The type of IPv6 address. This value must be one of the following: MACAddress, IP6Address, or InterfaceID.
name (str, optional)

The descriptive name for the IPv6 address. This value can be empty.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new IPv6 address.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

entity_id = <entity_id>
address = <ip6_address>
type = ObjectType.IP6_ADDRESS
name = "ipv6-address-name"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity_id = client.add_ip6_address(entity_id, address, type, name)
print(entity_id)

New in version 21.8.1.

add_ip6_block_by_mac_address(parent_ip6_block_id, mac_address, name=None, properties=None)

Add an IPv6 Block by a MAC address.

Parameters Description
parent_ip6_block_id (int)

The object ID of the parent object to which the IPv6 block is being added. The entity must be another IPv6 Block.
mac_address (str)

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 (str, optional)

The descriptive name for the IPv6 block. This value can be empty.
properties (dict, optional)

Object properties, including user-defined fields. This value can be empty.

Returns: The object ID of the new IPv6 Block.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

parent_ip6_block_id = <ip6_block_id>
mac_address = "00:1B:44:11:3A:B7"
name = "ip6-address-name"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity_id = client.add_ip6_block_by_mac_address(parent_ip6_block_id, mac_address, name)
print(entity_id)

New in version 21.8.1.

add_ip6_block_by_prefix(parent_ip6_block_id, prefix, name=None, properties=None)

Add an IPv6 Block by specifying the prefix for the block.

Parameters Description
parent_ip6_block_id (int)

The object ID of the entity to which the IPv6 address is being added. The entity is another IPv6 Block.
prefix (str)

The IPv6 prefix for the new block.
name (str, optional)

The descriptive name for the IPv6 Block. This value can be empty.
properties (dict, optional)

Object properties, including user-defined fields. This value can be empty.

Returns: The object ID of the new IPv6 Block.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

ip6_block_id = <parent_ip6_block_id>
prefix = "2001::/64"
name = "ipv6-block-name"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip6_block_id = client.add_ip6_block_by_prefix(ip6_block_id, prefix, name)
print(ip6_block_id)

New in version 21.8.1.

add_ip6_network_by_prefix(ip6_block_id, prefix, name=None, properties=None)

Add an IPv6 Network by specifying the prefix for the network.

Parameters Description
ip6_block_id (int)

The object ID of the IPv6 Block in which the new IPv6 Network is being located.
prefix (str)

The IPv6 prefix for the new network.
name (str, optional)

The descriptive name for the IPv6 Network. This value can be empty.
properties (dict, optional)

Object properties, including user-defined fields. This value can be empty.

Returns: The object ID of the new IPv6 Network.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

prefix = "2001::/64"
name = "ipv6-network-name"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip6_network_id = client.add_ip6_network_by_prefix(<ip6_block_id>, prefix, name)
print(ip6_network_id)

New in version 21.8.1.

add_mac_address(configuration_id, mac_address, properties=None)

Add a MAC address.

Parameters Description
configuration_id (int)

The object ID of the parent configuration in which the MAC address is being added.
mac_address (str)

The MAC address as a 12-digit hexadecimal in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn, or nn:nn:nn:nn:nn:nn.
properties (dict, optional)

Object properties and user-defined fields. The properties may include:

  • name - A name for the MAC address.

  • macPool - The object ID of the parent MAC pool.

Returns: The object ID of the new MAC address.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

mac_address = "09-08-07-06-05-04"
properties = {"name": "mac-address-name", "macPool": <mac_pool_id>, <UDF_name>: <UDF_value>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    mac_address_id = client.add_mac_address(<configuration_id>, mac_address, properties)
print(mac_address_id)

New in version 21.11.1.

add_mx_record(view_id, absolute_name, linked_record_name, priority, ttl=-1, properties=None)

Add an MX record.

Parameters Description
view_id (int)

The object ID of the view to which the MX record is being added.
absolute_name (str)

The FQDN of the MX record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
linked_record_name (str)

The name of the record to which the MX record is linked.
priority (int)

Specifies which mail server to send clients to first when multiple matching MX records are present. Multiple MX records with equal priority values are referred to in a round-robin fashion.
ttl (int, optional)

The time-to-live (TTL) value of the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new MX resource record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "mx.example.com"
linked_record_name = "host.record.zone"
priority = 1

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    mx_record_id = client.add_mx_record(<view_id>, absolute_name, linked_record_name, priority)
print(mx_record_id)

New in version 21.8.1.

add_naptr_record(view_id, absolute_name, order=0, preference=0, ttl=-1, service=None, regexp=None, replacement=None, flags=None, properties=None)

Add an NAPTR record.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
absolute_name (str)

The FQDN for the NAPTR record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
order (int, optional)

Specifies the order in which NAPTR records are read if several are present and are possible matches. The lower order value takes precedence.
preference (int, optional)

Specifies the order in which NAPTR records are read if the order values are the same in multiple records. The lower preference value takes precedence.
ttl (int, optional)

The time-to-live (TTL) value of the record. To ignore the TTL, set the value to -1.
service (str, optional)

Specifies the service used for the NAPTR record. Valid settings for this parameter are listed in ENUM services.
regexp (str, optional)

A regular expression, enclosed in double quotation marks, used to transform the client data. If a regular expression is not specified, a domain name in the replacement parameter must be specified.
replacement (str, optional)

Specifies a domain name as an alternative to the reg_exp. This parameter replaces client data with a domain name.
flags (list[str], optional)

An optional parameter used to set flag values for the record.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new NAPTR resource record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import EnumServices

absolute_name = "example.com"
order = 10
preference = 100
ttl = 100
service = EnumServices.SIP
regexp = '"!^.*$!sip:jdoe@corpxyz.com!"'

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    naptr_record_id = client.add_naptr_record(
        <view_id>, absolute_name, order, preference, ttl, service, regexp)
print(naptr_record_id)

New in version 21.8.1.

add_parent_block(object_ids)

Add a parent block. Create an IPv4 or IPv6 block from a list of IPv4 or IPv6 blocks or networks. All blocks and networks must have the same parent but it does not need to be contiguous.

Parameters Description
object_ids (list[int])

A list of the object IDs of IPv4 or IPv6 blocks or networks.

Returns: The object ID of the new IPv4 or IPv6 parent block. This method does not create a name for the new block.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

object_ids = [<ip4_network1_id>,<ip4_network2_id>]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_block_id = client.add_parent_block(object_ids)
print(ip4_block_id)

New in version 21.8.1.

add_parent_block_with_properties(object_ids, properties=None)

Add a parent block with properties. Create an IPv4 or IPv6 block with a name from a list of IPv4 or IPv6 blocks or networks. All blocks and networks must have the same parent but it does not need to be contiguous.

Parameters Description
object_ids (list[int])

A list of the object IDs of IPv4 or IPv6 blocks or networks.
properties (dict, optional)

A dictionary containing the following option:

  • name - the name of the new IPv4 or IPv6 block to be created.

Returns: The object ID of the new IPv4 or IPv6 parent block.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

object_ids = [<ip4_network1_id>,<ip4_network2_id>]
properties = {"name": "ip4_block_name"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_block_id = client.add_parent_block_with_properties(object_ids, properties)
print(ip4_block_id)

New in version 21.8.1.

add_raw_deployment_option(entity_id, type, value, properties=None)

Add a raw deployment option. Raw deployment options are added to DNS or DHCP services in a format that will be passed to the service when deployed.

Parameters Description
entity_id (int)

The object ID of the entity to which the deployment option is being added.
type (str)

The type of option. The type must be one of the following values:

  • DNS_RAW

  • DHCP_RAW

  • DHCPV6_RAW
value (str)

The raw option value. The maximum supported characters are 65,536. The raw option will be passed to the DNS or DHCP service on the managed server exactly as you enter here.
properties (dict, optional)

Object properties, including associated server and server group, and user-defined fields.

Returns: The object ID of the newly added Raw option.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

type = ObjectType.DNS_RAW_OPTION
value = "Example"
properties = {"server": <server_id>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_id = client.add_raw_deployment_option(<ip4_network_id>, type, value, properties)
print(deployment_id)

New in version 21.8.1.

add_resource_record(view_id, absolute_name, type, rdata, ttl=-1, properties=None)

Add a resource record. This method is a generic method for adding resource records by specifying the name, type, and record data arguments.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
absolute_name (str)

The FQDN of the record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
type (str)

The type of record being added. Valid values for this parameter are the resource record types shown in Object Types:

  • AliasRecord

  • HINFORecord

  • HostRecord

  • MXRecord

  • TXTRecord

Note:

To add NAPTRRecord, SRVRecord, and GenericRecord, must use addNAPTRRecord, addSRVRecord, and addGenericRecord methods respectively.
rdata (str)

The data of the resource record in BIND format.
ttl (int, optional)

The time-to-live (TTL) value for the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new resource record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

view_id = <view_id>
absolute_name = "example.com"
type = ObjectType.HOST_RECORD
rdata = "10.0.0.10"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    resource_record_id = client.add_resource_record(view_id, absolute_name, type, rdata)
print(resource_record_id)

New in version 21.8.1.

add_response_policy(configuration_id, name, type, ttl, properties=None)

Add a DNS response policy.

Parameters Description
configuration_id (int)

The object ID of the configuration to which the response policy is being added.
name (str)

The name of the DNS response policy.
type (str)

This type must be one of the constants for Response policy types.
ttl (int)

The time-to-live (TTL) value in seconds.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new DNS response policy.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ResponsePolicy

configuration_id = <configuration_id>
name = <policy_name>
type = ResponsePolicy.BLACKLIST
ttl = 300

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    policy_id = client.add_response_policy(configuration_id, name, type, ttl)
print(policy_id)

New in version 21.8.1.

add_response_policy_item(policy_id, absolute_name, options=None)

Add a DNS response policy item under a local DNS response policy.

Parameters Description
policy_id (int)

The object ID of the parent local response policy to which the response policy item is being added.
absolute_name (str)

The FQDN of the response policy item.
options (list, optional)

Reserved for future use.

Returns: A boolean value indicating whether the Response policy item is added.

Return type: bool

Example: 

from bluecat_libraries.address_manager.api import Client

policy_id = <policy_id>
absolute_name = <policy_item_name>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    status = client.add_response_policy_item(policy_id, absolute_name)
print(status)

New in version 21.8.1.

add_server(configuration_id, name, default_interface_address, absolute_name, profile, properties=None)

Add a server to Address Manager.

Parameters Description
configuration_id (int)

The object ID of the configuration to which the server is being added.
name (str)

The name of the server to add.
default_interface_address (str)

The physical IP address for the server within Address Manager.
absolute_name (str)

The DNS FQDN by which the server is referenced.
profile (str)

The server capability profile. The profile describes the type of server or appliance being added and determines the services that can be deployed to this server. This must be one of the constants found in Server capability profiles.
properties (dict, optional)

Object properties, a dictionary including the following options:

  • connected - either true or false; indicates whether or not to connect to a server. In order to add and configure multi-port DNS/DHCP Servers, this option must be set to true. If false, other interface property options will be ignored.

  • upgrade - indicates whether or not to apply the latest version of DNS/DHCP Server software once the appliance is under Address Manager control. The value is either true or false, by default, false.

  • password - the server password. For more information on the default server password, refer to BlueCat default login credentials (This must be authenticated to view this topic).

  • servicesIPv4Address - IPv4 address used only for services traffic such as DNS, DHCP, DHCPv6, and TFTP. If dedicated management is enabled, this option must be specified.

  • servicesIPv4Netmask - IPv4 netmask used only for services traffic such as DNS, DHCP, DHCPv6, and TFTP. If dedicated management is enabled, this option must be specified.

  • servicesIPv6Address - IPv6 address used only for services traffic such as DNS, DHCP, DHCPv6, and TFTP. This is optional.

  • servicesIPv6Subnet - IPv6 subnet used only for services traffic such as DNS, DHCP, DHCPv6, and TFTP. This is optional.

  • xhaIPv4Address - IPv4 address used for XHA. This is optional.

  • xhaIPv4Netmask - IPv4 netmask used for XHA. This is optional.

  • redundancyScenario - networking redundancy scenarios. The possible values are ACTIVE_BACKUP Failover and IEEE_802_3AD Load Balancing.

  • encryptedNotification - A boolean value. If true, encrypted notfications between Address Manager and BlueCat DNS/DHCP Servers are enabled. If false (the default), those encrypted communications are disabled. This property is optional and supported only by Address Manager v9.4.0 or greater.

Note:

For DNS/DHCP Servers without multi-port support, the interface-related property options will be ignored.

Returns: The object ID of the new server.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ServerCapabilityProfiles

configuration_id = <configuration_id>
name = "server-name"
default_interface_address = <ip_address>
absolute_name = "example.com"
profile = ServerCapabilityProfiles.ADONIS_1200
properties = {"connected": "false"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    server_id = client.add_server(
        configuration_id,
        name,
        default_interface_address,
        absolute_name,
        profile,
        properties
    )
print(server_id)

New in version 21.8.1.

add_srv_record(view_id, absolute_name, linked_record_name, priority, port, weight, ttl=-1, properties=None)

Add an SRV record.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
absolute_name (str)

The FQDN of the SRV record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
linked_record_name (str)

The name of the record to which the SRV record is being linked.
priority (int)

Specifies which SRV record to use when multiple matching SRV records are present. The record with the lowest value takes precedence.
port (int)

The TCP/UDP port on which the service is available.
weight (int)

If two matching SRV records within a zone have equal priority, the weight value is checked. If the weight value for one object is higher than the other, the record with the highest weight has its resource records returned first.
ttl (int, optional)

The time-to-live (TTL) value of the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new SRV record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "srv.example.com"
linked_record_name = "host.example.com"
port = <tcp_or_udp_available_port>
priority = 10
weight = 5

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    srv_record_id = client.add_srv_record(
        <view_id>, absolute_name, linked_record_name, priority, port, weight
    )
print(srv_record_id)

New in version 21.8.1.

add_start_of_authority(entity_id, email, refresh, retry, expire, minimum, properties=None)

Add an SOA record.

Parameters Description
entity_id (int)

The object ID of the parent object of the SOA record.
email (str)

Specifies the email address of the administrator for the zones to which the SOA applies.
refresh (int)

The amount of time that a secondary server waits before attempting to refresh zone files from the primary server. This is specified in seconds using a 32-bit integer value. RFC 1912 recommends a value between 1200 and 4300 seconds.
retry (int)

Specifies the amount of time that the secondary server should wait before re-attempting a zone transfer from the primary server after the refresh value has expired. This is specified as a number of seconds using a 32-bit integer value.
expire (int)

Specifies the length of time that a secondary server will use a non-updated set of zone data before it stops sending queries. This is specified as a number of seconds using a 32-bit integer. RFC 1912 recommends a value from 1209600 to 2419200 seconds or 2 to 4 weeks.
minimum (int)

Specifies the maximum amount of time that a negative cache response is held in cache. A negative cache response is a response to a DNS query that does not return an IP address a failed request. Until this value expires, queries for this DNS record return an error.
properties (dict, optional)

Object properties, including user-defined fields. The supported properties are:

  • ttl: Time-To-Live.

  • mname: Primary server.

  • serialNumberFormat: Serial number format.

Returns: The object ID of the new SOA record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

email = "mail@example.com"
refresh = 1200
retry = 3600
expire = 1209600
minimum = 7200
properties = {"ttl": 4800, "mname": "example.com"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    soa_record_id = client.add_start_of_authority(
        <entity_id>, email, refresh, retry, expire, minimum, properties
    )
print(soa_record_id)

New in version 21.11.1.

add_tag(entity_id, name, properties=None)

Add an object tag.

Parameters Description
entity_id (int)

The object ID of the parent for this object tag. The parent is either an object tag or an object tag group.
name (str)

The name of the object tag.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new object tag.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    tag_id = client.add_tag(<entity_id>, "tag-name")
print(tag_id)

New in version 21.8.1.

add_tag_group(name, properties=None)

Add an object tag group.

Parameters Description
name (str)

The name of the tag group.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new tag group.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    tag_group_id = client.add_tag_group("tag-group-name")
print(tag_group_id)

New in version 21.8.1.

add_tftp_deployment_role(tftp_group_id, server_id, properties=None)

Add a TFTP deployment role to a specified object.

Parameters Description
tftp_group_id (int)

The object ID of the TFTP group to which the TFTP deployment role is being added.
server_id (int)

The object ID of the server interface with which the TFTP deployment role associates.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new TFTP deployment role.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    tftp_deployment_role_id = client.add_tftp_deployment_role(
        <tftp_group_id>, <server_id>
    )
print(tftp_deployment_role_id)

New in version 21.11.1.

add_tftp_file(entity_id, name, data, version=None, properties=None)

Add a TFTP file.

Parameters Description
entity_id (int)

The object ID of the parent object of the TFTP file. The parent can be a TFTP folder or TFTP group.
name (str)

The name of the TFTP file.
data (Union[str, IO])

The data to be uploaded and distributed to clients by TFTP.
version (str, optional)

The version of the file.
properties (dict, optional)

Object properties, including user-defined fields and description properties.

Return type: int

Returns: The object ID of the new TFTP file.

Example: 

from bluecat_libraries.address_manager.api import Client

name = "tftp-file-name"
version = <file_version>
properties = {<udf_name>: <udf_value>}

# Add TFTP file where input data is a string
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    tftp_file_id = client.add_tftp_file(<entity_id>, name, "example data", version, properties)

# Add TFTP file where input data is an I/O stream
with Client(<bam_host_url>) as client, open("test.png", "rb") as file:
    client.login(<username>, <password>)
    tftp_file_id = client.add_tftp_file(<entity_id>, name, file, version, properties)
print(tftp_file_id)

New in version 21.11.1.

add_tftp_folder(entity_id, name, properties=None)

Add a TFTP folder.

Parameters Description
entity_id (int)

The object ID of the parent object of the TFTP folder. The parent is either a TFTP group or another TFTP folder object.
name (str)

The name of the TFTP folder.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new TFTP folder.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <tftp_group_id>
name = "tftp-folder-name"
properties = {"comments": "The new TFTP folder"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    tftp_folder_id = client.add_tftp_folder(entity_id, name, properties)
print(tftp_folder_id)

New in version 21.8.1.

add_tftp_group(configuration_id, name, properties=None)

Add a TFTP group.

Parameters Description
configuration_id (int)

The object ID of the configuration where the TFTP group is being added.
name (str)

The name of the TFTP group.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new TFTP group.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

configuration_id = <configuration_id>
name = "tftp-group-name"
properties = {"comments": "The new TFTP group"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    tftp_group_id = client.add_tftp_group(configuration_id, name, properties)
print(tftp_group_id)

New in version 21.8.1.

add_txt_record(view_id, absolute_name, data, ttl=-1, properties=None)

Add a TXT record.

Parameters Description
view_id (int)

The object ID of the view to which the record is being added.
absolute_name (str)

The FQDN of the text record. If a record is added in a zone that is linked to an incremental naming policy, a single hash sign (#) must be added at the appropriate location in the FQDN. Depending on the policy order value, the location of the single hash sign varies.
data (str)

The text data of the record.
ttl (int, optional)

The time-to-live (TTL) value of the record. To ignore the TTL, set the value to -1.
properties (dict, optional)

Object properties, including comments and user-defined fields.

Returns: The object ID of the new text record.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "example.com"
data = "test"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    txt_record_id = client.add_txt_record(<view_id>, absolute_name, data)
print(txt_record_id)

New in version 21.8.1.

add_user(username, password, properties)

Add an Address Manager user.

Parameters Description
username (str)

The name of the user.
password (str)

The Address Manager password for the user. The password must be set even if the authenticator property option is defined.
properties (dict)

Object properties. It includes user-defined fields and options listed in List of options:

  • authenticator: The object ID of the external authenticator defined in Address Manager.

  • securityPrivilege: A security privilege type for non-administrative users with GUI, API, or GUI and API access. The valid values are listed in User security privileges.

    Note:

    NO_ACCESS is the default value.

  • historyPrivilege: A history privilege type for non-administrative users with GUI or GUI and API access. The valid values are: HIDE or VIEW_HISTORY_LIST.

    Note:

    HIDE is the default value.

  • email: The user’s email address (required).

  • phoneNumber: The user’s phone number (optional).

  • userType: ADMIN or REGULAR

    Note:

    REGULAR represents a non-administrative user and is the default value.

  • userAccessType: API, GUI, or GUI_AND_API (required).

Returns: The object ID of the new Address Manager user.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {
    "email": "myemail@mail.com",
    "userAccessType": "GUI"
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    user_id = client.add_user(<new_username>, <user_password>, properties)
print(user_id)

New in version 21.8.1.

add_user_defined_field(object_type, udf)

Add a user-defined field for an object type.

Parameters Description
object_type (str)

The object type that the field is defined for.
udf (APIUserDefinedField)

The user-defined field to add.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIUserDefinedField
from bluecat_libraries.address_manager.constants import ObjectType, UserDefinedFieldType

udf = APIUserDefinedField(
    name="Unique UDF name",
    displayName="UDF display name",
    type=UserDefinedFieldType.TEXT,
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.add_user_defined_field(ObjectType.CONFIGURATION, udf)

Return type: None

New in version 21.5.1.

add_user_defined_link(definition)

Add a new user-defined link definition.

Parameters Description
definition (UDLDefinition)

The user-defined link to add.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import UDLDefinition
from bluecat_libraries.address_manager.constants import UserDefinedLinkEntityType

definition = UDLDefinition(
    linkType=<UniqueLinkTypeName>,
    displayName=<My Link Type>,
    description="My Link Type description",  # BAM 9.4.0 or greater
    sourceEntityTypes=[UserDefinedLinkEntityType.IP4_NETWORK],
    destinationEntityTypes=[
        UserDefinedLinkEntityType.IP4_NETWORK,
        UserDefinedLinkEntityType.IP4_BLOCK,
    ],
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.add_user_defined_link(definition)

Return type: None

New in version 21.5.1.

add_user_group(group_name, properties=None)

Add a user group.

Parameters Description
group_name (str)

The name of the user group.
properties (dict, optional)

A dictionary defining the User Groups’ properties. It includes the following key:

  • isAdministrator: either true or false, to indicate whether or not you wish to add an administrator user group to Address Manager.

Returns: The object ID of the new Address Manager user group.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

group_name = <user_group_name>
properties = {"isAdministrator": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    user_group_id = client.add_user_group(group_name, properties)
print(user_group_id)

New in version 21.8.1.

add_vendor_option_definition(profile_id, option_id, option_name, type, description, allow_multiple=False, properties=None)

Add a vendor option definition to a vendor profile.

Parameters Description
profile_id (int)

The object ID of the vendor profile.
option_id (int)

The deployment option ID. This value must be within the range of 1 to 254.
option_name (str)

The name of the vendor option.
type (str)

This type must be one of the constants listed for Vendor profile option types.
description (str)

A description of the vendor option.
allow_multiple (bool, optional)

Determines whether or not the custom option requires multiple values. The default value is false.
properties (dict, optional)

Object properties, including user-defined fields. This value can be empty.

Returns: The object ID of the new vendor option definition.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import VendorProfileOptionType

profile_id = <vendor_profile_id>
option_id = 12
name = "test_vendor_option"
type = VendorProfileOptionType.IP4
description = "example vendor option"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    option_id = client.add_vendor_option_definition(
        profile_id, option_id, name, type, description
    )
print(option_id)

New in version 21.8.1.

add_vendor_profile(name, identifier, description, properties=None)

Add a vendor profile.

Parameters Description
name (str)

An unique descriptive name for the vendor profile. This name is not matched against DHCP functionality.
identifier (str)

An unique identifier sent by the DHCP client software running on a device.
description (str)

A description of the vendor profile.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new vendor profile.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

identifier = "identifier_vendor_profile"
description = "New vendor profile"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    vendor_id = client.add_vendor_profile("test_vendor", identifier, description)
print(vendor_id)

New in version 21.8.1.

add_view(configuration_id, name, properties=None)

Add a DNS view.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the new DNS view is being located.
name (str)

The name of the view.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new DNS view.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {<UDF_name>: <value>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    view_id = client.add_view(<configuration_id>, "view-name", properties)
print(view_id)

New in version 21.8.1.

add_zone(entity_id, absolute_name, properties=None)

Add a DNS zone.

Parameters Description
entity_id (int)

The object ID of the parent object to which the zone is being added. For top-level domains, the parent object is a DNS view. For sub-zones, the parent object is a top-level domain or DNS zone.
absolute_name (str)

The FQDN of the zone with no trailing dot.
properties (dict, optional)

Object properties, including user-defined fields, and the following flags:

  • template - An optional network template association.

  • deployable - A boolean value. Set to true to make the zone deployable. The default value is false.

  • These properties are supported by Address Manager v9.4.0:

    • dynamicUpdate - A boolean value. If set to true, any resource records that are added, updated, or deleted within the zone will be selectively deployed to the associated primary DNS/DHCP Server of that zone. The default value is false.

    • moveDottedResourceRecords - A boolean value. If set to false, existing dotted-name resource records matching the new subdomain will not be moved into the new subdomain. The default value is true.

Note:

  • If the deployable flag is set to true, the dynamicUpdate flag can only be set to true.

  • Once the dynamicUpdate feature is enabled, a full DNS deployment must perform before resource record changes are automatically deployed.

  • If a deployment option within the zone is updated, deployment is not performed automatically.

  • If a deployment option followed by a resource record change is updated, only the resource record change is deployed. The deployment option change must be performed by a manual deployment.

Returns: The object ID of the new DNS zone.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

absolute_name = "example.com"
properties = {
    "deployable": "true",
    "template": <zone_template_id>,
    <UDF_name>: <UDF_value>,
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    zone_id = client.add_zone(<entity_id>, absolute_name, properties)
print(zone_id)

New in version 21.8.1.

add_zone_template(entity_id, name, properties=None)

Add a DNS zone template.

Parameters Description
entity_id (int)

The object ID of the DNS view if adding a view-level zone template. The object ID of the configuration if adding a configuration-level zone template.
name (str)

The name of the DNS zone template.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the new DNS zone template.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <view_id>
name = <zone_template_name>
properties = {<UDF_name>: <UDF_value>}

 with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    zone_template_id = client.add_zone_template(entity_id, name, properties)
print(zone_template_id)

New in version 21.8.1.

apply_ip4_template(object_id, template_id, properties=None)

Apply an IPv4 Template.

Parameters Description
object_id (int)

The object ID of the IPv4 template recipient. If the value is zero, the template is applied to all networks.
template_id (int)

The object ID of the IPv4 template
properties (dict, optional)

A dict defining what is applied. The option of any missing key will be ignored. The dict contains the following keys:

  • applyToNonConflictedNetworksOnly: A string specifying if the template is applied only to a non-conflicted network. The default value is ‘false’.

  • applyDeploymentOptions: A string specifying if the template’s deployment options are applied. The default value is ‘false’.

  • applyReservedAddresses: A string specifying if the template’s reserved IPv4 addresses are applied. The default value is ‘false’.

  • applyGateway: A string specifying if the template’s gateway offset is applied. The default value is ‘false’.

  • applyDHCPRanges: A string specifying if the template’s DHCP ranges are applied. The default value is ‘false’.

  • applyIPGroups: A string specifying if the template’s IP groups are applied. The default value is ‘false’.

  • conflictResolutionOption: ‘networkSettings’ or ‘templateSettings’. Specify which setting is taken in case of conflict. The default value is networkSettings.

  • convertOrphanedIPAddressesTo: ‘STATIC’ or ‘DHCP RESERVED’ or ‘UNASSIGNED’. Specify what to convert orphaned IP addresses to. The default value is ‘DHCP RESERVED’

Returns: The task ID of the network template apply task

Return type: str

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {'applyToNonConflictedNetworksOnly': 'false',
              'applyDeploymentOptions': 'true',
              'applyReservedAddresses': 'true',
              'applyGateway': 'true',
              'applyDHCPRanges': 'true',
              'applyIPGroups': 'true',
              'conflictResolutionOption': 'templateSettings'
              'convertOrphanedIPAddressesTo': 'UNASSIGNED'}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    task_id = client.apply_ip4_template(<object_id>, <template_id>, properties)
print(task_id)

New in version 21.5.1.

assign_ip4_address(configuration_id, ip4_address, action, mac_address=None, host_info=None, properties=None)

Assign a MAC address and other properties to an IPv4 address.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the IPv4 address is located.
ip4_address (str)

The IPv4 address.
action (str)

This parameter must be one of the constants of IP assignment action values.
mac_address (str, optional)

The MAC address to assign to the IPv4 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.
host_info (list, optional)

A list containing host information for the address with the following format: [hostname,viewId,reverseFlag,sameAsZoneFlag]. Where:

  • hostname - The FQDN of 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.
properties (dict, optional)

A dictionary containing the following property, including user-defined fields:

  • ptrs - a string containing the list of unmanaged external host records to be associated with the IPv4 address in the format: viewId,exHostFQDN[, viewId,exHostFQDN,…]

  • name - name of the IPv4 address.

  • locationCode - the hierarchical location code consists of a set of 1 to 3 alpha-numeric strings separated by a space. The first two characters indicate a country, followed by next three characters which indicate a city in UN/LOCODE. New custom locations created under a UN/LOCODE city are appended to the end of the hierarchy. For example, CA TOR OF1 indicates: CA= Canada TOR=Toronto OF1=Office 1.

  • allowDuplicateHost (optional) - duplicate hostname check option. There are three possible values for this property:

    • Enable - set to enable the property and refuse duplicate hostnames.

    • Disable - set to disable the property and allow duplicate hostnames.

    • Inherit - set to make the hostname use the option specified in the higher-level parent object.

    Note:

    Disable is the default value for allowDuplicateHost.

  • pingBeforeAssign (optional) - specifies whether Address Manager performs a ping check before assigning the IP address. The property can be one of the following values:

    • enable - specifies that Address Manager performs a ping check before assigning the IP address.

    • disable - specifies that Address Manager will not perform a ping check before assigning the IP address.

Returns: The object ID of the newly assigned IPv4 address.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import IPAssignmentActionValues

configuration_id = <configuration_id>
ip4_address = <ip4_address>
action = IPAssignmentActionValues.MAKE_STATIC
mac_address = <mac_address>
host_info = [<existing_host_name>, <view_id>, "false", "true"]
properties = {"locationCode": "CA"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_address_id = client.assign_ip4_address(
        configuration_id,
        ip4_address,
        action,
        mac_address,
        host_info,
        properties,
    )
print(ip4_address_id)

New in version 21.8.1.

assign_ip4_template(object_id, template_id, properties=None)

Assign an IPv4 template to an IP4 Block, IP4 Network, DHCPv4 Range or DHCPv4 Address.

Parameters Description
object_id (int)

The object ID of the IPv4 template recipient
template_id (int)

The object ID of the IPv4 template
properties (dict, optional)

A dict defining how the IPv4 template is assigned. It includes the following key:

  • overrideAssignedTemplate: A string specifying should the previous assigned template is overridden. The default value is ‘false’

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {'overrideAssignedTemplate': 'false'}
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.assign_ip4_template(<object_id>, <template_id>, properties)

Return type: None

New in version 21.5.1.

assign_ip6_address(entity_id, address, action, mac_address=None, host_info=None, properties=None)

Assign an IPv6 address to a MAC address and host.

Parameters Description
entity_id (int)

The object ID of the entity in which the IPv6 address is being assigned. This can be the object ID of a Configuration, IPv6 Block, or IPv6 Network.
address (str)

The IPv6 address. The address must be created with addIP6Address before it can be assigned.
action (str)

This parameter determines how to assign the address. Valid value is MAKE_STATIC or MAKE_DHCP_RESERVED.
mac_address (str, optional)

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.
host_info (list, optional)

The host information for the IPv6 address. This value can be empty. The host_info string uses the following format: viewId, hostname, ifSameAsZone, ifReverseMapping
properties (dict, optional)

Object properties, including user-defined fields, this value can be empty, containing the following properties:

  • ptrs - A string containing the list of unmanaged external host records to be associated with the IPv6 address in the format: viewId,exHostFQDN[, viewId,exHostFQDN,…]

  • name - The name of the IPv6 address.

  • locationCode - The hierarchical location code consists of a set of 1 to 3 alpha-numeric strings separated by a space. The first two characters indicate a country, followed by next three characters which indicate a city in UN/LOCODE. New custom locations created under a UN/LOCODE city are appended to the end of the hierarchy. For example, CA TOR OF1 indicates: CA = Canada TOR = Toronto OF1 = Office 1.

  • reserveUsing - Defines the type of reservation, if through Client DUID or MAC Address. Applicable only for DHCP Reserved IP Addresses. If this value is not defined, the system defaults to Client DUID.

  • DUID - The DHCPv6 unique identifier.

Returns: True if the IPv6 address is successfully assigned, return False if the address is not successfully assigned.

Return type: bool

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import IPAssignmentActionValues

entity_id = <ip6_block_id>
ip6_address = <ipv6_address>
action = IPAssignmentActionValues.MAKE_STATIC
mac_address = <MAC_address>
host_info = [<view id>, "www.example.com", "false", "true"]
properties = {"name": "ip6-address-name", "locationCode": "CA"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    assigned_ip6_address = client.assign_ip6_address(
        entity_id, ip6_address, action, mac_address, host_info, properties
    )
print(assigned_ip6_address)

New in version 21.8.1.

assign_next_available_ip4_address(configuration_id, entity_id, action, mac_address=None, host_info=None, properties=None)

Assign the next available IPv4 address. Assign a MAC address and other properties to the next available and unallocated IPv4 address within a configuration, block, or network.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the IPv4 address is located.
entity_id (int)

The object ID of the configuration, block, or network in which to look for the next available address.
action (str)

This parameter must be one of the constants of IP assignment action values.
mac_address (str, optional)

The MAC address to assign to the IPv4 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.
host_info (list, optional)

A list containing host information for the address in the following format: [hostname, viewId, reverseFlag, sameAsZoneFlag]. Where:

  • hostname - The FQDN of 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.
properties (dict, optional)

Object properties.

Returns: The APIEntity for the newly assigned IPv4 address.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import IPAssignmentActionValues

configuration_id = <configuration_id>
entity_id = <ip4_network_id>
action = IPAssignmentActionValues.MAKE_STATIC
mac_address = <mac_address>
host_info = [<existing_host_name>, <view_id>, "false", "true"]
properties = {"locationCode": "CA", "skip": "10.0.1.8,10.0.1.9", "allowDuplicateHost": "Enable"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_address = client.assign_next_available_ip4_address(
        configuration_id,
        entity_id,
        action,
        mac_address,
        host_info,
        properties,
    )
print(ip4_address)

New in version 21.8.1.

assign_or_update_template(zone_id, template_id, properties)

Assign, update, or remove a DNS zone template.

Parameters Description
zone_id (int)

The object ID of the zone to which the zone template is being assigned or updated.
template_id (int)

The object ID of the DNS zone template. To remove a template, set this value to 0 zero.
properties (dict)

A dictionary containing the following settings:

  • templateType - Mandatory. Specify the type of template on which this operation is being performed. The only possible value is “ZoneTemplate”.

  • zoneTemplateReapplyMode - Optional. Specify the re-apply mode for various properties of the template. If the re-apply mode is not specified, the default value is templateReapplyModeIgnore. The possible values are: ZoneTemplateReapplyMode.OVERWRITE, ZoneTemplateReapplyMode.UPDATE, ZoneTemplateReapplyMode.IGNORE

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

properties = {"templateType": ObjectType.ZONE_TEMPLATE}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.assign_or_update_template(<zone_id>, <template_id>, properties)

Return type: None

New in version 21.8.1.

associate_mac_address_with_pool(configuration_id, mac_pool_id, mac_address)

Associate a MAC address with a MAC pool. If a MAC address object does not exist for that MAC address, it will be created.

Parameters Description
configuration_id (int)

The object ID of the parent configuration in which the MAC address resides.
mac_pool_id (int)

The object ID of the MAC pool with which this MAC address is associated.
mac_address (str)

The MAC address as a 12-digit hexadecimal in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn, or nn:nn:nn:nn:nn:nn.

Example: 

from bluecat_libraries.address_manager.api import Client

mac_address = "1C:12:28:08:09:87"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.associate_mac_address_with_pool(<configuration_id>, <mac_pool_id>, mac_address)

Return type: None

New in version 21.11.1.

property bam_url

A URL to the Address Manager the client is created for.

This is not the verbatim value given during initialization. It contains only the scheme, host, and (if specified) port, which will be used by the client.

Return type: str

New in version 23.1.0.

property bam_version

Version of the BlueCat Address Manager the client is created for.

Provides a structured Version object in contrast to the simple str value of property system_version.

Return type: Version

Returns: A version or None if the client is not authenticated yet.

break_replication()

Break replication and return the primary server to the original stand-alone state.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.break_replication()

Return type: None

New in version 21.11.1.

break_xha_pair(xha_server_id, break_in_proteus_only=False)

Break an xHA pair and return each server to its original stand-alone state.

Parameters Description
xha_server_id (int)

The object ID of the xHA server.
break_in_proteus_only (bool, optional)

A boolean value, to determine whether or not the xHA pair breaks in the Address Manager interface only. This argument breaks the xHA pair in Address Manager, even if the xHA settings are not removed on the actual servers.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.break_xha_pair(<xha_server_id>, False)

Return type: None

New in version 21.11.1.

change_state_ip4_address(id, target_state, mac_address=None)

Convert the state of an address from and between Reserved, DHCP Reserved, and Static, or DHCP Allocated to DHCP Reserved.

Parameters Description
id (int)

The object ID of the address of which the state is being changed .
target_state (str)

One of MAKE_STATIC, MAKE_RESERVED, MAKE_DHCP_RESERVED.
mac_address (str, optional)

Optional and only needed, if the target requires it. For example, MAKE_DHCP_RESERVED. The MAC address to assign to the IPv4 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.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import IPAssignmentActionValues

id = <ip4_address_id>
target_state = IPAssignmentActionValues.MAKE_DHCP_RESERVED
mac_address = "00-1B-45-01-5A-B7"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.change_state_ip4_address(id, target_state, mac_address)

Return type: None

New in version 21.8.1.

clear_ip6_address(id)

Clear an IPv6 address assignment.

Parameters Description
id (int)

The object ID of the IPv6 address to unassign.

Raises:

ErrorResponse – When BAM fails to clear IPv6 address.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.clear_ip6_address(<id>)

Return type: None

New in version 21.8.1.

close()

Release any allocated resources, e.g., an internal session.

Return type: None

configure_audit_log_export(audit_log_settings)

Configure the audit data export service to an external database, either a Splunk server or an HTTP endpoint.

Attention:

This API method requires the following:

  • If you enter an HTTPS endpoint in the Output URI or Healthcheck URI field when configuring HTTP output or Host field when configuring Splunk output, you must select this check box and enter TLS information.

Parameters Description
audit_log_settings (dict)

The data for Audit data settings.

Example: 

from bluecat_libraries.address_manager.api import Client

audit_log_settings = {
    "sinks": [{"healthCheck": False, "type": "http", "uri": "http://localhost:9900"}],
    "enable": True,
}
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.configure_audit_log_export(audit_log_settings)

Return type: None

New in version 21.5.1.

configure_server_services(server_ids, configuration)

Get a token value of the services configuration task.

Parameters Description
server_ids (list)

The object IDs of the servers to configure.
configuration (dict)

The configuration description of the services to be configured on the servers.

Returns: The token of the configuration indicating that the server(s) are configured with services based on the specified configuration.

Return type: str

Example: 

from bluecat_libraries.address_manager.api import Client

server_ids = [2001, 2002, 2003]
configuration = {
    "version": "1.0.0",
    "services": {
        "ntp": {
            "configurations": [
                {
                    "ntpConfiguration": {
                        "enable": True,
                        "servers": [
                            {
                                "address": "192.0.2.10",
                                "stratum": "default"
                            }
                        ]
                    }
                }
            ]
        }
    }
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    token = client.configure_server_services(server_ids, configuration)
print(token)

New in version 21.5.1.

configure_streaming_replication(standby_server, compress_replication=False, latency_warning_threshold=3600, latency_critical_threshold=86400, properties=None)

Enable database replication on a remote system to automate the setup of replication between two or three Address Manager systems.

Note:

The Address Manager server that this method runs against becomes the primary Address Manager.

Parameters Description
standby_server (str)

The IP address of the standby Address Manager.

Note:

When adding a standby server, the server cannot be part of an existing database replication environment or a removed standby server. You can only add a standby server if it is operating as a Standalone server.
compress_replication (bool, optional)

If set to True, compress database replication files. The default value is False.

Note:

Compressing database replication files is a resource-intensive process that might affect system performance. Use caution when performing this action.
latency_warning_threshold (int, optional)

The value to specify the warning threshold latency of replication, in seconds (sec). Valid values for the parameter range from 0 to any positive value. The default value is 3600 seconds.
latency_critical_threshold (int, optional)

The value to specify the critical threshold latency of replication, in seconds (sec). Valid values for the parameter range from 0 to any positive value. The default value is 86400 seconds.
properties (dict, optional)

A dictionary containing the following option:

  • secondStandbyServer - Used to add an additional standby server. The server’s IP address is required.

Example: 

from bluecat_libraries.address_manager.api import Client

standby_server = <ip4_address>
properties = {"secondStandbyServer": <ip4_address>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.configure_streaming_replication(standby_server, False, 3600, 86400, properties)

Return type: None

New in version 21.11.1.

create_xha_pair(configuration_id, active_server_id, passive_server_id, active_server_new_ip4_address, properties)

Create an xHA pair.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the xHA servers are located.
active_server_id (int)

The object ID of the active DNS/DHCP Server.
passive_server_id (int)

The object ID of the passive DNS/DHCP Server.
active_server_new_ip4_address (str)

The new IPv4 address for the active server.

Note:

This is the physical interface of the active server used during creation of the pair. The original IP address of the active server is assigned to the virtual interface.
properties (dict)

A dictionary containing the following options:

  • activeServerPassword: The deployment password for the active server.

  • passiveServerPassword: The deployment password for the passive server.

    Note:

    For more information on default server password, refer to BlueCat default login credentials (the user must be authenticated to view this topic).

  • pingAddress: An IPv4 address that is accessible to both active and passive servers in the xHA pair.

  • ip6Address: An optional IPv6 address for the xHA pair.

  • newManagementAddress: The new IPv4 address for the Management interface for the active server (only for DNS/DHCP Servers with dedicated management enabled).

  • backboneActiveServerIPv4Address: The IPv4 address of the xHA interface for the active server (eth1).

  • backboneActiveServerIPv4Netmask: The IPv4 netmask of the xHA interface for the active server (eth1).

  • backbonePassiveServerIPv4Address: The IPv4 address of the xHA interface for the passive server (eth1).

  • backbonePassiveServerIPv4Netmask: The IPv4 netmask of the xHA interface for the passive server (eth1).

  • activeServerIPv4AddressForNAT: The inside virtual IPv4 address for the active server.

  • passiveServerIPv4AddressForNAT: The inside virtual IPv4 address for the passive server.

  • activeServerNewIPv4AddressForNAT: The inside physical IPv4 address for the active server.

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {"activeServerPassword": "bluecat", "passiveServerPassword": "bluecat"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.create_xha_pair(
        <configuration_id>, <active_server_id>, <passive_server_id>,
        <active_server_new_ip4_address>, properties
    )

Return type: None

New in version 21.11.1.

custom_search(type, filters, options=None, start=0, count=10, include_ha=None)

Search for a list of entities by specifying object properties.

Parameters Description
type (str)

The object type aiming to search. This must be one for the following object types:

  • IP4Block

  • IP4Network

  • IP4Addr

  • GenericRecord

  • HostRecord

  • Any other objects with user-defined fields.
filters (dict)

The list of valid supported search field names.
options (list, optional)

The list of search options specifying the search behavior. Reserved for future use.
start (int, optional)

Indicates where in the list of returned objects to start returning objects. The value must be a positive value, and the default value is 0.
count (int, optional)

The maximum number of objects to return. The value must be a positive value between 1 and 1000. The default value is 10.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: A list of APIEntities matching the specified object properties or an empty list. The APIEntities will at least contain Object Type, Object ID, Object Name, and Object Properties.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

type = ObjectType.IP4_NETWORK
filters = {'inheritDNSRestrictions': 'true'}
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.custom_search(type, filters)
for entity in entities:
    print(entity['name'])

New in version 21.5.1.

delete_access_right(entity_id, user_id)

Delete the access right of an object.

Parameters Description
entity_id (int)

The object ID of the entity to which the access right is assigned.
user_id (int)

The object ID of the user to whom this access right is applied.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <view_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_access_right(entity_id, <user_id>)

Return type: None

New in version 21.8.1.

delete_dhcp6_client_deployment_option(entity_id, server_id, option_name)

Delete a DHCPv6 client option.

Parameters Description
entity_id (int)

The object ID of the entity to which the client option is deleted.
server_id (int)

The specific server or server group to which this option is deployed. To return an option that has not been assigned to a server role, set this value to 0 (zero).
option_name (str)

The name of the DHCPv6 client option deleted. This name must be one of the constants listed for DHCP6 client options.

Example: 

from bluecat_libraries.address_manager.constants import DHCP6ClientDeploymentOptionType
from bluecat_libraries.address_manager.api import Client

entity_id = <ip_network_id>
option_name = DHCP6ClientDeploymentOptionType.INFORMATION_REFRESH_TIME

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dhcp6_client_deployment_option(entity_id, <server_id>, option_name)

Return type: None

New in version 21.8.1.

delete_dhcp6_service_deployment_option(entity_id, server_id, option_name)

Delete a DHCPv6 service deployment option.

Parameters Description
entity_id (int)

The object ID of the entity from which this deployment option is being deleted.
server_id (int)

Specifies the server or server group to which the option is deployed for the specified entity. To return an option that has not been assigned to a server role, set this value to 0 (zero)
option_name (str)

The name of the DHCPv6 service option being deleted. This name must be one of the constants listed in BAM DHCP client options.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dhcp6_service_deployment_option(entity_id, <server_id>, "ddns-updates")

Return type: None

New in version 21.8.1.

delete_dhcp_client_deployment_option(entity_id, server_id, option_name)

Delete a DHCP client deployment option.

Parameters Description
entity_id (int)

The object ID of the entity from which the deployment option will be deleted.
server_id (int)

The specific server or server group to which this option is deployed. To delete an option that has not been assigned to a server, set this value to 0 (zero).
option_name (str)

The name of the DHCPv4 client option to be deleted. This name must be one of the constants listed in BAM DHCP client options.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <ip4_block_id>
option_name = "time-server"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dhcp_client_deployment_option(entity_id, <server_id>, option_name)

Return type: None

New in version 21.8.1.

delete_dhcp_deployment_role(entity_id, server_interface_id)

Delete a DHCP deployment role.

Parameters Description
entity_id (int)

The object ID of the object from which the deployment role is to be deleted.
server_interface_id (int)

The object ID of the server interface from which the deployment roles is to be deleted.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <view_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dhcp_deployment_role(entity_id, <server_interface_id>)

Return type: None

New in version 21.8.1.

delete_dhcp_service_deployment_option(entity_id, server_id, option_name)

Delete a DHCP service deployment option.

Parameters Description
entity_id (int)

The object ID of the object from which the deployment service is deleted.
server_id (int)

Specifies the server or server group to which the option is deployed for the specified entity. To retrieve an option that has not been assigned to a server role, set this value to 0 (zero). Omitting this parameter from the method call will result in an error.
option_name (str)

The name of the DHCPv4 service option is deleted. This name must be one of the API constants listed for DHCP service options.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DHCPServiceOption

configuration_id = <configuration_id>
server_id = <server_id>
option_name = DHCPServiceOption.DDNS_DOMAINNAME

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dhcp_service_deployment_option(configuration_id, server_id, option_name)

Return type: None

New in version 21.8.1.

delete_dhcp_vendor_deployment_option(entity_id, server_id, option_id)

Delete a DHCP vendor deployment option.

Parameters Description
entity_id (int)

The object ID of the object from which the DHCP vendor deployment option is being deleted.
server_id (int)

The object ID of the server or server group where the DHCP vendor deployment option is used. If the option is generic, set this value to 0 (zero).
option_id (int)

The object ID of the vendor option definition.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dhcp_vendor_deployment_option(entity_id, <server_id>, <option_id>)

Return type: None

New in version 21.8.1.

delete_dns_deployment_option(entity_id, server_id, option_name)

Delete a DNS option.

Parameters Description
entity_id (int)

The object ID of the entity to which the deployment option is assigned.
server_id (int)

Specifies the server or server group to which the option is assigned. To delete an option that has not been assigned to a server role, set this value to 0 (zero).
option_name (str)

The name of the DNS option being deleted. This name must be one of the constants listed in DNS options.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <zone_id>
option_name = 'update-policy'

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dns_deployment_option(entity_id, <server_id>, option_name)

Return type: None

New in version 21.8.1.

delete_dns_deployment_role(entity_id, server_interface_id)

Delete a DNS deployment role.

Parameters Description
entity_id (int)

The object ID of the object from which the DNS deployment role is being deleted.
server_interface_id (int)

The object ID of the server interface to which the DNS deployment role is assigned.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <view_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dns_deployment_role(entity_id, <server_interface_id>)

Return type: None

New in version 21.8.1.

delete_dns_deployment_role_for_view(view_id, entity_id, server_interface_id)

Delete the DNS deployment role assigned to view-level object in the IP space for ARPA zones.

Parameters Description
view_id (int)

The object ID of the view from which the DNS deployment role is being deleted.
entity_id (int)

The object ID of the entity from which the DNS deployment role is being deleted.
server_interface_id (int)

The object ID of the server interface to which the DNS deployment role is assigned.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_dns_deployment_role_for_view(<view_id>, <entity_id>, <server_interface_id>)

Return type: None

New in version 21.8.1.

delete_entity(id)

Delete an entity object.

Parameters Description
id (int)

The ID of the entity to delete.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_entity(<id>)

Return type: None

New in version 21.5.1.

delete_entity_with_options(id, options=None)

Delete objects that have options associated with their removal. When deleting dynamic resource records, you can choose not to dynamically deploy the changes to the DNS/DHCP Server.

Parameters Description
id (int)

The ID of the object to delete.
options (dict, optional)

A dictionary containing the delete options:

  • noServerUpdate: a string value. This applies to the dynamic resource records. The value is ‘true’ to update the record only in the Address Manager web interface. The change will not be deployed to the DNS server. The default value is ‘false’.

  • deleteOrphanedIPAddresses: a string value. This applies to the delete operation on Host Records. The value is ‘true’ to free IP addresses associated with a host record if no other host records are associated with the IP address. The default value is ‘false’.

  • removeMacFromPool: a string value. This applies to the delete operation of DHCP Reserved addresses. The value is ‘true’ to remove the MAC address of the IP address from any associated MAC pools. The default value is ‘false’.

Example: 

from bluecat_libraries.address_manager.api import Client

# This applies to the dynamic resource records
options = {'noServerUpdate': 'true'}
# Delete operation on Host Records
# options = {'deleteOrphanedIPAddresses': 'true'}
# Delete operation of DHCP Reserved addresses (BAM version >= 9.3.0 is required)
# options = {'removeMacFromPool': 'true'}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_entity_with_options(<id>, options)

Return type: None

New in version 21.5.1.

delete_response_policy_item(policy_id, absolute_name, options=None)

Delete a DNS response policy item under a local DNS response policy.

Parameters Description
policy_id (int)

The object ID of the parent local response policy to which the response policy item is being deleted.
absolute_name (str)

The FQDN of the response policy item.
options (list, optional)

Reserved for future use.

Raises:

ErrorResponse – When response policy item is not found.

Example: 

from bluecat_libraries.address_manager.api import Client

policy_id = <policy_id>
absolute_name = <policy_name.policy_item_name>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_response_policy_item(policy_id, absolute_name)

Return type: None

New in version 21.8.1.

delete_user_defined_field(object_type, udf_name)

Delete user-defined field.

Parameters Description
object_type (str)

The object type that the field is defined for.
udf_name (str)

The name of the user-defined field.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

udf_name = "unique-UDF-name"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_user_defined_field(ObjectType.CONFIGURATION, udf_name)

Return type: None

New in version 21.5.1.

delete_user_defined_link(link_type)

Delete the user-defined link definition.

Parameters Description
link_type (str)

The link type that identifies a user-defined link definition.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.delete_user_defined_link('<unique-UDL-type-name>')

Return type: None

New in version 21.5.1.

deny_mac_address(configuration_id, mac_address)

Deny a MAC address by assigning it to the DENY MAC Pool. If a MAC address object does not exist for that MAC address, it will be created.

Parameters Description
configuration_id (int)

The object ID of the parent configuration in which the MAC address resides.
mac_address (str)

The MAC address as a 12-digit hexadecimal in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn, or nn:nn:nn:nn:nn:nn.

Example: 

from bluecat_libraries.address_manager.api import Client

mac_address = "2C:54:91:88:C9:E3"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.deny_mac_address(<configuration_id>, mac_address)

Return type: None

New in version 21.11.1.

deploy_server(id)

Deploy the server. When invoking this method, the server is immediately deployed.

Parameters Description
id (int)

The object ID of the server to deploy.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.deploy_server(<server_id>)

Return type: None

New in version 21.8.1.

deploy_server_config(server_id, properties)

Deploy specific configuration(s) to a particular server.

Parameters Description
server_id (int)

The object ID of the server to deploy immediately.
properties (dict)

Object properties. The values for properties are:

  • services - The valid service configuration to deploy. These are the valid values for the services: DNS, DHCP, DHCPv6, and TFTP.

  • forceDNSFullDeployment - A boolean value. Set to true to perform a full DNS deployment.

Example: 

from bluecat_libraries.address_manager.api import Client

server_id = <server_id>
properties = {"services": "DNS", "forceDNSFullDeployment": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.deploy_server_config(server_id, properties)

Return type: None

New in version 21.8.1.

deploy_server_services(server_id, services)

Deploy specific service(s) to a particular server.

Parameters Description
server_id (int)

The object ID of the server to deploy services to.
services (list)

The names of the valid services to deploy.

Example: 

from bluecat_libraries.address_manager.api import Client

server_id = <server_id>
services = ["DNS", "DHCP"]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.deploy_server_services(server_id, services)

Return type: None

New in version 21.8.1.

edit_xha_pair(xha_server_id, name, properties=None)

Update the xHA pair created.

Parameters Description
xha_server_id (int)

The object ID of the xHA server.
name (str)

The name of the xHA server being updated.
properties (dict, optional)

A dictionary containing the following options listed in editing xHA option list.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.edit_xha_pair(<xha_server_id>, <name>)

Return type: None

New in version 21.11.1.

establish_trust_relationship(remote_ip, username, password, properties=None)

Establish a trust relationship between a maximum of three Address Manager servers. This is a prerequisite for configuring replication in Address Manager.

Parameters Description
remote_ip (str)

The IP address of the standby server.

Note:

The standby server must be reachable from the primary server and must have database access from the primary server. To enable database access, refer to the Configuring database replication section in the Address Manager Administration Guide.
username (str)

The username of an API user that logs in to Address Manager.
password (str)

The password of the specified API user.
properties (dict, optional)

This is reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

remote_ip = <ip_of_another_bam>
username = <remote_bam_user>
password = <remote_bam_password>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.establish_trust_relationship(remote_ip, username, password)

Return type: None

New in version 21.11.1.

export_entities(select_criteria, start=0, count=1000)

Export an octet stream of entities.

Parameters Description
select_criteria (dict)

A dictionary specifying how you want to choose the entities to export. Possible keys: selector, keyword, startEntityId, children_only, or types. For more details, see Export entities in the Address Manager Administration Guide.
start (int, optional)

Indicates where in the list of returned objects to start returning objects. The list begins at an index of 0. The default value is 0.
count (int, optional)

Indicate the maximum number of entities to return. The default value is 1000.

Returns: An iterator object that uses a generator to return a dictionary of an entity for every loop.

Return type: iterator

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.export_entities(
        {"selector": "search", "types": "Configuration,View,Zone", "keyword": "*"}
    )
for entity in entities:
    print(entity)

New in version 22.4.1.

failover_replication(standby_server, properties)

Perform a manual replication failover.

Parameters Description
standby_server (str)

The IP address of the standby server, which will become the primary BAM server once a failover has been performed.
properties (dict)

A dictionary containing the following option:

  • forceFailover - A boolean value indicates whether or not a forced failover.

Note:

If the latency of the database replication of the server relative to the primary server is greater than 0, a forced failover can be performed.

Example: 

from bluecat_libraries.address_manager.api import Client

standby_server = <ip4_address>
properties = {"forceFailover": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.failover_replication(standby_server, properties)

Return type: None

New in version 21.11.1.

failover_xha(xha_server_id)

Perform a manual xHA failover.

Parameters Description
xha_server_id (int)

The object ID of the xHA server.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.failover_xha(<xha_server_id>)

Return type: None

New in version 21.11.1.

find_response_policies_with_item(configuration_id, item_name, options=None)

Find local DNS response policies with their associated response policy items.

Parameters Description
configuration_id (int)

The object ID of the configuration to which the local response policies are located. To find local response policies from all configurations, set the value of this parameter to 0
item_name (str)

The fully qualified domain name (FQDN) of the response policy item. The exact FQDN of the response policy item must be used.
options (dict, optional)

Reserved for future use.

Returns: A list of local response policies.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

item_name = 'item'
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    policies = client.find_response_policies_with_item(<configuration_id>, item_name)
for policy in policies:
    print(policy['name'])

New in version 21.5.1.

get_access_right(entity_id, user_id)

Get the access right to an object.

Parameters Description
entity_id (int)

The object ID of the entity to which the access rights is assigned.
user_id (int)

The object ID of the user to whom the access right applies.

Returns: The access right for the specified object.

Return type: APIAccessRight

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <view_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    access_right = client.get_access_right(entity_id, <user_id>)
print(access_right)

New in version 21.8.1.

get_access_rights_for_entity(id, start=0, count=10)

Get a list of access rights of an entity.

Parameters Description
id (int)

The object ID of the entity whose access rights are returned.
start (int, optional)

Indicates where in the list of child access right objects to start returning objects. The list begins at an index of 0.
count (int, optional)

The maximum number of access right child objects to return. The default value is 10.

Returns: A list of access rights of an entity.

Return type: list[APIAccessRight]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    access_rights = client.get_access_rights_for_entity(<id>, 0, 10)
for access_right in access_rights:
    print(access_right)

New in version 21.5.1.

get_access_rights_for_user(id, start=0, count=10)

Get a list of access rights for a user.

Parameters Description
id (int)

The object ID of the user whose access rights are returned.
start (int, optional)

Indicates where in the list of child access right objects to start returning objects. The list begins at an index of 0.
count (int, optional)

The maximum number of access right child objects to return. The default value is 10.

Returns: A list of access rights for the specified user.

Return type: list[APIAccessRight]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    access_rights = client.get_access_rights_for_user(<id>, 0, 10)
for access_right in access_rights:
    print(access_right)

New in version 21.5.1.

get_additional_ip_addresses(server_id, properties=None)

Get a list of IPv4 addresses and loopback addresses added to the Service interface for DNS services.

Parameters Description
server_id (int)

The object ID of the server from which the additional IP addresses is being retrieved.
properties (dict, optional)

The supported property is:

  • serviceType - type of service for which a list of IP addresses is being retrieved. If serviceType is not provided, all additional IP addresses of the services interface will be returned.

Returns: The list of additional IP addresses configured on the server.

Return type: list[str]

Example: 

from bluecat_libraries.address_manager.constants import AdditionalIPServiceType
from bluecat_libraries.address_manager.api import Client

server_id = <server_id>
properties = {"serviceType": AdditionalIPServiceType.SERVICE}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip_addresses = client.get_additional_ip_addresses(server_id, properties)
print(ip_addresses)

New in version 21.8.1.

get_aliases_by_hint(options, start=0, count=10)

Get a list of CNAMEs with linked record name.

Parameters Description
options (dict)

A dictionary containing the following options:

  • hint: A string value. If hint is not specified, searching criteria will be based on the same as zone host record.

  • retrieveFields: A string specifying if a user-defined field is returned in object’s properties. If this option is set to ‘true’, the user-defined field will be returned. If this option is set to ‘false’ or missing, the user-defined field will not be returned.
start (int, optional)

Indicates where in the list of objects to start returning objects. The list begins at an index of 0.
count (int, optional)

Indicates the maximum of child objects that this method will return. The value must be less than or equal to 10.

Returns: A list of Alias APIEntity objects.

Return type: list[APIEntity]

Note:

The following wildcards are supported in the hint option:

  • ^ - matches the beginning of a string. For example: ^ex matches example but not text.

  • $ - matches the end of string. For example: ple$ matches example but not please.

  • ^ $ - matches the exact characters between the two wildcards. For example: ^example$ only matches example.

  • ? - matches any one character. For example: ex?t matches exit.

  • * - matches zero or more characters within a string. For example: ex*t matches exit and excellent.

Example: 

from bluecat_libraries.address_manager.api import Client

options = {
    'hint': '^abc',
    'retrieveFields': 'false'
}
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.get_aliases_by_hint(options, 0, 10)
for entity in entities:
    print(entity['name'])

New in version 21.5.1.

get_all_used_locations()

GET a list of location objects that are used to annotate other objects.

Returns: A list of location APIEntity objects.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    locations = client.get_all_used_locations()
for location in locations:
    print(location["name"])

New in version 21.5.1.

get_audit_log_export_status()

Get the audit data export settings that were set using the configure_audit_log_export API method.

Returns: The current audit data export settings in Address Manager.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    settings = client.get_audit_log_export_status()
for k, v in settings.items():
    print(f"{k}: {v}")

New in version 21.5.1.

get_configuration_groups()

Get a list of all configuration groups in Address Manager.

Returns: A list of all configuration groups’ names.

Return type: list[str]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    config_groups = client.get_configuration_groups()
print(config_groups)

New in version 21.8.1.

get_configuration_setting(configuration_id, setting)

Get a configuration setting.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the setting is to be located.
setting (str)

The name of the specific setting to read. Only the “OPTION_INHERITANCE” setting is supported.

Returns: The configuration setting.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

setting_name = "OPTION_INHERITANCE"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    configuration_setting = client.get_configuration_setting(<configuration_id>, setting_name)
print(configuration_setting)

New in version 21.8.1.

get_configurations_by_group(group_name, properties=None)

Get a list of configurations in Address Manager based on the name of a configuration group.

Parameters Description
group_name (str)

The name of the configuration group in which the configurations are located.
properties (dict, optional)

This is reserved for future use.

Returns: A list of configurations in Address Manager based on the name of a configuration group.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

group_name = 'test_group'
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    configurations = client.get_configurations_by_group(group_name)
for configuration in configurations:
    print(configuration['name'])

New in version 21.5.1.

get_deployment_options(entity_id, server_id, option_types=None)

Get the deployment options for Address Manager DNS and DHCP services.

Parameters Description
entity_id (int)

The object ID of the entity to which the DNS or DHCP deployment option is assigned.
server_id (int)

The specific server or server group to which options are deployed. The valid values are as follows:

  • server_id>0: Return only the options that are linked to the specified server ID.

  • server_id<0: Return all options regardless of the server ID specified.

  • server_id=0: Return only the options that are linked to all servers.
option_types (list, optional)

The list of deployment options types. If specified as an empty list, all deployment options for the specified entity will be returned. This value must be one of the following items:

  • DNSOption

  • DNSRawOption

  • DHCPRawOption

  • DHCPV6RawOption

  • DHCPV4ClientOption

  • DHCPV6ClientOption

  • DHCPServiceOption

  • DHCPV6ServiceOption

  • StartOfAuthority

Returns: A list of APIDeploymentOptions

Return type: list[APIDeploymentOption]

Example: 

from bluecat_libraries.address_manager.api import Client

option_types = ["DNSOption", "DNSRawOption"]
server_id = -1
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_options = client.get_deployment_options(<entity_id>, server_id, option_types)
for deployment_option in deployment_options:
    print(deployment_option.get('type'))

New in version 21.5.1.

get_deployment_roles(entity_id)

Get the DNS and DHCP deployment roles associated with an object. For DNS views and zones, the result contains DNS deployment roles. For IP address space objects, such as IPv4 blocks and networks, IPv6 blocks and networks, DHCP classes, and MAC pools, the result contains DNS and DHCP deployment roles.

Parameters Description
entity_id (int)

The object ID of a DNS view, DNS zone, IPv4 block or network, IPv6 block or network, DHCP class, or MAC pool.

Returns: A list of the DNS and DHCP deployment roles associated with the specified object.

Return type: list[APIDeploymentRole].

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_roles = client.get_deployment_roles(<entity_id>)
for deployment_role in deployment_roles:
    print(deployment_role.get('type'))

New in version 21.5.1.

get_deployment_task_status(task_token)

Get the deployment status of the deployment task that was created using the selectiveDeploy API method.

Parameters Description
task_token (str)

The string token value that is returned from the selectiveDeploy API method.

Returns: A dictionary including the overall deployment status and the deployment status of individual entities.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

task_token = "fc093c43-d1a1-4a70-a3a6-511e783a9a73"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    task_status = client.get_deployment_task_status(task_token)
print(task_status)

New in version 21.8.1.

get_dhcp6_client_deployment_option(entity_id, server_id, option_name)

Get a DHCPv6 client option assigned to an object, excluding the options inherited from the higher-level parent objects.

Parameters Description
entity_id (int)

The object ID of the entity.
server_id (int)

The specific server or server group to which this option is deployed. To return an option that has not been assigned to a server role, set this value to zero.
option_name (str)

The name of the DHCPv6 client option being added. This name must be one of the constants listed in BAM DHCPv6 client options.

Returns: A DHCPv6 client option assigned to a specified object.

Return type: APIDeploymentOption

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>
option_name = "information-refresh-time"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_option = client.get_dhcp6_client_deployment_option(entity_id, <server_id>, option_name)
print(deployment_option)

New in version 21.8.1.

get_dhcp6_service_deployment_option(entity_id, server_id, option_name)

Get the DHCPv6 service option assigned to an object, excluding the options inherited from the higher-level parent objects.

Parameters Description
entity_id (int)

The object ID of the entity to which the deployment option is assigned.
server_id (int)

Specifies the server or server group to which the option is deployed for the specified entity. To retrieve an option that has not been assigned to a server role, set this value to zero.
option_name (str)

The name of the DHCPv6 service option being retrieved. This name must be one of the constants listed for DHCPv6 client options.

Returns: The requested DHCPv6 service option object.

Return type: APIDeploymentOption

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>
server_id = 0
option_name = "ddns-updates"

 with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcpv6_service = client.get_dhcp6_service_deployment_option(entity_id, server_id, option_name)
print(dhcpv6_service)

New in version 21.8.1.

get_dhcp_client_deployment_option(entity_id, option_name, server_id)

Get the DHCPv4 client option assigned to an object, excluding the options inherited from the higher-level parent objects.

Parameters Description
entity_id (int)

The object ID of the entity to which the deployment option has been applied.
option_name (str)

The name of the DHCPv4 client option. This name must be one of the constants listed in BAM DHCP client options.
server_id (int)

The specific server or server group to which this option is deployed. To return an option that has not been assigned to a server, set this value to 0 (zero).

Returns: The DHCPv4 client option object assigned to the specified object.

Return type: APIDeploymentOption

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcpv4_client = client.get_dhcp_client_deployment_option(<ip4_block_id>, "time-server", 0)
print(dhcpv4_client)

New in version 21.8.1.

get_dhcp_deployment_role(entity_id, server_interface_id)

Get the DHCP deployment role assigned to an object.

Parameters Description
entity_id (int)

The object ID of the object to which the deployment role is assigned.
server_interface_id (int)

The object ID of the server interface to which the role is assigned.

Returns: The DHCP deployment role assigned to the specified object, or an empty APIDeploymentRole if no role is defined.

Return type: APIDeploymentRole

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_role = client.get_dhcp_deployment_role(<entity_id>, <server_interface_id>)
print(deployment_role)

New in version 21.8.1.

get_dhcp_service_deployment_option(entity_id, server_id, option_name)

Get the DHCP service option assigned to an object, excluding the options inherited from the higher-level parent objects.

Parameters Description
entity_id (int)

The object ID of the entity to which the deployment option is assigned.
server_id (int)

Specifies the server or server group to which the option is deployed for the specified entity. To retrieve an option that has not been assigned to a server role, specify 0 as a value.
option_name (str)

The name of the DHCPv4 service option being retrieved. This name must be one of the constants listed for DHCP service options.

Returns: The requested DHCPv4 service option object from the database.

Return type: APIDeploymentOption

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DHCPServiceOption

entity_id = <configuration_id>
option_name = DHCPServiceOption.DDNS_DOMAINNAME

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcp_service_option = client.get_dhcp_service_deployment_option(entity_id, 0, option_name)
print(dhcp_service_option)

New in version 21.8.1.

get_dhcp_vendor_deployment_option(entity_id, server_id, option_id)

Get a DHCP vendor deployment option assigned to an object, excluding the options inherited from the higher-level parent objects.

Parameters Description
entity_id (int)

The object ID of the entity to which the DHCP vendor deployment option is assigned. This must be the ID of a Configuration, IP4Block, IP4Network, IP4NetworkTemplate, IPv4Address, IP4DHCPRange, Server, MACAddress, or MACPool.
server_id (int)

The specific server or server group to which this option is deployed for the specified entity. To return an option that has not been assigned to a server, set this value to 0 (zero).
option_id (int)

The object ID of the vendor option definition.

Returns: An APIDeploymentOption for the DHCP vendor client deployment option.

Return type: APIDeploymentOption

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dhcp_vendor_option = client.get_dhcp_vendor_deployment_option(entity_id, <server_id>, <option_id>)
print(dhcp_vendor_option)

New in version 21.8.1.

get_discovered_device(policy_id, device_id)

Return a specific device, discovered by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.
device_id (int)

The object ID of the device.

Returns: The discovered device object.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    device = client.get_discovered_device(<policy_id>, <device_id>)
print(device)

New in version 22.4.1.

get_discovered_device_arp_entries(policy_id, device_id)

Return all ARP entries of a specific device by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.
device_id (int)

The object ID of the device.

Returns: All ARP entries of a specific device.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    arp_entries = client.get_discovered_device_arp_entries(
        <policy_id>, <device_id>
    )
print(arp_entries)

New in version 22.4.1.

get_discovered_device_hosts(policy_id, device_id)

Returns all hosts of a specific device, discovered by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.
device_id (int)

The object ID of the device.

Returns: All hosts of the specified device.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    hosts = client.get_discovered_device_hosts(<policy_id>, <device_id>)
print(hosts)

New in version 22.4.1.

get_discovered_device_interfaces(policy_id, device_id)

Return all interfaces of a specific device, by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.
device_id (int)

The object ID of the device.

Returns: All interfaces of the specified device.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    interfaces = client.get_discovered_device_interfaces(<policy_id>, <device_id>)
print(interfaces)

New in version 22.4.1.

get_discovered_device_mac_address_entries(policy_id, device_id)

Return all MAC address entries of a specific device, discovered by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.
device_id (int)

The object ID of the device.

Returns: All MAC address entries of the specified device.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    mac_addresses = client.get_discovered_device_mac_address_entries(
        <policy_id>, <device_id>
    )
print(mac_addresses)

New in version 22.4.1.

get_discovered_device_networks(policy_id, device_id)

Return a list of all networks of a specific device, discovered by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.
device_id (int)

The object ID of the device.

Returns: All networks of the specified device.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    networks = client.get_discovered_device_networks(<policy_id>, <device_id>)
print(networks)

New in version 22.4.1.

get_discovered_device_vlans(policy_id, device_id)

Return all VLANs of a specific device, discovered by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.
device_id (int)

The object ID of the device.

Returns: All VLANs of the specified device.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    devices = client.get_discovered_device_vlans(<policy_id>, <device_id>)
print(devices)

New in version 22.4.1.

get_discovered_devices(policy_id)

Return a list of discovered Layer 2 or Layer 3 devices, discovered by running an IPv4 reconciliation policy.

Parameters Description
policy_id (int)

The object ID of the IPv4 reconciliation policy.

Returns: A list of discovered Layer 2 or Layer 3 devices.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    devices = client.get_discovered_devices(<policy_id>)
print(devices)

New in version 22.4.1.

get_dns_deployment_option(entity_id, server_id, option_name)

Get the DNS deployment option assigned to an object, excluding the options inherited from the higher-level parent objects.

Parameters Description
entity_id (int)

The object ID of the entity to which this deployment option is assigned.
server_id (int)

Specifies the server or server group to which this option is assigned. To retrieve an option that has not been assigned to a server role, set this value to 0 (zero).
option_name (str)

The name of the DNS option. This name must be one of the constants listed for DNS options.

Returns: An instance of the type APIDeploymentOption that represents the DNS deployment option or empty if none were found.

Return type: APIDeploymentOption

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <entity_id>
server_id = <server_id>
option_name = "update-policy"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dns_deployment_option = client.get_dns_deployment_option(entity_id, server_id, option_name)
print(dns_deployment_option)

New in version 21.8.1.

get_dns_deployment_role(entity_id, server_interface_id)

Get the DNS deployment role of an object.

Parameters Description
entity_id (int)

The object ID of the object to which the DNS deployment role is assigned.
server_interface_id (int)

The object ID of the server interface to which the DNS deployment role is assigned.

Returns: The DNS deployment role of the specified object, or None if no role is defined.

Return type: APIDeploymentRole

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dns_deployment_role = client.get_dns_deployment_role(<view_id>, <server_interface_id>)
print(dns_deployment_role)

New in version 21.8.1.

get_dns_deployment_role_for_view(view_id, entity_id, server_interface_id)

Get the DNS deployment role assigned to a view-level objects in the IP space for ARPA zones.

Parameters Description
view_id (int)

The object ID of the view in which the DNS deployment role is assigned.
entity_id (int)

The object ID of the object to which the DNS deployment role is assigned.
server_interface_id (int)

The object ID of the server interface to which the DNS deployment role is assigned.

Returns: The requested APIDeploymentRole object.

Return type: APIDeploymentRole

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <ip4_network_id>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    dns_deployment_role = client.get_dns_deployment_role_for_view(
        <view_id>, entity_id, <server_interface_id>
    )
print(dns_deployment_role.get('service'))

New in version 21.8.1.

get_entities(parent_id, type, start=0, count=10, include_ha=None)

Get a list of entities for a parent object.

Parameters Description
parent_id (int)

The object ID of the parent object of the entities.
type (str)

The type of object to return.
start (int, optional)

Indicates where in the list of child objects to start returning entities. The list begins at an index of 0.
count (int, optional)

Indicates the maximum number of child objects to return. The default value is 10.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: A list of entities. The list is empty if there are no matching entities.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.get_entities(<parent_id>, ObjectType.VIEW, 0, 10)
print(entities)

New in version 21.5.1.

get_entities_by_name(parent_id, name, type, start=0, count=10, include_ha=None)

Get a list of entities that match the specified parent, name, and object type.

Parameters Description
parent_id (int)

The object ID of the parent object of the entities.
name (str)

The name of the entity.
type (str)

The type of object to return.
start (int, optional)

Indicates where in the list of returned objects to start returning objects. The list begins at an index of 0.
count (int, optional)

The maximum number of objects to return. The default value is 10.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: A list of entities. The list is empty if there are no matching entities.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

name = "default"
type = ObjectType.VIEW

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.get_entities_by_name(<parent_id>, name, type, 0, 10)
print(entities)

New in version 21.5.1.

get_entities_by_name_using_options(parent_id, name, type, options=None, start=0, count=10, include_ha=None)

Get a list of entities that match the specified name and object type. Searching behavior can be changed by using the options parameter.

Parameters Description
parent_id (int)

The object ID of the parent object of the entities to return.
name (str)

The name of the entity.
type (str)

The type of object to return.
options (dict, optional)

A dictionary containing the search options.

  • ignoreCase: String value. Set to true to ignore case-sensitivity while searching for entities by name. The default value is false.
start (int, optional)

Indicates where in the list of returned objects to start returning objects. The list begins at an index of 0.
count (int, optional)

The maximum number of objects to return. The default value is 10.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: A list of entities that match the specified criteria.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

name = "default"
type = ObjectType.VIEW

# To ignore case-sensitivity while searching for entities by name
options = {"ignoreCase": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.get_entities_by_name_using_options(
        <parent_id>, name, type, options, 0, 10
    )
print(entities)

New in version 21.5.1.

get_entity_by_cidr(parent_id, cidr, type)

Get an IPv4 Network or IPv4 Block object using its CIDR notation.

Parameters Description
parent_id (int)

The object ID of the entity’s parent object
cidr (str)

The CIDR notation defining the network or block.
type (str)

The type of the object being returned. This must be one of the constants listed for Object types (IP4Block, IP4Network).

Returns: return: An IPv4 Network or IPv4 Block object.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

parent_id = <ip4_block_id>
cidr = "172.0.0/24"
type = ObjectType.IP4_NETWORK

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_entity_by_cidr(parent_id, cidr, type)
print(entity)

New in version 21.8.1.

get_entity_by_id(id, include_ha=None)

Get an entity object by its ID.

Parameters Description
id (int)

The ID of the entity object to return.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: An entity object.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_entity_by_id(<id>)

New in version 21.5.1.

get_entity_by_name(parent_id, name, type, include_ha=None)

Get objects from the database referenced by their name field.

Parameters Description
parent_id (int)

The ID of the target object’s parent object.
name (str)

The name of the target object.
type (str)

The type of object returned by the method.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: An entity object.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

name = "default"
type = ObjectType.VIEW

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_entity_by_name(<parent_id>, name, type)
print(entity)

New in version 21.5.1.

get_entity_by_prefix(container_id, prefix, type)

Get an IPv6 address of an IPv6 Block or Network.

Parameters Description
container_id (int)

The object ID of higher-level parent object IPv6 Block or Configuration in which the IPv6 Block or Network is being located.
prefix (str)

The prefix value for the IPv6 Block or Network.
type (str)

The type of object. The only supported object types are IP6Block and IP6Network.

Returns: An APIEntity for the specified IPv6 Block or Network. The APIEntity is empty if the IPv6 Block or Network does not exist.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

container_id = <global_ip6_block_id>
prefix = "2001::/64"
type = ObjectType.IP6_BLOCK

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip6_block = client.get_entity_by_prefix(container_id, prefix, type)
print(ip6_block)

New in version 21.8.1.

get_entity_by_range(parent_id, start_address, end_address, type)

Get an IPv4 or IPv6 DHCP range or block object defined by its range.

Parameters Description
parent_id (int)

The object ID of the parent object of the DHCP range.
start_address (str)

An IP address defining the lowest address or start of the range.
end_address (str)

An IP address defining the highest address or end of the range.
type (str)

The type of object returned, it must be one of the constants listed for Object types. For example: IP4Block, IP6Block, DHCP4Range, DHCP6Range.

Returns: A range object like an IP block or a DHCP range. None if the object was not found.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

parent_id = <configuration_id>
start_address = "10.0.0.1"
end_address = "10.0.0.10"
type = ObjectType.IP4_BLOCK

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    # The IP4 Block type is to be retrieved, the entity is a configuration id.
    entity = client.get_entity_by_range(parent_id, start_address, end_address, type)
print(entity)

New in version 21.8.1.

get_host_records_by_hint(options, start=0, count=10)

Get a list of objects with Host record type.

Parameters Description
options (dict)

A dictionary should contain following options:

  • hint: String value. If hint is not specified, searching criteria will be based on the same as zone host record.

  • retrieveFields: String value. Specify if user-defined field is returned in object’s properties. If this option is set to ‘true’, user-defined field will be returned. If this option is set to ‘false’ or missing, user-defined field will not be returned.
start (int, optional)

Indicates where in the list of objects to start returning objects. The list begins at an index of 0.
count (int, optional)

Indicates the maximum of child objects that this method will return. The value must be less than or equal to 10.

Returns: A list of Host record APIEntity objects.

Return type: list[APIEntity]

Note:

The following wildcards are supported in the hint option:

  • ^ - matches the beginning of a string. For example: ^ex matches example but not text.

  • $ - matches the end of string. For example: ple$ matches example but not please.

  • ^ $ - matches the exact characters between the two wildcards. For example: ^example$ only matches example.

  • ? - matches any one character. For example: ex?t matches exit.

  • * - matches zero or more characters within a string. For example: ex*t matches exit and excellent.

Example: 

from bluecat_libraries.address_manager.api import Client

options = {
    'hint': '^abc',
    'retrieveFields': 'false'
}
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.get_host_records_by_hint(options, 0, 10)
for entity in entities:
    print(entity['name'])

New in version 21.5.1.

get_ip4_address(entity_id, address)

Get the details for the requested IPv4 address object.

Parameters Description
entity_id (int)

The object ID of the configuration, block, network, or DHCP range in which the address is being located.
address (str)

The IPv4 address.

Returns: The requested IPv4 Address object.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <ip4_network_id>
address = "10.0.0.10"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    address_entity = client.get_ip4_address(entity_id, address)
print(address_entity)

New in version 21.8.1.

get_ip4_networks_by_hint(container_id, options=None, start=0, count=10)

Get a list of IPv4 networks found under a given container object.

Parameters Description
container_id (int)

The object ID of the container object. It can be the object ID of any object in the parent object hierarchy.
options (dict, optional)

A dictionary containing search options. It includes the following keys:

  • hint: String value. This can be the prefix of the IP address or the name of a network.

  • overrideType: String value. The overrides of the zone. It must be a BAM Object value.

  • accessRight: String value. The access right for the zone. Must be a BAM Access right value.
start (int, optional)

Indicates where in the list of objects to start returning objects. The list begins at an index of 0. The default value is 0.
count (int, optional)

Indicates the maximum number of child objects that this method will return. The maximum value is 10. The default value is 10.

Returns: A list of entities

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import AccessRightValues, ObjectType

options = {
    'hint': '172.0.0',
    'overrideType': ObjectType.HOST_RECORD,
    'accessRight': AccessRightValues.ViewAccess
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_networks = client.get_ip4_networks_by_hint(<container_id>, options, 0, 10)
for zone in zones:
    print(ip4_networks['properties'])

New in version 21.5.1.

get_ip6_address(entity_id, address)

Get an IPv6 address object.

Parameters Description
entity_id (int)

The object ID of the entity that contains the IPv6 address. The entity can be a Configuration, IPv6 Block, or IPv6 Network.
address (str)

The IPv6 address.

Returns: An IPv6 address object. The value is None if the IPv6 address does not exist.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <entity_id>
address = <ip6_address>

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip6_address = client.get_ip6_address(entity_id, address)
print(ip6_address)

New in version 21.8.1.

get_ip6_objects_by_hint(container_id, type, options=None, start=0, count=10)

Get a list of IPv6 objects found under a given container object. The networks can be filtered by using hint and accessRight options. Only supports IPv6 Networks.

Parameters Description
container_id (int)

The object ID of the container object. It can be the object ID of any object in the parent object hierarchy. The highest parent object is the configuration level.
type (str)

The type of object containing the IPv6 Network. Currently, it only supports IP6Network.
options (dict, optional)

A dictionary containing the following options:

  • hint: The values for the hint option can be the prefix of the IP address for a network or the name of a network.

  • accessRight: The values for the accessRight option must be one of the constants listed for Access right values and Object types. If the Access right value isn’t specified, the View access level will be used by default.
start (int, optional)

Indicate where in the list of objects to start returning objects. The list begins at an index of 0.
count (int, optional)

Indicate the maximum number of child objects that this method will return. The default value is 10.

Returns: A list of IPv6 objects based on the input arguments, or return an empty list if the ID of the container object is invalid.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType
from bluecat_libraries.address_manager.constants import AccessRightValues

container_id = <entity_id>
type = ObjectType.IP6_NETWORK
options = {"hint": <prefix_IPv6_address>, "accessRight": AccessRightValues.AddAccess}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip6_objects = client.get_ip6_objects_by_hint(container_id, type, options)
print(ip6_objects)

New in version 21.8.1.

get_ip_ranged_by_ip(container_id, address, type=None)

Get an IPv4 or IPv6 DHCP range, block, or network containing an IPv4 or IPv6 address.

Parameters Description
container_id (int, optional)

The object ID of the container in which the IPv4 or IPv6 address is located. The entity can be a configuration, IPv4 or IPv6 block, network, or DHCP range.
address (str, optional)

An IPv4 or IPv6 address.
type (str, optional)

The type of object containing the IP address. Specify ObjectTypes.IP4Block or ObjectTypes.IP6Block, ObjectTypes.IP4Network or ObjectTypes.IP6Network, or ObjectTypes.DHCP4Range or ObjectTypes.DHCP6Range to find the block, network, or range containing the IPv4 or IPv6 address. If the type isn’t specified, the method will return the most direct container for the IPv4 or IPv6 address.

Returns: An IPv4 or IPv6 DHCP range, block, or network containing the specified IPv4 or IPv6 address.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

container_id = <configuration_id>
address = <ip4_address>
type = ObjectType.IP4_BLOCK

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_ip_ranged_by_ip(container_id, address, type)
print(entity)

New in version 21.8.1.

get_ksk(entity_id, key_format)

Get a list of strings containing all active Key Signing Keys (KSK) for an entity.

Parameters Description
entity_id (int)

The object ID of the entity associated with the KSK. The only supported entity types are zone, IPv4 block, and IPv4 network.
key_format (str)

The output format of the KSK. The value must be one of the constants listed in BAM’s DNSSEC key format:

  • DNS_KEY

  • DS_RECORD

  • TRUST_ANCHOR

Returns: A list of strings containing up to two active KSK(s) for an entity.

Return type: list[str]

Example: 

from bluecat_libraries.address_manager.api import Client

key_format = "DNS_KEY"
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    key_list = client.get_ksk(<zone_id>, key_format)
for key in key_list:
    print(key)

New in version 21.5.1.

get_linked_entities(entity_id, linked_type, start=0, count=10, include_ha=None)

Get a list of entities linked to an entity. The list is empty if there are no linked entities.

Parameters Description
entity_id (int)

The object ID of the entity to return linked entities for.
linked_type (str)

The type of linked entities to return. This value must be one of the types listed in Object types.
start (int, optional)

Indicates where in the list of returned objects to start returning objects. The list begins at an index of 0.
count (int, optional)

The maximum number of objects to return. The default value is 10.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: A list of entities that are linked to the specified entity.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

linked_type = ObjectType.HOST_RECORD
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.get_linked_entities(<entity_id>, <linked_type>, 0, 10)
for entity in entities:
    print(entity['id'])

New in version 21.5.1.

get_linked_entities_by_udl(link_type, entity_id=None)

Return a list of objects detailing entities currently linked by a given UDL type, with an optional parameter to qualify results by source or destination entity ID.

Parameters Description
link_type (str)

The unique name for the user-defined link.
entity_id (int, optional)

The source or destination entity ID. If an ID is not provided or is 0, all linked entities matching the specified link type will be returned.

Returns: By giving an existing UDL type:A list of objects detailing entities currently linked if it was found. For example:[ { "sourceId": <source_id_1>, "description": "Description for the link", "destinationId": <destination_id_1> }, { "sourceId": <source_id_2>, "description": "Description for the link", "destinationId": <destination_id_2> } ]An empty list if it was not found.

Return type: list[dict]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.get_linked_entities_by_udl(<link_type>, <entity_id>)
print(entities)

New in version 22.4.1.

get_linked_entities_ex(relationship)

Get a list of entity IDs linked using the given link type to the given source or destination entity ID.

Parameters Description
relationship (UDLRelationship)

The link type that identifies a user-defined link definition.

Returns: A list of the IDs of the linked entities.

Return type: list[int]

Example: 

from bluecat_libraries.address_manager.api import Client

relationship = UDLRelationship(
     linkType="UniqueLinkTypeName",
     sourceEntityId=256021,
)
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    linked_ids = client.get_linked_entities_ex(relationship)
print(linked_ids)

New in version 21.5.1.

get_linked_ip4_object_conflicts(template_id, entity_id)

Get a list of deployment options that conflict with the associated IPv4 objects, including networks, that are linked to the IPv4 template.

Parameters Description
template_id (int)

The object ID of the IPv4 template.
entity_id (int)

The object ID of the IPv4 object that is linked to the IPv4 template. Setting a value of zero returns all conflicting objects linked to the template.

Returns: A dictionary containing the conflicting network ranges and deployment options.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    conflicts = client.get_linked_ip4_object_conflicts(<template_id>, <entity_id>)
print(conflicts)

New in version 21.11.1.

get_location_by_code(code)

Get the location object with a hierarchical location code.

Parameters Description
code (str)

The hierarchical location code consists of a set of 1 to 3 alpha-numeric strings separated by a space. The first two characters indicate a country, followed by next three characters which indicate a city in UN/LOCODE. New custom locations created under a UN/LOCODE city are appended to the end of the hierarchy. For example, CA TOR OF1 indicates:

  • CA - Canada

  • TOR - Toronto

  • OF1 - Office 1

Note:

The code is case-sensitive. It must be all UPPER CASE letters.

The county code and child location code should be alphanumeric strings.

Returns: The location with the specified hierarchical location code. If no entity is found, return None.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

code = "CA"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_location_by_code(code)
print(entity)

New in version 21.8.1.

get_mac_address(configuration_id, mac_address)

Get a MAC address object by the address value.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the MAC address is located.
mac_address (str)

The MAC address as a 12-digit hexadecimal in the format nnnnnnnnnnnn, nn-nn-nn-nn-nn-nn, or nn:nn:nn:nn:nn:nn.

Returns: An object with the MAC address data. Returns None if the MAC address cannot be found.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

mac_address = "2C:54:91:88:C9:E3"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    mac_object = client.get_mac_address(<configuration_id>, mac_address)
print(mac_object)

New in version 21.11.1.

get_max_allowed_range(range_id)

Find the maximum possible address range to which the existing IPv4 DHCP range can be extended. This method only supports the IPv4 DHCP range.

Parameters Description
range_id (int)

The object ID of the IPv4 DHCP range.

Returns: The possible start address and end address for the specified IPv4 DHCP range.

Return type: list[str]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    max_allowed_range = client.get_max_allowed_range(<range_id>)
print(max_allowed_range)

New in version 21.11.1.

get_network_linked_properties(network_id)

Get a list of IP addresses with linked records and the IP addresses that are assigned as DHCP Reserved, Static, or Gateway.

Parameters Description
network_id (int)

The object ID of the IPv4 network.

Returns: A list of IP address APIEntity objects.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    addresses = client.get_network_linked_properties(<ip4_network_id>)
for address in addresses:
    print(address['properties'])

New in version 21.5.1.

get_next_available_ip4_address(entity_id)

Get the IPv4 address for the next available (unallocated) address within a configuration, block, or network.

Parameters Description
entity_id (int)

The object ID of configuration, block, or network in which the next available address is being retrieving.

Returns: The next available IPv4 address in an existing network.

Return type: str

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    available_ip4_address = client.get_next_available_ip4_address(<entity_id>)
print(available_ip4_address)

New in version 21.8.1.

get_next_available_ip4_network(entity_id, size, is_larger_allowed, auto_create)

Get the object ID of the next available (unused) network within a configuration or block.

Parameters Description
entity_id (int)

The object ID of the network’s parent object.
size (int)

The size of the network, expressed as a power of 2. The size represents the number of hosts on the network. For example, if a /24 network is created or searched for, the size would be 256.
is_larger_allowed (bool)

This Boolean value indicates whether to return larger networks than those specified with the size parameter.
auto_create (bool)

This Boolean value indicates whether the next available network should be created if it does not exist.

Returns: The object ID of the existing next available IPv4 network or, if the next available network did not exist and auto_create was set to true, the newly created IPv4 network. if the next available network did not exist and auto_create was set to false, the method will return 0.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

ip4_block_id = <ip4_block_id>
size = 4
is_larger_allowed = False
auto_create = True

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_network_id = client.get_next_available_ip4_network(
        ip4_block_id, size, is_larger_allowed, auto_create
    )
print(ip4_network_id)

New in version 21.8.1.

get_next_available_ip6_address(entity_id, properties=None)

Get a list of the next available IPv6 addresses within an IPv6 Block or Network.

Parameters Description
entity_id (int)

The object ID of IPv6 Block or Network where the next available IPv6 addresses is requested.
properties (dict, optional)

Object properties, containing the following optional properties:

  • startOffset - An integer that specifies from which offset to retrieve the available IPv6 address(es). The valid value ranges from 0 to 2 ^ 63 (2 to the power of 63).

  • skip - Specifies the IPv6 address ranges or IPv6 addresses to skip, separated by a comma.

  • includeDHCPRanges - A boolean that specifies whether DHCP ranges should be included when retrieving the next available IPv6 address. The default value is false.

  • numberOfAddresses - An integer that is the number of requested IPv6 addresses. The default value is 1. The valid value is from 1 to 100. All IPv6 addresses will be returned from a single network.

Returns: A list of available IPv6 addresses in an existing IPv6 Block or Network.

Return type: list[str]

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <ip6_network_id>
properties = {
    "numberOfAddresses": 5,
    "skip": <skip_addresses>,
    "includeDHCPRanges": "False",
    "startOffset": 100,
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    available_ip6_addresses = client.get_next_available_ip6_address(entity_id, properties)
for available_ip6_address in available_ip6_addresses:
    print(available_ip6_address)

New in version 21.8.1.

get_next_available_ip_range(parent_id, size, type, properties=None)

Get the next available (unused) block or network within a configuration or block. If no existing range can be returned, a new one may be requested to be created if there’s enough space.

Parameters Description
parent_id (int)

The object ID of the parent object under which the next available range resides.
size (int)

The size of the range. Must be an integer power of 2.
type (str)

The object type of the requested range. The method supports IPv4 blocks and networks.
properties (dict, optional)

Additional options of the operation:

  • reuseExisting - A boolean value to indicate whether to search existing empty networks to find the requested range. The default value is false. If both reuseExisting and autoCreate are defined, reuseExisting takes precedence over autoCreate.

  • isLargerAllowed - A boolean value to indicate whether to return larger networks than those specified with the size parameter. The default value is false.

  • autoCreate - A boolean value to indicate whether the next available IP range should be created in the parent object if it does not exist. The default value is the opposite value of reuseExisting.

  • traversalMethod - The algorithm used to find the next available range. Defaults to DEPTH_FIRST. The possible values are:

    • NO_TRAVERSAL - will attempt to find the next range directly under the specified parent object. It will not search through to the lower level objects.

    • DEPTH_FIRST - will attempt to find the next range under the specified object by iterating through its children one by one. After exploring the object recursively for its child ranges, it will move to the next child object.

    • BREADTH_FIRST - will attempt to find the next range under the specified object by iterative levels. It will first find the range immediately below the specified parent object. If not found, then it will attempt to find the range under all the first child objects.

Returns: An object representing the existing next available IP range, or a newly created IP range if the next available range does not exist and autoCreate was set to true. None if the next available range does not exist and autoCreate was set to false.

Return type: APIEntity

Raises:

ErrorResponse – autoCreate was set to true, but there isn’t enough space to create a range of the requested size in the containing entity.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType, TraversalMethod

parent_id = <ip4_block_id>
properties = {
    "reuseExisting": "true",
    "traversalMethod": TraversalMethod.NO_TRAVERSAL
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    available_ip4_network = client.get_next_available_ip_range(
        parent_id, 128, ObjectType.IP4_NETWORK, properties
    )
print(available_ip4_network)

New in version 21.11.1.

get_next_available_ip_ranges(parent_id, type, count, size, properties=None)

Get a list of the next available (unused) networks within a configuration or block. If no existing ranges can be returned, a new list of IP ranges may be requested to be created if there’s enough space.

Parameters Description
parent_id (int)

The object ID of the parent object under which the next available range resides.
type (str)

The object type of the requested range. This method supports IPv4 networks.
count (int)

The number of IP ranges to be found.

Note:

If this value is greater than 1:

  • The isLargerAllowed property will not be applicable.
size (int)

The size of the range. Must be an integer power of 2.
properties (dict, optional)

Additional options of the operation:

  • reuseExisting - A boolean value to indicate whether to search existing empty networks to find the requested range. The default value is false. If both reuseExisting and autoCreate are defined, reuseExisting takes precedence over autoCreate.

  • isLargerAllowed - A boolean value to indicate whether to return larger networks than those specified with the size parameter. The default value is false.

  • autoCreate - A boolean value to indicate whether the next available IP ranges should be created in the parent object if they do not exist already. The default value is the opposite value of reuseExisting.

  • traversalMethod - The algorithm used to find the next available ranges. Defaults to DEPTH_FIRST. The possible values are:

    • NO_TRAVERSAL - will attempt to find the next range directly under the specified parent object. It will not search through to the lower level objects.

    • DEPTH_FIRST - will attempt to find the next range under the specified object by iterating through its children one by one. After exploring the object recursively for its child ranges, it will move to the next child object.

    • BREADTH_FIRST - will attempt to find the next range under the specified object by iterative levels. It will first find the range immediately below the specified parent object. If not found, then it will attempt to find the range under all the first child objects.

    Note:

    Only DEPTH_FIRST supports finding multiple available ranges.

Returns: A list of objects representing the next existing available IP ranges or the newly created IP ranges if the next available IP ranges do not exist and autoCreate was set to true. Returns an empty list if the next available ranges do not exist and autoCreate was set to false.

Return type: list[APIEntity]

Raises:

ErrorResponse – autoCreate was set to true, but there is not enough space to create a range of the requested size in the containing entity.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

parent_id = <ip4_block_id>
properties = {"reuseExisting": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    available_ip4_networks = client.get_next_available_ip_ranges(
        parent_id, ObjectType.IP4_NETWORK, 4, 64, properties
    )
print(available_ip4_networks)

New in version 21.11.1.

get_next_ip4_address(entity_id, properties=None)

Get the next available IP address in octet notation under specified circumstances.

Parameters Description
entity_id (int)

The object ID of the configuration or network in which the address is located.
properties (dict, optional)

Contain three properties skip, offset and excludeDHCPRange. The values for skip and offset must be IPv4 addresses and must appear in dotted octet notation.

  • skip - This is optional. It is used to specify the IP address ranges or IP addresses to skip, separated by comma. A hyphen (-), not a dash is used to separate the start and end addresses.

  • offset - This is optional. This is to specify from which address to start to assign IPv4 Address.

  • excludeDHCPRange - This specifies whether IP addresses in DHCP ranges should be excluded from assignment. The value is either true or false, default value is false.

Note:

Do not use the skip property with IP address ranges if the entity id is a configuration id. If you do, an error message appears, Skip is not allowed for configuration level.

Returns: The IPv4 address in octet notation.

Return type: str

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {"offset": "10.0.0.1", "excludeDHCPRange": "true"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_address = client.get_next_ip4_address(<ip4_network_id>, properties)
print(ip4_address)

New in version 21.8.1.

get_parent(entity_id, include_ha=None)

Get the parent entity of a given entity.

Parameters Description
entity_id (int)

The entity ID of the child object that you would like to find its parent entity ID.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: The APIEntity for the parent entity with its properties fields populated.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_parent(<entity_id>)

New in version 21.5.1.

get_probe_data(defined_probe, properties=None)

Get data for the DHCP Heat Map, IP Allocation Overlay, and DNS Deployment Role Overlay.

Parameters Description
defined_probe (str)

Pre-defined SQL queries that will be triggered to collect data. The available values are LEASE_COUNT_PER_DATE and NETWORK_BLOOM.
properties (dict, optional)

This is reserved for future use.

Returns: A dictionary containing data for the DHCP Heat Map, IP Allocation Overlay, or DNS Deployment Role Overlay.

Return type: APIData

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DefinedProbe

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    data = client.get_probe_data(DefinedProbe.NETWORK_BLOOM)
print(data)

New in version 21.11.1.

get_probe_status(defined_probe)

Check the status of the pre-defined SQL queries that have been triggered to collect data. The available constants are LEASE_COUNT_PER_DATE and NETWORK_BLOOM.

Parameters Description
defined_probe (str)

The SQL query probe object for which the status is being checked.

Returns: Integer value between 0 and 3 representing the status of the data collection process.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DefinedProbe

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    status_code = client.get_probe_status(DefinedProbe.LEASE_COUNT_PER_DATE)
print(status_code)

New in version 21.11.1.

get_replication_info()

Get Address Manager replication information.

Returns: The Address Manager replication information containing the hostname, status of replication, latency, the IP address of the Primary and standby servers, and cluster information.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    status = client.get_replication_info()
print(status)

New in version 21.11.1.

get_server_deployment_roles(server_id)

Get a list of all deployment roles associated with a server.

Parameters Description
server_id (int)

The object ID of the server with which deployment roles are associated.

Returns: A list of all deployment roles associated with the server.

Return type: list[APIDeploymentRole]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    deployment_roles = client.get_server_deployment_roles(<server_id>)
for deployment_role in deployment_roles:
    print(deployment_role)

New in version 21.5.1.

get_server_deployment_status(server_id, properties=None)

Get the deployment status of a server.

Parameters Description
server_id (int)

The object ID of the server whose deployment status needs to be checked.
properties (dict, optional)

The valid value is empty.

Returns: The status code for deployment of a particular server.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    status_code = client.get_server_deployment_status(<server_id>)
print(status_code)

New in version 21.8.1.

get_server_for_role(id)

Get the server associated with a deployment role.

Parameters Description
id (int)

The object ID of the deployment role whose server is to be returned.

Returns: APIEntity object representing the server associated with the specified deployment role.

Return type: APIEntity

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    server = client.get_server_for_role(<id>)
print(server)

New in version 21.8.1.

get_server_services(id)

Get a description of the configured server services of a DNS/DHCP Server.

Parameters Description
id (int)

The ID of the DNS/DHCP Server.

Returns: A description of the configured server services. The returned value is the Address Manager’s response as a Python dictionary.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    data = client.get_server_services(<id>)
for name, value in data['services'].items():
    print(name, value['configurations'])

New in version 21.5.1.

get_server_services_configuration_status(configuration_token)

Get the status of the services configuration task created using the configure_server_services API method.

Parameters Description
configuration_token (str)

The object type that the fields are defined for.

Returns: The service configuration status based on the token.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    resp = client.get_server_services_configuration_status(<configuration_token>)
for k, v in resp.items():
    print(f"{k}: {v}")

New in version 21.5.1.

get_shared_networks(tag_id)

Get a list of IPv4 networks linked to the given shared network tag.

Parameters Description
tag_id (int)

The object ID of the tag that is linked with shared IPv4 networks.

Returns: A list of entities of all the IPv4 networks linked to the given shared network tag

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    networks = client.get_shared_networks(<tag_id>)
for network in networks:
    print(network['properties'])

New in version 21.5.1.

get_system_info()

Get Address Manager system information.

Returns: Address Manager system information.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    data = client.get_system_info()

for key, value in data.items():
    print('{}: {}'.format(key, value))

New in version 21.5.1.

get_template_task_status(task_id)

Get the status of the task for applying an IPv4 template.

Parameters Description
task_id (str)

The ID of the task for applying an IPv4 template.

Returns: Details about the task status and associated objects.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

task_id = "d596d7e3-682b-4155-80e8-f509f7cae78a"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    task_status = client.get_template_task_status(task_id)
print(task_status)

New in version 21.11.1.

get_token()

Get the authentication token used when communicating with BAM API. The value of the token includes the authentication scheme, e.g. BAMAuthToken. It is used verbatim for header Authorization.

Return type: str

New in version 23.1.0.

get_user_defined_fields(object_type, required_fields_only)

Get the user-defined fields defined for an object type.

Parameters Description
object_type (str)

The object type that the fields are defined for.
required_fields_only (bool)

Whether all user-defined fields of the object type will be returned. If set to True, only required fields will be returned.

Returns: The user-defined fields defined for an object type.

Return type: list[APIUserDefinedField]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    udfs = client.get_user_defined_fields(ObjectType.CONFIGURATION, False)
print(udfs)

New in version 21.5.1.

get_user_defined_link(link_type='')

Get a list of link definitions for a user-defined link type. The resulting list contains all link definitions when no link type is specified.

Parameters Description
link_type (str, optional)

The link type that identifies a user defined link definition.

Returns: A list of link definitions from user-defined link type.

Return type: list[UDLDefinition]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    udls = client.get_user_defined_link('<unique-UDL-type-name>')
for udl in udls:
    print(udl.get('linkType'))

New in version 21.5.1.

get_zones_by_hint(container_id, options, start=0, count=10)

Get a list of accessible zones of child objects for a given container_id value.

Parameters Description
container_id (int)

The object ID of the container object. It can be the object ID of any object in the parent object hierarchy. The highest parent object is the configuration level.
options (dict)

A dictionary containing search options. It includes the following keys:

  • hint: A string specifying the start of a zone name.

  • overrideType: A string specifying the overriding of the zone. Must be a BAM Object value.

  • accessRight: A string specifying the access right for the zone. Must be a BAM Access right value.
start (int, optional)

Indicates where in the list of objects to start returning objects. The list begins at an index of 0. The default value is 0.
count (int, optional)

Indicates the maximum number of child objects that this method will return. The maximum value is 10. The default value is 10.

Returns: A list of entities

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import AccessRightValues, ObjectType

options = {
    'hint': 'test-zone',
    'overrideType': ObjectType.ZONE,
    'accessRight': AccessRightValues.ViewAccess
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    zones = client.get_zones_by_hint(<container_id>, options, 0, 10)
for zone in zones:
    print(zone['name'])

New in version 21.5.1.

import_entities(configuration_name, data, data_type, *, commit=True, max_size=1000, max_failures=0, user_comment=None, ignore_fields=None)

Import entities into the Address Manager database.

Parameters Description
configuration_name (str)

The name of the configuration that the entities will be imported into.
data (Union[str, list[list, dict], IO])

A string, two-dimensional list, list of dictionaries or file in CSV or NDJSON format containing entities to be imported.
data_type (str)

The type of data that is being imported. Supported data types are IP4Address, IP4Block, IP4DHCPRange, IP4Network, and MACAddress.
commit (bool, optional)

Indicates if the Address Manager database will be updated after processing the input file. Set to False for validation purposes to view results without updating the database. The default value is True.
max_size (int, optional)

The maximum number of entities allowed in a single Import Entities call. The default value is 1000.
max_failures (int, optional)

The number of failures allowed before Import entities stops processing. When the value is 0, all entities will be processed in one transaction and any failure will stop the process and rollback any updates made to the database. When the value is greater than 0, each entity will be processed individually in a separate transaction until the maximum number of failures is reached (therefore entities processed before reaching the max failure limit will remain in database). The default value is 0.
user_comment (str, optional)

The user comment that will be added to the transaction history.
ignore_fields (list[str], optional)

The fields that will be skipped during validation of entities. The parameter is useful when an input entity contains fields that are not supported for processing. When importing content that was exported using Export entities, ensure that extra fields such as id, parentid, type, and state are ignored.

Return type: iterator

Returns: An iterator object that uses a generator to return a dictionary of the raw entity input for each loop. Each dictionary detail whether the entities were processed successfully, object IDs if processed successfully, the transaction history ID if processed in one transaction (max_failures = 0), and the total number of entities input, accepted, rejected, and skipped.

Note:

  • Address Manager administrator privilege is required to use this method.

  • UDFs are supported but must exist in Address Manager first.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType

# Import entities where input data as a string
ip4_block_data = '{"range": "10.244.140.0/24"}'

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    responses = client.import_entities(
        <configuration_name>,
        ip4_block_data,
        ObjectType.IP4_BLOCK,
        user_comment="Import IP4 Block Entities",
    )
    for response in responses:
        print(response)

# Import entities where input data as a list of dictionaries
ip4_block_data = [
    {"range": "10.244.140.0/24"},
    {"range": "10.244.141.0/24", "allowDuplicateHost": "disable"},
    {"range": "10.244.142.0/24", "pingBeforeAssign": "disable"},
]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    responses = client.import_entities(
        <configuration_name>,
        ip4_block_data,
        ObjectType.IP4_BLOCK,
        ignore_fields=["allowDuplicateHost", "pingBeforeAssign"],
    )
    for response in responses:
        print(response)

# Import entities where input data as a list of lists
mac_address_data = [
    ["name", "macaddress", "macpool"],
    ["mac1_DENY", "20-00-00-00-00-10", "DENY"],
    ["mac1_NO_POOL", "20-00-00-00-00-11", None],
]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    responses = client.import_entities(
        <configuration_name>,
        mac_address_data,
        ObjectType.MAC_ADDRESS,
        user_comment="Import Mac Address Entities",
    )
    for response in responses:
        print(response)

# Import entities where input data as an I/O stream
with Client(<bam_host_url>) as client, open(<path_to_file>, "rb") as file:
    client.login(<username>, <password>)
    responses = client.import_entities(
        <configuration_name>,
        file,
        <data_type>,
    )
    for response in responses:
        print(response)

New in version 23.1.0.

is_address_allocated(configuration_id, ip_address, mac_address)

Query a MAC address to determine if the address has been allocated to an IP address.

Parameters Description
configuration_id (int)

The object ID of the configuration in which the MAC address resides.
ip_address (str)

The IPv4 DHCP allocated address to be checked against the MAC address.
mac_address (str)

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: A Boolean value indicating whether the address is allocated.

Return type: bool

Example: 

from bluecat_libraries.address_manager.api import Client

configuration_id = <configuration_id>
ip_address = "10.0.0.10"
mac_address = "00-60-56-9B-29-9B"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    is_allocated = client.is_address_allocated(configuration_id, ip_address, mac_address)
print(is_allocated)

New in version 21.8.1.

property is_authenticated

Determine whether the authentication necessary to communicate with the target service is set.

Return type: bool

is_migration_running(filename=None)

Report whether the migration service is running. The method can be used to determine the processing of a specific file. If no filename is specified, the result indicates whether any files are being migrated or queued for migration.

Parameters Description
filename (str, optional)

The filename of an XML file in directory /data/migration/incoming on BlueCat Address Manager. Do not include a path in the filename. This defaults to None.

Returns: A boolean value indicating if the specified file is currently migrating. When using the default None value of the filename, returns True if there are any migration files queued for migration or currently migrating.

Return type: bool

Example: 

from bluecat_libraries.address_manager.api import Client

filename = "filename.xml"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    running = client.is_migration_running(filename)
print(running)

New in version 21.11.1.

link_entities(entity1_id, entity2_id, properties=None)

Establish a link between two Address Manager entities.

Parameters Description
entity1_id (int)

The object ID of the first entity in the pair of linked entities.
entity2_id (int)

The object ID of the second entity in the pair of linked entities.
properties (dict, optional)

Adds object properties, including user-defined fields.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.link_entities(<entity1_id>, <entity2_id>, <properties>)

Return type: None

New in version 21.5.1.

link_entities_ex(relationship)

Establish a user-defined link between two Address Manager entities. The link has a direction - a source and a destination.

Parameters Description
relationship (UDLRelationship)

The link type that identifies a user-defined link definition.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import UDLRelationship

relationship = UDLRelationship(
    linkType=<UniqueLinkTypeName>,
    description="Description for the link",  # BAM 9.4.0 or greater
    sourceEntityId=<source_id>,
    destinationEntityId=<destination_id>
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.link_entities_ex(relationship)

Return type: None

New in version 21.5.1.

login(username, password)

Log user into BAM and store authentication token for later use by subsequent calls.

Parameters Description
username (str)

The username of a BAM user. They must be configured as an API user in BAM.
password (str)

The password of the BAM user.

Returns: The authentication token returned by BAM, including the authentication scheme.

Return type: str

login_with_options(username, password, options)

Log user into BAM with additional options - locale: option to indicate the locale - isReadOnly: option to initiate a read only api session

Parameters Description
username (str)

Username
password (str)

Password
options (dict)

The options for login
Note:

isReadOnly is available with BAM 9.3 or greater

logout()

Log user out from BAM and clear any stored authentication token.

Return type: str

Returns: The message from BAM for the logout request.

merge_blocks_with_parent(ip4_block_ids)

Merge specified IPv4 blocks into a single block. The blocks must all have the same parent. If blocks are not contiguous, The gap between blocks will be automatically found and made contiguous so they can be merged. If the parent of the block is a configuration, they cannot contain networks.

Parameters Description
ip4_block_ids (list[int])

The object IDs of the IPv4 blocks to be merged.

Example: 

from bluecat_libraries.address_manager.api import Client

ip4_block_ids = [<ip4_block1_id>, <ip4_block2_id>]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.merge_blocks_with_parent(ip4_block_ids)

Return type: None

New in version 21.11.1.

merge_selected_blocks_or_networks(object_id_to_keep, object_ids_to_merge)

Merge specified IPv4 blocks or IPv4 networks into a single IPv4 block or IPv4 network. The list of objects to be merged must all be of the same type (for example, all blocks or all networks). The objects must all have the same parent and must be contiguous.

Parameters Description
object_id_to_keep (int)

The object ID of the IPv4 block or IPv4 network that will retain its identity after the merge.
object_ids_to_merge (list[int])

The object IDs of the IPv4 blocks or IPv4 networks to be merged.

Example: 

from bluecat_libraries.address_manager.api import Client

object_ids_to_merge = [<ip4_block1_id>, <ip4_block2_id>, <ip4_block3_id>]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.merge_selected_blocks_or_networks(<ip4_block1_id>, object_ids_to_merge)

Return type: None

New in version 21.11.1.

migrate_file(filename)

Process the specified XML file into Address Manager. The file must reside in the /data/migration/incoming directory on the Address Manager server.

Parameters Description
filename (str)

The filename of the XML file in the /data/migration/incoming directory. Do not include a path in the filename.

Example: 

from bluecat_libraries.address_manager.api import Client

filename = "filename.xml"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.migrate_file(filename)

Return type: None

New in version 21.11.1.

move_deployment_roles(source_server_id, target_server_interface_id, move_dns_roles, move_dhcp_roles, options=None)

Move DNS/DHCP deployment roles from a server to the specified interface of another server.

Parameters Description
source_server_id (int)

The object ID of the server that contains the roles.
target_server_interface_id (int)

The object ID of the server interface of the server to which the roles are to be moved.
move_dns_roles (bool)

If set to True, all DNS roles will be moved to the target server interface.
move_dhcp_roles (bool)

If set to True, all DHCP roles will be moved to the target server interface.
options (dict, optional)

This is reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.move_deployment_roles(
        <source_server_id>, <target_server_interface_id>, True, False
    )

Return type: None

New in version 21.11.1.

move_ip_object(entity_id, address, options=None)

Move an IPv4 block, IPv4 network, IPv4 address, IPv6 block, or IPv6 network to a new address.

Parameters Description
entity_id (int)

The ID of the object. IPv4 blocks, IPv4 networks, IPv4 addresses, IPv6 blocks, and IPv6 networks are supported.
address (str)

The new address for the object.
options (dict, optional)

A dictionary containing the following option:

  • noServerUpdate - A boolean value. If set to true, instant dynamic host record changes will not be performed on DNS/DHCP Servers when moving an IPv4 address object.

    Note:

    noServerUpdate works only for an IPv4 address object.

Example: 

from bluecat_libraries.address_manager.api import Client

address = "10.0.0.0"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.move_ip_object(<ipv4_network_id>, address)

Return type: None

New in version 21.11.1.

move_resource_record(id, destination_zone)

Move a resource record between different zones that already exist.

Parameters Description
id (int)

The object ID of the resource record to be moved.
destination_zone (str)

The FQDN of the destination DNS zone to which the resource record will be moved.

Example: 

from bluecat_libraries.address_manager.api import Client

destination_zone = "example.com"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.move_resource_record(<id>, destination_zone)

Return type: None

New in version 21.11.1.

purge_history_now(number_of_days_to_keep=-1, number_of_months_to_keep=-1, until_when_timestamp=None, wait_option=False)

Run the history purge function.

Parameters Description
number_of_days_to_keep (int, optional)

The number of days to preserve the data in the database. Valid values for this parameter are between 1 and 3650. Set to -1 if using either until_when_timestamp or number_of_months_to_keep. Using this parameter will archive all history that will be purged and overwrite existing archive files in the /data/archive directory.
number_of_months_to_keep (int, optional)

The number of months to preserve data in the database. Valid values are integers of 0 or greater. Set to -1 if using either until_when_timestamp or number_of_days_to_keep. Using this parameter will not archive any data.
until_when_timestamp (str, optional)

A string specifying a point in time after which history is will be preserved. The valid timestamp pattern is YYYY-MM[-DD[ HH:MM:SS[.mmm]]]. Set this parameter is None if using either number_of_days_to_keep or number_of_months_to_keep. Using this parameter will not archive any data.
wait_option (bool, optional)

If set to True, the purge will be performed and the result will be returned when completed. The default value is False.

Returns: Returns 0 (zero) when the purge service has successfully completed, otherwise -1.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    result = client.purge_history_now(2, -1)
print(result)

New in version 22.4.1.

quick_deploy(entity_id, properties=None)

Instantly deploy changes made to DNS resource records since the last full or quick deployment. This method only applies to DNS resource records that have been changed and does not deploy any other data.

Parameters Description
entity_id (int)

The object ID of the DNS zone or network for which the deployment service is being deployed.
properties (dict, optional)

A dictionary containing the services option. It can also be None.

  • services - the name of the valid service that need to be deployed. The only valid service name for quick deployment is DNS. Any other service names will throw an error.

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {"services": "DNS"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.quick_deploy(<entity_id>, properties)

Return type: None

New in version 21.8.1.

property raw_api

The underlying automatically generated client for the endpoints specified by the BAM REST API v1 service.

Return type: Client

reapply_template(id, properties)

Reapply a DNS zone template.

Parameters Description
id (int)

The object ID of the DNS zone template being assigned or updated.
properties (dict)

A dictionary containing the following settings:

  • templateType - Mandatory. Specify the type of template on which this operation is being performed. The only possible value is “ZoneTemplate”.

  • zoneTemplateReapplyMode - Optional. Specify the re-apply mode for various properties of the template. If the re-apply mode is not specified, the default value is templateReapplyModeIgnore. The possible values are: ZoneTemplateReapplyMode.OVERWRITE, ZoneTemplateReapplyMode.UPDATE, ZoneTemplateReapplyMode.IGNORE

Note:

  • ZoneTemplateReapplyMode.OVERWRITE is NOT applicable for Gateway and Reserved Addresses. Use ZoneTemplateReapplyMode.UPDATE instead to update.

  • ZoneTemplateReapplyMode.UPDATE is NOT applicable for Reserved DHCP Ranges, IP Groups and Zone Templates. Use ZoneTemplateReapplyMode.OVERWRITE instead to update.

  • Both ZoneTemplateReapplyMode.UPDATE and ZoneTemplateReapplyMode.OVERWRITE are applicable for Deployment Options.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType, ZoneTemplateReapplyMode

properties = {
    "templateType": ObjectType.ZONE_TEMPLATE,
    "zoneTemplateReapplyMode": ZoneTemplateReapplyMode.OVERWRITE,
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.reapply_template(<template_id>, properties)

Return type: None

New in version 21.8.1.

reassign_ip6_address(old_address_id, destination, properties=None)

Reassign an existing IPv6 address to a new IPv6 address.

Parameters Description
old_address_id (int)

The object ID of the IPv6 address to reassign.
destination (str)

The destination of the reassigned address. This can be an IPv6 address or a MAC address from which the new IPv6 address is being calculated. Specify the MAC address in the format nnnnnnnnnnnn or nn-nn-nn-nn-nn-nn, where nn is a hexadecimal value.
properties (dict, optional)

Object properties, including user-defined fields.

Returns: The object ID of the reassigned IPv6 address.

Return type: int

Example: 

from bluecat_libraries.address_manager.api import Client

old_address_id = <old_address_id>
destination = "2000:33::3"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip6_address_id = client.reassign_ip6_address(old_address_id, destination)
print(ip6_address_id)

New in version 21.8.1.

remove_additional_ip_addresses(server_id, ips, properties=None)

Remove additional IPv4 addresses and loopback addresses from the Service interface.

Parameters Description
server_id (int)

The object ID of the server from which additional IP addresses is being removed.
ips (list[str])

The list of IP addresses to remove. The multiple IP addresses are specified with a separator (|). The supported format is [IP,serviceType| IP,serviceType].
properties (dict, optional)

Object properties. Currently there is no supported properties. Reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

server_id = <server_id>
ips = [
    "10.0.0.10/32,loopback",
    "11.0.0.3/24,service"
]

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.remove_additional_ip_addresses(server_id, ips)

Return type: None

New in version 21.8.1.

remove_trust_relationship(remote_ip, properties=None)

Remove a remote Address Manager server from the trust relationship.

Parameters Description
remote_ip (str)

The IP address of the standby server.

Note:

If the standby server is in replication, it must first be removed from replication before it can be removed from the trust relationship.
properties (dict, optional)

This is reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.remove_trust_relationship(<remote_ip>)

Return type: None

New in version 21.11.1.

replace_server(server_id, name, default_interface, host_name, password, upgrade, properties)

Replace a server.

Parameters Description
server_id (int)

The object ID of the server to replace.
name (str)

Name of the server to replace.
default_interface (str)

Management interface address for the server.
host_name (str)

The DNS FQDN by which the server is referenced.
password (str)

The server password. For more information on the default server password, refer to BlueCat default login credentials.
upgrade (bool)

Flag indicating that server needs to be upgraded or not. True means server needs to be upgraded.
properties (dict)

A dictionary containing the following options:

  • servicesIPv4Address - IPv4 address used only for services traffic such as DNS, DHCP, DHCPv6 and TFTP. If dedicated management is enabled, this option must be specified. If dedicated management is disabled, this address must be the same as defaultInterfaceAddress which is management interface address.

  • servicesIPv4Netmask - IPv4 netmask used only for services traffic such as DNS, DHCP, DHCPv6 and TFTP. If dedicated management is enabled, this option must be specified. If dedicated management is disabled, this netmask address must be the same as the management interface netmask address.

  • servicesIPv6Address - IPv6 address used only for services traffic such as DNS, DHCP, DHCPv6 and TFTP. This is optional.

  • servicesIPv6Subnet - IPv6 subnet used only for services traffic such as DNS, DHCP, DHCPv6 and TFTP. This is optional.

  • xhaIPv4Address - IPv4 address used for XHA. This is optional.

  • xhaIPv4Netmask - IPv4 netmask used for XHA. This is optional.

  • redundancyScenario - networking redundancy scenarios. The possible values are ACTIVE_BACKUP Failover and IEEE_802_3AD Load Balancing.

  • resetServices - allow for replacing the DNS/DHCP Server while maintaining existing configurations for DNS, DHCP, and TFTP services. Define this option only if the IPv4 or IPv6 addresses of the Services interface have been modified or the configurations needs to be reset for DNS, DHCP, and TFTP services on the DNS/DHCP Server. The value is either true or false by default, false.

  • encryptedNotification - A boolean value. It enables or disables encrypted notifications between Address Manager and BlueCat DNS/DHCP Servers. This property is optional and supported from Address Manager v9.4.0. The default value is false.

    Note:

    For DNS/DHCP Servers without multi-port support, the interface-related property options will be ignored.

    Note:

    Resetting DNS/DHCP Servers will result in a service outage. This service outage will last until services have been deployed to the replacement system. Only reset DNS/DHCP Server services if the DNS/DHCP Server are being replaced with a new appliance of a different type or reconfiguring the IPv4 or IPv6 addresses of the Services interface on the appliance. BlueCat recommends that a maintenance window is scheduled before performing a reset of DNS/DHCP Server services.

Example: 

from bluecat_libraries.address_manager.api import Client

server_id = <server_id>
name = "server-name"
default_interface = <ip_address>
host_name = <existing_hostname>
password = <server_password>
upgrade = "false"
properties = {
    "servicesIPv4Address": <ip4_address>,
    "servicesIPv4Netmask": <ipr_netmask>
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.replace_server(
        server_id, name, default_interface, host_name, password, upgrade, properties
    )

Return type: None

New in version 21.8.1.

resize_range(entity_id, range, options=None)

Change the size of an IPv4 block, IPv4 network, DHCPv4 range, IPv6 block, or IPv6 network.

Parameters Description
entity_id (int)

The ID of the object to be resized. The method supports IPv4 block, IPv4 network, DHCPv4 range, IPv6 block, and IPv6 network.
range (str)

The new size for the object to be resized.

  • For an IPv4 block and network, specify the size in CIDR notation or as an address range in the ipAddressStart-ipAddressEnd format.

  • For a DHCPv4 range, specify the size in the ipAddressStart-ipAddressEnd format.

  • For an IPv6 block and network, specify the size in the Starting address/Size format.
options (dict, optional)

A dictionary containing the following option:

  • convertOrphanedIPAddressesTo. The possible values are: STATIC, DHCP_RESERVED, UNALLOCATED. For example: options={"convertOrphanedIPAddressesTo": "STATIC"}.

    Note:

    This option applies only to DHCPv4 range.

    • The default is DHCP_RESERVED.

    • If the option value is incorrect, an exception will be thrown.

    • If the option name is incorrect, the option will be ignored. Therefore, orphaned IP addresses will remain as assigned.

Example: 

from bluecat_libraries.address_manager.api import Client

range = "10.244.140.5-10.244.140.15"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.resize_range(<dhcp4_range_id>, range)

Return type: None

New in version 21.11.1.

search_by_category(category, keyword, start=0, count=10, include_ha=None)

Get a list of entities by searching for keywords associated with objects of a specified object category.

Parameters Description
category (str)

The entity category to search. This must be one of the entity categories listed in BAM Entity categories.
keyword (str)

The search keyword string. The following wildcards are supported in the options:

  • ^ - matches the beginning of a string. For example: ^ex matches example but not text.

  • $ - matches the end of string. For example: ple$ matches example but not please.

  • ^ $ - matches the exact characters between the two wildcards. For example: ^example$ only matches example.

  • ? - matches any one character. For example: ex?t matches exit.

  • * - matches zero or more characters within a string. For example: ex*t matches exit and excellent.
start (int, optional)

Indicates where in the list of returned objects to start returning objects. The list begins at an index of 0.
count (int, optional)

The maximum number of objects to return. The default value is 10.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: A list of entities matching the keyword text and the category type, or an empty list.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

keyword = 'test'
category = 'CONFIGURATION'
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.search_by_category(category, keyword, 0, 10)
for entity in entities:
    print(entity['name'])

New in version 21.5.1.

search_by_object_types(keyword, types, start=0, count=10, include_ha=None)

Get a list of entities for keywords associated with objects of specified object types. We can search for multiple object types with a single method call.

Parameters Description
keyword (str)

The search keyword string.
types (list[str])

The object types for which to search. The object type must be one of the types listed in BAM Object types.
start (int, optional)

Indicates where in the list of returned objects to start returning objects. The list begins at an index of 0.
count (int, optional)

The maximum number of objects to return. The default value is 10.
include_ha (bool, optional)

A boolean value. This parameter is supported Address Manager from v9.4.0. Allows to include or exclude HA information when getting properties from a server. If set to False, the query for HA status will be skipped. The default value is True.

Returns: A list of entities matching the keyword text and the category type, or an empty list.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

keyword = 'test'
types = ['Configuration', 'View']
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entities = client.search_by_object_types(keyword, types, 0, 10)
for entity in entities:
    print(entity['name'])

New in version 21.5.1.

search_response_policy_items(scope, keyword, properties=None, start=0, count=10)

Search Response Policy items configured in local Response Policies or predefined BlueCat Security feed data. The search will return a list of all matching items in Address Manager across all configurations.

Parameters Description
scope (str)

The scope in which the search is to be performed.

  • Local - to search policy items configured in local Response Policies.

  • Feed - to search policy items configured in predefined BlueCat Security Feed data.

  • All - to search policy items configured in both local Response Policies and predefined BlueCat Security Feed data.
keyword (str)

The search string for which you wish to search.

  • ^ - matches the beginning of a string. For example: ^ex matches example but not text.

  • $ - matches the end of string. For example: ple$ matches example but not please.

  • * - matches zero or more characters within a string. For example: ex*t matches exit and excellent.
properties (dict, optional)

Reserved for future use.
start (int, optional)

A starting number from where the search result will be returned. The possible value is a positive integer ranging from 0 to 999.
count (int, optional)

The total number of results to return. The possible value is a positive integer ranging from 1 to 1000.

Returns: A list of ResponsePolicySearchResult objects. Each object contains information of one Response Policy item found either in local Response Policies or BlueCat Security feed data.

Return type: list[ResponsePolicySearchResult]

Example: 

from bluecat_libraries.address_manager.api import Client

# Using local Response Policies scope
scope = "Local"
keyword = "^te*"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    policy_items = client.search_response_policy_items(scope, keyword)
for policy_item in policy_items:
    print(policy_item)

New in version 21.5.1.

selective_deploy(entity_ids, properties=None)

Create a differential deployment task to deploy changes made to specific DNS entities, such as resource records, to a managed DNS/DHCP Server.

Note:

The selectiveDeploy API method can be used to deploy DNS resource records that have moved zones. The new zone of the resource record must be deployed to the same DNS/DHCP Server as the previous zone that the resource record was deployed to. The DNS resource record cannot be deployed if the new zone is deployed to a different DNS/DHCP Server.

Parameters Description
entity_ids (list[int])

A list of entity IDs that specify the DNS entities to deploy. Currently, only DNS resource records are supported.

Note:

Restrictions:

  • Only deploy a maximum of 100 DNS entities per selective deployment API call.

  • Cannot deploy dynamic records, external host records, and resource records which belongs to multiple DNS/DHCP Servers.

  • If resource records are being deployed that have moved zones, the new zone of the resource record must be deployed to the same DNS/DHCP Server as the previous zone that the resource record was deployed to. The resource record cannot be deployed if the new zone is deployed to a different DNS/DHCP Server.
properties (dict, optional)

Contains the following deployment options:

  • scope - a string value. This property defines whether the deployment task includes objects that are related to the defined DNS resource records. The scope can be one of the following values:

    • related (default value) - deploys the DNS resource records defined in the entityIds list including DNS resource records that are related to those entities. For more information on additional entities that are deployed when the related scope is defined, refer to Reference: selective deployment related scope.

    • specific - deploys only the DNS resource records that are defined in the entity_ids list.

  • batchMode - an enum value. This property batches selective deployment tasks. The scope can be one of the following values:

    • disabled (default value) - disables the batching of selective deployment tasks.

    • batch_by_server - enables the batching of selective deployment tasks.

    Note:

    The batching of selective deployment tasks is dependent on the following conditions:

    • The tasks are from the same server.

    • Each deployment task that is configured for batching must have batchMode set to batch_by_server.

    • The batched deployment contains less than 100 resource records.

  • continueOnFailure - a boolean value. This property specifies the mode of operation on a failed resource record. If set to false, deployment stops when a record fails. If set to true, deployment continues when a record fails and moves to the next record. The default value is true if batchMode is set to batch_by_server, otherwise the default value is false.

  • dynamicRecords - an enum value. This property defines how dynamic records are handled with selective deployment tasks. The value can be one of the following:

    • fail (default value) - the selective deployment task fails when a dynamic record is encountered.

    • skip - skips dynamic records by removing them from the list of entity IDs before the selective deployment task is performed.

      Note:

      If a selective deployment is performed where all entities are dynamic and the skip option is defined, all records will be removed from the selective deployment task and the deployment fails with the following message: Verify input error.: Empty entity id input

    • makestatic - dynamic records are updated to static records before the selective deployment task is performed. This option can be used to convert previously created dynamic records, such as records created using the addDeviceInstance method, to static records and selectively deploy the changes to the DNS/DHCP Server. This has no effect on related records that are deployed using the related scope.

      Note:

      If the makestatic option is defined and the selective deployment task fails for any reason, the updated records are not rolled back and remain static records.

Returns: A token string value of the deployment task.

Return type: str

Example: 

from bluecat_libraries.address_manager.api import Client

entity_ids = [<entity_1>, <entity_n>]
properties = {"batchMode": "batch_by_server"}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    token = client.selective_deploy(entity_ids, properties)
print(token)

New in version 21.8.1.

set_token(token)

Set authentication token to be used when communicating with BAM API.

Parameters Description
token (str)

Value of the token, including the scheme, e.g. BAMAuthToken. The value is used verbatim for header Authorization.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.set_token(<auth_token>)
    data = client.get_system_info()

for key, value in data.items():
    print('{}: {}'.format(key, value))

Return type: None

share_network(network_id, tag_id)

Link an IPv4 network with a shared network tag. To use shared networks, you must create a tag and tag group, and associate the tag group with a configuration. A configuration can have multiple associated tags but only one tag is required for creating a shared network.

Parameters Description
network_id (int)

The object ID of the IPv4 network that is being linked with a shared network tag.
tag_id (int)

The object ID of the tag that is linked.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.share_network(<network_id>, <tag_id>)

Return type: None

New in version 21.11.1.

split_ip4_network(network_id, number_of_parts, options=None)

Split an IPv4 network into the specified number of networks.

Parameters Description
network_id (int)

The object ID of the network that is being split.
number_of_parts (int)

The number of the networks into which the network is being split. Valid values are 2, 4, 8, 16, 32, 64, 128, 256, 512, or 1024.
options (dict, optional)

Additional options of the operation:

  • assignDefaultGateway - a boolean value. If set to true, each network will have a default gateway created using the first IP address in that network. The default value is true.

  • overwriteConflicts - a boolean value. If set to true, any conflicts within the split IPv4 network will be removed. The default value is false.

  • preserveGateway - a boolean value. If set to true, the gateway in the original network will be preserved. The default value is true.

  • template - a network template ID. Specify a network template ID if it is applied. The default value is zero (0) which means no network template will be used.

Returns: A list of networks after splitting the network.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

options = {"assignDefaultGateway": "false", "template": <template_id>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip4_networks = client.split_ip4_network(<ip4_network_id>, 4, options)
print(ip4_networks)

New in version 21.11.1.

split_ip6_range(entity_id, number_of_parts, options=None)

Split an IPv6 block or network into a number of blocks or networks.

Parameters Description
entity_id (int)

The object ID of the block or network that is being split.
number_of_parts (int)

The number of the blocks or networks into which the block or network is being split. Valid values are 2, 4, 8, 16, 32, 64, 128, 256, 512, or 1024.
options (dict, optional)

No options available. Reserved for future use.

Returns: A list of the IPv6 blocks or networks created after splitting the block or network.

Return type: list[APIEntity]

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    ip6_blocks = client.split_ip6_range(<ip6_block_id>, 2)
print(ip6_blocks)

New in version 21.8.1.

start_probe(defined_probe, properties=None)

Start collecting data from the Address Manager database using pre-defined SQL queries.

Parameters Description
defined_probe (str)

Pre-defined SQL queries that will be triggered to collect data. The available values are LEASE_COUNT_PER_DATE and NETWORK_BLOOM.
properties (dict, optional)

This is reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DefinedProbe

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.start_probe(DefinedProbe.NETWORK_BLOOM)

Return type: None

New in version 21.11.1.

property system_version

Version of the BlueCat Address Manager the client is connected to. Return value None means this client has never been logged into.

Returns: Version of BlueCat Address Manager.

Return type: Optional[str]

terminate_user_sessions(username, properties=None)

Terminate all active user sessions in Address Manager.

Parameters Description
username (str)

The username of the user for which all active sessions are terminated.
properties (dict, optional)

Reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.terminate_user_sessions(<username>)

Return type: None

New in version 21.8.1.

unassign_ip4_template(object_id, template_id, properties=None)

Unassign an IPv4 template.

Parameters Description
object_id (int)

The object ID of the IPv4 template recipient
template_id (int)

The object ID of the IPv4 template
properties (dict, optional)

Reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.unassign_ip4_template(<object_id>, <template_id>)

Return type: None

New in version 21.5.1.

unlink_entities(entity1_id, entity2_id, properties=None)

Remove the link between two Address Manager entities.

Parameters Description
entity1_id (int)

The object ID of the first entity in the pair of linked entities.
entity2_id (int)

The object ID of the second entity in the pair of linked entities.
properties (dict, optional)

Adds object properties, including user-defined fields.

Example: 

from bluecat_libraries.address_manager.api import Client

properties = {<UDF_name>: <value>}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.unlink_entities(<entity1_id>, <entity2_id>, properties)

Return type: None

New in version 21.5.1.

unlink_entities_ex(relationship)

Remove a user-defined link between two Address Manager entities.

Parameters Description
relationship (UDLRelationship)

The link type that identifies a user-defined link definition.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import UDLRelationship

relationship = UDLRelationship(
    linkType=<UniqueLinkTypeName>,
    description="Description for the link",  # BAM 9.4.0 or greater
    sourceEntityId=<source_id>,
    destinationEntityId=<destination_id>
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.unlink_entities_ex(relationship)

Return type: None

New in version 21.5.1.

unshare_network(ip4_network_id)

Unlink the shared network tag from an IPv4 network.

Parameters Description
ip4_network_id (int)

The object ID of the IPv4 network that is being unlinked from a shared network tag.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.unshare_network(<ip4_network_id>)

Return type: None

New in version 21.11.1.

update_access_right(entity_id, user_id, value, overrides=None, properties=None)

Update the access right for an object.

Parameters Description
entity_id (int)

The object ID of the entity to which the access right is assigned. Set to zero (0) to add the access right to the default root level.
user_id (int)

The object ID of the user to whom the access right is assigned. This value is not mutable.
value (str)

The value of the access right being added. This value must be one of the following items:

  • ADD

  • CHANGE

  • FULL

  • HIDE

  • VIEW
overrides (dict, optional)

A dictionary of type-specific overrides.
properties (dict, optional)

A dictionary including the following options:

  • workflowLevel - valid values for this option are:

    • NONE - changes made by the user or group take effect immediately.

    • RECOMMEND - changes made by the user or group are saved as change requests and must be reviewed and approved before they take effect.

    • APPROVE - changes made by the user or group take effect immediately and the user or group can approve change requests from other users or groups.

  • deploymentAllowed - A boolean value indicating whether or not the user or group can perform a full deployment of data from the configuration to a managed server.

  • quickDeploymentAllowed - A boolean value indicating whether or not the user or group can instantly deploy changed DNS resource records.

  • selectiveDeploymentAllowed - A boolean value indicating whether a user or group can perform a selective deployment of data to a managed server, and dynamically deploy resource records that are added, updated, and deleted within a DNS zone that has the dynamicUpdate parameter enabled. This option supports from Address Manager v9.4.0.

Note:

  • All of these properties are optional.

  • The deploymentAllowed property applies only to configuration, server, or root entities with Full access rights.

  • The selectiveDeploymentAllowed property can only be configured at the root level.

  • The workflowLevel property applies only to Change, Add, or Full access rights.

Example: 

from bluecat_libraries.address_manager.constants import AccessRightValues
from bluecat_libraries.address_manager.api import Client

value = AccessRightValues.FullAccess
overrides = {"IP4Block": "FULL", "View": "FULL"}
properties = {
    "deploymentAllowed": "true",
    "quickDeploymentAllowed": "true",
    "workflowLevel": "RECOMMEND",
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_access_right(0, <user_id>, value, overrides, properties)

Return type: None

New in version 21.8.1.

update_bulk_udf(data, properties=None)

Update value of various user-defined fields (UDFs) for different objects.

Parameters Description
data (str, list[list[Any]], IO)

A CSV string, two-dimensional list, or file with the following columns:

  1. Entity Id - The object ID of the entity on which the UDF needs to be updated.

  2. UDF Name - The actual name of the UDF that needs to be updated.

  3. New UDF Value - The new value of the UDF which needs to be updated on the entity.

Note:

If you are using a CSV string or file, the input must not contain headers and data must start on the first line.
properties (dict, optional)

This is reserved for future use.

Returns: An empty dictionary is returned when all rows in the input data were successfully processed. If there were errors processing the input data, a dictionary is returned containing the following information:key - The respective line number of CSV string or file; or the index of data as a list.value - The reason for the failure identified by the system.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

data = "<entity_id>,<udf_name>,<new_udf_value>"

# Update bulk UDF where input data as a string
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    result = client.update_bulk_udf(data)

data = [
    [<entity1_id>,<udf1_name>,<new_udf1_value>],
    [<entity2_id>,<udf2_name>,<new_udf2_value>],
]

# Update bulk UDF where input data as a list
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    result = client.update_bulk_udf(data)

# Update bulk UDF where input data as an I/O stream
with Client(<bam_host_url>) as client, open("test.csv", "rb") as file:
    client.login(<username>, <password>)
    result = client.update_bulk_udf(file)
print(result)

New in version 21.11.1.

update_configuration_setting(entity_id, setting, properties)

Update a configuration setting.

Parameters Description
entity_id (int)

The object ID of the configuration.
setting (str)

The name of the specific setting. Only the “OPTION_INHERITANCE” setting is supported.
properties (dict)

The new properties of the configuration setting to be updated. Only the “disableDnsOptionInheritance” property is supported.

Example: 

from bluecat_libraries.address_manager.api import Client

entity_id = <configuration_id>
setting = "OPTION_INHERITANCE"
properties = {
    "disableDnsOptionInheritance": "true"
}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_configuration_setting(entity_id, setting, properties)

Return type: None

New in version 21.8.1.

update_dhcp6_client_deployment_option(option)

Update a DHCPv6 client options for entity.

Note:

The Name field of the DHCPv6 client deployment option object cannot be updated.

Parameters Description
option (APIDeploymentOption)

The DHCPv6 client option is being updated.

Example: 

from bluecat_libraries.address_manager.api.models import APIDeploymentOption
from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import OptionType

option = APIDeploymentOption(
    id=<entity_id>,
    name="information-refresh-time",
    type=OptionType.DHCP6_CLIENT,
    value=['3600'],
    properties={"inherited": "false"}
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dhcp6_client_deployment_option(option)

Return type: None

New in version 21.8.1.

update_dhcp6_service_deployment_option(option)

Update a DHCPv6 service deployment option.

Note:

The Name field of the DHCPv6 service deployment option object cannot be updated.

Parameters Description
option (APIDeploymentOption)

The DHCPv6 service option object to update.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import OptionType
from bluecat_libraries.address_manager.api.models import APIDeploymentOption

option = APIDeploymentOption(
    id=<entity_id>,
    name="ddns-update-style",
    type=OptionType.DHCP6_SERVICE,
    value=["standard"],
    properties={"inherited": "false"}
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dhcp6_service_deployment_option(option)

Return type: None

New in version 21.8.1.

update_dhcp_client_deployment_option(option)

Update a DHCP client option.

Note:

The name field of the DHCP client deployment option object cannot be updated.

Parameters Description
option (APIDeploymentOption)

The DHCP client option object to update.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIDeploymentOption
from bluecat_libraries.address_manager.constants import OptionType

option = APIDeploymentOption(
    id=103709,
    name="time-server",
    type=OptionType.DHCP_CLIENT
    value=['10.244.140.122', '10.244.140.124'],
    properties={"inherited": "false"}
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dhcp_client_deployment_option(option)

Return type: None

New in version 21.8.1.

update_dhcp_deployment_role(role)

Update a DHCP deployment role.

Parameters Description
role (APIDeploymentRole)

The DHCP deployment role object to update.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIDeploymentRole
from bluecat_libraries.address_manager.constants import DHCPDeploymentRoleType

role = APIDeploymentRole(
    id=<dhcp4_role_id>,
    entityId=<ip4_network_id>,
    serverInterfaceId=<server_interface_id>,
    type=DHCPDeploymentRoleType.MASTER,
    service="DHCP",
    properties={"secondaryServerInterfaceId": <secondary_server_interface_id>}
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dhcp_deployment_role(role)

Return type: None

New in version 21.8.1.

update_dhcp_service_deployment_option(option)

Update a DHCP service deployment option.

Parameters Description
option (APIDeploymentOption)

The DHCP service deployment option object to be updated.

Note:

The name field of the DHCP service deployment option object cannot be updated.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIDeploymentOption
from bluecat_libraries.address_manager.constants import OptionType
from bluecat_libraries.address_manager.constants import (
    DHCPServiceOption,
    DHCPServiceOptionConstant,
)

option = APIDeploymentOption(
    id=<option_id>,
    name=DHCPServiceOption.DDNS_HOSTNAME,
    type=OptionType.DHCP_SERVICE,
    value=[
        DHCPServiceOptionConstant.DDNS_HOSTNAME_TYPE_IP,
        DHCPServiceOptionConstant.DDNS_HOSTNAME_POSITION_APPEND,
        '10.0.0.10'
    ],
    properties={"inherited": "false"}
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dhcp_service_deployment_option(option)

Return type: None

New in version 21.8.1.

update_dhcp_vendor_deployment_option(option)

Update a DHCP vendor deployment option.

Parameters Description
option (APIDeploymentOption)

The DHCP vendor option object being updated.

Note:

The name field of the DHCP vendor deployment option object cannot be updated.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIDeploymentOption
from bluecat_libraries.address_manager.constants import ObjectType

option = APIDeploymentOption(
    id=<ip4_network_id>,
    name="test_option",
    type=ObjectType.DHCP_VENDOR_CLIENT,
    value=["test"],
    properties={"server": <server_id>}
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dhcp_vendor_deployment_option(option)

Return type: None

New in version 21.8.1.

update_dns_deployment_option(option)

Update a DNS option.

Parameters Description
option (APIDeploymentOption)

The DNS option to update.

Note:

Depending on the type of deployment option, the format of the value might differ.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIDeploymentOption

option = APIDeploymentOption(
    id=<entity_id>,
    name="allow-notify",
    value=["10.0.0.6"],
    properties={<udf_name>: <udf_value>}
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dns_deployment_option(option)

Return type: None

New in version 21.8.1.

update_dns_deployment_role(role)

Update a DNS deployment role.

Parameters Description
role (APIDeploymentRole)

The DNS deployment role object to update.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import DNSDeploymentRoleType
from bluecat_libraries.address_manager.api.models import APIDeploymentRole

role = APIDeploymentRole(
    id=<deployment_role_id>,
    entityId=<zone_id>,
    serverInterfaceId=<server_interface_id>,
    type=DNSDeploymentRoleType.MASTER,
    service="DNS",
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_dns_deployment_role(role)

Return type: None

New in version 21.8.1.

update_entity(entity)

Update an entity object.

Parameters Description
entity (APIEntity)

The actual API entity passed as an entire object that has its mutable values updated.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_entity_by_id(<entity_id>)
    entity['name'] = 'new name'
    entity['properties']['configurationGroup'] = 'new group name'
    client.update_entity(entity)

Return type: None

New in version 21.5.1.

update_entity_with_options(entity, options)

Update objects requiring a certain behavior that is not covered by the regular update method. This method applies to CNAME, MX, and SRV records, and DNS/DHCP Servers.

Parameters Description
entity (APIEntity)

The actual API entity to update.
options (dict)

A dictionary containing the update options:

  • linkToExternalHost: a String value. If the value is ‘true’, it will search for the external host record specified in linkedRecordName even if a host record with the same exists under the same DNS View. If the external host record is not present, it will throw an exception. If the value is ‘false’, it will search for the host record specified in linkedRecordName.

  • disable: a String value. If the value is ‘true’, the DNS/DHCP Server is disabled. Disabling a server stops all deployments, DDNS updates, and services on that server. If the value is ‘false’, the server is enabled and restores the disabled server to normal operation.

  • resetControl: a String value. If the value is ‘true’, the DNS/DHCP Server is removed from Address Manager control. Once you have removed a DNS/DHCP Server from Address Manager control, you must replace the server from Address Manager to reconfigure it.

Example: 

from bluecat_libraries.address_manager.api import Client

# Updating CNAME, MX, and SRV records
options = {'linkToExternalHost': 'true'}
# Updating DNS/DHCP Servers
# options = {'disable': 'true', 'resetControl': 'true'}

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    entity = client.get_entity_by_id(<entity_id>)
    entity['name'] = 'new name'
    client.update_entity_with_options(entity, options)

Return type: None

New in version 21.5.1.

update_raw_deployment_option(option)

Update a raw deployment option.

Parameters Description
option (APIDeploymentOption)

The raw deployment option to update.
Note:

The type of the option must be one of the following values:

  • DNS_RAW

  • DHCP_RAW

  • DHCPV6_RAW

Note:

The value for key value is the raw option value. The maximum supported characters are 65,536. When given as a str it will be passed to the DNS or DHCP service on the managed server verbatim.

Note:

The value for name is ignored when working with raw deployment options. Even if it is set in the structure, it will not be changed.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.constants import ObjectType
from bluecat_libraries.address_manager.api.models import APIDeploymentOption

option = APIDeploymentOption(
    id=<entity_id>,
    type=ObjectType.DNS_RAW_OPTION,
    value="an-example-value",
    properties={
        "server": <server_id>,
        <udf_name>: <udf_value>,
    }
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_raw_deployment_option(option_id)

Return type: None

New in version 21.8.1.

update_retention_settings(settings=None)

Set the new value for history retention settings and return the existing values.

Parameters Description
settings (, optional)

The history retention settings.

Returns: RetentionSettings

Return type: RetentionSettings

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import RetentionSettings

# To get existing retention settings value
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    retention_settings = client.update_retention_settings()

# To update history retention settings which administrative history is 1(day),
session event history is 3(days), DDNS history is 2(days) and DHCP history is 2(days)
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    retention_settings = client.update_retention_settings(
        RetentionSettings(admin=1, sessionEvent=3, ddns=2, dhcp=2)
    )
print('Administrative retention history:', retention_settings['admin'])

New in version 21.5.1.

update_user_defined_field(object_type, udf)

Update a user-defined field for an object type.

Parameters Description
object_type (str)

The object type that the field is defined for.
udf (APIUserDefinedField)

The user-defined field to update.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import APIUserDefinedField
from bluecat_libraries.address_manager.constants import ObjectType, UserDefinedFieldType

udf = APIUserDefinedField(
    name="Unique UDF name",
    displayName="UDF display name",
    type=UserDefinedFieldType.TEXT,
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_user_defined_field(ObjectType.CONFIGURATION, udf)

Return type: None

New in version 21.5.1.

update_user_defined_link(definition)

Update a user-defined link for an object type.

Parameters Description
definition (UDLDefinition)

The user-defined link to update.

Example: 

from bluecat_libraries.address_manager.api import Client
from bluecat_libraries.address_manager.api.models import UDLDefinition
from bluecat_libraries.address_manager.constants import UserDefinedLinkEntityType

definition = UDLDefinition(
    linkType=<UniqueLinkTypeName>,
    displayName=<My Link Type>,
    description="My Link Type description",  # BAM 9.4.0 or greater
    sourceEntityTypes=[UserDefinedLinkEntityType.IP4_NETWORK],
    destinationEntityTypes=[
        UserDefinedLinkEntityType.IP4_NETWORK,
        UserDefinedLinkEntityType.IP4_BLOCK,
    ],
)

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_user_defined_link(definition)

Return type: None

New in version 21.5.1.

update_user_password(user_id, password, options=None)

Update an Address Manager user password. The user must be an Address Manager administrator to invoke this method.

Parameters Description
user_id (int)

The user ID of an application user who is either a primary or a secondary authenticator.
password (str)

The new password for the user. The password must be set even if the authenticator property option is defined.
options (list, optional)

Reserved for future use.

Example: 

from bluecat_libraries.address_manager.api import Client

user_id = <user_id>
password = 'ChooseApassword@123'
with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    client.update_user_password(user_id, password)

Return type: None

New in version 21.8.1.

upload_docker_image(server_id, file_name, data)

Upload a Docker image file to a BlueCat DNS/DHCP Server for configuration of the Gateway service via the configureServerServices method.

Parameters Description
server_id (int)

The object ID of the BlueCat DNS/DHCP Server.
file_name (str)

The name of the file to be uploaded.
data (IO)

The Docker image file to be uploaded. The file is passed to Address Manager as an octet-stream.

Note:

The Docker image file must be packaged in tar or tar.gz format.

Return type: str

Returns: The image name of the Docker image file.

Example: 

from bluecat_libraries.address_manager.api import Client

with Client(<bam_host_url>) as client, open("test_image.tar.gz", "rb") as file:
    client.login(<username>, <password>)
    image_name = client.upload_docker_image(<server_id>, 'test_image.tar.gz', file)
print(image_name)

New in version 23.1.0.

upload_response_policy_file(parent_id, data)

Upload one response policy file containing a list of fully qualified domain names (FQDNs).

Parameters Description
parent_id (int)

The object ID of the parent response policy under which the response policy item is being uploaded.
data (str, IO)

The file or a string to be uploaded under the response policy.

Note:

The size of the content should not be more than 75 MB.

Returns: An empty dictionary is returned when all rows in the input data were uploaded successfully. Otherwise, a dictionary containing the respective lines from the input data and the reason they were skipped.

Return type: dict

Example: 

from bluecat_libraries.address_manager.api import Client

# Upload response policy items where input data as an I/O stream.
with Client(<bam_host_url>) as client, open("test.txt", "rb") as file:
    client.login(<username>, <password>)
    result = client.upload_response_policy_file(<policy_id>, file)
print(result)

# Upload response policy items where input data as a string.
data = "www.example.com"

with Client(<bam_host_url>) as client:
    client.login(<username>, <password>)
    result = client.upload_response_policy_file(<policy_id>, data)
print(result)

New in version 21.11.1.