Configure the DNS of your Domain Name

Table of Contents

• Introduction
• Order a Domain Name
• Tasks Management
• Manage Contacts of a Domain Name
• Managing Eligibility Rules
• Configure the Display of Contact Data in the Whois
• Configure the DNS of your Domain Name
• Transfer a Domain Name

We remind you that the given API routes links lead to European API. Do not forget to replace https://eu.api.ovh.com with https://ca.api.ovh.com in API URLs to use it with your identifier.

Introduction

This page describes the information related to the DNS resolution of domain names. This includes:

• the name servers declaration;
• glue records.

DNS Setup Types

On a domain name, DNS setup type can be either hosted or external.

The hosted type means that the DNS zone is managed automatically by OVHcloud, which means that you don't have to create your own name server. Of course, you have control over the content of this zone, but the choice of servers on which the zone is hosted cannot be modified. In return, OVHcloud will take care of the declaration of these servers to the registry and manage the DNSSEC.

Retrieve the DNS Setup Type of a Domain Name

Using the following API will allow you to retrieve the name server type defined on your domain name:

{
  "parentService": null,
  "domain": "test.com",
  "offer": "gold",
  "dnssecSupported": true,
  "owoSupported": true,
  "transferLockStatus": "locked",
  "whoisOwner": "123456",
  "hostSupported": true,
  "glueRecordIpv6Supported": true,
  "glueRecordMultiIpSupported": true,
  "lastUpdate": "2021-11-02T12:01:13+01:00",
  "nameServerType": "hosted"
}

As we can see from the example above, the DNS setup type can be retrieved in the field nameServerType.

We can also see from the hostSupported field, that the hosts are supported as entities by the domain name registry. This will be important later on, if you decide to declare glue records on your domain name.

Update the Domain Name DNS Setup Type

The following API allows to update some domain name setup, including the name server type.

{
  "nameServerType": "external" // (hosted or external)
}

As we can see from the example above, the DNS configuration type has been changed to external.

It is important to know that:

• To change from external to hosted, you need to have a DNS zone at OVHcloud to make the change. It is possible to order one on your OVHcloud Control Panel.
• To change from hosted to external, you first have to do the modification, and then change the name servers declaration of the domain name as explained in the following section.

Name Servers Declaration

When the nameServerType of a domain name is external, it is necessary to set up the name servers on the registry, in order to resolve them. If the nameServerType is hosted, it is possible to check the name servers declared on a domain name thanks to the GET APIs below.

Be careful, however, not to confuse the declaration of name servers with the management of DNS zones. The management of your OVHcloud zones must be done using the route:

Retrieve the Name Servers Declared on a Domain Name

Using the following API will allow you to retrieve the IDs of the name servers defined on a domain name:

[
  33578504,
  33578505
]

As we can see from the example above, this call will only retrieve the identifiers corresponding to the DNS servers declared on a domain name.

To get the details of a name server, you need to call the following API:

{
  "id": 33578504,
  "host": "ns16.ovh.net",
  "ip": null,
  "isUsed": true,
  "toDelete": false
}

This call allows to get the technical details of the name server, like the host or the associated ip if it is a glue record (cf. glue records declaration). More information is also available through the following API:

{
  "state": "ok",
  "type": "hosted",
  "usedSince": "2021-11-02T11:59:13.177558+01:00"
}

Modify the Name Servers Declared on a Domain Name

As a reminder, you can only change the declaration of your name servers if the nameServerType of the domain name is external. If it is the case, there are several APIs available which we describe in this section.

The following API allows you to add new name servers on your domain name:

{
  "nameServer": [
    {
      // When a registry like eurid (.eu) doesn't support hosts, we declare the glue records directly here
      "host": "ns1.test.eu",
      "ip": "140.2.113.151"
    },
    {
      "host": "ns1.other-domain.eu"
    }
  ]
}

{
  "id": 414283125,
  "status": "todo",
  "function": "DomainDnsUpdate",
  "creationDate": "2022-04-07T15:56:01.593746+02:00",
  "todoDate": "2022-04-07T15:56:01+02:00",
  "lastUpdate": "2022-04-07T15:56:01+02:00",
  "doneDate": null,
  "canRelaunch": false,
  "canAccelerate": false,
  "canCancel": true
}

This route will add the new name servers on the domain name and trigger a DomainDnsUpdate synchronisation task on the registry side. You will be able to track this task via the dedicated APIs.

It is also possible to completely replace the name servers declaration of a domain name through the following API:

{
  "nameServer": [
    { "host": "ns1.other-domain.com" },
    { "host": "ns2.other-domain.com" }
  ]
}

{
  "id": 414283126,
  "status": "todo",
  "function": "DomainDnsUpdate",
  "creationDate": "2022-04-07T15:56:01.593746+02:00",
  "todoDate": "2022-04-07T15:56:01+02:00",
  "lastUpdate": "2022-04-07T15:56:01+02:00",
  "doneDate": null,
  "canRelaunch": false,
  "canAccelerate": false,
  "canCancel": true
}

