Fix indentation of user documentation code blocks

This removes unnecessary quotes to the left of code blocks.

Change-Id: I759b5c15c857e6dc4397ab3947ce8696421a75ce
This commit is contained in:
Pierre Riteau 2023-08-02 13:19:27 +02:00
parent 7d622d374d
commit 031eb8b5d3
2 changed files with 209 additions and 209 deletions

View File

@ -56,27 +56,27 @@ To recreate the earlier example using the OpenStack client with the Designate
plugin, the user would run:
.. code-block:: console
.. code-block:: console
$ openstack recordset create --type A --record 192.0.2.1 example.org. www
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | CREATE |
| created_at | 2021-05-03T03:13:46.000000 |
| description | None |
| id | 549c3e83-443f-474b-b467-6bcd7cb9f37d |
| name | www.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.1 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | None |
| version | 1 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
$ openstack recordset create --type A --record 192.0.2.1 example.org. www
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | CREATE |
| created_at | 2021-05-03T03:13:46.000000 |
| description | None |
| id | 549c3e83-443f-474b-b467-6bcd7cb9f37d |
| name | www.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.1 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | None |
| version | 1 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
As the final argument ``www`` is not a fully qualified domain name (FQDN) it
is prepended to the zone name. You can achieve the same result using the FQDN,
@ -87,44 +87,44 @@ You can supply the ``--record`` argument multiple times to create multiple
records within the recordset. A typical use for this is `Round-robin DNS`_.
.. code-block:: console
.. code-block:: console
$ openstack recordset create --type A --record 192.0.2.1 --record 192.0.2.2 example.org. web
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | CREATE |
| created_at | 2021-05-03T03:26:43.000000 |
| description | None |
| id | 9e0fba43-ca67-44ed-b9d9-fc1242920319 |
| name | web.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.1 |
| | 192.0.2.2 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | None |
| version | 1 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
$ openstack recordset create --type A --record 192.0.2.1 --record 192.0.2.2 example.org. web
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | CREATE |
| created_at | 2021-05-03T03:26:43.000000 |
| description | None |
| id | 9e0fba43-ca67-44ed-b9d9-fc1242920319 |
| name | web.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.1 |
| | 192.0.2.2 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | None |
| version | 1 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
You can view the recordsets for a zone using the ``openstack recordset list``
command:
.. code-block:: console
.. code-block:: console
$ openstack recordset list example.org.
+--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+
| id | name | type | records | status | action |
+--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+
| 3bebbd03-07d7-4274-a784-39c32a2be8c6 | example.org. | SOA | ns1.example.net. admin.example.org. 1620012616 3599 600 86400 3600 | ACTIVE | NONE |
| 7d34e4d3-a2f1-4af0-831c-ba52a8312c6a | example.org. | NS | ns1.example.net. | ACTIVE | NONE |
| 9e0fba43-ca67-44ed-b9d9-fc1242920319 | web.example.org. | A | 192.0.2.1 | ACTIVE | NONE |
| | | | 192.0.2.2 | | |
| 549c3e83-443f-474b-b467-6bcd7cb9f37d | www.example.org. | A | 192.0.2.1 | ACTIVE | NONE |
+--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+
$ openstack recordset list example.org.
+--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+
| id | name | type | records | status | action |
+--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+
| 3bebbd03-07d7-4274-a784-39c32a2be8c6 | example.org. | SOA | ns1.example.net. admin.example.org. 1620012616 3599 600 86400 3600 | ACTIVE | NONE |
| 7d34e4d3-a2f1-4af0-831c-ba52a8312c6a | example.org. | NS | ns1.example.net. | ACTIVE | NONE |
| 9e0fba43-ca67-44ed-b9d9-fc1242920319 | web.example.org. | A | 192.0.2.1 | ACTIVE | NONE |
| | | | 192.0.2.2 | | |
| 549c3e83-443f-474b-b467-6bcd7cb9f37d | www.example.org. | A | 192.0.2.1 | ACTIVE | NONE |
+--------------------------------------+------------------+------+---------------------------------------------------------------------+--------+--------+
The ``SOA`` and ``NS`` records for the zone are also visible here, but cannot
be modified.
@ -133,21 +133,21 @@ The authoritative nameserver for the zone is listed as the record data for the
``NS`` type record of the zone, which in this example is ``ns1.example.net.``.
To verify this you can query the nameserver using ``dig`` for the ``NS`` type:
.. code-block:: console
.. code-block:: console
$ dig @ns1.example.net example.org. -t NS +short
ns1.devstack.org.
$ dig @ns1.example.net example.org. -t NS +short
ns1.devstack.org.
You can also verify the ``A`` recordsets. You don't need the ``-t`` option
because it is the default:
.. code-block:: console
.. code-block:: console
$ dig @ns1.example.net web.example.org. +short
192.0.2.2
192.0.2.1
$ dig @ns1.example.net www.example.org. +short
192.0.2.1
$ dig @ns1.example.net web.example.org. +short
192.0.2.2
192.0.2.1
$ dig @ns1.example.net www.example.org. +short
192.0.2.1
If you want to construct a ``TXT`` record that exceeds the 255-octet
maximum length of a character-string, it has to be split into
@ -161,9 +161,9 @@ and unescaped double quotation marks as in RFC1035 section 5.1.
For example, to create a ``TXT`` record made of one string of 410
characters you can split it into 2 to like this:
.. code-block:: console
.. code-block:: console
$ openstack recordset create --type TXT --record '"210 characters string" "200 characters string"' example.org. _domainkey
$ openstack recordset create --type TXT --record '"210 characters string" "200 characters string"' example.org. _domainkey
Updating a recordset
--------------------
@ -174,28 +174,28 @@ OpenStack commands, you can also use recordset ID. For example, to update
the recordset ``www.example.org.`` to contain two records, you could use
the following:
.. code-block:: console
.. code-block:: console
$ openstack recordset set example.org. www.example.org. --record 192.0.2.1 --record 192.0.2.2
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | UPDATE |
| created_at | 2021-05-03T03:30:16.000000 |
| description | None |
| id | 549c3e83-443f-474b-b467-6bcd7cb9f37d |
| name | www.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.2 |
| | 192.0.2.1 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | 2021-05-03T03:44:16.000000 |
| version | 5 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
$ openstack recordset set example.org. www.example.org. --record 192.0.2.1 --record 192.0.2.2
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | UPDATE |
| created_at | 2021-05-03T03:30:16.000000 |
| description | None |
| id | 549c3e83-443f-474b-b467-6bcd7cb9f37d |
| name | www.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.2 |
| | 192.0.2.1 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | 2021-05-03T03:44:16.000000 |
| version | 5 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
Deleting a recordset
--------------------
@ -203,28 +203,28 @@ Deleting a recordset
You can use the ``openstack recordset delete`` command to remove recordsets
using the zone and either the FQDN or the recordset ID.
.. code-block:: console
.. code-block:: console
$ openstack recordset delete example.org. web.example.org.
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | DELETE |
| created_at | 2021-05-03T03:47:00.000000 |
| description | None |
| id | 5ab3418f-5377-47eb-b967-9e9ff7f3c26b |
| name | web.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.1 |
| | 192.0.2.2 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | 2021-05-03T03:47:13.000000 |
| version | 2 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
$ openstack recordset delete example.org. web.example.org.
+-------------+--------------------------------------+
| Field | Value |
+-------------+--------------------------------------+
| action | DELETE |
| created_at | 2021-05-03T03:47:00.000000 |
| description | None |
| id | 5ab3418f-5377-47eb-b967-9e9ff7f3c26b |
| name | web.example.org. |
| project_id | c85fdba96041438fa0cad2dc7909d3f5 |
| records | 192.0.2.1 |
| | 192.0.2.2 |
| status | PENDING |
| ttl | None |
| type | A |
| updated_at | 2021-05-03T03:47:13.000000 |
| version | 2 |
| zone_id | 077460ef-34db-486a-8d59-c9564dc3a3a9 |
| zone_name | example.org. |
+-------------+--------------------------------------+
.. _letter codes: https://en.wikipedia.org/wiki/List_of_DNS_record_types
.. _Round-robin DNS: https://en.wikipedia.org/wiki/Round-robin_DNS

