DNS Serv

Introduction

KisoLabs allows you to have more control over your zone than most other DNS providers. Your SOA record and TTLs for other records are fully customizable. If you're not sure what values would be appropriate for your zone, the defaults should work just fine!

SOA Record

The SOA (start of authority) record defines authoritative information about your zone. It is a required record for every zone, and its parameters are described below.

These values in the SOA record will have no functional impact on your zone: Serial, Refresh, Retry, and Expire. They are included in your zone configuration for compatibility and uniformity.

Parameter	Description
Serial	An integer that should increment with each change to the zone's configuration. By default, auto incrementing is enabled. Changing the serial along with any change to another zone record helps you to identify whether or not your DNS changes have propagated to public DNS servers. Serial must be an integer between 1 and 10 digits long. Note that the common use for the serial number is to facilitate zone transfers from master to slave DNS servers. KisoLabs' DNS infrastructure does not propagate zone changes using zone transfers, and so incrementing the serial is not strictly required, nor does it serve any technical purpose.
Primary NS	The Primary NS (name server) is set by default to the appropriate KisoLabs DNS server. You should not change this setting unless instructed to do so by KisoLabs' support team, or if you are very certain that changing it would be necessary. Primary NS must be a well-formed hostname or FQDN ending in a period (.).
Responsible Person	The email address of the person responsible for this zone and to which email may be sent to report errors or problems. This defaults to "hostmaster", which means that hostmaster@[Your Domain] will receive any such emails. Note that in this field, the at (@) symbol cannot be used, and a period (.) should be used in its place. Also, any email address not within the zone should end with a period (.). So, if you wanted emails for the responsible person to go to bob@foo.com, you would put the value bob.foo.com. in the responsible person field. Responsible Person must be in the format of a well-formed hostname or FQDN ending in a period (.).
Refresh Time	The interval (in seconds) at which a slave DNS server will attempt to refresh the zone from the master. This value is not used or acknowledged by the KisoLabs DNS infrastructure, and will be ignored. It is included for compatibility. Refresh time must be an integer between 3 and 6 digits long.
Retry Time	The interval (in seconds) at which a slave DNS server will attempt to retry a refresh of the zone from the master. This value is not used or acknowledged by the KisoLabs DNS infrastructure, and will be ignored. It is included for compatibility. Retry time must be an integer between 3 and 6 digits long.
Expire Time	The time (in seconds) after which the zone data is no longer authoritative on slave servers. This value is not used or acknowledged by the KisoLabs DNS infrastructure, and will be ignored. It is included for compatibility. Expire time must be an integer between 3 and 6 digits long.
Minimum TTL	The minimum TTL (time-to-live) is the default TTL (in seconds) for all records in the zone that have unspecified TTLs, and it tells other DNS servers how long they should keep the data in their cache. Note that this value is used differently by some types of DNS servers. Minimum TTL must be an integer between 3 and 6 digits long.

Other Record Types

KisoLabs supports a wide variety of resource records types. They are selectable under "Record Type", and the most common record types are listed first: A, CNAME, MX, NS, TXT, and AAAA.

All record types require the "Host" and "Data" fields be filled in, and acceptable values for data differ for each record type.

The Host Field

There are four general values that may be used in the host field:

Value	Description
@	The at (@) symbol indicates that the record is applicable at the zone level. For example, if you wanted your website to be accessible at www.foo.com and foo.com you would create an A record with @ in the name field and the IP address of your web server in the data field.
blank	If you leave the name field blank, it is equivalent to using the at (@) symbol. Upon saving your zone, any blank name fields will be replaced with @.
host[.subdomain[.subdomain]...]	Any value you put in the name field will be interpreted as a named resource within your zone. For example, if you were configuring an A record for the zone foo.com and you set a the name to "bar", then the host would be accessible at bar.foo.com. "Subdomains" may also be specified in the name field. For example, if you set the name field to "www.admin.bar", you could access that record at www.admin.bar.foo.com.
FQDN.	You may also specify the FQDN (fully-qualified domain name) of a host within the name field. Any name ending in a period (.) will be interpreted as an FQDN. For example, if you were configuring an A record for the zone foo.com and you set a the name to "bar.foo.com." (note the period at the end), then the host would be accessible at bar.foo.com. Conversely, if you were to set the name field to "bar.foo.com" (note the lack of a period on the end), then the host would be accessible at bar.foo.com.foo.com because the DNS server would not treat the name as a FQDN.
*[.subdomain[.subdomain]...]	You may use wildcard host names with KisoLabs' DNS services. The asterisk (*) symbol indicates that any valid name may apply to it. For example, if you were configuring an A record for the zone foo.com and you set a the name to "*", then the host would be accessible at bar.foo.com, www.foo.com, mail.foo.com, and any other valid hostname under foo.com. Important: If you set a name to "*" and another name to (for example) "www" for the same record type and those records have different values in the data field, there will be a conflict. When www is requested from your zone, one DNS server may return the data for the record with the name "www", whereas another DNS server may respond with the data for the record with the name "*". Avoid using a wildcard at the same domain/subdomain level within your zone!

Additional Data

The additional data column will remain blank unless additional data is required for a particular record type. For example, if the MX record type is selected, the priority field will be displayed under additional data.

The DNS API

Our DNS Serv Pro service supports the manipulation of DNS records via an API. The API consists of an HTTP POST containing a payload of data in JSON or XML format. Returned data will be in the same format as the request.

