.. _user-host-entries-configuration-9ad4c060eb15:

=======================================
User-Defined Host Entries Configuration
=======================================

You can configure user-defined host entries for external resources. This
capability enables the configuration of local host records, supplementing
hosts resolvable by external |DNS| server(s).

.. only:: starlingx

   User-defined host entries can be configured at bootstrap time and/or
   post-deployment.

.. only:: partner

   .. include:: /_includes/user-host-entries-configuration-9ad4c060eb15.rest
      :start-after: host-entries-start
      :end-before: host-entries-end

The following methods are enabled to configure user host records/entries and
local |DNS| entries.

-  :ref:`Configure User-Defined Host Entries During Bootstrap <bootstrap-user-host-entries-configuration-9ad4c060eb15>`

-  :ref:`Configure User-Defined Host Entries via System Inventory API/CLI <CLI-user-host-entries-configuration-9ad4c060eb15>`

.. only:: partner

   .. include:: /_includes/user-host-entries-configuration-9ad4c060eb15.rest
      :start-after: deploy-manager-ref-start
      :end-before: deploy-manager-ref-end

-  :ref:`Configure User-Defined Local DNS Scope Entries <local-dns-entries-configuration-9ad4c060eb15>`

.. _bootstrap-user-host-entries-configuration-9ad4c060eb15:

Configure User-Defined Host Entries During Bootstrap
----------------------------------------------------

During the bootstrap phase, update the Ansible playbook override file,
``localhost.yaml <hostname.yaml>``, with the following data within the
``user_dns_host_records`` section.

To add host records, use the following command syntax:

.. code-block:: none

    user_dns_host_records:
      <host-record-name>: <fqdn>[,<fqdn>...],[<IPv4-address>],[<IPv6-address>][,<TTL>]

Where, |TTL| can be optionally provided and fqdn = fully qualified domain
name.

For example:

.. code-block:: none

    user_dns_host_records:
      test-server: example.com,192.168.0.1,1234::100,300
      host1: host,example2.com,127.0.0.1

.. note::

    Upon system initialization, you can observe that data has been updated
    within the system database, and it can be listed using the system CLI.

.. _CLI-user-host-entries-configuration-9ad4c060eb15:

Configure User-Defined Host Entries via System Inventory API/CLI
----------------------------------------------------------------

After system deployment, update host records using the CLI. Source the script
``/etc/platform/openrc`` to obtain administrative privileges and use the
following procedure:

.. rubric:: |proc|

#.  Use the following command syntax to add the parameter.

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-add dns host-record <host-record-name>=<fqdn>[,<fqdn>...],[<IPv4-address>],[<IPv6-address>][,<TTL>]
        ~(keystone_admin)]$ system service-parameter-apply dns

    Where fqdn = fully qualified domain name.

    For example:

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-add dns host-record test-server1=host1,testserver1.com,127.0.0.1

    .. image:: figures/add-parameter.png
         :width: 800

#.  Use the following command syntax to modify the parameter.

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-modify dns host-record <host-record-name>:<fqdn>[,<fqdn>...],[<IPv4-address>],[<IPv6-address>][,<TTL>]
        ~(keystone_admin)]$ system service-parameter-apply dns

    Where fqdn = fully qualified domain name.

    The following example shows the command syntax to add another |DNS| name
    for the existing host entry.

    Example:

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-modify dns host-record test-server1=host1,host,testserver1.com,127.0.0.1

    .. image:: figures/modify-parameter.png
         :width: 800

#.  Follow the steps below to delete the parameter.

    #.  Run the command to display the service parameter list for ``host-record
        service-parameter`` type.

        .. code-block:: none

            ~(keystone_admin)]$ system service-parameter-list | grep host-record

        Copy the |UUID| of the parameter that needs to be deleted.

    #.  Run the command to delete the entry.

        .. code-block:: none

            ~(keystone_admin)]$ system service-parameter-delete <uuid>

        For example:

        .. code-block:: none

            ~(keystone_admin)]$ system service-parameter-delete  a24e147f-2d13-4d7b-a8e7-47a1d77b95b5


.. _deployment_manager:

.. only:: partner

   .. include:: /_includes/user-host-entries-configuration-9ad4c060eb15.rest
      :start-after: deploy-manager-start
      :end-before: deploy-manager-end

.. _local-dns-entries-configuration-9ad4c060eb15:

Configure User-Defined Local DNS Scope Entries
----------------------------------------------

You can configure user-defined domain entries within the local |DNS| scope to
prevent DNS queries for those domains from being forwarded to external DNS
server(s) (i.e. ``nameservers`` in ``system dns-show/dns-modify``).

This capability enhances the ``User-Defined Host Entries Configuration``by
ensuring that resolution of these entries occurs strictly within the local DNS
scope (for example, resolving ``registry.central`` in subcloud environments).

This setup is especially beneficial for systems using a single IP stack
(either IPv4 or IPv6). If the system uses only IPv4 and receives |DNS| queries
for both IPv4 and IPv6 for ``registry.central``, ``dnsmasq`` can respond locally
with the IPv4 record and disregard the IPv6 query.

Without this configuration, IPv6 queries would be unnecessarily forwarded to
external |DNS| server(s), causing delays in resolution and impacting application
performance.

.. only:: starlingx

   User-defined DNS local scope entries can be configured post-deployment.

.. _CLI-local-dns-entries-configuration-9ad4c060eb15:

Configure User-Defined Local DNS Scope Entries via System Inventory API/CLI
***************************************************************************

After system deployment, update |DNS| local scope entries using the CLI. Source
the script ``/etc/platform/openrc`` to obtain administrative privileges and use
the following procedure:

.. rubric:: |proc|

#.  Use the following command syntax to add the parameter.

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-add dns local <local-scope-name>=<domain>
        ~(keystone_admin)]$ system service-parameter-apply dns

    Example:

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-add dns local test-domain=host.domain

    .. image:: figures/add-dns-local-parameter.png
         :width: 800

#.  Use the following command syntax to modify the parameter.

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-modify dns local <local-scope-name>=<new_domain>
        ~(keystone_admin)]$ system service-parameter-apply dns

    Example:

    .. code-block:: none

        ~(keystone_admin)]$ system service-parameter-modify dns local test-domain=host.domain2

    .. image:: figures/modify-dns-local-parameter.png
         :width: 800

#.  Follow the steps below to delete the parameter.

    #.  Run the command to display the service parameter list for ``dns local
        service-parameter`` type.

        .. code-block:: none

            ~(keystone_admin)]$ system service-parameter-list | grep local

        Copy the |UUID| of the parameter that needs to be deleted.

    #.  Run the command to delete the entry.

        .. code-block:: none

            ~(keystone_admin)]$ system service-parameter-delete <uuid>

        For example:

        .. code-block:: none

            ~(keystone_admin)]$ system service-parameter-delete 49318709-3bb9-4b47-9e9a-54ed79d731c3