This route will replace the name servers declaration on the domain name and, as the previous route, trigger a DomainDnsUpdate synchronisation task with the registry. You will be able to track this task via the dedicated APIs.

It is also possible to delete a name server declared on a domain name through the following API:

{
  "id": 414283127,
  "status": "todo",
  "function": "DomainDnsUpdate",
  "creationDate": "2022-04-07T15:56:01.593746+02:00",
  "todoDate": "2022-04-07T15:56:01+02:00",
  "lastUpdate": "2022-04-07T15:56:01+02:00",
  "doneDate": null,
  "canRelaunch": false,
  "canAccelerate": false,
  "canCancel": true
}

This route will delete the name server declared on your domain name and trigger a DomainDnsUpdate update task on the registry. You will be able to track this task via the dedicated APIs.

Glue Records Declaration

A glue record is used to define the IP address of a name server, to allow the domain name to be resolved if this one uses name servers hosted under this same domain name.

For instance, if you want to declare the name server ns1.test.com on the domain name test.com, an IP must be provided to the registry so that the resolution does not loop. If no IP was provided, during test.com DNS resolution, the DNS resolver would try to resolve the ns1.test.com name server by fetching the resolution from test.com, creating an infinite resolution loop.

There are two ways to manage glue records declared on a domain name. Depending on the registry, the glue records can be:

• declared via dedicated host objects, used as entities in their own right. In this case, it will be necessary to use the APIs dedicated to glue records.

  DELETE /domain/{serviceName}/nameServer/{id}

• declared together with the name servers by providing an IP. In this case you will have to use the name server APIs.

  DELETE /domain/{serviceName}/nameServer/{id}

To know which APIs to use, it is necessary to retrieve the information via the DNS setup of the domain name, in the hostSupported field.

Retrieve the Glue Records Declared on a Domain Name

If the hostSupported field of the DNS setup of the domain name is set to false, the data retrieving will be done via the name servers APIs described above.

If the hostSupported field of the DNS setup of the domain name is set to true, you will be able to modify the hosts declared on a domain name via the following APIs:

[
  "ns1.test.com",
  "ns2.test.com"
]

To get the details of a glue record, you will have to retrieve the host and use the following API:

{
  "host": "ns1.test.com",
  "ips": [
      "140.2.113.151"
  ]
}

Modify the Glue Records Declared on a Domain Name

If the hostSupported field of the DNS setup of the domain name is set to false, data is fetched and updated via the name servers APIs described above.

If the hostSupported field of the DNS setup of the domain name is set to true, it is possible to handle the hosts declared on a domain name via the glue records dedicated APIs.

Create a New Glue Record

The following API allows you to add a glue record on your domain name:

{
  "host": "ns1.test.com",
  "ips": [
    "140.2.113.151"
  ]
}

{
  "id": 414283128,
  "status": "todo",
  "function": "DomainHostCreate",
  "creationDate": "2022-04-07T15:56:01.593746+02:00",
  "todoDate": "2022-04-07T15:56:01+02:00",
  "lastUpdate": "2022-04-07T15:56:01+02:00",
  "doneDate": null,
  "canRelaunch": false,
  "canAccelerate": false,
  "canCancel": true
}

This route will trigger a DomainHostCreate task to create the host on the domain name registry. You will be able to track this task via the dedicated APIs.

Update an Existing Glue Record

It is also possible to update a glue record through the following API:

{
  "host": "ns1.test.`com",
  "ips": [
    "140.2.113.152"
  ]
}

{
  "id": 414283129,
  "status": "todo",
  "function": "DomainHostUpdate",
  "creationDate": "2022-04-07T15:56:01.593746+02:00",
  "todoDate": "2022-04-07T15:56:01+02:00",
  "lastUpdate": "2022-04-07T15:56:01+02:00",
  "doneDate": null,
  "canRelaunch": false,
  "canAccelerate": false,
  "canCancel": true
}

This route will trigger a DomainHostUpdate task to modify the host on the domain name registry. You will be able to track this task via the dedicated APIs, and you will not have to re-declare the name server on the domain name.

Delete an Existing Glue Record

It is also possible to delete a glue record, but you will have to remove the host from the domain name first, using the name servers APIs.

Then you can call the following API to delete the glue record:

{
  "id": 414283130,
  "status": "todo",
  "function": "DomainHostDelete",
  "creationDate": "2022-04-07T15:56:01.593746+02:00",
  "todoDate": "2022-04-07T15:56:01+02:00",
  "lastUpdate": "2022-04-07T15:56:01+02:00",
  "doneDate": null,
  "canRelaunch": false,
  "canAccelerate": false,
  "canCancel": true
}

This route will trigger a DomainHostDelete task to delete the host on the domain name registry. You will be able to track this task via the dedicated APIs.