Chapter 5. Managing top level domain names

This section introduces top-level domains and describes how to create and manage them in the Red Hat OpenStack Platform DNS service (designate). The way in which you manage what domain names users are allowed to create is through denylists.

The topics included in this section are:

5.1. About top-level domains

You can use top-level domains (TLDs) to restrict the domains under which users can create zones. In the Domain Name System (DNS) the term TLD refers specifically to the set of domains that reside directly below the root, such as .com. In the Red Hat OpenStack Platform (RHOSP) DNS service (designate), a TLD can be any valid domain.

Because TLDs define the set of allowed domains, the zone that a user creates must exist within one of the TLDs. If no TLDs have been created in the DNS service, then users can create any zone. TLDs do not have a policy that allows privileged users to create zones outside the allowed TLDs.

Example

After creating the .com TLD, if a user attempts to create a zone that is not contained within the .com TLD, the attempt fails. 

$ openstack zone create --email admin@test.net test.net.

Sample output

Invalid TLD

You can create, list, show, modify, and delete TLDs using the OpenStack Client openstack tld commands.

Additional resources

  • tld in the Command Line Interface Reference
  • zone in the Command Line Interface Reference

5.2. Creating top-level domains

Top-level domains (TLDs) enable you to restrict the domains under which users can create zones. In the Red Hat OpenStack Platform (RHOSP) DNS service (designate), a TLD can be any valid domain. To create TLDs, use the OpenStack Client openstack tld create command.

Prerequisites

  • You must be a RHOSP user with the admin role.

Procedure

  1. As a cloud administrator, source your credentials file.

    Example

    $ source ~/overcloudrc

  2. You create a TLD by running the openstack tld create command.

    Example

    For example, if you want to require that users create zones ending in .org, you can create a single .org TLD: 

    $ openstack tld create --name org

    Sample output

    +-------------+--------------------------------------+
| Field       | Value                                |
+-------------+--------------------------------------+
| created_at  | 2022-01-10T13:07:33.000000           |
| description | None                                 |
| id          | 9fd0a12d-511e-4024-bf76-6ec2e3e71edd |
| name        | org                                  |
| updated_at  | None                                 |
+-------------+--------------------------------------+

    Tip

    When using the openstack tld command, ensure that the fully qualified domain name (FQDN) that you enter has no trailing dot, for example, .net..

Verification

  • Run the openstack tld list command, and confirm that your TLD exists.

    Example

    $ openstack tld list --name zone1.cloud.example.com

Additional resources

  • tld create in the Command Line Interface Reference

5.3. Listing and showing top-level domains

You can query the Red Hat OpenStack Platform DNS service (designate) database and list all of the top-level domains (TLDs), or display properties for a particular TLD. The OpenStack Client commands for doing this are openstack tld list and openstack tld show, respectively.

Procedure

  1. Source your credentials file.

    Example 

    $ source ~/overcloudrc

  2. Use the following command to list all of the TLDs in the DNS service database: 

    $ openstack tld list

  3. Use the openstack tld show <TLD_NAME_or_ID> command to display the properties for a particular TLD.

    Example

    $ openstack tld show org

Additional resources

  • tld list in the Command Line Interface Reference
  • tld show in the Command Line Interface Reference

5.4. Modifying top-level domains

The Red Hat OpenStack Platform (RHOSP) DNS service (designate) enables you to change various properties of a top-level domain (TLD), such as its name. You modify TLDs by using the OpenStack Client openstack tld set command.

Prerequisites

  • You must be a RHOSP user with the admin role.

Procedure

  1. As a cloud administrator, source your credentials file.

    Example

    $ source ~/overcloudrc

  2. You can modify a TLD in various ways by using the following command options: 

    openstack tld set [--name NAME] \
                  [--description DESCRIPTION | --no-description] \
                  [TLD_ID | TLD_NAME]
    Note

    The earlier syntax diagram does not show the various formatting options for the openstack tld set command. For the list of all the command options, see the link in "Additional resources," later.

    In this example, the openstack tld set command renames the org TLD to example.net:

    Example

    $ openstack tld set org --name example.net

    Sample output

    +-------------+--------------------------------------+
| Field       | Value                                |
+-------------+--------------------------------------+
| created_at  | 2022-01-10T13:07:33.000000           |
| description |                                      |
| id          | 9fd0a12d-511e-4024-bf76-6ec2e3e71edd |
| name        | example.net                          |
| updated_at  | 2022-01-10T22:35:20.000000           |
+-------------+--------------------------------------+

Verification

  • Run the openstack tld show <TLD_NAME_or_ID> command, and confirm that your modifications exist.

Additional resources

  • tld set in the Command Line Interface Reference

5.5. Deleting top-level domains

The Red Hat OpenStack Platform (RHOSP) DNS service (designate) enables you to remove a top-level domain (TLD) by using the OpenStack Client openstack tld delete command.

Prerequisites

  • You must be a RHOSP user with the admin role.

Procedure

  1. As a cloud administrator, source your credentials file.

    Example

    $ source ~/overcloudrc

  2. Obtain the ID or the name for the TLD that you want to delete, by running the following command: 

    $ openstack tld list

  3. Using either the name or the ID from the previous step, enter the following command: 

    $ openstack tld delete <TLD_NAME_or_ID>

    There is no output when this command is successful.

Verification

  • Run the openstack tld show <TLD_NAME_or_ID> command, and verify that the TLD has been removed.

Additional resources

  • tld delete in the Command Line Interface Reference

5.6. About DNS service denylists