DNS records can be added, modified, or removed both on the KisoLabs website and via the API. The API is accessed at the following URL:

https://api-dns.kisolabs.net/dns/records[?f=json|xml]

The DNS records API can be accessed via plain-text HTTP by using http:// in place of https://, however it is not recommended for security reasons.

The query string parameter supplied with the url, f=json|xml, specifies the format of the request. This parameter is optional, however if it is not given then the first character of the HTTP content must be { for JSON or < for XML.

Common request parameters

All calls to the API must include the following two parameters:

Parameter	Name	Type
s_guid	Service GUID	GUID1	This is the GUID provided to you when configuring your DNS service.
act	Action	string	The action to be performed: lst - Lists all DNS records. get - Get a specific DNS record. set - Add or change a DNS record. del - Delete a DNS record.

¹ A GUID must be a 42 character hexadecimal string. The GUID is not case sensitive.

All responses from the API will include the following two parameters:

Parameter	Name	Type
s	Status	integer	The status of the API call: 100 - Success 150 - General failure 155 - Invalid request 160 - No account (invalid service GUID) 170 - Invalid record id 180 - Invalid record data
s_c	Readable Status	string	The status of the API call in human-readable format.

For each action, additional parameters may be required. Those parameters are described below for each action.

When responses are formatted as JSON, DNS record fields are grouped as objects in an array named records.

When responses are formatted as XML, DNS record fields are grouped within <record /> tags under the parent tag <records />.

Action: lst

Request parameters

Parameter	Name	Type
The list action has no additional parameters.

Response fields

Parameter	Name	Type
id	Identifier	integer	The identifier of the DNS record.
host	Host	string	The host field of the DNS record.
type	Record Type	string	Any valid DNS record type (e.g. A, CNAME, MX, etc.)
data	Data	string	The data field of the DNS record (e.g. 1.2.3.4).
ttl	Time to Live	integer	The TTL of the record (in seconds).
mx_priority	MX Priority	integer (optional)	The mail exchanger priority of the record. Only returned for MX records.
Other Fields	-	-	If the SOA record is requested, the following fields will be returned: serial, primary_ns, resp_person, refresh, retry, expire, ttl, minimum It is unlikely that these fields are significant to your zone's configuration. For more details on these fields and how KisoLabs uses them, see the section on the SOA Record.

Sample Request

JSON | XML

Sample Response (Assuming the zone contains a NS record and an A record)

JSON | XML

Action: get

Request parameter

Parameter	Name	Type
id	Identifier	integer	The identifier of a DNS record. The id can be obtained from a lst or set API call.

Response fields

Parameter	Name	Type
id	Identifier	integer	The identifier of the DNS record.
host	Host	string	The host field of the DNS record.
type	Record Type	string	Any valid DNS record type (e.g. A, CNAME, MX, etc.)
data	Data	string	The data field of the DNS record (e.g. 1.2.3.4).
ttl	Time to Live	integer	The TTL of the record (in seconds).
mx_priority	MX Priority	integer (optional)	The mail exchanger priority of the record. Only returned for MX records.
Other Fields	-	-	If the SOA record is requested, the following fields will be returned: serial, primary_ns, resp_person, refresh, retry, expire, ttl, minimum It is unlikely that these fields are significant to your zone's configuration. For more details on these fields and how KisoLabs uses them, see the section on the SOA Record.

Sample Request

JSON | XML

Sample Response (Assuming an A record was requested)

JSON | XML

Action: set

Request parameters

Parameter	Name	Type
id	Identifier	integer (optional)	The identifier of the DNS record. To create a new DNS record, this field may be omitted or set to 0 (zero).
host	Host	string	The host field of the DNS record. For more information on how to properly format the host field, see the section on the Host Field.
type	Record Type	string (case-insensitive)	Any valid DNS record type (e.g. A, CNAME, MX, etc.)
data	Data	string	The data field of the DNS record. Depending upon the record type, this may be an IP address, a host name, a FQDN (ending in a period), a Dynamo DNS Token, or another string relevant to the record type.
ttl	Time to Live	integer	The TTL of the record in seconds (must be between 100 and 999999).
mx_priority	MX Priority	integer (optional)	The mail exchanger priority of the record. If not provided when setting an MX record, it will default to 0 (zero).
Other Fields	-	-	If the SOA record is being set, the following fields are required: serial, primary_ns, resp_person, refresh, retry, expire, ttl, minimum It is unlikely that these fields are significant to your zone's configuration. For more details on these fields and how KisoLabs uses them, see the section on The SOA Record.

Response fields

Parameter	Name	Type
id	Identifier	integer	The identifier of the DNS record. If the request updated an existing record, id will be the same as the id submitted in the request. If the request created a record, id will be the identifier of the new record.
errors	Errors	mixed (optional)	An array (for JSON) or group of elements (for XML) of error fields and associated error messages. This is only returned during error condition 180 (invalid DNS data). Each field that failed validation will be enumerated, along with an error message describing the problem.

Sample Request

JSON | XML

Sample Response

JSON | XML

Action: del

Request parameters

Parameter	Name	Type
id	Identifier	integer (optional)	The identifier of the DNS record.
restore	Restore Flag	integer (optional)	Set this to 1 (one) to restore a DNS record that has been deleted. Any other value will be ignored and the record referenced will be deleted.

Response fields

Parameter	Name	Type
No additional response fields are returned.

Sample Request

JSON | XML

Sample Response

JSON | XML