You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by mi...@apache.org on 2018/12/20 22:54:10 UTC
[trafficcontrol] 02/02: implemented proper text roles for RFC and
mimetypes
This is an automated email from the ASF dual-hosted git repository.
mitchell852 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
commit ebd295cf7c0ffe41bb3280c8eaf42200baf68bf0
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Wed Dec 19 13:21:36 2018 -0700
implemented proper text roles for RFC and mimetypes
---
docs/source/admin/traffic_router.rst | 6 ++----
docs/source/api/cdns_name_snapshot.rst | 4 ++--
docs/source/api/cdns_name_snapshot_new.rst | 4 ++--
.../api/deliveryservices_xmlid_urisignkeys.rst | 24 +++++++++++-----------
docs/source/api/index.rst | 2 +-
docs/source/api/origins.rst | 2 +-
docs/source/basics/cache_revalidation.rst | 2 +-
docs/source/basics/http_11.rst | 2 +-
8 files changed, 22 insertions(+), 24 deletions(-)
diff --git a/docs/source/admin/traffic_router.rst b/docs/source/admin/traffic_router.rst
index 052a9bc..9cf9f8b 100644
--- a/docs/source/admin/traffic_router.rst
+++ b/docs/source/admin/traffic_router.rst
@@ -149,7 +149,7 @@ Overview
--------
Domain Name System Security Extensions (DNSSEC) is a set of extensions to DNS that provides a cryptographic mechanism for resolvers to verify the authenticity of responses served by an authoritative DNS server.
-Several RFCs (4033, 4044, 4045) describe the low level details and define the extensions, RFC 7129 provides clarification around authenticated denial of existence of records, and finally RFC 6781 describes operational best practices for administering an authoritative DNSSEC enabled DNS server. The authenticated denial of existence RFC describes how an authoritative DNS server responds in NXDOMAIN and NODATA scenarios when DNSSEC is enabled.
+Several RFCs (:rfc:`4033`, :rfc:`4044`, :rfc:`4045`) describe the low level details and define the extensions, :rfc:`7129` provides clarification around authenticated denial of existence of records, and finally RFC 6781 describes operational best practices for administering an authoritative DNSSEC enabled DNS server. The authenticated denial of existence RFC describes how an authoritative DNS server responds in NXDOMAIN and NODATA scenarios when DNSSEC is enabled.
Traffic Router currently supports DNSSEC with NSEC, however, NSEC3 and more configurable options are planned for the future.
@@ -165,9 +165,7 @@ To enable DNSSEC for a CDN in Traffic Portal, Go to 'CDNs' from the sidebar and
Rolling Zone Signing Keys
-------------------------
-Traffic Router currently follows the zone signing key pre-publishing operational best practice described in `section 4.1.1.1 of RFC 6781`_. Once DNSSEC is enabled for a CDN in Traffic Portal, key rolls are triggered by Traffic Ops via the automated key generation process, and Traffic Router selects the active zone signing keys based on the expiration information returned from the 'keystore' API of Traffic Ops.
-
-.. _section 4.1.1.1 of RFC 6781: https://tools.ietf.org/html/rfc6781#section-4.1.1.1
+Traffic Router currently follows the zone signing key pre-publishing operational best practice described in :rfc:`6781#section-4.1.1.1`. Once DNSSEC is enabled for a CDN in Traffic Portal, key rolls are triggered by Traffic Ops via the automated key generation process, and Traffic Router selects the active zone signing keys based on the expiration information returned from the 'keystore' API of Traffic Ops.
.. _tr-logs:
diff --git a/docs/source/api/cdns_name_snapshot.rst b/docs/source/api/cdns_name_snapshot.rst
index facc93b..2e00eba 100644
--- a/docs/source/api/cdns_name_snapshot.rst
+++ b/docs/source/api/cdns_name_snapshot.rst
@@ -97,7 +97,7 @@ Response Structure
:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
:retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
- .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+ .. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
@@ -253,7 +253,7 @@ Response Structure
:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
:retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
- .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+ .. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
diff --git a/docs/source/api/cdns_name_snapshot_new.rst b/docs/source/api/cdns_name_snapshot_new.rst
index b2238b8..d981f3c 100644
--- a/docs/source/api/cdns_name_snapshot_new.rst
+++ b/docs/source/api/cdns_name_snapshot_new.rst
@@ -96,7 +96,7 @@ Response Structure
:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
:retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
- .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+ .. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
@@ -252,7 +252,7 @@ Response Structure
:refresh: A string containing an integer that sets the number of seconds after which secondary name servers should query the master for the SOA record, to detect zone changes
:retry: A string containing an integer that sets the number of seconds after which secondary name servers should retry to request the serial number from the master if the master does not respond
- .. note:: `RFC 1035 <https://tools.ietf.org/html/rfc1035>`_ dictates that this should always be less than ``refresh``.
+ .. note:: :rfc:`1035` dictates that this should always be less than ``refresh``.
.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
diff --git a/docs/source/api/deliveryservices_xmlid_urisignkeys.rst b/docs/source/api/deliveryservices_xmlid_urisignkeys.rst
index 996f1a5..039136e 100644
--- a/docs/source/api/deliveryservices_xmlid_urisignkeys.rst
+++ b/docs/source/api/deliveryservices_xmlid_urisignkeys.rst
@@ -62,13 +62,13 @@ DELETE
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
| ``keys`` | string | json array of jwt symmetric keys . |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``alg`` | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, RFC 7518. |
+ | ``alg`` | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``kid`` | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in RFC 7516. |
+ | ``kid`` | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``kty`` | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in RFC 7516. |
+ | ``kty`` | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``k`` | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see RFC 7516. |
+ | ``k`` | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
**Response Example** ::
@@ -121,13 +121,13 @@ DELETE
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
| ``keys`` | string | json array of jwt symmetric keys . |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``alg`` | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, RFC 7518. |
+ | ``alg`` | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``kid`` | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in RFC 7516. |
+ | ``kid`` | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``kty`` | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in RFC 7516. |
+ | ``kty`` | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``k`` | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see RFC 7516. |
+ | ``k`` | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
**Request Example** ::
@@ -179,13 +179,13 @@ DELETE
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
| ``keys`` | string | json array of jwt symmetric keys . |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``alg`` | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, RFC 7518. |
+ | ``alg`` | string | this parameter repeats for each jwt key in the array and specifies the jwa encryption algorithm to use with this key, :rfc:`7518` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``kid`` | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in RFC 7516. |
+ | ``kid`` | string | this parameter repeats for each jwt key in the array and specifies the unique id for the key as defined in :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``kty`` | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in RFC 7516. |
+ | ``kty`` | string | this parameter repeats for each jwt key in the array and specifies the key type as defined in :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
- | ``k`` | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see RFC 7516. |
+ | ``k`` | string | this parameter repeats for each jwt key in the array and specifies the base64 encoded symmetric key see :rfc:`7516` |
+---------------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------+
**Request Example** ::
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index e5cb648..1a24dbc 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -53,7 +53,7 @@ The methods of endpoints that require/accept data payloads - unless otherwise no
All fields are mandatory in a request payload, or always present in a response payload unless otherwise noted in the field description.
-In most cases, JSON objects have been "pretty-printed" by inserting line breaks and indentation. This means that the ``Content-Length`` HTTP header does not, in general, accurately portray the length of the content displayed in Request Examples and Response Examples. Also, the Traffic Ops endpoints will ignore any content negotiation, meaning that the ``Content-Type`` header of a request is totally meaningless. A utility may choose to pass the data as e.g. ``application/x-www-form-urlenc [...]
+In most cases, JSON objects have been "pretty-printed" by inserting line breaks and indentation. This means that the ``Content-Length`` HTTP header does not, in general, accurately portray the length of the content displayed in Request Examples and Response Examples. Also, the Traffic Ops endpoints will ignore any content negotiation, meaning that the ``Content-Type`` header of a request is totally meaningless. A utility may choose to pass the data as e.g. :mimetype:`application/x-www-fo [...]
.. _to-api-response-structure:
diff --git a/docs/source/api/origins.rst b/docs/source/api/origins.rst
index 8165cdc..cdece7d 100644
--- a/docs/source/api/origins.rst
+++ b/docs/source/api/origins.rst
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _to-api-origin:
+.. _to-api-origins:
***********
``origins``
diff --git a/docs/source/basics/cache_revalidation.rst b/docs/source/basics/cache_revalidation.rst
index 8af957d..3aa0c48 100644
--- a/docs/source/basics/cache_revalidation.rst
+++ b/docs/source/basics/cache_revalidation.rst
@@ -20,7 +20,7 @@
Cache Control Headers and Revalidation
======================================
-The `HTTP/1.1 spec <https://www.ietf.org/rfc/rfc2616.txt>`_ allows for origin servers and clients to influence how caches treat their requests and responses. By default, the Traffic Control CDN will honor cache control headers. Most commonly, origin servers will tell the downstream caches how long a response can be cached
+The HTTP/1.1 spec :rfc:`2616` allows for origin servers and clients to influence how caches treat their requests and responses. By default, the Traffic Control CDN will honor cache control headers. Most commonly, origin servers will tell the downstream caches how long a response can be cached
.. code-block:: http
:caption: This Response may Only be Cached for 86400 Seconds
diff --git a/docs/source/basics/http_11.rst b/docs/source/basics/http_11.rst
index 9283248..816c876 100644
--- a/docs/source/basics/http_11.rst
+++ b/docs/source/basics/http_11.rst
@@ -21,7 +21,7 @@ HTTP/1.1
========
For a comprehensive look at Traffic Control, it is important to understand basic HTTP/1.1 protocol operations and how caches function. The example below illustrates the fulfillment of an HTTP/1.1 request in a situation without CDN or proxy, followed by viewing the changes after inserting different types of (caching) proxies. Several of the examples below are simplified for clarification of the essentials.
-For complete details on HTTP/1.1 see `RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1 <https://www.ietf.org/rfc/rfc2616.txt>`_.
+For complete details on HTTP/1.1 see :rfc:`2616`.
Below are the steps of a client retrieving the URL ``http://www.origin.com/foo/bar/fun.html`` using HTTP/1.1 without proxies: