.. meta:: :description: This documentation will guide you through the use of the Memset API. .. index:: double: Methods; dns .. _dns: DNS Methods ----------- API for DNS This provides an API for the Memset DNS (Domain Name Service). The Memset DNS API has three main objects * A zone domain * A zone record * A zone A zone is composed of a number of zone domains and a number of zone records. The zone domains specify which domains the nameservers will return this zone for, and the zone records specify which records are returned. Zone records are usually relative, which means that they have the zone domain appended to them. If you make a zone record with `name` or `www` and a domain of `example.com` then the record will be served for queries matching `www.example.com`. If you were to add `example.co.uk` to the zone domains for this zone then `www.example.co.uk` would be served with the same value. Zone records are relative if the relative flag is `True`. If the relative flag is `False` and the name contains dots, then they are treated as absolute, otherwise they are treated as relative. For example if you make a zone record with name `www.example.com` it will be served under any domain as `www.example.com`, however if you set the relative flag to `True` it will be served under the domain specified. The relative flag is essential if you want to host zones under multiple domains where part of the name contains dots, e.g. if name was `a.www` and domain was `example.com` then you would need to set the relative flag in the zone record if you wanted it served as `a.www.example.com` rather than `a.www`. .. function:: dns.reload Reloads the name servers with recent changes. Running this will ensure that the current state of your DNS records is synced with your DNS server. DNS records are pushed out the the server every 15 minutes normally, but running this will speed up the process. You may poll the job returned to discover when this has been done. We don't guarantee any particular timescale for this, but normally it will only take a few seconds. :returns: A dictionary as described in :func:`job.status`. .. function:: dns.reverse_map_list Query the reverse maps for all servers, or a single server if name is supplied, or a single address if address is supplied. If name and address are supplied then it will only show address if it is attached to that server. :param name: Name of the server. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters. :type name: String, Optional :param address: The IPv4 or IPv6 address to list. Ensure this value has at most 250 characters. :type address: String, Optional :returns: a list of dictionary with the following keys: **name** String: Which server name this is attached to **address** String: IPv4 or IPv6 address **reverse_map** String: what this IP address reverse maps to .. function:: dns.reverse_map_update Updates a reverse map. If name is supplied then it checks that address is attached to that server before updating it. :param name: Name of the server. Service names are 1-64 characters A-Z, a-z, 0-9, -, . and _. Ensure this value has at most 64 characters. :type name: String, Optional :param address: The IPv4 or IPv6 address to change the reverse map for. Ensure this value has at most 250 characters. :type address: String :param reverse_map: The name this IP address reverse maps to. Must be a valid hostname. Ensure this value has at most 250 characters. :type reverse_map: String :returns: a list of dictionaries as described in :func:`dns.reverse_map_list`. .. function:: dns.zone_create Create a zone, optionally providing records and domains. :param nickname: A customer specified name for the zone file. Not guaranteed unique. Ensure this value has at most 250 characters. :type nickname: String :param ttl: Time to live - 0 for use this zone's default TTL. Acceptable values 0 Default 300 5 minutes 600 10 minutes 900 15 minutes 1800 30 minutes 3600 1 hour 7200 2 hours 10800 3 hours 21600 6 hours 43200 12 hours 86400 24 hours :type ttl: Integer, Optional :param records: A List of Dictionaries describing zone records to create as described in :func:`dns.zone_record_create`. Note that the dictionaries shouldn't include the ``zone_id`` parameter as this will be automatically inserted. :type records: List, Optional :param domains: A List of Dictionaries describing zone domains to create as described in :func:`dns.zone_domain_create`. Note that the dictionaries shouldn't include the ``zone_id`` parameter as this will be automatically inserted. :type domains: List, Optional :returns: a dictionary with information about the created zone as decribed in :func:`dns.zone_info`. .. function:: dns.zone_delete Deletes a zone **NB** this will delete any zone records and zone domains that are part of this zone. :param id: The Zone ID. Zone IDs are 32 hex digits. :type id: String :returns: a dictionary with zone in before it was deleted as returned by :func:`dns.zone_info` .. function:: dns.zone_domain_create Create a zone domain. :param domain: The zone domain name. Ensure this value has at most 250 characters. :type domain: String :param zone_id: The Zone ID. Zone IDs are 32 hex digits. :type zone_id: String, Optional :returns: a dictionary containing the contents of the zone domain after addition as described in :func:`dns.zone_domain_info`. .. function:: dns.zone_domain_delete Deletes the zone domain :param domain: The zone domain name. Ensure this value has at most 250 characters. :type domain: String :returns: a dictionary containing the contents of the zone domain before it was deleted as described in :func:`dns.zone_domain_info`. .. function:: dns.zone_domain_info Info about a zone domain :param domain: The zone domain name. Ensure this value has at most 250 characters. :type domain: String :returns: a dictionary with the following keys **domain** String: The domain name in question, e.g. 'example.com' **zone_id** String, Optional: zone id (32 hex digits) that this domain is part of. If it isn't present then this domain is not part of a zone, or part of a zone you can't change. .. function:: dns.zone_domain_list Returns all the zone domains for this account :returns: list of dictionaries as described in :func:`dns.zone_domain_info`. .. function:: dns.zone_domain_update Updates the zone domain. :param domain: The zone domain name. Ensure this value has at most 250 characters. :type domain: String :param zone_id: The Zone ID. Zone IDs are 32 hex digits. :type zone_id: String, Optional :returns: a dictionary containing the contents of the zone domain after addition as described in :func:`dns.zone_domain_info`. .. function:: dns.zone_info Info about a zone :param id: The Zone ID. Zone IDs are 32 hex digits. :type id: String :returns: a dictionary with the following keys **id** String: zone id (32 hex digits). **nickname** String: your name for this zone **ttl** Integer: the default TTL for records in this zone in seconds, 0 means use Memset default of 1800 seconds. **records** List: a list of dictionaries describing zone records that are used in this zone :func:`dns.zone_record_info`. **domains** List: a list of dictionaries describing zone domains that are used for this zone see :func:`dns.zone_domain_info`. .. function:: dns.zone_list Lists all the zones in this account :returns: a list of dictionaries as described in :func:`zone_info` .. function:: dns.zone_record_create Create a zone record in the zone supplied :param zone_id: The Zone ID. Zone IDs are 32 hex digits. :type zone_id: String :param type: Domain record type, e.g. 'A'. Acceptable values: 'A', 'AAAA', 'CNAME', 'MX', 'NS', 'SRV', 'TXT'. :type type: String :param record: Name of record, e.g. 'www'. Use the empty string '' to create a record for the domain itself. Must be a valid zone record name. Ensure this value has at most 250 characters. :type record: String, Optional :param address: Address of record, e.g. '1.2.3.4'. Only printable ASCII characters are allowed. Ensure this value has at most 250 characters. :type address: String :param ttl: Time to live - 0 for use this zone's default TTL. Acceptable values 0 Default 300 5 minutes 600 10 minutes 900 15 minutes 1800 30 minutes 3600 1 hour 7200 2 hours 10800 3 hours 21600 6 hours 43200 12 hours 86400 24 hours :type ttl: Integer, Optional :param priority: Priority for MX and SRV records, eg 10. Ensure this value is greater than or equal to 0. Ensure this value is less than or equal to 999. :type priority: Integer, Optional :param relative: If set then we add the current domain onto the address field for CNAME, MX, NS and SRV record types. :type relative: Boolean, Optional :returns: a dictionary with the zone record in as described in :func:`dns.zone_record_info` .. function:: dns.zone_record_delete Delete a zone record :param id: The Zone Record ID. Zone Record IDs are 32 hex digits. :type id: String :returns: the zone record information before it was deleted as a dictionary as described in :func:`dns.zone_record_info`. .. function:: dns.zone_record_info Info about a zone record :param id: The Zone Record ID. Zone Record IDs are 32 hex digits. :type id: String :returns: a dictionary with the following keys **id** String: id (32 hex digits) of this zone record **zone_id** String: zone id (32 hex digits) that this zone record is part of. **type** String: Domain record type: 'A', 'AAAA', 'CNAME', 'MX', 'NS', 'SRV', 'TXT' **record** String: Name of record, e.g. 'www' **address** String: Address of record, e.g. '1.2.3.4' **ttl** Integer: Time to live - 0 for use this zone's default TTL **priority** Integer: Priority for MX and SRV records, e.g. 10, not used for other record types **relative** Boolean: If true we never assume the `name` is absolute. Normally if the `name` does not contain any dots we assume it is relative to the current domain. The domain is added for CNAME, MX, NS and SRV record types which are deemed to be relative. .. function:: dns.zone_record_list Returns all the zone records for this account :returns: list of dictionaries as described in :func:`dns.zone_record_info`. .. function:: dns.zone_record_update Update a zone record. Supply any parameters you want updated. :param id: The Zone Record ID. Zone Record IDs are 32 hex digits. :type id: String :param zone_id: The Zone ID. Zone IDs are 32 hex digits. :type zone_id: String, Optional :param type: Domain record type, e.g. 'A'. Acceptable values: 'A', 'AAAA', 'CNAME', 'MX', 'NS', 'SRV', 'TXT'. :type type: String, Optional :param record: Name of record, e.g. 'www'. Use the empty string '' to create a record for the domain itself. Must be a valid zone record name. Ensure this value has at most 250 characters. :type record: String, Optional :param address: Address of record, eg '1.2.3.4'. Only printable ASCII characters are allowed. Ensure this value has at most 250 characters. :type address: String, Optional :param ttl: Time to live - 0 for use this zone's default TTL. Acceptable values 0 Default 300 5 minutes 600 10 minutes 900 15 minutes 1800 30 minutes 3600 1 hour 7200 2 hours 10800 3 hours 21600 6 hours 43200 12 hours 86400 24 hours :type ttl: Integer, Optional :param priority: Priority for MX and SRV records, e.g. 10. Ensure this value is greater than or equal to 0. Ensure this value is less than or equal to 999. :type priority: Integer, Optional :param relative: If set then we add the current domain onto the address field for CNAME, MX, NS and SRV record types. :type relative: Boolean, Optional :returns: a dictionary with the zone record in as described in :func:`dns.zone_record_info` .. function:: dns.zone_update Modifies a zone Any parameters passed in will be used to update the zone. If you want to create, update or delete zone records and zone domains then use the zone_record and zone_domain methods with the ``zone_id`` parameter. :param id: The Zone ID. Zone IDs are 32 hex digits. :type id: String :param nickname: A customer specified name for the zone file. Not guaranteed unique. Ensure this value has at most 250 characters. :type nickname: String, Optional :param ttl: Time to live - 0 for use this zone's default TTL. Acceptable values 0 Default 300 5 minutes 600 10 minutes 900 15 minutes 1800 30 minutes 3600 1 hour 7200 2 hours 10800 3 hours 21600 6 hours 43200 12 hours 86400 24 hours :type ttl: Integer, Optional :returns: a dictionary with zone in after modification as returned by :func:`dns.zone_info`.