The Red Hat OpenStack Platform (RHOSP) DNS service (designate) has a denylist feature that enables you to prevent users from creating zones with names that match a particular regular expression. For example, you might use a denylist to prevent users from:

  • creating a specific zone.
  • creating zones that contain a certain string.
  • creating subzones of a certain zone.

If example.com. is a member of a denylist, and a domain or a project user attempts to create a zone like, foo.example.com. or example.com., they encounter an error: 

$ openstack zone create --email admin@example.com example.com.
Blacklisted zone name
$ openstack zone create --email admin@example.com foo.example.com.
Blacklisted zone name
Note

Users who satisfy the use_blacklisted_zone role-based access control can create zones with names that are on a denylist. By default, the only users who have this override are RHOSP system administrators.

You can create, list, show, modify, and delete denylists using the OpenStack Client openstack zone blacklist commands.

Additional resources

5.7. About DNS service regular expressions in denylists

A large part of working with denylists in the Red Hat OpenStack Platform DNS service (designate) is using regular expressions (regexes), which can be difficult to use. The Python documentation about regex might serve as a useful introduction. Online regex tools can assist when building and testing regexes for use with the denylist API.

Additional resources

5.8. Creating DNS service denylists

Denylists in the Red Hat OpenStack Platform DNS service (designate) enable you to prevent users from creating zones with names that match a particular regular expression. You create denylists with the OpenStack Client openstack zone blacklist create command.

Prerequisites

  • You must be a RHOSP user with the admin role.

Procedure

  1. As a cloud administrator, source your credentials file.

    Example

    $ source ~/overcloudrc

  2. Use the openstack zone blacklist create command to create a denylist.

    In this example, the domain example.com. and all of its subdomains are added to a denylist.

    Example

    $ openstack zone blacklist create --pattern ".*example.com."

    Sample output

    +-------------+--------------------------------------+
| Field       | Value                                |
+-------------+--------------------------------------+
| created_at  | 2021-10-20T16:15:18.000000           |
| description | None                                 |
| id          | 7622e241-8c3d-4c03-a692-8747e3cf2658 |
| pattern     | .*example.com.                       |
| updated_at  | None                                 |
+-------------+--------------------------------------+

Verification

  • Run the openstack zone blacklist list command, and confirm that your denylist exists.

Additional resources

5.9. Listing and showing DNS service denylists

You can query the Red Hat OpenStack Platform DNS service (designate) database and view all of the denylists, or display properties for a particular denylist. The OpenStack Client commands for doing this are openstack zone blacklist list and openstack zone blacklist show, respectively.

Viewing all of the denylists can be helpful, because you must know the denylist ID to be able to use the other denylist commands.

Procedure

  1. Source your credentials file.

    Example 

    $ source ~/overcloudrc

  2. Use the following command to list the denylists in the DNS service database: 

    $ openstack zone blacklist list

    • With the denylist ID obtained in the previous step, use the openstack zone blacklist show <denylist_ID> command to display properties for a particular denylist.

      Example

      $ openstack zone blacklist show 7622e241-8c3d-4c03-a692-8747e3cf2658

Additional resources

5.10. Modifying DNS service denylists

The Red Hat OpenStack Platform DNS service (designate) enables you to modify denylists. For example, you might want to change the denylist to allow users to create a zone with a particular domain name that in the past was restricted. You modify denylists with the OpenStack Client openstack zone blacklist set command.

Prerequisites

  • You must be a RHOSP user with the admin role.

Procedure

  1. As a cloud administrator, source your credentials file.

    Example

    $ source ~/overcloudrc

  2. Obtain the ID for the denylist that you want to modify, by running the following command: 

    $ openstack zone blacklist list

  3. You can modify a denylist in various ways by using the following command options: 

    $ openstack zone blacklist set \
         [--description DESCRIPTION | --no-description] denylist_ID
    Note

    The earlier syntax diagram does not show the various formatting options for the openstack zone blacklist set command. For the list of all the command options, see the link in "Additional resources," later.

    In this example, the regular expression (regex) is changed to allow the web.example.com domain:

    Example

    $ openstack zone blacklist set 81fbfe02-6bf9-4812-a40e-1522ab6862ca --pattern ".*web.example.com"

    Sample output

    +-------------+--------------------------------------+
| Field       | Value                                |
+-------------+--------------------------------------+
| created_at  | 2022-01-08T09:11:43.000000           |
| description | None                                 |
| id          | 81fbfe02-6bf9-4812-a40e-1522ab6862ca |
| pattern     | .*web.example.com                    |
| updated_at  | 2022-01-15T14:26:18.000000           |
+-------------+--------------------------------------+

Verification

  • Run the openstack zone blacklist show <denylist_ID> command, and confirm that your modifications exist.

Additional resources

5.11. Deleting DNS service denylists

Denylists in the Red Hat OpenStack Platform DNS service (designate) enable you to prevent users from creating zones with names that match a particular regular expression. You remove denylists with the OpenStack Client openstack zone blacklist delete command.

Prerequisites

  • You must be a RHOSP user with the admin role.

Procedure

  1. As a cloud administrator, source your credentials file.

    Example

    $ source ~/overcloudrc

  2. Obtain the ID for the denylist that you want to delete, by running the following command: 

    $ openstack zone blacklist list

  3. Using the ID from the previous step, enter the following command: 

    $ openstack zone blacklist delete <denylist_ID>

    There is no output when this command is successful.

Verification

  • Run the openstack zone blacklist show <denylist_ID> command, and verify that the denylist has been removed.

Additional resources