Dynamic DNS

The Dynamic DNS service provides a unified, federation-wide Dynamic DNS support for VMs in EGI infrastructure. Users can register their chosen meaningful and memorable DNS hostnames in given domains (e.g. my-server.vo.fedcloud.eu) and assign to public IPs of their servers.

By using Dynamic DNS, users can host services in EGI Cloud with their meaningful service names, can freely move VMs from sites to sites without modifying server/client configurations (federated approach), can request valid server certificates in advance (critical for security) and many other advantages.

A short demonstration video is available at fedcloud.eu YouTube channel.

Dynamic DNS GUI portal

The Dynamic DNS offers a web GUI portal where users can login using their Check-in credentials. For doing so, click on the Login link (top left) and then click on the egi button.

Once logged in, you will be presented with the following page:

To register a new DNS host name:

1. Click on Overview and then on Add Host.

2. Type in the hostname you’d like to register and select the domain to use.

   

3. The portal will then show you a secret than can be used for updating the host ip whenever needed. Note it down so you can use it later.

4. From the VM you’d like to assign the name to, run a command like follows:

   curl "https://<hostname>:<secret>@nsupdate.fedcloud.eu/nic/update"
   

   where <hostname> is the full hostname generated before, e.g. myserver.fedcloud-tf.fedcloud.eu and <secret> is the secret generated in the previous step. You can add that as a boot command in your cloud-init configuration:

   #cloud-config
   
   runcmd:
     - [curl, "https://<hostname>:<secret>@nsupdate.fedcloud.eu/nic/update"]
   

5. You can also manually edit your registered hostnames in the Overview menu by clicking on the hostname you’d like to manage

Dynamic DNS support in Infrastructure Manager

Infrastructure Manager (IM) automatically creates hostname and assign the correct public IP of the head node of your infrastructure in the Dynamic DNS. Just fill in the DNS name to be used for the VM or DNS name to set to the Kubernetes Front-end (other infrastructures may have similar names for this field) with a FQDN within the supported domains of the Dynamic DNS:

IM will take care of registering the hostname, assigning the IP and eventually removing the hostname once the infrastructure is destroyed.

Wildcard hosts

For certain use cases, it is desirable for all hosts within a specific subdomain to resolve to the same IP address. For example, if the head node of a Kubernetes cluster is accessible at kubernetes.fedcloud.eu, all services within the cluster can share the same IP and be represented using a wildcard entry *.kubernetes.fedcloud.eu, where * stands for any of the services; e.g. dashboard.kubernetes.fedcloud.eu, api.kubernetes.fedcloud.eu, app1.kubernetes.fedcloud.eu. In such setup, request routing is handled internally by the cluster, typically through an Ingress or Gateway resource.

This kind of names can be registered using the API calls as described below.

API