View File

@ -57,114 +57,114 @@ Creating a zone
Creating a zone requires only the name of the zone and an email address of the
party responsible for the zone.
.. code-block:: console
.. code-block:: console
$ openstack zone create --email dnsmaster@example.com example.com.
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | CREATE |
| attributes | {} |
| created_at | 2016-07-13T14:54:16.000000 |
| description | None |
| email | dnsmaster@example.com |
| id | 14093115-0f0f-497a-ac69-42235e46c26f |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 656bc359067844fba6005d400f19df76 |
| serial | 1468421656 |
| status | PENDING |
| transferred_at | None |
| ttl | 3600 |
| type | PRIMARY |
| updated_at | None |
| version | 1 |
+----------------+--------------------------------------+
$ openstack zone create --email dnsmaster@example.com example.com.
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | CREATE |
| attributes | {} |
| created_at | 2016-07-13T14:54:16.000000 |
| description | None |
| email | dnsmaster@example.com |
| id | 14093115-0f0f-497a-ac69-42235e46c26f |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 656bc359067844fba6005d400f19df76 |
| serial | 1468421656 |
| status | PENDING |
| transferred_at | None |
| ttl | 3600 |
| type | PRIMARY |
| updated_at | None |
| version | 1 |
+----------------+--------------------------------------+
Note that the state is PENDING. Designate has received the request to create
the zone, but may not have completed it yet. After a short time, verify
successful creation of the DNS Zone:
.. code-block:: console
.. code-block:: console
$ openstack zone list
+--------------------------------------+--------------+---------+------------+--------+--------+
| id | name | type | serial | status | action |
+--------------------------------------+--------------+---------+------------+--------+--------+
| 14093115-0f0f-497a-ac69-42235e46c26f | example.com. | PRIMARY | 1468421656 | ACTIVE | NONE |
+--------------------------------------+--------------+---------+------------+--------+--------+
$ openstack zone list
+--------------------------------------+--------------+---------+------------+--------+--------+
| id | name | type | serial | status | action |
+--------------------------------------+--------------+---------+------------+--------+--------+
| 14093115-0f0f-497a-ac69-42235e46c26f | example.com. | PRIMARY | 1468421656 | ACTIVE | NONE |
+--------------------------------------+--------------+---------+------------+--------+--------+
There will now be two recordsets visible in the zone:
.. code-block:: console
.. code-block:: console
$ openstack recordset list example.com.
+--------------------------------------+--------------+------+---------------------------------------------------------------------+--------+--------+
| id | name | type | records | status | action |
+--------------------------------------+--------------+------+---------------------------------------------------------------------+--------+--------+
| 269cf8d2-c498-49a8-aef9-01e81d078313 | example.com. | SOA | ns1.devstack.org. admin.example.com. 1618291836 3509 600 86400 3600 | ACTIVE | NONE |
| 31b50023-88b2-4011-b31b-474fa25a8e39 | example.com. | NS | ns1.devstack.org. | ACTIVE | NONE |
+--------------------------------------+--------------+------+---------------------------------------------------------------------+--------+--------+
$ openstack recordset list example.com.
+--------------------------------------+--------------+------+---------------------------------------------------------------------+--------+--------+
| id | name | type | records | status | action |
+--------------------------------------+--------------+------+---------------------------------------------------------------------+--------+--------+
| 269cf8d2-c498-49a8-aef9-01e81d078313 | example.com. | SOA | ns1.devstack.org. admin.example.com. 1618291836 3509 600 86400 3600 | ACTIVE | NONE |
| 31b50023-88b2-4011-b31b-474fa25a8e39 | example.com. | NS | ns1.devstack.org. | ACTIVE | NONE |
+--------------------------------------+--------------+------+---------------------------------------------------------------------+--------+--------+
The values for refresh, retry, minimum and expire on the SOA record are set by
the Designate operator. The TTL, however, can be modified by users via the
zone:
.. code-block:: console
.. code-block:: console
$ openstack zone set example.com. --ttl 3000
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | UPDATE |
| attributes | |
| created_at | 2021-04-13T05:30:36.000000 |
| description | None |
| email | admin@example.com |
| id | b9861a55-0e50-4896-8ab9-25d8c4494f64 |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 9d69e3a004aa40c581f00d7bb7763e0a |
| serial | 1618545015 |
| status | PENDING |
| transferred_at | None |
| ttl | 3000 |
| type | PRIMARY |
| updated_at | 2021-04-16T03:50:15.000000 |
| version | 11 |
+----------------+--------------------------------------+
$ openstack zone set example.com. --ttl 3000
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | UPDATE |
| attributes | |
| created_at | 2021-04-13T05:30:36.000000 |
| description | None |
| email | admin@example.com |
| id | b9861a55-0e50-4896-8ab9-25d8c4494f64 |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 9d69e3a004aa40c581f00d7bb7763e0a |
| serial | 1618545015 |
| status | PENDING |
| transferred_at | None |
| ttl | 3000 |
| type | PRIMARY |
| updated_at | 2021-04-16T03:50:15.000000 |
| version | 11 |
+----------------+--------------------------------------+
The ``dig`` tool can be used to query one of the backend nameservers to confirm
the result. In this example, there is a DNS server at ``192.168.122.186``
managed by designate as part of the default pool.
.. code-block:: console
.. code-block:: console
$ dig @192.168.122.186 example.com.
$ dig @192.168.122.186 example.com.
; <<>> DiG 9.11.20-RedHat-9.11.20-5.el8_3.1 <<>> @192.168.122.186 example.com.
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 63663
;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available
; <<>> DiG 9.11.20-RedHat-9.11.20-5.el8_3.1 <<>> @192.168.122.186 example.com.
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 63663
;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 1
;; WARNING: recursion requested but not available
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
; COOKIE: 970f584e4cb93505eaf46f526079097ac959da76062f1d0a (good)
;; QUESTION SECTION:
;example.com. IN A
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
; COOKIE: 970f584e4cb93505eaf46f526079097ac959da76062f1d0a (good)
;; QUESTION SECTION:
;example.com. IN A
;; AUTHORITY SECTION:
example.com. 3000 IN SOA ns1.devstack.org. admin.example.com. 1618545015 3509 600 86400 3600
;; AUTHORITY SECTION:
example.com. 3000 IN SOA ns1.devstack.org. admin.example.com. 1618545015 3509 600 86400 3600
;; Query time: 0 msec
;; SERVER: 192.168.122.186#53(192.168.122.186)
;; WHEN: Fri Apr 16 03:50:18 UTC 2021
;; MSG SIZE rcvd: 126
;; Query time: 0 msec
;; SERVER: 192.168.122.186#53(192.168.122.186)
;; WHEN: Fri Apr 16 03:50:18 UTC 2021
;; MSG SIZE rcvd: 126
In the ``AUTHORITY`` section, the numeric value between the name and `IN` is
the TTL, which has updated to the new value of 3000.
@ -174,30 +174,30 @@ Deleting a zone
A zone can be deleted using either its name or ID:
.. code-block:: console
.. code-block:: console
$ openstack zone delete example.com.
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | DELETE |
| attributes | |
| created_at | 2021-04-13T05:30:36.000000 |
| description | None |
| email | admin@example.com |
| id | b9861a55-0e50-4896-8ab9-25d8c4494f64 |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 9d69e3a004aa40c581f00d7bb7763e0a |
| serial | 1618545024 |
| status | PENDING |
| transferred_at | None |
| ttl | 3000 |
| type | PRIMARY |
| updated_at | 2021-04-16T10:18:05.000000 |
| version | 15 |
+----------------+--------------------------------------+
$ openstack zone delete example.com.
+----------------+--------------------------------------+
| Field | Value |
+----------------+--------------------------------------+
| action | DELETE |
| attributes | |
| created_at | 2021-04-13T05:30:36.000000 |
| description | None |
| email | admin@example.com |
| id | b9861a55-0e50-4896-8ab9-25d8c4494f64 |
| masters | |
| name | example.com. |
| pool_id | 794ccc2c-d751-44fe-b57f-8894c9f5c842 |
| project_id | 9d69e3a004aa40c581f00d7bb7763e0a |
| serial | 1618545024 |
| status | PENDING |
| transferred_at | None |
| ttl | 3000 |
| type | PRIMARY |
| updated_at | 2021-04-16T10:18:05.000000 |
| version | 15 |
+----------------+--------------------------------------+
Any records present in the zone are also deleted and will no longer resolve.