The API is accessible via the API_BASE_URL endpoint (e.g. https://nsupdate.fedcloud.eu) and exposes several endpoints for domain management and related operations.

Authorization

All API requests require a valid ACCESS_TOKEN. This token must be included in the HTTP request Authorization header using the Bearer scheme for authentication.

List domains

Retrieves all private domains owned by the authenticated user, as well as all available public domains.

Endpoint

GET {{API_BASE_URL}}/nic/domains
Authorization: Bearer {{ACCESS_TOKEN}}

Response

Returns a JSON object containing two arrays:

• private — Domains owned by the requesting user.
• public — Public domains available for use.

Sample response

{
  "status": "ok",
  "private": [],
  "public": [
    {
      "name": "cloud.ai4eosc.eu",
      "public": true,
      "available": true,
      "comment": "Domain for stable services in AI4EOSC project",
      "owner": "viet02"
    },
    {
      "name": "cloud.eosc-siesta.eu",
      "public": true,
      "available": true,
      "comment": "Domain for production services in EOSC-SIESTA project",
      "owner": "root"
    }
  ]
}

Domain Fields Description

Each domain object (private or public) includes the following fields:

Register Host

This endpoint registers a host in the specified domain, optionally setting a wildcard and adding a comment. The response confirms whether the registration was successful or if an error occurred.

Endpoint

Option 1

GET {{API_BASE_URL}}/nic/register?fqdn={{HOSTNAME}}&ip={{IP}}&wildcard={{WILDCARD}}&comment={{COMMENT}}
Authorization: Bearer {{ACCESS_TOKEN}}

Parameters

Option 2

GET {{API_BASE_URL}}/nic/register?name={{NAME}}&domain={{DOMAIN}}&ip={{IP}}&wildcard={{WILDCARD}}&comment={{COMMENT}}
Authorization: Bearer {{ACCESS_TOKEN}}

Parameters

Sample Response

{
  "status": "ok",
  "message": "Host registered.",
  "host": {
    "fqdn": "test.vm.fedcloud.eu",
    "name": "test",
    "domain": "vm.fedcloud.eu",
    "wildcard": false,
    "comment": "test",
    "available": true,
    "client_faults": 0,
    "server_faults": 0,
    "abuse_blocked": false,
    "abuse": false,
    "last_update_ipv4": "2025-10-13T11:24:51.165433+00:00",
    "tls_update_ipv4": false,
    "ipv4": "10.10.0.253",
    "last_update_ipv6": null,
    "tls_update_ipv6": false,
    "ipv6": null,
    "update_secret": "some_secret",
    "IPv4_update_url_basic_auth": "https://test.vm.fedcloud.eu:some_secret@nsupdate.fedcloud.eu/nic/update",
    "IPv4_update_url_bearer_auth": "https://nsupdate.fedcloud.eu/nic/update?hostname=test.vm.fedcloud.eu&myip=${myip}"
  }
}

Response Fields

host Object

Update DNS record

The dynamic DNS update server uses the dyndns2 protocol, compatible with commercial providers such as dyn.com and noip.com, and allows clients to update the IP address of a registered host. In addition to Basic authentication using an update secret, this endpoint also supports authentication with the Bearer scheme for enhanced security.

Endpoint

Update using Bearer token authentication

GET {{API_BASE_URL}}/nic/update?hostname={{HOSTNAME}}&myip={{IP_ADDRESS}}
Authorization: Bearer {{ACCESS_TOKEN}}

Update using Basic authentication with update secret

GET {{API_BASE_URL}}/nic/update?hostname={{HOSTNAME}}&myip={{IP_ADDRESS}}
Authorization: Basic {{BASE64_ENCODED_AUTH_STRING}}

Creating Basic authentication secret

To create the Basic authentication token, encode FQDN of the target host and corresponding update secret using the Base64 encoding. To retrieve the update secret, use the /nic/generate_secret endpoint.

$ echo -n "${HOSTNAME}:${UPDATE_SECRET}" | base64 -
c3Rldm8tZ3B1Og==

Parameters

Sample response

HTTP/2 200 OK
(Headers) ...content-type: text/plain...

good 123.45.67.89

• The response body returns the status of the update followed by the current IP address assigned to the host.
• Example: good 123.45.67.89 indicates the update succeeded and the host now points to 123.45.67.89.

List Hosts

Retrieves all hosts registered by the authenticated user. Optionally, you can filter hosts by a specific domain.

Endpoint

GET {{API_BASE_URL}}/nic/hosts?domain={{DOMAIN}}
Authorization: Bearer {{ACCESS_TOKEN}}

Parameters

Sample response

{
  "status": "ok",
  "hosts": [
    {
      "fqdn": "myhost.cloud.ai4eosc.eu",
      "name": "myhost",
      "domain": "cloud.ai4eosc.eu",
      "wildcard": false,
      "comment": "comment",
      "available": true,
      "client_faults": 1,
      "server_faults": 0,
      "abuse_blocked": false,
      "abuse": false,
      "last_update_ipv4": "2025-04-10T10:33:06.930760+00:00",
      "tls_update_ipv4": false,
      "ipv4": "147.213.65.206",
      "last_update_ipv6": "2025-04-10T10:21:57.975176+00:00",
      "tls_update_ipv6": false,
      "ipv6": null
    }
  ]
}

Response Fields

hosts Object

Unregister Host

Removes a previously registered host from the specified domain. The response confirms whether the unregistration was successful or if an error occurred.

Endpoint

Option 1

GET {{API_BASE_URL}}/nic/unregister?fqdn={{HOSTNAME}}
Authorization: Bearer {{ACCESS_TOKEN}}

Parameters

Option 2

GET {{API_BASE_URL}}/nic/unregister?name={{NAME}}&domain={{DOMAIN}}
Authorization: Bearer {{ACCESS_TOKEN}}

Parameters

Sample response

{
  "status": "ok",
  "message": "Host unregistered.",
  "host": {
    "fqdn": "test.vm.fedcloud.eu",
    "name": "test",
    "domain": "vm.fedcloud.eu",
    "wildcard": false,
    "comment": "host for testing purposes"
  }
}

Response Fields

host Object

Generate update secret

Generates a new update secret for clients to update a registered host. The secret can be used for authenticated dynamic updates to the host’s IP records.

Endpoint

GET {{API_BASE_URL}}/nic/generate_secret?fqdn={{HOSTNAME}}
Authorization: Bearer {{ACCESS_TOKEN}}

Parameters

Sample response

{
  "status": "ok",
  "secret": "bMkzLXMr75"
}

Response Fields

Security

• For updating IP address, only hostname and its secret are needed. No user information is stored on VM in any form for updating IP.

• NS-update server uses HTTPS protocol, hostname/secret are encrypted as data and not visible during transfer so it is secure to use the update URL

• NS-update portal does not store host secret in recoverable form. If you forget the secret of your hostname, simply generate new one via “Show configuration” button in the host edit page. The old secret will be invalid.

Support

Support for Dynamic DNS service is provided via EGI Helpdesk “Dynamic DNS” support unit, where users can ask questions, report issues or make requests for additional domains for specific projects or user communities.