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 2019/02/14 16:37:25 UTC
[trafficcontrol] branch master updated: Implemented proper text
roles throughout documentation (#3299)
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
The following commit(s) were added to refs/heads/master by this push:
new f78f4fa Implemented proper text roles throughout documentation (#3299)
f78f4fa is described below
commit f78f4fa6f2233c442cfa6a239e35af2095aa4254
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Thu Feb 14 09:37:20 2019 -0700
Implemented proper text roles throughout documentation (#3299)
This means that POSIX commands link to their respective man pages, Traffic Control
terms link to their respective glossary entries, RFC links are maintained by the
'rfc' role rather than hard-coded URLs, PEP links are maintained by the 'pep' role
rather than hard-coded URLs, abbreviations are defined using the 'abbr' role and
external files are referenced directly as 'download' links instead of just by
relative filename in the repository.
This change also fixes documentation inconsistencies with the guidelines, as well
as fixes for many warnings generated by the inclusion of docstrings from the Python
client. Some such warnings still exist because each method of the client links to
documentation for the endpoint(s) used, but many of those endpoints do not yet have
documentation. The warnings should disappear when said documentation is added -
presuming naming convention is followed.
---
docs/source/admin/index.rst | 15 +-
.../admin/quick_howto/anonymous_blocking.rst | 12 +-
docs/source/admin/quick_howto/ciab.rst | 226 ++++----
docs/source/admin/quick_howto/dnssec.rst | 22 +-
docs/source/admin/quick_howto/ds_requests.rst | 18 +-
docs/source/admin/quick_howto/federations.rst | 12 +-
docs/source/admin/quick_howto/index.rst | 2 +-
docs/source/admin/quick_howto/multi_site.rst | 32 +-
docs/source/admin/quick_howto/regionalgeo.rst | 33 +-
docs/source/admin/quick_howto/steering.rst | 58 +--
docs/source/admin/traffic_monitor.rst | 35 +-
docs/source/admin/traffic_ops/configuration.rst | 368 ++++++-------
docs/source/admin/traffic_ops/extensions.rst | 55 +-
.../source/admin/traffic_ops/images/topography.png | Bin 0 -> 226962 bytes
docs/source/admin/traffic_ops/installation.rst | 95 ++--
.../admin/traffic_ops/migration_from_10_to_20.rst | 74 ---
.../admin/traffic_ops/migration_from_20_to_22.rst | 148 ------
docs/source/admin/traffic_ops/using.rst | 86 ++-
.../admin/traffic_portal/default_profiles.rst | 29 +-
docs/source/admin/traffic_portal/installation.rst | 36 +-
.../admin/traffic_portal/usingtrafficportal.rst | 455 ++++++++--------
docs/source/admin/traffic_router.rst | 577 +++++++++++----------
.../source/admin/traffic_router/migrationto2-3.rst | 55 +-
docs/source/admin/traffic_server.rst | 109 ++--
docs/source/admin/traffic_stats.rst | 208 ++++----
docs/source/admin/traffic_vault.rst | 245 +++++----
docs/source/api/cache_stats.rst | 2 +-
docs/source/api/cachegroupparameters.rst | 2 +-
.../source/api/cachegroups_id_deliveryservices.rst | 6 +-
docs/source/api/cdns_name_configs_monitoring.rst | 16 +-
docs/source/api/cdns_name_federations.rst | 6 +-
docs/source/api/cdns_name_federations_id.rst | 6 +-
docs/source/api/cdns_name_name_dnsseckeys.rst | 4 +-
.../api/cdns_name_name_dnsseckeys_delete.rst | 2 +-
docs/source/api/cdns_name_name_sslkeys.rst | 6 +-
docs/source/api/cdns_name_snapshot.rst | 86 +--
docs/source/api/cdns_name_snapshot_new.rst | 86 +--
.../api/deliveryservice_server_dsid_serverid.rst | 20 +-
docs/source/api/deliveryservice_stats.rst | 10 +-
docs/source/api/deliveryservice_user.rst | 12 +-
.../api/deliveryservice_user_dsid_userid.rst | 16 +-
docs/source/api/deliveryservices.rst | 294 +++++------
.../api/deliveryservices_dnsseckeys_generate.rst | 2 +-
.../api/deliveryservices_hostname_name_sslkeys.rst | 67 ++-
docs/source/api/deliveryservices_id.rst | 244 ++++-----
docs/source/api/deliveryservices_id_capacity.rst | 22 +-
docs/source/api/deliveryservices_id_health.rst | 14 +-
docs/source/api/deliveryservices_id_regexes.rst | 30 +-
.../source/api/deliveryservices_id_regexes_rid.rst | 14 +-
docs/source/api/deliveryservices_id_routing.rst | 32 +-
docs/source/api/deliveryservices_id_safe.rst | 124 ++---
..._metric_types_start_date_start_end_date_end.rst | 2 +-
docs/source/api/deliveryservices_id_servers.rst | 4 +-
.../api/deliveryservices_id_servers_eligible.rst | 4 +-
docs/source/api/deliveryservices_id_state.rst | 24 +-
.../api/deliveryservices_id_unassigned_servers.rst | 4 +-
docs/source/api/deliveryservices_regexes.rst | 6 +-
docs/source/api/deliveryservices_request.rst | 56 +-
docs/source/api/deliveryservices_sslkeys_add.rst | 12 +-
.../api/deliveryservices_sslkeys_generate.rst | 8 +-
docs/source/api/deliveryservices_xmlid_servers.rst | 20 +-
.../api/deliveryservices_xmlid_xmlid_sslkeys.rst | 24 +-
...deliveryservices_xmlid_xmlid_sslkeys_delete.rst | 10 +-
.../api/deliveryservices_xmlid_xmlid_urlkeys.rst | 16 +-
...d_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst | 16 +-
...liveryservices_xmlid_xmlid_urlkeys_generate.rst | 12 +-
docs/source/api/deliveryserviceserver.rst | 22 +-
docs/source/api/federations.rst | 24 +-
.../source/api/federations_id_deliveryservices.rst | 14 +-
.../api/federations_id_deliveryservices_id.rst | 16 +-
docs/source/api/jobs.rst | 18 +-
docs/source/api/jobs_id.rst | 2 +-
docs/source/api/origins.rst | 218 ++++----
docs/source/api/servers.rst | 34 +-
docs/source/api/servers_hostname_name_details.rst | 2 +-
docs/source/api/servers_hostname_update_status.rst | 96 ++++
docs/source/api/servers_id_deliveryservices.rst | 153 +++---
docs/source/api/servers_status.rst | 60 +++
docs/source/api/staticdnsentries.rst | 62 +--
docs/source/api/steering_id_targets.rst | 62 +--
docs/source/api/steering_id_targets_targetID.rst | 74 +--
docs/source/api/system_info.rst | 4 +-
docs/source/api/user_current_jobs.rst | 8 +-
.../api/user_id_deliveryservices_available.rst | 18 +-
docs/source/api/users_id_deliveryservices.rst | 104 ++--
docs/source/basics/cache_revalidation.rst | 34 +-
docs/source/basics/caching_proxies.rst | 217 --------
docs/source/basics/content_delivery_networks.rst | 22 +-
docs/source/basics/http_11.rst | 28 +-
docs/source/basics/index.rst | 5 +-
docs/source/cg_hierarchy.png | Bin 0 -> 98713 bytes
docs/source/cg_hierarchy.svg | 79 +++
docs/source/conf.py | 11 +
docs/source/development/building.rst | 13 +-
.../development/documentation_guidelines.rst | 33 +-
docs/source/development/index.rst | 1 -
docs/source/development/traffic_monitor.rst | 79 ++-
.../traffic_monitor/traffic_monitor_api.rst | 28 +-
docs/source/development/traffic_ops.rst | 169 +++---
docs/source/development/traffic_portal.rst | 4 +-
docs/source/development/traffic_router.rst | 211 ++++++--
.../traffic_router/traffic_router_api.rst | 500 +++++++++++++++---
docs/source/development/traffic_stats.rst | 45 +-
docs/source/faq.rst | 53 ++
docs/source/faq/administration.rst | 95 ----
docs/source/faq/cache_groups_1.png | Bin 80623 -> 0 bytes
docs/source/faq/development.rst | 21 -
docs/source/faq/general.rst | 55 --
docs/source/faq/index.rst | 26 -
docs/source/glossary.rst | 332 +++++++++++-
docs/source/index.rst | 2 +-
docs/source/overview/introduction.rst | 37 +-
docs/source/overview/traffic_monitor.rst | 14 +-
docs/source/overview/traffic_ops.rst | 14 +-
docs/source/overview/traffic_portal.rst | 23 +-
docs/source/overview/traffic_router.rst | 59 +--
docs/source/overview/traffic_stats.rst | 18 +-
docs/source/overview/traffic_vault.rst | 25 +-
docs/source/tools/compare.rst | 208 +++++---
docs/source/tools/traffic_vault_util.rst | 60 ++-
tools/.gitignore | 1 +
.../clients/python/trafficops/__version__.py | 2 +-
.../clients/python/trafficops/tosession.py | 23 +-
123 files changed, 4201 insertions(+), 3683 deletions(-)
diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst
index 19d535c..d183131 100644
--- a/docs/source/admin/index.rst
+++ b/docs/source/admin/index.rst
@@ -13,6 +13,7 @@
.. limitations under the License.
..
+*********************
Administrator's Guide
*********************
@@ -22,27 +23,21 @@ When installing a complete CDN from scratch, a sample recommended order is:
#. Traffic Ops
#. Traffic Vault (Riak)
+#. Traffic Portal
#. Traffic Monitor
#. Apache Traffic Server Mid-Tier Caches
#. Apache Traffic Server Edge-Tier Caches
#. Traffic Router
#. Traffic Stats
-#. Traffic Portal
Once everything is installed, you will need to configure the servers to talk to each other. You will also need Origin server(s), from which the Mid-Tier Cache(s) will obtain content. An Origin server is simply an HTTP(S) server which serves the content you wish to cache on the CDN.
.. toctree::
:maxdepth: 3
+ :glob:
- traffic_ops/installation.rst
- traffic_ops/migration_from_10_to_20.rst
- traffic_ops/migration_from_20_to_22.rst
- traffic_ops/configuration.rst
- traffic_ops/using.rst
- traffic_ops/extensions.rst
- traffic_portal/installation.rst
- traffic_portal/usingtrafficportal.rst
- traffic_portal/default_profiles.rst
+ traffic_ops/*
+ traffic_portal/*
traffic_monitor.rst
traffic_router.rst
traffic_router/migrationto2-3.rst
diff --git a/docs/source/admin/quick_howto/anonymous_blocking.rst b/docs/source/admin/quick_howto/anonymous_blocking.rst
index e62d651..7f45577 100644
--- a/docs/source/admin/quick_howto/anonymous_blocking.rst
+++ b/docs/source/admin/quick_howto/anonymous_blocking.rst
@@ -21,7 +21,7 @@ Configure Anonymous Blocking
.. Note:: Anonymous Blocking is only supported for HTTP delivery services. You will need access to a database that provides anonymous IP statistics (`Maxmind's database <https://www.maxmind.com/en/solutions/geoip2-enterprise-product-suite/anonymous-ip-database>`_ is recommended, as this functionality was built specifically to work with it.)
-#. Prepare the Anonymous Blocking configuration file. Anonymous Blocking uses a configuration file in JSON format to define blocking rules for Delivery Services. The file needs to be put on an HTTP server accessible to Traffic Router.
+#. Prepare the Anonymous Blocking configuration file. Anonymous Blocking uses a configuration file in JSON format to define blocking rules for :term:`Delivery Service`\ s. The file needs to be put on an HTTP server accessible to Traffic Router.
.. code-block:: json
:caption: Example Configuration JSON
@@ -43,11 +43,11 @@ Configure Anonymous Blocking
}
anonymousIp
- Contains the types of IPs which can be checked against the Anonymous IP Database. There are 4 types of IPs which can be checked: VPNs, Hosting Providers, Public Proxies, and Tor Exit Nodes. Each type of IP can be enabled or disabled. If the value is true, IPs matching this type will be blocked when the feature is enabled in the Delivery Service. If the value is false, IPs which match this type will not be blocked. If an IP matches more than 1 type and any type is enabled, the IP will b [...]
+ Contains the types of IPs which can be checked against the Anonymous IP Database. There are 4 types of IPs which can be checked: :abbr:`VPN (Virtual Private Network)`\ s, Hosting Providers, Public Proxies, and :abbr:`TOR (The Onion Ring)` "Exit Nodes". Each type of IP can be enabled or disabled. If the value is true, IPs matching this type will be blocked when the feature is enabled in the :term:`Delivery Service`. If the value is false, IPs which match this type will not be blocked. I [...]
redirectUrl
- The URL that will be returned to the blocked clients. Without a redirectUrl, the clients will receive an HTTP response code ``403 Forbidden``. With a redirectUrl, the clients will be redirected with an HTTP response code ``302 Found``.
+ The URL that will be returned to the blocked clients. Without a :dfn:`redirectUrl`, the clients will receive an HTTP response code ``403 Forbidden``. With a :dfn:`redirectUrl`, the clients will be redirected with an HTTP response code ``302 Found``.
ipWhiteList
- An optional element. It includes a list of Classless Inter-Domain Routing (CIDR) blocks indicating the IPv4 and IPv6 subnets that are allowed by the rule. If this list exists and the value is not ``null``, client IPs will be matched against the CIDR list, and if there is any match, the request will be allowed. If there is no match in the white list, further anonymous blocking logic will continue.
+ An optional element. It includes a list of :abbr:`CIDR (Classless Inter-Domain Routing)` blocks indicating the IPv4 and IPv6 subnets that are allowed by the rule. If this list exists and the value is not ``null``, client IPs will be matched against the :abbr:`CIDR (Classless Inter-Domain Routing)` list, and if there is any match, the request will be allowed. If there is no match in the white list, further anonymous blocking logic will continue.
#. Add the following three Anonymous Blocking parameters in Traffic Portal into CRConfig.json:
@@ -63,13 +63,13 @@ Configure Anonymous Blocking
:scale: 100%
:align: center
-#. Enable Anonmyous Blocking for a Delivery Service
+#. Enable Anonmyous Blocking for a :term:`Delivery Service`
.. figure:: anonymous_blocking/02.png
:scale: 100%
:align: center
-#. Go to Tools->Snapshot CRConfig, perform “Diff CRConfig” and click "Write CRConfig".
+#. Go to :menuselection:`Tools --> Snapshot CRConfig`, perform :guilabel:`Diff CRConfig` and click :guilabel:`Write CRConfig`.
.. figure:: regionalgeo/03.png
:scale: 70%
diff --git a/docs/source/admin/quick_howto/ciab.rst b/docs/source/admin/quick_howto/ciab.rst
index b4d438a..36bc652 100644
--- a/docs/source/admin/quick_howto/ciab.rst
+++ b/docs/source/admin/quick_howto/ciab.rst
@@ -18,7 +18,7 @@
************
CDN in a Box
************
-"CDN in a Box" is a name given to the time-honored tradition of new Traffic Control developers/potential users attempting to set up their own miniature CDN to just see how it all fits together. Historically, this has been a nightmare of digging through leftover ``virsh`` scripts and manually configuring pretty hefty networking changes (don't even get me started on DNS) and just generally having a bad time. For a few years now, different people had made it to various stages of merging the [...]
+"CDN in a Box" is a name given to the time-honored tradition of new Traffic Control developers/potential users attempting to set up their own, miniature CDN to just see how it all fits together. Historically, this has been a nightmare of digging through leftover ``virsh`` scripts and manually configuring pretty hefty networking changes (don't even get me started on DNS) and just generally having a bad time. For a few years now, different people had made it to various stages of merging th [...]
Getting Started
===============
@@ -29,21 +29,20 @@ Because it runs in Docker, the only true prerequisites are:
Building
--------
-The CDN in a Box directory is found within the Traffic Control repository at ``infrastructure/cdn-in-a-box/``. CDN in a Box relies on the presence of pre-built RPM files for the following Traffic Control components:
+The CDN in a Box directory is found within the Traffic Control repository at :file:`infrastructure/cdn-in-a-box/`. CDN in a Box relies on the presence of pre-built :file:`{component}.rpm` files for the following Traffic Control components:
-* Traffic Monitor - at ``infrastructure/cdn-in-a-box/traffic_monitor/traffic_monitor.rpm``
-* Traffic Ops - at ``infrastructure/cdn-in-a-box/traffic_ops/traffic_ops.rpm``
-* Traffic Portal - at ``infrastructure/cdn-in-a-box/traffic_portal/traffic_portal.rpm``
-* Traffic Router - at ``infrastructure/cdn-in-a-box/traffic_router/traffic_router.rpm`` - also requires an Apache Tomcat RPM at ``infrastructure/cdn-in-a-box/traffic_router/tomcat.rpm``
+* Traffic Monitor - at :file:`infrastructure/cdn-in-a-box/traffic_monitor/traffic_monitor.rpm`
+* Traffic Ops - at :file:`infrastructure/cdn-in-a-box/traffic_ops/traffic_ops.rpm`
+* Traffic Portal - at :file:`infrastructure/cdn-in-a-box/traffic_portal/traffic_portal.rpm`
+* Traffic Router - at :file:`infrastructure/cdn-in-a-box/traffic_router/traffic_router.rpm` - also requires an Apache Tomcat RPM at :file:`infrastructure/cdn-in-a-box/traffic_router/tomcat.rpm`
.. note:: These can also be specified via the ``RPM`` variable to a direct Docker build of the component - with the exception of Traffic Router, which instead accepts ``JDK8_RPM`` to specify a Java Development Kit RPM, ``TRAFFIC_ROUTER_RPM`` to specify a Traffic Router RPM, and ``TOMCAT_RPM`` to specify an Apache Tomcat RPM.
-These can all be supplied manually via the steps in :ref:`dev-building` (for Traffic Control component RPMs) or via some external source. Alternatively, the ``infrastructure/cdn-in-a-box/Makefile`` file contains recipes to build all of these - simply run ``make``\ [2]_ from the ``infrastructure/cdn-in-a-box/`` directory.
-Once all RPM dependencies have been satisfied, run ``docker-compose build`` from the ``infrastructure/cdn-in-a-box/`` directory to construct the images needed to run CDN in a Box.
+These can all be supplied manually via the steps in :ref:`dev-building` (for Traffic Control component RPMs) or via some external source. Alternatively, the :file:`infrastructure/cdn-in-a-box/Makefile` file contains recipes to build all of these - simply run :manpage:`make(1)`\ [2]_ from the :file:`infrastructure/cdn-in-a-box/` directory. Once all RPM dependencies have been satisfied, run ``docker-compose build`` from the :file:`infrastructure/cdn-in-a-box/` directory to construct the im [...]
Usage
-----
-In a typical scenario, if the steps in `Building`_ have been followed, all that's required to start the CDN in a Box is to run ``docker-compose up`` - optionally with ``-d`` to run without binding to the terminal - from the ``infrastructure/cdn-in-a-box/`` directory. This will start up the entire stack and should take care of any needed initial configuration. The services within the containers are exposed locally to the host on specific ports. These are configured within the ``infrastru [...]
+In a typical scenario, if the steps in `Building`_ have been followed, all that's required to start the CDN in a Box is to run ``docker-compose up`` - optionally with the ``-d`` flag to run without binding to the terminal - from the :file:`infrastructure/cdn-in-a-box/` directory. This will start up the entire stack and should take care of any needed initial configuration. The services within the containers are exposed locally to the host on specific ports. These are configured within the [...]
.. _ciab-service-info:
.. table:: Service Info
@@ -77,7 +76,7 @@ In a typical scenario, if the steps in `Building`_ have been followed, all that'
.. seealso:: :ref:`tr-api` and :ref:`tm-api`
-While the components may be interacted with by the host using these ports, the true operation of the CDN can only truly be seen from within the Docker network. To see the CDN in action, connect to a container within the CDN in a Box project and use cURL to request the URL ``http://video.demo1.mycdn.ciab.test`` which will be resolved by the DNS container to the IP of the Traffic Router, which will provide a ``302 FOUND`` response pointing to the Edge-Tier cache. A typical choice for this [...]
+While the components may be interacted with by the host using these ports, the true operation of the CDN can only truly be seen from within the Docker network. To see the CDN in action, connect to a container within the CDN in a Box project and use cURL to request the URL ``http://video.demo1.mycdn.ciab.test`` which will be resolved by the DNS container to the IP of the Traffic Router, which will provide a ``302 FOUND`` response pointing to the Edge-Tier cache. A typical choice for this [...]
.. code-block:: shell
:caption: Example Command to See the CDN in Action
@@ -93,7 +92,7 @@ variables.env
:start-line: 16
:tab-width: 4
-.. note:: While these port settings can be changed without hampering the function of the CDN in a Box system, note that changing a port without also changing the matching port-mapping in ``infrastructure/cdn-in-a-box/docker-compose.yml`` for the affected service *will* make it unreachable from the host.
+.. note:: While these port settings can be changed without hampering the function of the CDN in a Box system, note that changing a port without also changing the matching port-mapping in :file:`infrastructure/cdn-in-a-box/docker-compose.yml` for the affected service *will* make it unreachable from the host.
.. [1] It is perfectly possible to build and run all containers without Docker Compose, but it's not recommended and not covered in this guide.
.. [2] Consider ``make -j`` to build quickly, if your computer can handle multiple builds at once.
@@ -101,72 +100,73 @@ variables.env
X.509 SSL/TLS Certificates
==========================
-All components in Apache Traffic Control utilize SSL/TLS secure communications by default. For SSL/TLS connections to properly validate within the "CDN in a Box" container network a shared self-signed X.509 Root Certificate Authority (CA) is generated at the first initial startup. An X.509 Intermediate Certificate Authority (CA) is also generated and signed by the Root CA. Additional wildcard certificates are generated/signed by the Intermediate CA for each container service and demo1, [...]
+All components in Apache Traffic Control utilize SSL/TLS secure communications by default. For SSL/TLS connections to properly validate within the "CDN in a Box" container network a shared self-signed X.509 Root :abbr:`CA (Certificate Authority)` is generated at the first initial startup. An X.509 Intermediate :abbr:`CA (Certificate Authority)` is also generated and signed by the Root :abbr:`CA (Certificate Authority)`. Additional "wildcard" certificates are generated/signed by the Inter [...]
.. _ciab-x509-certificate-list:
.. table:: Self-Signed X.509 Certificate List
- +---------------------------+-------------------------------------------+------------------------------+
- | Filename | Description | X.509 CN/SAN |
- +===========================+===========================================+==============================+
- | CIAB-CA-root.crt | Shared Root CA Certificate | N/A |
- +---------------------------+-------------------------------------------+------------------------------+
- | CIAB-CA-intr.crt | Shared Intermediate CA Certificate | N/A |
- +---------------------------+-------------------------------------------+------------------------------+
- | CIAB-CA-fullchain.crt | Shared CA Certificate Chain Bundle [5]_ | N/A |
- +---------------------------+-------------------------------------------+------------------------------+
- | infra.ciab.test.crt | Infrastruture Certificate | \*.infra.ciab.test |
- +---------------------------+-------------------------------------------+------------------------------+
- | demo1.mycdn.ciab.test.crt | Demo1 Delivery Service Certificate | \*.demo1.mycdn.ciab.test |
- +---------------------------+-------------------------------------------+------------------------------+
- | demo2.mycdn.ciab.test.crt | Demo2 Delivery Service Certificate | \*.demo2.mycdn.ciab.test |
- +---------------------------+-------------------------------------------+------------------------------+
- | demo3.mycdn.ciab.test.crt | Demo3 Delivery Service Certificate | \*.demo3.mycdn.ciab.test |
- +---------------------------+-------------------------------------------+------------------------------+
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
+ | Filename | Description | X.509 CN/SAN |
+ +===========================+==========================================================================+========================================+
+ | CIAB-CA-root.crt | Shared Root :abbr:`CA (Certificate Authority)` Certificate | N/A |
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
+ | CIAB-CA-intr.crt | Shared Intermediate :abbr:`CA (Certificate Authority)` Certificate | N/A |
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
+ | CIAB-CA-fullchain.crt | Shared :abbr:`CA (Certificate Authority)` Certificate Chain Bundle\ [5]_ | N/A |
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
+ | infra.ciab.test.crt | Infrastruture Certificate | :file:`{prefix}.infra.ciab.test` |
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
+ | demo1.mycdn.ciab.test.crt | Demo1 :term:`Delivery Service` Certificate | :file:`{prefix}.demo1.mycdn.ciab.test` |
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
+ | demo2.mycdn.ciab.test.crt | Demo2 :term:`Delivery Service` Certificate | :file:`{prefix}.demo2.mycdn.ciab.test` |
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
+ | demo3.mycdn.ciab.test.crt | Demo3 :term:`Delivery Service` Certificate | :file:`{prefix}.demo3.mycdn.ciab.test` |
+ +---------------------------+--------------------------------------------------------------------------+----------------------------------------+
.. [4] The ``ca`` volume is not purged with normal ``docker volume`` commands. This feature is by design to allow the existing shared SSL certificate to be trusted at the system level across restarts. To re-generate all SSL certificates and keys, remove the ``infrastructure/cdn-in-a-box/traffic_ops/ca`` directory before startup.
-.. [5] The full chain bundle is a file that contains both the Root and Intermediate CA certificates.
-
-Trusting the CA
----------------
-For developer and testing use-cases, it may be necessary to have full x509 CA validation by HTTPS clients [6]_ [7]_. For x509 validation to work properly, the self-signed x509 CA certificate must be trusted either at the system level or by the client application itself. Procedures to import and trust the CA x.509 certificate are outlined below [8]_.
-
-Importing the CA Certificate on OSX
------------------------------------
-#. Copy the CIAB root and intermediate CA certificates from ``infrastructure/cdn-in-a-box/traffic_ops/ca`` to the Mac.
-#. Double-click the CIAB CA certificate to open it in Keychain Access.
-#. The CIAB root CA certificate appears in login.
-#. Copy the CIAB root CA certificate to System.
-#. Open the CIAB root CA certificate, expand Trust, select Use System Defaults, and save your changes.
-#. Reopen the CIAB root CA certificate, expand Trust, select Always Trust, and save your changes.
-#. Delete the CIAB root CA certificate from login.
-#. Repeat the last six steps to import the Intermediate CA Certificate
+.. [5] The full chain bundle is a file that contains both the Root and Intermediate :abbr:`CA (Certificate Authority)` certificates.
+
+Trusting the Certificate Authority
+----------------------------------
+For developer and testing use-cases, it may be necessary to have full x509 :abbr:`CA (Certificate Authority)` validation by HTTPS clients\ [6]_\ [7]_. For x509 validation to work properly, the self-signed x509 :abbr:`CA (Certificate Authority)` certificate must be trusted either at the system level or by the client application itself.
+
+.. note:: HTTP Client applications such as Google Chrome, Firefox, :manpage:`curl(1)`, and :manpage:`wget(1)` can also be individually configured to trust the :abbr:`CA (Certificate Authority)` certificate. Review each program's respective documentation for instructions.
+
+Importing the :abbr:`CA (Certificate Authority)` Certificate on OSX
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+#. Copy the CIAB root and intermediate :abbr:`CA (Certificate Authority)` certificates from :file:`infrastructure/cdn-in-a-box/traffic_ops/ca/` to the Mac.
+#. Double-click the CIAB root :abbr:`CA (Certificate Authority)` certificate to open it in Keychain Access.
+#. The CIAB root :abbr:`CA (Certificate Authority)` certificate appears in login.
+#. Copy the CIAB root :abbr:`CA (Certificate Authority)` certificate to System.
+#. Open the CIAB root :abbr:`CA (Certificate Authority)` certificate, expand :guilabel:`Trust`, select :guilabel:`Use System Defaults`, and save your changes.
+#. Reopen the CIAB root :abbr:`CA (Certificate Authority)` certificate, expand :guilabel:`Trust, select :guilabel:`Always Trust`, and save your changes.
+#. Delete the CIAB root :abbr:`CA (Certificate Authority)` certificate from login.
+#. Repeat the previous steps with the Intermediate :abbr:`CA (Certificate Authority)` certificate to import it as well
#. Restart all HTTPS clients (browsers, etc).
-Importing the CA certificate on Windows
----------------------------------------
-#. Copy the CIAB root and intermediate CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca`` to Windows filesystem.
+Importing the :abbr:`CA (Certificate Authority)` certificate on Windows
+-----------------------------------------------------------------------
+#. Copy the CIAB root :abbr:`CA (Certificate Authority)` and intermediate :abbr:`CA (Certificate Authority)` certificates from :file:`infrastructure/cdn-in-a-box/traffic_ops/ca/` to Windows filesystem.
#. As Administrator, start the Microsoft Management Console.
#. Add the Certificates snap-in for the computer account and manage certificates for the local computer.
-#. Import the CIAB root CA certificate into Trusted Root Certification Authorities > Certificates.
-#. Import the CIAB intermediate CA certificate into Trusted Root Certification Authorities > Certificates.
+#. Import the CIAB root :abbr:`CA (Certificate Authority)` certificate into :menuselection:`Trusted Root Certification Authorities --> Certificates`.
+#. Import the CIAB intermediate :abbr:`CA (Certificate Authority)` certificate into :menuselection:`Trusted Root Certification Authorities --> Certificates`.
#. Restart all HTTPS clients (browsers, etc).
-Importing the CA certificate on Linux/Centos7
----------------------------------------------
-#. Copy the CIAB full chain CA certificate bundle from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA-fullchain.crt`` to path ``/etc/pki/ca-trust/source/anchors``.
-#. Run ``update-ca-trust-extract`` as the root user.
+Importing the :abbr:`CA (Certificate Authority)` certificate on Linux/Centos7
+-----------------------------------------------------------------------------
+#. Copy the CIAB full chain :abbr:`CA (Certificate Authority)` certificate bundle from :file:`infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA-fullchain.crt` to path :file:`/etc/pki/ca-trust/source/anchors/`.
+#. Run ``update-ca-trust-extract`` as the root user or with :manpage:`sudo(8)`.
#. Restart all HTTPS clients (browsers, etc).
-Importing the CA certificate on Linux/Ubuntu
---------------------------------------------
-#. Copy the CIAB full chain CA certificate bundle from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA-fullchain.crt`` to path ``/usr/local/share/ca-certificates``.
-#. Run ``update-ca-certificates`` as the root user.
+Importing the :abbr:`CA (Certificate Authority)` certificate on Linux/Ubuntu
+----------------------------------------------------------------------------
+#. Copy the CIAB full chain :abbr:`CA (Certificate Authority)` certificate bundle from :file:`infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA-fullchain.crt` to path :file:`/usr/local/share/ca-certificates/`.
+#. Run ``update-ca-certificates`` as the root user or with :manpage:`sudo(8)`.
#. Restart all HTTPS clients (browsers, etc).
-.. [6] All containers within CDN-in-a-Box start up with the self-signed CA already trusted.
-.. [7] The demo1 Delivery Service X509 certificate is automatically imported into traffic vault on startup.
-.. [8] HTTP Client applications such as Google Chrome, Firefox, curl, and wget can also be individually configured to trust the CA certificate. Each application procedure can be found quickly online via Google.
+.. [6] All containers within CDN-in-a-Box start up with the self-signed :abbr:`CA (Certificate Authority)` already trusted.
+.. [7] The 'demo1' :term:`Delivery Service` X509 certificate is automatically imported into Traffic Vault on startup.
Advanced Usage
==============
@@ -174,20 +174,35 @@ This section will be amended as functionality is added to the CDN in a Box proje
The Enroller
------------
-The "enroller" provides an efficient way for Traffic Ops to be populated with data as CDN in a Box starts up. It connects to Traffic Ops as the admin user and processes files places in the docker volume shared between the containers. The enroller watches each directory within the ``/shared/enroller`` directory for new ``.json`` files to be created there. These files must follow the format outlined in the API guide for the ``POST`` method for each data type, (e.g. for a ``tenant``, follo [...]
+The "enroller" began as an efficient way for Traffic Ops to be populated with data as CDN in a Box starts up. It connects to Traffic Ops as the "admin" user and processes files places in the docker volume shared between the containers. The enroller watches each directory within the ``/shared/enroller`` directory for new :file:`{filename}.json` files to be created there. These files must follow the format outlined in the API guide for the ``POST`` method for each data type, (e.g. for a ` [...]
-The enroller runs within CDN in a Box using the ``-dir <dir>`` switch which provides the above behavior. It can also be run using the ``-http :<port>`` switch to instead have it listen on the indicated port. In this case, it accepts only POST requests with the JSON provided using the POST JSON method, e.g. ``curl -X POST https://enroller/api/1.4/regions -d @newregion.json``. CDN in a Box does not currently use this method, but may be modified in the future to avoid using the shared volu [...]
+.. program::enroller
+
+.. option:: --dir directory
+
+ Base directory to watch for data. Mutually exclusive with :option:`--http`\ .
+
+.. option:: --http port
+
+ Act as an HTTP server for ``POST`` requests on this port. Mutually exclusive with :option:`--dir`\ .
+
+.. option:: --started filename
+
+ The name of a file which will be created in the :option:`--dir` directory when given, indicating service was started (default: "enroller-started").
+
+
+The enroller runs within CDN in a Box using :option:`--dir` which provides the above behavior. It can also be run using :option:`--http` to instead have it listen on the indicated port. In this case, it accepts only ``POST`` requests with the JSON provided in the request payload, e.g. ``curl -X POST https://enroller/api/1.4/regions -d @newregion.json``. CDN in a Box does not currently use this method, but may be modified in the future to avoid using the shared volume approach.
Auto Snapshot/Queue-Updates
---------------------------
-An automatic snapshot of the current Traffic Ops CDN configuration/toplogy will be performed once the "enroller" has finished loading all of the data and a minimum number of servers have been enrolled. To enable this feature, set the boolean ``AUTO_SNAPQUEUE_ENABLED`` to ``true`` [9]_. The snapshot and queue-updates actions will not be performed until all servers in ``AUTO_SNAPQUEUE_SERVERS`` (comma-delimited string) have been enrolled. The current enrolled servers will be polled ever [...]
+An automatic snapshot of the current Traffic Ops CDN configuration/toplogy will be performed once the "enroller" has finished loading all of the data and a minimum number of servers have been enrolled. To enable this feature, set the boolean ``AUTO_SNAPQUEUE_ENABLED`` to ``true`` [8]_. The snapshot and queue-updates actions will not be performed until all servers in ``AUTO_SNAPQUEUE_SERVERS`` (comma-delimited string) have been enrolled. The current enrolled servers will be polled ever [...]
-.. [9] Automatic Snapshot/Queue-Updates is enabled by default in `variables.env`_.
-.. [10] Server poll interval and delay action wait are defaulted to a value of 2 seconds.
+.. [8] Automatic Snapshot/Queue-Updates is enabled by default in :file:`infrastructure/cdn-in-a-box/variables.env`.
+.. [9] Server poll interval and delay action wait are defaulted to a value of 2 seconds.
Mock Origin Service
-------------------
-The default "origin" service container provides a basic static file HTTP server as the central respository for content. Additional files can be added to the origin root content directory located at ``infrastructure/cdn-in-a-box/origin/content``. To request content directly from the origin directly and bypass the CDN:
+The default "origin" service container provides a basic static file HTTP server as the central repository for content. Additional files can be added to the origin root content directory located at :file:`infrastructure/cdn-in-a-box/origin/content`. To request content directly from the origin directly and bypass the CDN:
* Origin Service URL: http://origin.infra.ciab.test/index.html
* Docker Host: http://localhost:9200/index.html
@@ -199,16 +214,16 @@ Optional Containers
All optional containers that are not part of the core CDN-in-a-Box stack are located in the ``infrastructure/cdn-in-a-box/optional`` directory.
-.. code-block:: shell
-
- infrastructure/cdn-in-a-box/optional/docker-compose.$NAME.yml
- infrastructure/cdn-in-a-box/optional/$NAME/Dockerfile
+- :file:`infrastructure/cdn-in-a-box/optional/docker-compose.{NAME}.yml`
+- :file:`infrastructure/cdn-in-a-box/optional/{NAME}/Dockerfile`
Multiple optional containers may be combined by using a shell alias:
.. code-block:: shell
+ :caption: Starting Optional Containers with an Alias
# From the infrastructure/cdn-in-a-box directory
+ # (Assuming the names of the optional services are stored in the `NAME1` and `NAME2` environment variables)
alias mydc="docker-compose -f $PWD/docker-compose.yml -f $PWD/optional/docker-compose.$NAME1.yml -f $PWD/optional/docker-compose.$NAME2.yml"
docker volume prune -f
mydc build
@@ -216,10 +231,10 @@ Multiple optional containers may be combined by using a shell alias:
VNC Server
----------
-The TightVNC optional container provides a basic lightweight window manager (fluxbox), Firefox browser, xterm, and a few other utilities within the CDN-In-A-Box tcnet bridge network. This can be very helpful for quick demonstrations of CDN-in-a-Box that require the use of real container network FQDNs and full X.509 validation.
+The TightVNC optional container provides a basic lightweight window manager (fluxbox), Firefox browser, xterm, and a few other utilities within the CDN-In-A-Box "tcnet" bridge network. This can be very helpful for quick demonstrations of CDN-in-a-Box that require the use of real container network :abbr:`FQDN (Fully Qualified Domain Name)`\ s and full X.509 validation.
#. Download and install a VNC client. TightVNC client is preferred as it supports window resizing, host-to-vnc copy/pasting, and optimized frame buffer compression.
-#. Set your VNC console password by adding the ``VNC_PASSWD`` environment variable to ``infrastructure/cdn-in-a-box/varibles.env``. The password needs to be at least six characters long. The default password is randomized for security.
+#. Set your VNC console password by adding the ``VNC_PASSWD`` environment variable to :file:`infrastructure/cdn-in-a-box/varibles.env`. The password needs to be at least six characters long. The default password is randomized for security.
#. Start up CDN-in-a-Box stack. It is recommended that this be done using a custom bash alias
.. code-block:: shell
@@ -241,11 +256,11 @@ Socks Proxy
-----------
Dante's socks proxy is an optional container that can be used to provide browsers and other clients the ability to resolve DNS queries and network connectivity directly on the tcnet bridged interface. This is very helpful when running the CDN-In-A-Box stack on OSX/Windows docker host that lacks network bridge/IP-forward support. Below is the basic procedure to enable the Socks Proxy support for CDN-in-a-Box:
-#. Start the CDN-in-a-Box stack at least once so that the x.509 self-signed certificate authority (CA) is created.
-#. On the host, import and Trust the CA for your target OS. See `Trusting the CA`_
-#. On the host, using either Firefox or Chrome, download the FoxyProxy Standard browser plugin which enables dynamic proxy support via URL regular expression
-#. Once FoxyProxy is installed, click the Fox icon on the upper right hand of the browser window, select 'Options'
-#. Once in Options Dialog, Click 'Add New Proxy' and navigate to the General tab:
+#. Start the CDN-in-a-Box stack at least once so that the x.509 self-signed :abbr:`CA (Certificate Authority)` is created.
+#. On the host, import and Trust the :abbr:`CA (Certificate Authority)` for your target Operating System. See `Trusting the Certificate Authority`_
+#. On the host, using either Firefox or Chrome, download the `FoxyProxy browser plugin <https://getfoxyproxy.org/>`_ which enables dynamic proxy support via URL regular expression
+#. Once FoxyProxy is installed, click the Fox icon on the upper right hand of the browser window, select :guilabel:`Options`
+#. Once in Options Dialog, Click :guilabel:`Add New Proxy` and navigate to the General tab:
#. Fill in the General tab according to the table
.. table:: General Tab Values
@@ -280,21 +295,21 @@ Dante's socks proxy is an optional container that can be used to provide browser
.. table:: URL Patters Tab Values
- +--------------+--------------+
- | Name | Value |
- +==============+==============+
- | Pattern Name | CIAB Pattern |
- +--------------+--------------+
- | URL Pattern | \*.test/\* |
- +--------------+--------------+
- | Whitelist | selected |
- +--------------+--------------+
- | Wildcards | selected |
- +--------------+--------------+
+ +--------------+-----------------------+
+ | Name | Value |
+ +==============+=======================+
+ | Pattern Name | CIAB Pattern |
+ +--------------+-----------------------+
+ | URL Pattern | :regexp:`\*.test/\*` |
+ +--------------+-----------------------+
+ | Whitelist | selected |
+ +--------------+-----------------------+
+ | Wildcards | selected |
+ +--------------+-----------------------+
-#. Enable dynamic 'pre-defined and patterns' mode by clicking the fox icon in the upper right of the browser. This mode only forwards URLs that match the wildcard ``\*.test/\*`` to the Socks V5 proxy.
+#. Enable dynamic 'pre-defined and patterns' mode by clicking the fox icon in the upper right of the browser. This mode only forwards URLs that match the wildcard :regexp:`\*.test/\*` to the Socks V5 proxy.
-10. On the docker host start up CDN-in-a-Box stack. It is recommended that this be done using a custom bash alias
+#. On the docker host start up CDN-in-a-Box stack. It is recommended that this be done using a custom bash alias
.. code-block:: shell
:caption: CIAB Startup Using Bash Alias
@@ -307,7 +322,7 @@ Dante's socks proxy is an optional container that can be used to provide browser
mydc rm -fv
mydc up
-#. Once the CDN-in-a-box stack has started, use the aforementioned browser to access traffic portal via the socks proxy on the docker host.
+#. Once the CDN-in-a-box stack has started, use the aforementioned browser to access Traffic Portal via the socks proxy on the docker host.
.. seealso:: `The official Docker Compose documentation CLI reference <https://docs.docker.com/compose/reference/>`_ for complete instructions on how to pass service definition files to the ``docker-compose`` executable.
@@ -324,10 +339,9 @@ Since ``docker-compose`` will randomly create a subnet and it has a chance to co
mydc build
mydc up
-VNC Server
+VPN Server
----------
-This container provide an OpenVPN service.
-It could let user or developer easily access CIAB network.
+This container provides an OpenVPN service. It's primary use is to allow users and developers to easily access CIAB network.
How to use it
"""""""""""""
@@ -342,46 +356,42 @@ How to use it
mydc build
mydc up
-#. All certificates, keys, and client configuration are stored at ``infrastruture/cdn-in-a-box/optional/vpn/vpnca``. You just simply change ``REALHOSTIP`` and ``REALPORT`` of ``client.ovpn`` to fit your environment, and then you can connect to this OpenVPN server by it.
+#. All certificates, keys, and client configuration are stored at ``infrastruture/cdn-in-a-box/optional/vpn/vpnca``. You just simply change ``REALHOSTIP`` and ``REALPORT`` of ``client.ovpn`` to fit your environment, and then you can use it to connect to this OpenVPN server.
The proposed VPN client
"""""""""""""""""""""""
-On Linux, you could choose ``openvpn``. Take ubuntu/debian as an example, you can install it by the following instructions.
+On Linux, we suggest ``openvpn``. On most Linux distributions, this will also be the name of the package that provides it.
.. code-block:: shell
:caption: Install openvpn on ubuntu/debian
apt-get update && apt-get install -y openvpn
-On OSX, it only works with brew installed openvpn client, not the *OpenVPN GUI client*. You can install it by the following instruction.
+On OSX, it only works with brew installed openvpn client, not the *OpenVPN GUI client*.
.. code-block:: shell
:caption: Install openvpn on OSX
brew install openvpn
-If you want a GUI version of VPN client, you can choose `Tunnelblick <https://tunnelblick.net/>`_.
+If you want a GUI version of VPN client, we recommend `Tunnelblick <https://tunnelblick.net/>`_.
Private Subnet for Routing
""""""""""""""""""""""""""
-Since ``docker-compose`` randomly create subnet, this container prepares 2 default private subnet for routing:
+Since ``docker-compose`` randomly creates a subnet, this container prepares 2 default private subnets for routing:
* 172.16.127.0/255.255.240.0
* 10.16.127.0/255.255.240.0
-The strategy of choosing default private subnet is comparing the subnet prefix.
-If the subnet prefix which ``docker-compose`` selected is 192. or 10.,
-this container goes to select 172.16.127.0/255.255.240.0 for its routing subnet.
-Otherwise, it selects 10.16.127.0/255.255.240.0.
+The subnet that will be used is determined automatically based on the subnet prefix. If the subnet prefix which ``docker-compose`` selected is ``192.`` or ``10.``, this container will select 172.16.127.0/255.255.240.0 for its routing subnet. Otherwise, it selects 10.16.127.0/255.255.240.0.
-Of course, you can decide which routing subnet subnet by supply environment
-variable ``PRIVATE_NETWORK`` and ``PRIVATE_NETMASK``.
+Of course, you can decide which routing subnet subnet by supplying the environment variables ``PRIVATE_NETWORK`` and ``PRIVATE_NETMASK``.
Pushed Settings
"""""""""""""""
Pushed settings are shown as follows:
* DNS
-* A routing rule for CIAB subnet
+* A routing rule for the ``CIAB`` subnet
-.. note:: It will not change your default gateway. That means apart from CIAB traffic and DNS request, all other traffic goes out standard interface bound to the default gateway.
+.. note:: It will not change your default gateway. That means apart from CDN in a Box traffic and DNS requests, all other traffic will use the standard interface bound to the default gateway.
diff --git a/docs/source/admin/quick_howto/dnssec.rst b/docs/source/admin/quick_howto/dnssec.rst
index 3c99a0c..9c34da8 100644
--- a/docs/source/admin/quick_howto/dnssec.rst
+++ b/docs/source/admin/quick_howto/dnssec.rst
@@ -23,9 +23,9 @@ Configure DNSSEC
.. Note:: In order for Traffic Ops to successfully store keys in Traffic Vault, at least one Riak Server needs to be configured in Traffic Ops. See the `Traffic Vault admin page <../traffic_vault.html>`_ for more information.
-.. Note:: Currently DNSSEC is only supported for DNS delivery services.
+.. Note:: Currently :abbr:`DNSSEC (DNS Security Extensions)` is only supported for DNS :term:`Delivery Service`\ s.
-#. Go to 'CDNs' and click on the desired CDN.
+#. Go to :guilabel:`CDNs` and click on the desired CDN.
.. figure:: dnssec/00.png
:width: 60%
@@ -34,7 +34,7 @@ Configure DNSSEC
CDNs Page
-#. Click on 'Manage DNSSEC Keys' under the 'More' drop-down menu.
+#. Click on :menuselection:`More --> Manage DNSSEC Keys`.
.. figure:: dnssec/01.png
:width: 60%
@@ -43,7 +43,7 @@ Configure DNSSEC
CDN Details Page
-#. Click on the 'Generate DNSSEC Keys' button.
+#. Click on the :guilabel:`Generate DNSSEC Keys` button.
.. figure:: dnssec/02.png
:width: 60%
@@ -61,9 +61,9 @@ Configure DNSSEC
Confirmation Modal
-#. Input the required information (reasonable defaults should be generated for you). When done, click on the green 'Generate' button.:
+#. Input the required information (reasonable defaults should be generated for you). When done, click on the green :guilabel:`Generate` button.
- .. note:: Depending upon the number of Delivery Services in the CDN, generating DNSSEC keys may take several seconds.
+ .. note:: Depending upon the number of :term:`Delivery Service`\ s in the CDN, generating DNSSEC keys may take several seconds.
.. figure:: dnssec/04.png
:width: 50%
@@ -72,7 +72,7 @@ Configure DNSSEC
DNSSEC Key Generation Page
-#. You will be prompted to confirm the changes by typing the name of the CDN into a text box. After doing so, click on the red 'Confirm' button.
+#. You will be prompted to confirm the changes by typing the name of the CDN into a text box. After doing so, click on the red :guilabel:`Confirm` button.
.. figure:: dnssec/05.png
:width: 30%
@@ -82,9 +82,9 @@ Configure DNSSEC
DNSSEC Key Change Confirmation
-#. In order for DNSSEC to work properly, the DS Record information needs to be added to the parent zone of the CDN's domain (e.g. If the CDN's domain is 'ciab.cdn.local' the parent zone is 'cdn.local'). If you control your parent zone you can enter this information yourself, otherwise you will need to work with your DNS team to get the DS Record added to the parent zone.
+#. In order for :abbr:`DNSSEC (DNS Security Extensions)` to work properly, the :abbr:`DS (Delegation of Signing)` Record information needs to be added to the parent zone of the CDN's domain (e.g. If the CDN's domain is 'ciab.cdn.local' the parent zone is 'cdn.local'). If you control your parent zone you can enter this information yourself, otherwise you will need to work with your DNS team to get the :abbr:`DS (Delegation of Signing)` Record added to the parent zone.
-#. Once DS Record information has been added to the parent zone, DNSSEC needs to be activated for the CDN so that Traffic Router will sign responses. Go back to the CDN details page for this CDN, and set the 'DNSSEC Enabled' field to 'true', then click the green 'Update' button.
+#. Once :abbr:`DS (Delegation of Signing)` Record information has been added to the parent zone, DNSSEC needs to be activated for the CDN so that Traffic Router will sign responses. Go back to the CDN details page for this CDN, and set the 'DNSSEC Enabled' field to 'true', then click the green :guilabel:`Update` button.
.. figure:: dnssec/06.png
:width: 60%
@@ -93,6 +93,6 @@ Configure DNSSEC
Change 'DNSSEC Enabled' to 'true'
-#. DNSSEC should now be active on your CDN and Traffic Router should be signing responses. This should be tested e.g. with this ``dig`` command: ``dig edge.cdn.local. +dnssec``.
+#. :abbr:`DNSSEC (DNS Security Extensions)` should now be active on your CDN and Traffic Router should be signing responses. This should be tested e.g. with this :manpage:`dig(1)` command: ``dig edge.cdn.local. +dnssec``.
-#. When KSK expiration is approaching (default 365 days), it is necessary to manually generate a new KSK for the TLD (Top Level Domain) and add the DS Record to the parent zone. In order to avoid signing errors, it is suggested that an effective date is chosen which allows time for the DS Record to be added to the parent zone before the new KSK becomes active.
+#. When :abbr:`KSK (Key-Signing Key)` expiration is approaching (default 365 days), it is necessary to manually generate a new :abbr:`KSK (Key Signing Key)` for the :abbr:`TLD (Top Level Domain)` and add the :abbr:`DS (Delegation of Signing)` Record to the parent zone. In order to avoid signing errors, it is suggested that an effective date is chosen which allows time for the :abbr:`DS (Delegation of Signing)` Record to be added to the parent zone before the new :abbr:`KSK (Key-Signing K [...]
diff --git a/docs/source/admin/quick_howto/ds_requests.rst b/docs/source/admin/quick_howto/ds_requests.rst
index 75d7fcc..833db82 100644
--- a/docs/source/admin/quick_howto/ds_requests.rst
+++ b/docs/source/admin/quick_howto/ds_requests.rst
@@ -18,9 +18,9 @@
*************************
Delivery Service Requests
*************************
-When enabled in ``traffic_portal_properties.json``, Delivery Service requests are created when *all* users attempt to create, update or delete a Delivery Service. This allows users with higher level permissions (ops or admin) to review the changes for completeness and accuracy before deploying the changes. In addition, most Delivery Service changes require cache configuration updates (aka queue updates) and/or a CDN snapshot. Both of these actions are reserved for users with elevated per [...]
+When enabled in :file:`traffic_portal_properties.json`, Delivery Service Requests are created when *all* users attempt to create, update or delete a :term:`Delivery Service`. This allows users with higher level permissions ("operations" or "admin") to review the changes for completeness and accuracy before deploying the changes. In addition, most :term:`Delivery Service` changes require cache configuration updates (aka queue updates) and/or a CDN :term:`Snapshot`. Both of these actions a [...]
-A list of the Delivery Service requests associated with your tenant can be found under 'Services' -> 'Delivery Service Requests'
+A list of the Delivery Service requests associated with your :term:`Tenant` can be found under :menuselection:`Services --> Delivery Service Requests`
.. figure:: ../traffic_portal/images/tp_table_ds_requests.png
:width: 60%
@@ -31,11 +31,11 @@ A list of the Delivery Service requests associated with your tenant can be found
Who Can Create a Delivery Service Request and How?
==================================================
-Users with the Portal role (or above) can create Delivery Service Requests by doing one of three things:
+Users with the Portal :term:`Role` (or above) can create Delivery Service Requests by doing one of three things:
-- Creating a new Delivery Service
-- Updating an existing Delivery Service
-- Deleting an exiting Delivery Service
+- Creating a new :term:`Delivery Service`
+- Updating an existing :term:`Delivery Service`
+- Deleting an exiting :term:`Delivery Service`
By performing one of these actions, a Delivery Service Request will be created for you with a status of 'draft' or 'submitted'. You determine the status of your request upon submission. Only change the status of your request to 'submitted' once the request is ready for review and deployment.
@@ -43,7 +43,7 @@ Who Can Fulfill a Delivery Service Request and How?
===================================================
Users with elevated permissions (Operations or above) can fulfill (apply the changes) or reject the Delivery Service Request. In fact, they can do all of the following:
-Update the contents of the Delivery Service request
+Update the contents of the Delivery Service Request
This will update the "Last Edited By" field to indicate who last updated the request.
Assign or Unassign the Delivery Service Request
@@ -53,10 +53,10 @@ Reject the Delivery Service Request
Rejecting a Delivery Service Request will set status to 'rejected' and the request can no longer be modified. This will auto-assign the request to the user doing the rejection.
Fulfill the Delivery Service Request
- Fulfilling a Delivery Service Request will show the requested changes and, once committed, will apply the desired changes and set status to 'pending'. The request is pending because many types of changes will require cache configuration updates (aka queue updates) and/or a CDN snapshot. Once queue updates and/or CDN snapshot is complete, the request should be marked 'complete'.
+ Fulfilling a Delivery Service Request will show the requested changes and, once committed, will apply the desired changes and set status to 'pending'. The request is pending because many types of changes will require :term:`cache server` configuration updates (aka queue updates) and/or a CDN snapshot. Once queue updates and/or CDN snapshot is complete, the request should be marked 'complete'.
Complete the Delivery Service Request
- Only after the Delivery Service Request has been fulfilled and the changes have been applied can a Delivery Service Request be marked as 'complete'. Marking a Delivery Service as 'complete' is currently a manual step because some changes require cache configuration updates (aka queue updates) and/or a CDN snapshot. Once that is done and the changes have been deployed, the request status should be changed from 'pending' to 'complete'.
+ Only after the Delivery Service Request has been fulfilled and the changes have been applied can a Delivery Service Request be marked as 'complete'. Marking a Delivery Service Request as 'complete' is currently a manual step because some changes require :term:`cache server` configuration updates (aka queue updates) and/or a CDN :term:`Snapshot`. Once that is done and the changes have been deployed, the request status should be changed from 'pending' to 'complete'.
Delete the Delivery Service request
Delivery Service Requests with a status of 'draft' or 'submitted' can always be deleted entirely if appropriate.
diff --git a/docs/source/admin/quick_howto/federations.rst b/docs/source/admin/quick_howto/federations.rst
index 2e1191e..629afe1 100644
--- a/docs/source/admin/quick_howto/federations.rst
+++ b/docs/source/admin/quick_howto/federations.rst
@@ -19,7 +19,7 @@
Configure Federations
*********************
-#. Create a user with a federations role ('User Admin' -> 'Users' -> '+' button). This user will need the ability to:
+#. Create a user with a federations role (:menuselection:`User Admin --> Users --> '+' button`). This user will need the ability to:
- Create/edit/delete federations
- Add IPV4 resolvers
@@ -29,21 +29,21 @@ Configure Federations
:scale: 100%
:align: center
-#. As a user with administrative priveleges, create a Federation Mapping by going to 'Services' -> 'Delivery Services' -> 'Federations' under 'More' and then clicking 'Add Federation Mapping'
+#. As a user with administrative privileges, create a Federation Mapping by going to :menuselection:`Services --> :term:`Delivery Service`\ s --> More --> Federations` and then clicking :guilabel:`Add Federation Mapping`.
-#. Choose the Delivery Service to which the federation will be mapped and assign it to the Federation-role user; click Add.
+#. Choose the :term:`Delivery Service` to which the federation will be mapped and assign it to the Federation-role user; click :guilabel:`Add`.
.. figure:: federations/02.png
:scale: 100%
:align: center
-#. After the Federation is added, Traffic Ops will display the Federation. Changes can be made at this time or the Federation can be deleted. Notice that no resolvers have been added to the fedeation yet. This can only be done by the Federation-role user to whom the Fedarated Delivery Service was assigned. If no further action is necessary, the Close button will close the window and display the list of all Federations.
+#. After the Federation is added, Traffic Ops will display the Federation. Changes can be made at this time or the Federation can be deleted. Notice that no resolvers have been added to the Federation yet. This can only be done by the Federation-role user to whom the Federated :term:`Delivery Service` was assigned. If no further action is necessary, the :guilabel:`Close` button will close the window and display the list of all Federations.
.. figure:: federations/03.png
:scale: 100%
:align: center
-#. The federation user logs into either the Traffic Ops API or the Traffic Portal UI and stores the Mojolicious cookie. The Mojolicious cookie can be obtained manually using the debug tools on a web browser or via a command line utility like cURL.
+#. The federation user logs into either the Traffic Ops API or the Traffic Portal UI and stores the Mojolicious cookie. The Mojolicious cookie can be obtained manually using the debug tools on a web browser or via a command line utility like :manpage:`curl(1)`.
.. code-block:: shell
:caption: Example cURL Command
@@ -108,7 +108,7 @@ Configure Federations
:scale: 100%
:align: center
-Any requests made from a client that resolves to one of the federation resolvers will now be given a CNAME from Traffic Router.
+Any requests made from a client that resolves to one of the federation resolvers will now be given a :abbr:`CNAME (Canonical Name)` Record from Traffic Router.
.. code-block:: shell
:caption: Example DNS request (via ``dig``)
diff --git a/docs/source/admin/quick_howto/index.rst b/docs/source/admin/quick_howto/index.rst
index a12dea9..171779d 100644
--- a/docs/source/admin/quick_howto/index.rst
+++ b/docs/source/admin/quick_howto/index.rst
@@ -16,7 +16,7 @@
*******************
Quick How To Guides
*******************
-Traffic Control is a complicated system, and documenting it is not trivial. Sometimes a picture says more than a thousand words, so here are some screen shot based tutorials on how to use some of the more involved features.
+Traffic Control is a complicated system, and documenting it is not trivial. Sometimes a picture says more than a thousand words, so here are some screenshot-based tutorials on how to use some of the more involved features.
.. toctree::
diff --git a/docs/source/admin/quick_howto/multi_site.rst b/docs/source/admin/quick_howto/multi_site.rst
index 493d32f..f919e6b 100644
--- a/docs/source/admin/quick_howto/multi_site.rst
+++ b/docs/source/admin/quick_howto/multi_site.rst
@@ -19,9 +19,8 @@
Configure Multi-Site Origin
***************************
-The following steps will take you through the procedure of setting up a Multi-Site Origin (MSO).
-
-#. Create :term:`Cache Group`\ s for the origin locations, and assign the appropriate parent-child relationship between the mid and origin :term:`Cache Group`\ s. Each mid :term:`Cache Group` can be assigned a primary and secondary origin parent :term:`Cache Group`. When the mid cache parent configuration is generated, origins in the primary :term:`Cache Group`\ s will be listed first, followed by origins in the secondary :term:`Cache Group`. Origin servers assigned to the Delivery Servi [...]
+The following steps will take you through the procedure of setting up an :abbr:`MSO (Multi-Site Origin)`.
+#. Create :term:`Cache Group`\ s for the origin locations, and assign the appropriate parent-child relationship between the Mid-tier :term:`Cache Group`\ (s) and origin :term:`Cache Group`\ s. Each Mid-tier :term:`Cache Group` can be assigned a primary and secondary origin parent :term:`Cache Group`. When the :term:`Cache Group` parent configuration is generated, origins in the primary :term:`Cache Group`\ s will be listed first, followed by origins in the secondary :term:`Cache Group`. [...]
.. figure:: multi_site/00.png
:scale: 100%
@@ -39,35 +38,35 @@ The following steps will take you through the procedure of setting up a Multi-Si
:scale: 100%
:align: center
-#. Check the multi-site check box in the delivery service screen:
+#. Check the multi-site check box in the :term:`Delivery Service`\ screen:
.. figure:: multi_site/mso-enable.png
:scale: 100%
:align: center
-#. Assign the org servers to the delivery service that will have the multi site feature. Org servers assigned to a delivery service with multi-site checked will be assigned to be the origin servers for this DS.
+#. Assign the org servers to the :term:`Delivery Service` that will have the multi site feature. Origin servers assigned to a :term:`Delivery Service` with multi-site checked will be assigned to be the origin servers for this :term:`Delivery Service`.
.. figure:: multi_site/03.png
:scale: 100%
:align: center
- .. Note:: “Origin Server Base URL” uniqueness: In order to enable MID caches to distinguish delivery services by different MSO algorithms while performing parent fail-over, it requires that “Origin Server Base URL” (OSBU) for each MSO-enabled Delivery Service is unique. This means that the OSBU of a MSO-enabled Delivery Service should be different with the OSBUs of any other Delivery Service, regardless of whether they are MSO-enabled or not. The exceptions to this rule are:
+ .. Note:: “Origin Server Base URL” uniqueness: In order to enable Mid-tier :term:`Cache Group` to distinguish :term:`Delivery Service`\ s by different :abbr:`MSO (Multi-Site Origin)` algorithms while performing parent fail-over, it requires that :abbr:`OSBU (Origin Server Base URL)` for each :abbr:`MSO (Multi-Site Origin)`\ -enabled :term:`Delivery Service` is unique. This means that the :abbr:`OSBU (Origin Server Base URL)` of an :abbr:`MSO (Multi-Site Origin)`\ -enabled :term:`Deliver [...]
- - If there are multiple CDNs created on the same Traffic Ops, delivery services across different CDNs may have the same OSBU configured.
- - If several delivery services in the same CDN have the same MSO algorithm configured, they may share the same OSBU.
- - If delivery services are assigned with different MID :term:`Cache Group`\ s respectively, they can share the same OSBU.
- - This OSBU must be valid - ATS will perform a DNS lookup on this FQDN even if IPs, not DNS, are used in the parent.config.
- - The OSBU entered as the "Origin Server Base URL" will be sent to the origins as a host header. All origins must be configured to respond to this host.
+ - If there are multiple CDNs created on the same Traffic Ops, :term:`Delivery Service`\ s across different CDNs may have the same :abbr:`OSBU (Origin Server Base URL)` configured.
+ - If several :term:`Delivery Service`\ s in the same CDN have the same :abbr:`MSO (Multi-Site Origin)` algorithm configured, they may share the same :abbr:`OSBU (Origin Server Base URL)`.
+ - If delivery services are assigned with different Mid-tier :term:`Cache Group`\ s respectively, they can share the same :abbr:`OSBU (Origin Server Base URL)`.
+ - This :abbr:`OSBU (Origin Server Base URL)` must be valid - :abbr:`ATS (Apache Traffic Server)` will perform a DNS lookup on this :abbr:`FQDN (Fully Qualified Domain Name)` even if IPs, not DNS, are used in the :file:`parent.config`.
+ - The :abbr:`OSBU (Origin Server Base URL)` entered as the "Origin Server Base URL" will be sent to the origins as a host header. All origins must be configured to respond to this host.
-#. Create a delivery service profile. This must be done to set the MSO algorithm. Also, as of ATS 6.x, multi-site options must be set as parameters within the parent.config. Header rewrite parameters will be ignored. See `ATS parent.config <https://docs.trafficserver.apache.org/en/6.2.x/admin-guide/files/parent.config.en.html>`_ for more details. These parameters are now handled by the creation of a delivery service profile.
+#. Create a delivery service profile. This must be done to set the :abbr:`MSO (Multi-Site Origin)` algorithm. Also, as of :abbr:`ATS (Apache Traffic Server)` 6.x, multi-site options must be set as parameters within the :file:`parent.config`. Header rewrite parameters will be ignored. See `ATS parent.config <https://docs.trafficserver.apache.org/en/6.2.x/admin-guide/files/parent.config.en.html>`_ for more details. These parameters are now handled by the creation of a :term:`Delivery Servi [...]
- a) Create a profile of the type DS_PROFILE for the delivery service in question.
+ a) Create a profile of the type ``DS_PROFILE`` for the :term:`Delivery Service` in question.
.. figure:: multi_site/ds_profile.png
:scale: 50%
:align: center
- #) Click "Show profile parameters" to bring up the parameters screen for the profile. Create parameters for the following:
+ #) Click :guilabel:`Show profile parameters` to bring up the parameters screen for the profile. Create parameters for the following:
+----------------------------------------+------------------+--------------------------+-------------------------+
| Parameter Name | Config File Name | Value | ATS parent.config value |
@@ -96,9 +95,8 @@ The following steps will take you through the procedure of setting up a Multi-Si
:scale: 100%
:align: center
- #) In the delivery service page, select the newly created DS_PROFILE and save the delivery service.
+ #) In the :term:`Delivery Service` page, select the newly created ``DS_PROFILE`` and save the :term:`Delivery Service`.
#. Turn on parent_proxy_routing in the MID profile.
-.. Note:: Support for multisite configurations with single-layer CDNs is now available. If a cachegroup's defined parents are either blank or of the type ORG_LOC, that cache's parent.config will be generated as a top layer cache, even if it is an edge. In the past, parent.config generation was strictly determined by cache type. The new method examines the parent cachegroup definitions and generates the parent.config accordingly.
-
+.. Note:: Support for multisite configurations with single-layer CDNs is now available. If a :term:`Cache Group`\ s defined parents are either blank or of the type ``ORG_LOC``, that :term:`cache server`'s ``parent.config`` will be generated as a top layer cache, even if it is an edge. In the past, ``parent.config`` generation was strictly determined by cache type. The new method examines the parent :term:`Cache Group` definitions and generates the :file:`parent.config` accordingly.
diff --git a/docs/source/admin/quick_howto/regionalgeo.rst b/docs/source/admin/quick_howto/regionalgeo.rst
index e2859f7..13de32c 100644
--- a/docs/source/admin/quick_howto/regionalgeo.rst
+++ b/docs/source/admin/quick_howto/regionalgeo.rst
@@ -18,9 +18,9 @@
*************************************
Configure Regional Geo-blocking (RGB)
*************************************
-.. Note:: RGB is only supported for HTTP delivery services.
+.. Note:: :abbr:`RGB (Regional Geographic-based Blocking)` is only supported for HTTP :term:`Delivery Service`\ s.
-#. Prepare an RGB configuration file. RGB uses a configuration file in JSON format to define regional geographic blocking rules for Delivery Services. The file needs to be put on an HTTP server accessible to Traffic Router.
+#. Prepare an :abbr:`RGB (Regional Geographic-based Blocking)` configuration file. :abbr:`RGB (Regional Geographic-based Blocking)` uses a configuration file in JSON format to define regional geographic blocking rules for :term:`Delivery Service`\ s. The file needs to be put on an HTTP server accessible to Traffic Router.
.. code-block:: json
:caption: Example Configuration File
@@ -45,35 +45,35 @@ Configure Regional Geo-blocking (RGB)
}
``deliveryServiceId``
- Should be equal to the ``ID`` or ``xml_id`` field of the intended Delivery Service as configured in Traffic Portal
+ Should be equal to the ``ID`` or ``xml_id`` field of the intended :term:`Delivery Service` as configured in Traffic Portal
``urlRegex``
A regular expression to be used to determine to what URLs the rule shall apply; a URL that matches it is subject to the rule
``geoLocation``
- An object that currently supports only the keys ``includePostalCode`` and ``excludePostalCode`` (mutually exclusive). When the ``includePostalCode`` key is used, only the clients whose Forward Sortation Areas (FSA)s - the first three postal characters of Canadian postal codes - are in the ``includePostalCode`` list are able to view the content at URLs matched by the ``urlRegex``. When ``excludePostalCode`` is used, any client whose FSA is not in the ``excludePostalCode`` list will be a [...]
+ An object that currently supports only the keys ``includePostalCode`` and ``excludePostalCode`` (mutually exclusive). When the ``includePostalCode`` key is used, only the clients whose :abbr:`FSA (Forward Sortation Areas)`\ s - the first three postal characters of Canadian postal codes - are in the ``includePostalCode`` list are able to view the content at URLs matched by the ``urlRegex``. When ``excludePostalCode`` is used, any client whose :abbr:`FSA (Forward Sortation Areas)` is not [...]
``redirectUrl``
- The URL that will be returned to the blocked clients. Without a domain name in the URL, the URL will still be served in the same Delivery Service. Thus Traffic Router will redirect the client to a chosen cache server assigned to the Delivery Service. If the URL includes a domain name, Traffic Router simply redirects the client to the defined URL. In the later case, the redirect URL must not match the ``urlRegex`` value, or an infinite loop of HTTP ``302 Found`` responses will occur at [...]
+ The URL that will be returned to the blocked clients. Without a domain name in the URL, the URL will still be served in the same :term:`Delivery Service`. Thus Traffic Router will redirect the client to a chosen :term:`cache server` assigned to the :term:`Delivery Service`. If the URL includes a domain name, Traffic Router simply redirects the client to the defined URL. In the later case, the redirect URL must not match the ``urlRegex`` value, or an infinite loop of HTTP ``302 Found`` [...]
``ipWhiteList``
- An optional element that is an array of CIDR (Classless Inter-Domain Routing) blocks indicating the IPv4 subnets that are allowed by the rule. If this list exists and the value is not empty, client IP will be matched against the CIDR list, bypassing the value of ``geoLocation``. If there is no match in the white list, Traffic Router defers to the value of ``geoLocation`` to determine if content ought to be blocked.
+ An optional element that is an array of :abbr:`CIDR (Classless Inter-Domain Routing)` blocks indicating the IPv4 subnets that are allowed by the rule. If this list exists and the value is not empty, client IP will be matched against the :abbr:`CIDR (Classless Inter-Domain Routing)` list, bypassing the value of ``geoLocation``. If there is no match in the white list, Traffic Router defers to the value of ``geoLocation`` to determine if content ought to be blocked.
-#. Add RGB parameters in Traffic Portal to the Delivery Service's Traffic Router(s)'s profile(s). The ``configFile`` field should be set to ``CRConfig.json``, and the following two parameter name/values need to be specified:
+#. Add :abbr:`RGB (Regional Geographic-based Blocking)` parameters in Traffic Portal to the :term:`Delivery Service`'s Traffic Router(s)'s profile(s). The ``configFile`` field should be set to ``CRConfig.json``, and the following two parameter name/values need to be specified:
``regional_geoblocking.polling.url``
The URL of the RGB configuration file. Traffic Router will fetch the file from this URL using an HTTP ``GET`` request.
``regional_geoblocking.polling.interval``
- The interval on which Traffic Router polls the RGB configuration file.
+ The interval on which Traffic Router polls the :abbr:`RGB (Regional Geographic-based Blocking)` configuration file.
.. figure:: regionalgeo/01.png
:scale: 100%
:align: center
-#. Enable RGB for a delivery service
+#. Enable RGB for a :term:`Delivery Service`
.. figure:: regionalgeo/02.png
:scale: 100%
:align: center
-#. Go to Tools->Snapshot CRConfig, perform “Diff CRConfig” and click "Write CRConfig".
+#. Go to :menuselection:`Tools --> Snapshot CRConfig`, perform :guilabel:`Diff CRConfig` and click :guilabel:`Write CRConfig`.
.. figure:: regionalgeo/03.png
:scale: 70%
@@ -83,24 +83,25 @@ Traffic Router Access Log
=========================
.. seealso:: :ref:`tr-logs`
-RGB extends the ``rtype`` field and adds a new field ``rgb`` in Traffic Router access.log to help to monitor this feature. A value of ``RGALT`` in the ``rtype`` field indicates that a request is redirected to an alternate URL by RGB; a value of ``RGDENY`` indicates that a request is denied by RGB because there is no matching rule in the RGB configuration file for this request. When RGB is enabled, the ``RGB`` field will be non-empty with following format::
+RGB extends the ``rtype`` field and adds a new field ``rgb`` in Traffic Router access.log to help to monitor this feature. A value of ``RGALT`` in the ``rtype`` field indicates that a request is redirected to an alternate URL by :abbr:`RGB (Regional Geographic-based Blocking)`; a value of ``RGDENY`` indicates that a request is denied by :abbr:`RGB (Regional Geographic-based Blocking)` because there is no matching rule in the :abbr:`RGB (Regional Geographic-based Blocking)` configuration [...]
- {FSA}:{allowed/disallowed}:{include/exclude postal}:{fallback config}:{allowed by whitelist}
+``{FSA}:{allowed/disallowed}:{include/exclude postal}:{fallback config}:{allowed by whitelist}``
FSA
- FSA part of the client’s postal code, which is retrieved from a geographic location database. If this field is empty, a dash (“-“) is filled in.
+ :dfn:`FSA` part of the client’s postal code, which is retrieved from a geographic location database. If this field is empty, a dash (“-“) is filled in.
allowed/disallowed
- This flag shows if a request was allowed or disallowed by RGB (1 for yes, and 0 for no).
+ This flag shows if a request was allowed or disallowed by :abbr:`RGB (Regional Geographic-based Blocking)` (1 for yes, and 0 for no).
include/exclude postal
This shows that when a rule in JSON is matched for a request, it's value is "I" if the rule matched because of an ``includePostalCode`` rule, "X" if the rule matched because of an ``excludePostalCode`` rule, or "-" if no rule matched.
fallback config
- When Traffic Router fails to parse an RGB configuration file as JSON, Traffic Router will handle requests with latest valid configuration that it had, but will set the ``fallback config`` flag to 1. If no fall-back occurred, then the flag is set to 0.
+ When Traffic Router fails to parse an :abbr:`RGB (Regional Geographic-based Blocking)` configuration file as JSON, Traffic Router will handle requests with latest valid configuration that it had, but will set the ``fallback config`` flag to 1. If no fall-back occurred, then the flag is set to 0.
allowed by whitelist
If a request is allowed by a ``whitelist`` field in the configuration, this flag is set to 1; for all other cases, it is 0.
-Example::
+.. code-block:: squid
+ :caption: Example
1446442214.685 qtype=HTTP chi=129.100.254.79 url="http://foo.geo2.cdn.com/live5.m3u8" cqhm=GET cqhv=HTTP/1.1 rtype=GEO rloc="-" rdtl=- rerr="-" rgb="N6G:1:X:0:0" pssc=302 ttms=3 rurl=http://cent6-44.geo2.cdn.com/live5.m3u8 rh="-"
diff --git a/docs/source/admin/quick_howto/steering.rst b/docs/source/admin/quick_howto/steering.rst
index f1d3325..735872a 100644
--- a/docs/source/admin/quick_howto/steering.rst
+++ b/docs/source/admin/quick_howto/steering.rst
@@ -19,25 +19,25 @@
Configure Delivery Service Steering
***********************************
-#. Create two target Delivery Services in Traffic Ops. They must both be HTTP Delivery Services that are part of the same CDN.
+#. Create two target :term:`Delivery Service`\ s in Traffic Portal. They must both be HTTP :term:`Delivery Service`\ s that are part of the same CDN.
.. figure:: steering/01.png
:width: 80%
:align: center
:alt: Table of Target Delivery Services
- Target Delivery Services
+ Target :term:`Delivery Service`\ s
-#. Create a Delivery Service with Type STEERING or CLIENT_STEERING in Traffic Ops.
+#. Create a :term:`Delivery Service` with Type ``STEERING`` or ``CLIENT_STEERING`` in Traffic Ops.
.. figure:: steering/02.png
:width: 50%
:align: center
:alt: Delivery Service Creation Page for STEERING Delivery Service
- Creating a STEERING Delivery Service
+ Creating a STEERING :term:`Delivery Service`
-#. In the 'More' drop-down menu, click 'View Targets' and then use the blue '+' to assign targets.
+#. Click :menuselection:`More --> View Targets` and then use the blue :guilabel:`+` button to assign targets.
.. figure:: steering/03.png
:width: 50%
@@ -47,44 +47,10 @@ Configure Delivery Service Steering
STEERING Targets
-#. If desired, a 'steering' user can create filters for the target Delivery Services (only available via API). Sample JSON request body:
-
- .. code-block:: json
-
- {
- "filters": [
- {
- "pattern": ".*\\gototarget1\\..*",
- "deliveryService": "target-deliveryservice-1"
- }
- ],
- "targets": [
- {
- "weight": "1000",
- "deliveryService": "target-deliveryservice-1"
- },
- {
- "weight": "9000",
- "deliveryService": "target-deliveryservice-2"
- }
- {
- "order": -1,
- "deliveryService": "target-deliveryservice-3"
- }
- {
- "order": 3,
- "deliveryService": "target-deliveryservice-4"
- }
- ]
- }
-
- Sample script of ``curl`` commands to accomplish this, given the above request body is saved as ``/tmp/steering.json`` [1]_:
-
- .. code-block:: shell
-
- curl -sc cookie.jar https://to.cdn.local/api/1.2/user/login -d '{"u":"admin","p":"twelve"}'
- curl -sb cookie.jar -XPUT "https://to.cdn.local/internal/api/1.2/steering/steering-ds" -d @/tmp/steering.json
-
-#. Any requests to Traffic Router for the steering Delivery Service should now be routed to target Delivery Services based on configured weight or order.
-
-.. [1] This example also assumes that the Traffic Ops instance is running at ``to.cdn.local`` and the administrative username and password are ``admin`` and ``twelve``, respectively. This is *not* recommended in production, but merely meant to replicate the default 'CDN-in-a-box' environment!
+#. If desired, a 'steering' :term:`Role` user can create filters for the target :term:`Delivery Service`\ s using :ref:`to-api-steering-id-targets`
+
+ .. note:: This is only available via the :ref:`to-api`; no functionality for manipulating steering targets is offered by Traffic Portal. This feature has been requested and is tracked by `GitHub Issue #2811 <https://github.com/apache/trafficcontrol/issues/2811>`_
+
+#. Any requests to Traffic Router for the steering :term:`Delivery Service`\ should now be routed to target :term:`Delivery Service`\ s based on configured weight or order.
+
+.. note:: This example assumes that the Traffic Ops instance is running at ``to.cdn.local`` and the administrative username and password are ``admin`` and ``twelve``, respectively. This is *not* recommended in production, but merely meant to replicate the default :ref:`ciab` environment!
diff --git a/docs/source/admin/traffic_monitor.rst b/docs/source/admin/traffic_monitor.rst
index 8a73639..85dab8c 100755
--- a/docs/source/admin/traffic_monitor.rst
+++ b/docs/source/admin/traffic_monitor.rst
@@ -21,58 +21,49 @@ Traffic Monitor Administration
Installing Traffic Monitor
==========================
-
The following are hard requirements requirements for Traffic Monitor to operate:
* CentOS 7+
* Successful install of Traffic Ops (usually on a separate machine)
* Administrative access to the Traffic Ops (usually on a separate machine)
-
These are the recommended hardware specifications for a production deployment of Traffic Monitor:
* 8 CPUs
* 16GB of RAM
-* It is also recommended that you know the physical address of the site where the Traffic Monitor machine lives for optimal performance
+* It is also recommended that you know the geographic coordinates and/or mailing address of the site where the Traffic Monitor machine lives for optimal performance
#. Enter the Traffic Monitor server into Traffic Portal
.. note:: For legacy compatibility reasons, the 'Type' field of a new Traffic Monitor server must be 'RASCAL'.
-#. Make sure the Fully Qualified Domain Name (FQDN) of the Traffic Monitor is resolvable in DNS.
-#. Install Traffic Monitor, either from source or by running the command ``yum install traffic_monitor`` as the root user, or with ``sudo``.
-#. Configure Traffic Monitor. See :ref:`here <tm-configure>`
-#. Start the service, usually by running the command ``systemctl start traffic_monitor`` as the root user, or with ``sudo``
+#. Make sure the :abbr:`FQDN (Fully Qualified Domain Name)` of the Traffic Monitor is resolvable in DNS.
+#. Install Traffic Monitor, either from source or by installing a :file:`traffic_monitor-{version string}.rpm` package generated by the instructions in :ref:`dev-building` with :manpage:`yum(8)` or :manpage:`rpm(8)`
+#. Configure Traffic Monitor according to `Configuring Traffic Monitor`_
+#. Start Traffic Monitor, usually by starting its :manpage:`systemd(1)` service
#. Verify Traffic Monitor is running by e.g. opening your preferred web browser to port 80 on the Traffic Monitor host.
+.. _tm-configure:
+
Configuring Traffic Monitor
===========================
Configuration Overview
----------------------
-
-.. _tm-configure:
-
-Traffic Monitor is configured via two JSON configuration files, ``traffic_ops.cfg`` and ``traffic_monitor.cfg``, by default located in the ``conf`` directory in the install location. ``traffic_ops.cfg`` contains Traffic Ops connection information. Specify the URL, username, and password for the instance of Traffic Ops of which this Traffic Monitor is a member. ``traffic_monitor.cfg`` contains log file locations, as well as detailed application configuration variables such as processing f [...]
+Traffic Monitor is configured via two JSON configuration files, :file:`traffic_ops.cfg` and :file:`traffic_monitor.cfg`, by default located in the ``conf`` directory in the install location. :file:`traffic_ops.cfg` contains Traffic Ops connection information. Specify the URL, username, and password for the instance of Traffic Ops of which this Traffic Monitor is a member. :file:`traffic_monitor.cfg` contains log file locations, as well as detailed application configuration variables such [...]
Stat and Health Flush Configuration
-----------------------------------
+The Monitor has a health flush interval, a stat flush interval, and a stat buffer interval. Recall that the monitor polls both stats and health. The health poll is so small and fast, a buffer is largely unnecessary. However, in a large CDN, the stat poll may involve thousands of :term:`cache server` s with thousands of stats each, or more, and CPU may be a bottleneck.
-The Monitor has a health flush interval, a stat flush interval, and a stat buffer interval. Recall that the monitor polls both stats and health. The health poll is so small and fast, a buffer is largely unnecessary. However, on a large CDN, the stat poll may involve thousands of caches with thousands of stats each, or more, and CPU may be a bottleneck.
-
-The flush intervals, ``health_flush_interval_ms`` and ``stat_flush_interval_ms``, indicate how often to flush stats or health, if results are continuously coming in with no break. This prevents starvation. Ideally, if there is enough CPU, the flushes should never occur.
-
-The default flush times are 200 milliseconds, which is suggested as a reasonable starting point, from which operators may adjust them higher or lower, depending on the need to get health data and stop serving to unhealthy caches as quickly as possible, balanced by the need to reduce CPU usage.
+The flush intervals, ``health_flush_interval_ms`` and ``stat_flush_interval_ms``, indicate how often to flush stats or health, if results are continuously coming in with no break. This prevents starvation. Ideally, if there is enough CPU, the flushes should never occur. The default flush times are 200 milliseconds, which is suggested as a reasonable starting point; operators may adjust them higher or lower depending on the need to get health data and stop directing client traffic to unhe [...]
The stat buffer interval, ``stat_buffer_interval_ms``, also provides a temporal buffer for stat processing. Stats will not be processed except after this interval, whereupon all pending stats will be processed, unless the flush interval occurs as a starvation safety. The stat buffer and flush intervals may be thought of as a state machine with two states: the "buffer state" accepts results until the buffer interval has elapsed, whereupon the "flush state" is entered, and results are acce [...]
-Note that this means the stat buffer interval acts as "bufferbloat," increasing the average and maximum time a cache may be down before it is processed and marked as unhealthy. If the stat buffer interval is non-zero, the average time a cache may be down before being marked unavailable is half the poll time plus half the stat buffer interval, and the maximum time is the poll time plus the stat buffer interval. For example, if the stat poll time is 6 seconds, and the stat buffer interval [...]
-
-The default stat buffer interval is 0, which results in all stats being processed as quickly as possible. This is recommended, if a CDN operator is okay with the CPU usage and processing time, to minimize the time a cache may be unhealthy before being marked unavailable. If operators feel the need to set the stat buffer interval to a nonzero value, a recommended starting point is 5 milliseconds.
-
-It is not recommended to set either flush interval to 0, irrespective of the stat buffer interval. This will cause new results to be immediately processed, with little to no processing of multiple results concurrently. Result processing does not scale linearly, for example, it is not significantly more CPU or time to process 100 results than 10 at once. Thus, a flush interval which is too low will cause increased CPU usage, and potentially increased overall poll times, with little or no [...]
+Note that this means the stat buffer interval acts as "bufferbloat," increasing the average and maximum time a :term:`cache server` may be down before it is processed and marked as unhealthy. If the stat buffer interval is non-zero, the average time a :term:`cache server` may be down before being marked unavailable is half the poll time plus half the stat buffer interval, and the maximum time is the poll time plus the stat buffer interval. For example, if the stat poll time is 6 seconds, [...]
+It is not recommended to set either flush interval to 0, regardless of the stat buffer interval. This will cause new results to be immediately processed, with little to no processing of multiple results concurrently. Result processing does not scale linearly. For example, processing 100 results at once does not cost significantly more CPU usage or time than processing 10 results at once. Thus, a flush interval which is too low will cause increased CPU usage, and potentially increased ove [...]
Troubleshooting and Log Files
=============================
-Traffic Monitor log files are in ``/opt/traffic_monitor/var/log/``.
+Traffic Monitor log files are in :file:`/opt/traffic_monitor/var/log/`.
diff --git a/docs/source/admin/traffic_ops/configuration.rst b/docs/source/admin/traffic_ops/configuration.rst
index 7ca4a213..8d75494 100644
--- a/docs/source/admin/traffic_ops/configuration.rst
+++ b/docs/source/admin/traffic_ops/configuration.rst
@@ -13,10 +13,11 @@
.. limitations under the License.
..
+.. _`regex_revalidate plugin`: https://docs.trafficserver.apache.org/en/7.1.x/admin-guide/plugins/regex_revalidate.en.html
+
*************************
Traffic Ops - Configuring
*************************
-
Follow the steps below to configure the newly installed Traffic Ops Instance.
Installing the SSL Certificate
@@ -25,10 +26,8 @@ By default, Traffic Ops runs as an SSL web server (that is, over HTTPS), and a c
Self-signed Certificate (Development)
-------------------------------------
-
-Example Procedure
-
-.. code-block:: shell
+.. code-block:: console
+ :caption: Example Procedure
$ openssl genrsa -des3 -passout pass:x -out localhost.pass.key 2048
Generating RSA private key, 2048 bit long modulus
@@ -69,11 +68,12 @@ Example Procedure
Certificate from Certificate Authority (Production)
---------------------------------------------------
-.. Note:: You will need to know the appropriate answers when generating the certificate request file ``trafficopss.csr`` below.
+.. Note:: You will need to know the appropriate answers when generating the certificate request file :file:`trafficopss.csr` below.
Example Procedure
-
-.. code-block:: shell
+"""""""""""""""""
+.. code-block:: console
+ :caption: Example Procedure
$ openssl genrsa -des3 -passout pass:x -out trafficops.pass.key 2048
Generating RSA private key, 2048 bit long modulus
@@ -82,9 +82,10 @@ Example Procedure
writing RSA key
$ rm localhost.pass.key
-Generate the Certificate Signing Request (CSR) file needed for Certificate Authority (CA) request
+Generate the :abbr:`CSR (Certificate Signing Request)` file needed for :abbr:`CA (Certificate Authority)` request
-.. code-block:: shell
+.. code-block:: console
+ :caption: Example Certificate Signing Request File Generation
$ openssl req -new -key trafficops.key -out trafficops.csr
You are about to be asked to enter information that will be incorporated
@@ -109,18 +110,20 @@ Generate the Certificate Signing Request (CSR) file needed for Certificate Autho
$ sudo cp trafficops.key /etc/pki/tls/private
$ sudo chown trafops:trafops /etc/pki/tls/private/trafficops.key
-You must then take the output file ``trafficops.csr`` and submit a request to your Certificate Authority (CA). Once you get approved and receive your ``trafficops.crt`` file
+You must then take the output file :file:`trafficops.csr` and submit a request to your :abbr:`CA (Certificate Authority)`. Once you get approved and receive your :file:`trafficops.crt` file
.. code-block:: shell
+ :caption: Certificate Installation
- $ sudo cp trafficops.crt /etc/pki/tls/certs
- $ sudo chown trafops:trafops /etc/pki/tls/certs/trafficops.crt
+ sudo cp trafficops.crt /etc/pki/tls/certs
+ sudo chown trafops:trafops /etc/pki/tls/certs/trafficops.crt
-If necessary, install the CA certificate's ``.pem`` and ``.crt`` files in ``/etc/pki/tls/certs``.
+If necessary, install the :abbr:`CA (Certificate Authority) certificate's ``.pem`` and ``.crt`` files in ``/etc/pki/tls/certs``.
-You will need to update the file ``/opt/traffic_ops/app/conf/cdn.conf`` with the any necessary changes. e.g. given trafficops.crt and trafficops.key
+You will need to update the file :file:`/opt/traffic_ops/app/conf/cdn.conf` with the any necessary changes.
-.. code-block:: perl
+.. code-block:: text
+ :caption: Sample 'listen' Line When Path to ``trafficops.crt`` and ``trafficops.key`` are Known
'hypnotoad' => ...
'listen' => 'https://[::]:443?cert=/etc/pki/tls/certs/trafficops.crt&key=/etc/pki/tls/private/trafficops.key&ca=/etc/pki/tls/certs/localhost.ca&verify=0x00&ciphers=AES128-GCM-SHA256:HIGH:!RC4:!MD5:!aNULL:!EDH:!ED'
@@ -134,206 +137,221 @@ Content Delivery Networks
Profile Parameters
------------------
-Many of the settings for the different servers in a Traffic Control CDN are controlled by parameters in the Configure -> Parameters view of Traffic Portal. Parameters are grouped in profiles and profiles are assigned to a server or a Delivery Service. For a typical cache there are hundreds of configuration settings to apply. The Traffic Portal 'Parameters' view contains the defined settings. To make life easier, Traffic Portal allows for duplication, comparison, import and export of prof [...]
-
-
-.. index::
- Global Profile
-
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Config File | Value |
-+==========================+===============+=======================================================================================================================================+
-| tm.url | global | The URL where this Traffic Ops instance is being served from. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| tm.rev_proxy.url | global | Not required. The URL where the Traffic Ops Configuration file cache instance is being served from. Requires Traffic Ops ORT 2.1 and |
-| | | above. When configured, ORT will request configuration files via this FQDN, which should be setup as a reverse proxy to the Traffic |
-| | | Ops host or hosts. Suggested cache lifetime for these files is ~3 minutes or less. This setting allows for greater scalability of a |
-| | | CDN maintained by Traffic Ops by caching configuration files of profile and CDN scope. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| tm.toolname | global | The name of the Traffic Ops tool. Usually "Traffic Ops". Used in the About screen and in the comments headers of the files generated. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| tm.infourl | global | This is the "for more information go here" URL, which is visible in the About page. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| tm.logourl | global | This is the URL of the logo for Traffic Ops and can be relative if the logo is under ``traffic_ops/app/public``. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| tm.instance_name | global | The name of the Traffic Ops instance. Can be used when multiple instances are active. Visible in the About page. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| tm.traffic_mon_fwd_proxy | global | When collecting stats from Traffic Monitor, Traffic Ops uses this forward proxy to pull the stats through. |
-| | | This can be any of the MID tier caches, or a forward cache specifically deployed for this purpose. Setting |
-| | | this variable can significantly lighten the load on the Traffic Monitor system and it is recommended to |
-| | | set this parameter on a production system. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| geolocation.polling.url | CRConfig.json | The location of a GeoIP2 database for Traffic Router to use. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| geolocation6.polling.url | CRConfig.json | The location of an IPv6 GeoIP2 database for Traffic Router to use when routing IPv6 traffic. |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| maxmind.default.override | CRConfig.json | The destination geographic coordinates to use for client location when the GeoIP2 database returns a default location that matches |
-| | | the country code. This parameter can be specified multiple times with different values to support default overrides for multiple |
-| | | countries. The reason for the name 'MaxMind' is because that is the default GeoIP2 implementation used by Comcast production servers. |
-| | | Format: ``<Country Code>;<Latitude>,<Longitude>`` Ex: ``US;37.751,-97.822`` |
-+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+Many of the settings for the different servers in a Traffic Control CDN are controlled by parameters in the :menuselection:`Configure --> Parameters` view of Traffic Portal. Parameters are grouped in profiles and profiles are assigned to a server or a :term:`Delivery Service`. For a typical cache there are hundreds of configuration settings to apply. The Traffic Portal :menuselection:`Parameters` view contains the defined settings. To make life easier, Traffic Portal allows for duplicati [...]
+
+.. _global-profile-parameters:
+.. table:: Global Profile Parameters
+
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | ConfigFile | Value |
+ +==========================+===============+=======================================================================================================================================+
+ | tm.url | global | The URL at which this Traffic Ops instance services requests |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | tm.rev_proxy.url | global | Not required. The URL where a caching proxy for configuration files generated by Traffic Ops may be found. Requires a minimum |
+ | | | :term:`ORT` version of 2.1. When configured, :term:`ORT` will request configuration files via this |
+ | | | :abbr:`FQDN (Fully Qualified Domain Name)`, which should be set up as a reverse proxy to the Traffic Ops server(s). The suggested |
+ | | | cache lifetime for these files is 3 minutes or less. This setting allows for greater scalability of a CDN maintained by Traffic Ops |
+ | | | by caching configuration files of profile and CDN scope, as generating these is a very computationally expensive process |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | tm.toolname | global | The name of the Traffic Ops tool. Usually "Traffic Ops" - this will appear in the comment headers of the generated files |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | tm.infourl | global | This is the "for more information go here" URL, which used to be visible in the "About" page of the now-deprecated Traffic Ops UI |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | tm.logourl | global | This is the URL of the logo for Traffic Ops and can be relative if the logo is under :file:`traffic_ops/app/public` |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | tm.instance_name | global | The name of the Traffic Ops instance - typically to distinguish instances when multiple are active |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | tm.traffic_mon_fwd_proxy | global | When collecting stats from Traffic Monitor, Traffic Ops will use this forward proxy instead of the actual Traffic Monitor host. |
+ | | | This can be any of the MID tier caches, or a forward cache specifically deployed for this purpose. Setting |
+ | | | this variable can significantly lighten the load on the Traffic Monitor system and it is recommended to |
+ | | | set this parameter on a production system. |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | geolocation.polling.url | CRConfig.json | The location of a geographic IP mapping database for Traffic Router instances to use |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | geolocation6.polling.url | CRConfig.json | The location of a geographic IPv6 mapping database for Traffic Router instances to use |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
+ | maxmind.default.override | CRConfig.json | The destination geographic coordinates to use for client location when the geographic IP mapping database returns a default location |
+ | | | that matches the country code. This parameter can be specified multiple times with different values to support default overrides for |
+ | | | multiple countries. The reason for the name "maxmind" is because MaxMind's GeoIP2 database is the default geographic IP mapping |
+ | | | database implementation used by Comcast production servers (and the only officially supported implementation at the time of this |
+ | | | writing). The format of this Parameter's value is: ``<Country Code>;<Latitude>,<Longitude>``, e.g. ``US;37.751,-97.822`` |
+ +--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
These parameters should be set to reflect the local environment.
-
-After running the ``postinstall`` script, Traffic Ops has the following profiles pre-loaded:
-
-+----------+-------------------------------------------------------------------------------------------------+
-| Name | Description |
-+==========+=================================================================================================+
-| EDGE1 | The profile to be applied to the latest supported version of ATS, when running as an EDGE cache |
-+----------+-------------------------------------------------------------------------------------------------+
-| TR1 | The profile to be applied to the latest version of Traffic Router |
-+----------+-------------------------------------------------------------------------------------------------+
-| TM1 | The profile to be applied to the latest version of Traffic Monitor |
-+----------+-------------------------------------------------------------------------------------------------+
-| MID1 | The profile to be applied to the latest supported version of ATS, when running as an MID cache |
-+----------+-------------------------------------------------------------------------------------------------+
-| RIAK_ALL | Riak profile for all CDNs to be applied to the Traffic Vault servers |
-+----------+-------------------------------------------------------------------------------------------------+
-
-.. Note:: The Traffic Server profiles contain some information that is specific to the hardware being used (most notably the disk configuration), so some parameters will have to be changed to reflect your configuration. Future releases of Traffic Control will separate the hardware and software profiles so it is easier to "mix-and-match" different hardware configurations.
-
-Below is a list of cache parameters that are likely to need changes from the default profiles shipped with Traffic Ops:
-
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Config File | Description |
-+==========================+===================+====================================================================================================================================================================+
-| allow_ip | astats.config | This is a comma separated list of IPv4 Classless Inter-Domain Routing (CIDR) blocks that will have access to the 'astats' statistics on the caches. The Traffic |
-| | | Monitor IP addresses have to be included in this, if they are using IPv4 to monitor the caches. |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| allow_ip6 | astats.config | This is a comma-separated list of IPv6 CIDR blocks that will have access to the 'astats' statistics on the caches. The Traffic Monitor IP addresses have to be |
-| | | included in this, if they are using IPv6 to monitor the caches. |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Drive_Prefix | storage.config | The device path start of the disks. For example, if you have ``/dev/sda`` through ``/dev/sdf`` set this to ``/dev/sd`` |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Drive_Letters | storage.config | The letter part of the disks, in the same example as above set this to ``a,b,c,d,e,f`` |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| purge_allow_ip | ip_allow.config | The IP address range that is allowed to execute the PURGE method on the caches (not related to :ref:`purge`) |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| coalesce_masklen_v4 | ip_allow.config | The mask length to use when coalescing IPv4 networks into one line using `the NetAddr\:\:IP Perl library. <http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm>`_ |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| coalesce_number_v4 | ip_allow.config | The number to use when coalescing IPv4 networks into one line using `the NetAddr\:\:IP Perl library. <http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm>`_ |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| coalesce_masklen_v6 | ip_allow.config | The mask length to use when coalescing IPv6 networks into one line using `the NetAddr\:\:IP Perl library. <http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm>`_ |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| health.threshold.loadavg | rascal.properties | The Unix 'load average' (see ``man uptime``) at which Traffic Router will stop sending traffic to this cache |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| health.threshold.\\ | rascal.properties | The amount of bandwidth (in kilobits per second) that Traffic Router will try to keep available on the cache. For example: "">1500000" means stop sending new |
-| availableBandwidthInKbps | | traffic to this cache when traffic is at 8.5Gbps on a 10Gbps interface. |
-+--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
-Below is a list of Traffic Server plug-ins that need to be configured in the parameter table:
-
-+------------------+---------------+----------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
-| Name | Config File | Description | Details |
-+==================+===============+==========================================================+============================================================================================================+
-| astats_over_http | package | The package version for the ``astats_over_http plugin``. | `astats_over_http <http://trafficcontrol.apache.org/downloads/index.html>`_ |
-+------------------+---------------+----------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
-| trafficserver | package | The package version for the ``trafficserver`` plugin. | `trafficserver <http://trafficcontrol.apache.org/downloads/index.html>`_ |
-+------------------+---------------+----------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
-| regex_revalidate | plugin.config | The configuration to be used for ``regex_revalidate``. | `regex_revalidate <https://docs.trafficserver.apache.org/en/5.3.x/reference/plugins/regex_remap.en.html>`_ |
-+------------------+---------------+----------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
-| remap_stats | plugin.config | The configuration to be used for ``remap_stats``. | `remap_stats <https://github.com/apache/trafficserver/tree/master/plugins/experimental/remap_stats>`_ |
-| | | Value is left blank. | |
-+------------------+---------------+----------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
-
-Below is a list of cache parameters for special configuration, which are unlikely to need changes, but may be useful in particular circumstances:
-
-+--------------------------+-------------------+---------------------------------------------------------------------------------------------------------------------------------+
-| Name | Config File | Description |
-+==========================+===================+=================================================================================================================================+
-| not_a_parent | parent.config | This is a boolean flag and is considered 'true' if it exists and has any value except 'false'. |
-| | | This prevents servers with this parameter in their profile from being inserted into the ``parent.config`` generated for servers |
-| | | with this server's :term:`Cache Group` as a parent of their :term:`Cache Group`. This is primarily useful for when edge caches |
-| | | are configured to have a :term:`Cache Group` of other edge caches as parents (a highly unusual configuration), and it is |
-| | | necessary to exclude some, but not all, edges in the parent :term:`Cache Group` from the ``parent.config`` (for example, |
-| | | because they lack necessary capabilities), but still have all edges in the same :term:`Cache Group` in order to take traffic |
-| | | from ordinary Delivery Services at that :term:`Cache Group`\ 's geographic location. Once again, this is a highly unusual |
-| | | scenario, and under ordinary circumstances this parameter should not exist. |
-+--------------------------+-------------------+---------------------------------------------------------------------------------------------------------------------------------+
-
+After running the :program:`postinstall` script, Traffic Ops has the :ref:`tbl-default-profiles` pre-loaded.
+
+.. _tbl-default-profiles:
+.. table:: Default Profiles
+
+ +----------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +==========+=================================================================================================================================================+
+ | EDGE1 | The profile to be applied to the latest supported version of :abbr:`ATS (Apache Traffic Server)`, when running as an Edge-tier cache |
+ +----------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+ | TR1 | The profile to be applied to the latest version of Traffic Router |
+ +----------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+ | TM1 | The profile to be applied to the latest version of Traffic Monitor |
+ +----------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+ | MID1 | The profile to be applied to the latest supported version of :abbr:`ATS (Apache Traffic Server)`, when running as a Mid-tier cache |
+ +----------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+ | RIAK_ALL | "Riak" profile for all CDNs to be applied to the Traffic Vault servers ("Riak" being the name of the underlying database used by Traffic Vault) |
+ +----------+-------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. Note:: The "EDGE1" and "MID1" profiles contain some information that is specific to the hardware being used (most notably the disk configuration), so some parameters will have to be changed to reflect your configuration. Future releases of Traffic Control will separate the hardware and software profiles so it is easier to "mix-and-match" different hardware configurations. The :ref:`cache-server-hardware-parameters` table tabulates the cache parameters that are likely to need changes f [...]
+
+.. _cache-server-hardware-parameters:
+.. table:: Cache Server Hardware Parameters
+
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | ConfigFile | Description |
+ +===========================================+===================+==============================================================================================================================================+
+ | allow_ip | astats.config | This is a comma-separated list of IPv4 :abbr:`CIDR (Classless Inter-Domain Routing)` blocks that will have access to the 'astats' statistics |
+ | | | on the cache servers. The Traffic Monitor IP addresses have to be included in this if they are using IPv4 to monitor the cache servers |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | allow_ip6 | astats.config | This is a comma-separated list of IPv6 :abbr:`CIDR (Classless Inter-Domain Routing)` blocks that will have access to the 'astats' statistics |
+ | | | on the cache servers. The Traffic Monitor IP addresses have to be included in this if they are using IPv6 to monitor the cache servers |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | Drive_Prefix | storage.config | The device path start of the disks. For example, if storage devices ``/dev/sda`` through ``/dev/sdf`` are to be used for caching, this |
+ | | | should be set to ``/dev/sd`` |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | Drive_Letters | storage.config | A comma-separated list of the letter part of the storage devices to be used for caching. For example, if storage devices ``/dev/sda`` |
+ | | | through ``/dev/sdf`` are to be used for caching, this should be set to ``a,b,c,d,e,f`` |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | purge_allow_ip | ip_allow.config | The IP address range that is allowed to execute the PURGE method on the caches (not related to :ref:`purge`) |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | coalesce_masklen_v4 | ip_allow.config | The mask length to use when coalescing IPv4 networks into one line using |
+ | | | `the NetAddr\:\:IP Perl library <http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm>`_ |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | coalesce_number_v4 | ip_allow.config | The number to use when coalescing IPv4 networks into one line using |
+ | | | `the NetAddr\:\:IP Perl library <http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm>`_ |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | coalesce_masklen_v6 | ip_allow.config | The mask length to use when coalescing IPv6 networks into one line using |
+ | | | `the NetAddr\:\:IP Perl library. <http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm>`_ |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | health.threshold.loadavg | rascal.properties | The Unix 'load average' (as given by :manpage:`uptime(1)`) at which Traffic Router will stop sending traffic to this cache |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+ | health.threshold.availableBandwidthInKbps | rascal.properties | The amount of bandwidth (in kilobits per second) that Traffic Router will try to keep available on the cache. For example ">1500000" means |
+ | | | "stop sending new traffic to this cache server when traffic is at 8.5Gbps on a 10Gbps interface" |
+ +-------------------------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------+
+
+The :ref:`plugin-parameters` table contains all Traffic Server plug-ins that must be configured as global parameters.
+
+.. _plugin-parameters:
+.. table:: Plugin Parameters
+
+ +------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | ConfigFile | Description |
+ +==================+===============+===========================================================================================================================================+
+ | astats_over_http | package | The package version for the :abbr:`ATS (Apache Traffic Server)` |
+ | | | `astats_over_http plugin <https://github.com/apache/trafficcontrol/tree/master/traffic_server/plugins/astats_over_http>`_ |
+ +------------------+---------------+----------------------------------------------------------+--------------------------------------------------------------------------------+
+ | trafficserver | package | The package version of :abbr:`ATS (Apache Traffic Server)` |
+ +------------------+---------------+----------------------------------------------------------+--------------------------------------------------------------------------------+
+ | regex_revalidate | plugin.config | The configuration to be used for the :abbr:`ATS (Apache Traffic Server)` `regex_revalidate plugin`_ |
+ +------------------+---------------+----------------------------------------------------------+--------------------------------------------------------------------------------+
+ | remap_stats | plugin.config | The configuration to be used for the :abbr:`ATS (Apache Traffic Server)` |
+ | | | `remap_stats plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/remap_stats>`_ - value should be left blank |
+ +------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+
+Cache server parameters for special configurations, which are unlikely to need changes but may be useful in particular circumstances, may be found in the :ref:`special-parameters` table.
+
+.. _special-parameters:
+.. table:: Special Parameters
+
+ +--------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | ConfigFile | Description |
+ +==============+===================+=============================================================================================================================================================================+
+ | not_a_parent | parent.config | This is a boolean flag and is considered ``true`` if it exists and has any value except ``false``. This prevents cache servers with this parameter in their profile from being |
+ | | | inserted into the ``parent.config`` files generated for other cache servers that have the affected cache server(s)'s :term:`Cache Group` as a parent of their own |
+ | | | :term:`Cache Group`. This is primarily useful for when Edge-tier cache servers are configured to have a :term:`Cache Group` of other Edge-tier cache servers as parents (a |
+ | | | highly unusual configuration), and it is necessary to exclude some - but not all - Edge-tier cache servers in the parent :term:`Cache Group` from the ``parent.config`` (for |
+ | | | example because they lack necessary capabilities), but still have all Edge-tier cache servers in the same :term:`Cache Group` in order to take traffic from ordinary |
+ | | | :term:`Delivery Service`\ s at that :term:`Cache Group`\ 's geographic location. Once again, this is a highly unusual scenario, and under ordinary circumstances this parameter |
+ | | | should not exist. |
+ +--------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Regions, Locations and Cache Groups
===================================
-All servers have to have a 'location', which is their physical location. Each location is part of a 'region', and each region is part of a 'division'. For Example, ``Denver`` could be a location in the ``Mile High`` region and that region could be part of the ``West`` division. The hierarchy between these terms is illustrated graphically below.
+All servers have to have a :term:`Physical Location`, which defines their geographic latitude and longitude. Each :term:`Physical Location` is part of a :term:`Region`, and each :term:`Region` is part of a :term:`Division`. For example, ``Denver`` could be the name of a :term:`Physical Location` in the ``Mile High`` :term:`Region` and that :term:`Region` could be part of the ``West`` :term:`Division`. The hierarchy between these terms is illustrated graphically in :ref:`topography-hierarchy`.
-.. figure:: images/topography.svg
+.. _topography-hierarchy:
+.. figure:: images/topography.*
:align: center
+ :alt: A graphic illustrating the hierarchy exhibited by topological groupings
:figwidth: 25%
Topography Hierarchy
-To create these structures in Traffic Portal, first in enter your divisions under `Topology->Divisions`, then enter the regions in `Topology->Regions`, referencing the divisions entered and, finally, enter the physical locations in `Topology->Phys Locations`, referencing the regions entered.
-
-All servers also have to be part of a :term:`Cache Group`. A :term:`Cache Group` is a logical grouping of caches, that don't have to be in the same physical location (in fact, usually a :term:`Cache Group` is spread across minimally 2 physical Locations for redundancy purposes), but share geographical coordinates for content routing purposes.
-
+To create these structures in Traffic Portal, first make at least one :term:`Division` under :menuselection:`Topology --> Divisions`. Next enter the desired :term:`Region`\ (s) in :menuselection:`Topology --> Regions`, referencing the earlier-entered :term:`Division`\ (s). Finally, enter the desired :term:`Physical Location`\ (s) in :menuselection:`Topology --> Phys Locations`, referencing the earlier-entered :term:`Region`\ (s).
+All servers also have to be part of a :term:`Cache Group`. A :term:`Cache Group` is a logical grouping of cache servers, that don't have to be in the same :term:`Physical Location` (in fact, usually a :term:`Cache Group` is spread across minimally two :term:`Physical Location`\ s for redundancy purposes), but share geographical coordinates for content routing purposes.
Configuring Content Purge
=========================
-Content purge using ATS is not simple; there is no file system to delete files/directories from, and in large caches it can be hard to delete a simple regular expression from the cache. This is why Traffic Control uses the `Regex Revalidate Plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_revalidate.en.html>`_ to purge content from the system. We don't actually remove the content, we have a check that gets run before each request on each cache to see if t [...]
-
-Content Purge is controlled by the following parameters in the profile of the cache:
+Purging cached content using :abbr:`ATS (Apache Traffic Server)` is not simple; there is no file system from which to delete files and/or directories, and in large caches it can be hard to delete content matching a simple regular expression from the cache. This is why Traffic Control uses the `Regex Revalidate Plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_revalidate.en.html>`_ to purge content from the cache. The cached content is not actually removed, [...]
-+----------------------+-------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
-| Name | Config File | Description | Details |
-+======================+=========================+==================================================+=================================================================================================================+
-| location | regex_revalidate.config | Where in the file system file should located on | The presence of this parameter tells ORT to distribute this file; delete this parameter from the profile if |
-| | | the cache server. | this file is distributed using other means. |
-+----------------------+-------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
-| maxRevalDurationDays | regex_revalidate.config | The maximum duration for which a purge shall be | To prevent a build up of many checks before each request, this is longest duration (in days) for which the |
-| | | active. | system will allow content purges to remain active. |
-+----------------------+-------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
-| regex_revalidate | plugin.config | The configuration to be used for | `regex_revalidate <https://docs.trafficserver.apache.org/en/5.3.x/reference/plugins/regex_remap.en.html>`_ |
-| | | ``regex_revalidate``. | |
-+----------------------+-------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
-| use_reval_pending | global | Configures Traffic Ops to use a separate | When this flag is in use ORT will check for a new ``regex_revalidate.config`` every 60 seconds in SYNCDS mode |
-| | | ``reval_pending`` flag for each cache server. | during the dispersal timer. This will also allow ORT to be run in REVALIDATE mode, which will check for and |
-| | | | clear the ``reval_pending`` flag. This can be set to run via ``cron`` task. Enable with a value of '1'. This |
-| | | | feature will not work on Traffic Ops versions older than 2.1. |
-+----------------------+-------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
+.. _content-purge-parameters:
+.. table:: Content Purge Parameters
+ +----------------------+-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | ConfigFile | Description |
+ +======================+=========================+================================================================================================================================================================+
+ | location | regex_revalidate.config | Where in the file system the ``regex_revalidate.config`` file should located on the cache server. The presence of this parameter tells ORT to distribute this |
+ | | | file; delete this parameter from the profile if this file is distributed using other means |
+ +----------------------+-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | maxRevalDurationDays | regex_revalidate.config | The maximum duration for which a purge shall be active. To prevent a build-up of many checks before each request, this is longest duration (in days) for which |
+ | | | the system will allow content purges to remain active |
+ +----------------------+-------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
+ | regex_revalidate | plugin.config | The configuration to be used for the `regex_revalidate plugin`_ |
+ +----------------------+-------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
+ | use_reval_pending | global | Configures Traffic Ops to use a separate ``reval_pending`` flag for each cache server. When this flag is in use :term:`ORT` will check for a new |
+ | | | ``regex_revalidate.config`` every 60 seconds in "SYNCDS" mode during the dispersal timer. This will also allow :term:`ORT` to be run in "REVALIDATE" mode, |
+ | | | which will check for and clear the ``reval_pending`` flag. This can be set to run via :manpage:`cron(8)` task. Enable with a value of ``1``. |
+ +----------------------+-------------------------+--------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
-Note that the TTL the adminstrator enters in the purge request should be longer than the TTL of the content to ensure the bad content will not be used. If the CDN is serving content of unknown, or unlimited TTL, the administrator should consider using `proxy-config-http-cache-guaranteed-min-lifetime <https://docs.trafficserver.apache.org/en/latest/admin-guide/files/records.config.en.html#proxy-config-http-cache-guaranteed-min-lifetime>`_ to limit the maximum time an object can be in the [...]
+.. versionadded:: 2.1
+ ``use_reval_pending`` was unavailable prior to Traffic Ops version 2.1.
+.. Note:: The :abbr:`TTL (Time To Live)` entered by the administrator in the purge request should be longer than the :abbr:`TTL (Time To Live)` of the content to ensure the bad content will not be used. If the CDN is serving content of unknown, or unlimited :abbr:`TTL (Time To Live)`, the administrator should consider using `proxy-config-http-cache-guaranteed-min-lifetime <https://docs.trafficserver.apache.org/en/latest/admin-guide/files/records.config.en.html#proxy-config-http-cache-gua [...]
.. _Creating-CentOS-Kickstart:
Creating the CentOS Kickstart File
-----------------------------------
-The kickstart file is a text file, containing a list of items, each identified by a keyword. You can create it by using the Kickstart Configurator application, or writing it from scratch. The Red Hat Enterprise Linux installation program also creates a sample kickstart file based on the options that you selected during installation. It is written to the file ``/root/anaconda-ks.cfg``. This file is editable using most text editors that can save files as ASCII text.
+==================================
+The Kickstart file is a text file, containing a list of items, each identified by a keyword. This file can be generated using the `Red Hat Kickstart Configurator application <https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/5/html/installation_guide/ch-redhat-config-kickstart>`_, or it can be written from scratch. The Red Hat Enterprise Linux installation program also creates a sample Kickstart file based on the options selected during installation. It is written to [...]
-To generate ISO, the CentOS Kickstart is necessary:
-
-#. Create a kickstart file.
-#. Create a boot media with the kickstart file or make the kickstart file available on the network.
+Generating a System Image
+-------------------------
+#. Create a Kickstart file.
+#. Create a boot media with the Kickstart file or make the Kickstart file available on the network.
#. Make the installation tree available.
-#. Start the kickstart installation.
-
-Create a ks.src file in the root of the selection location. See the example below:
+#. Start the Kickstart installation.
.. code-block:: shell
+ :caption: Creating a New System Image Definition Tree from an Existing One
+ # Starting from the Kickstart root directory (`/var/www/files` by default)
mkdir newdir
cd newdir/
+
+ # In this example, the pre-existing system image definition tree is for CentOS 7.4 located in `centos74`
cp -r ../centos74/* .
vim ks.src
vim isolinux/isolinux.cfg
- cd vim osversions.cfg
+ cd ..
vim osversions.cfg
+:file:`ks.src` is a standard, Kickstart-formatted file that the will be used to create the Kickstart (ks.cfg) file for the install whenever a system image is generated from the source tree. :file:`ks.src` is a template - it will be overwritten by any information set in the form submitted from :menuselection:`Tools --> Generate ISO` in Traffic Portal. Ultimately, the two are combined to create the final Kickstart file (:file:`ks.cfg`).
-This is a standard kickstart formatted file that the generate ISO process uses to create the kickstart (ks.cfg) file for the install. The generate ISO process uses the ks.src, overwriting any information set in the Generate ISO tab in Traffic Ops, creating ks.cfg.
-
-.. Note:: Streamline your install folder for under 1GB, which assists in creating a CD.
+.. Note:: It is highly recommended for ease of use that the system image source trees be kept under 1GB in size.
-.. seealso:: For in-depth instructions, please see `Kickstart Installation <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Installation_Guide/s1-kickstart2-howuse.html>`_
+.. seealso:: For in-depth instructions, please see `Kickstart Installation <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Installation_Guide/s1-kickstart2-howuse.html>`_ in the Red Hat documentation.
Configuring the Go Application
==============================
-Traffic Ops is in the process of migrating from Perl to Go, and currently runs as two applications. The Go application serves all endpoints which have been rewritten in the Go language, and transparently proxies all other requests to the old Perl application. Both applications are installed by the RPM, and both run as a single service. When the project has fully migrated to Go, the Perl application will be removed, and the RPM and service will consist solely of the Go application.
+Traffic Ops is in the process of migrating from Perl to Go, and currently runs as two applications. The Go application serves all endpoints which have been rewritten in the Go language, and transparently proxies all other requests to the old Perl application. Both applications are installed by the RPM, and both run as a single :manpage:`systemd(1)` service. When the project has fully migrated to Go, the Perl application will be removed, and the RPM and service will consist solely of the [...]
-By default, the postinstall script configures the Go application to behave and transparently serve as the old Perl Traffic Ops did in previous versions. This includes reading the old ``cdn.conf`` and ``database.conf`` config files, and logging to the old ``access.log`` location. However, if you wish to customize the Go Traffic Ops application, you can do so by running it with the ``-oldcfg=false`` argument. By default, it will then look for a config file in ``/opt/traffic_ops/conf/traffi [...]
+By default, the :program:`postinstall` script configures the Go application to behave and transparently serve as the old Perl Traffic Ops did in previous versions. This includes reading the old ``cdn.conf`` and ``database.conf`` config files, and logging to the old ``access.log`` location. However, the Go Traffic Ops application may be customized by passing the command-line flag, ``-oldcfg=false``. By default, it will then look for a configuration file at :file:`/opt/traffic_ops/conf/tra [...]
diff --git a/docs/source/admin/traffic_ops/extensions.rst b/docs/source/admin/traffic_ops/extensions.rst
index 6135cd8..9d745d4 100644
--- a/docs/source/admin/traffic_ops/extensions.rst
+++ b/docs/source/admin/traffic_ops/extensions.rst
@@ -19,7 +19,7 @@
Managing Traffic Ops Extensions
*******************************
-Traffic Ops supports two types of extensions. 'Check Extensions' are analytics scripts that collect and display information as columns in the table under 'Monitor' -> 'Cache Checks' in Traffic Portal. 'Data Source Extensions' provide ways to add data to the graph views and usage APIs.
+Traffic Ops supports two types of extensions. `Check Extensions`_ are analytics scripts that collect and display information as columns in the table under :menuselection:`Monitor --> Cache Checks` in Traffic Portal. `Data Source Extensions`_ provide ways to add data to the graph views and usage APIs.
.. |checkmark| image:: images/good.png
.. |X| image:: images/bad.png
@@ -28,7 +28,7 @@ Traffic Ops supports two types of extensions. 'Check Extensions' are analytics s
Check Extensions
================
-Check Extensions are scripts that, after registering with Traffic Ops, have a column reserved in the "Monitor"->"Cache Checks" view ("Health"->"Server Checks" in the legacy UI) and usually run periodically using ``cron``. Each extension is a separate executable located in ``$TO_HOME/bin/checks/`` on the Traffic Ops server (though all of the default extensions are written in Perl, this is in *no way* a requirement; they can be any valid executable). The currently registered extensions can [...]
+Check Extensions are scripts that, after registering with Traffic Ops, have a column reserved in the :menuselection:`Monitor --> Cache Checks` view and usually run periodically using :manpage:`cron(8)`. Each extension is a separate executable located in :file:`{$TO_HOME}/bin/checks/` on the Traffic Ops server (though all of the default extensions are written in Perl, this is in *no way* a requirement; they can be any valid executable). The currently registered extensions can be listed by [...]
.. code-block:: shell
:caption: Example Check Extension Call
@@ -36,44 +36,39 @@ Check Extensions are scripts that, after registering with Traffic Ops, have a co
$TO_HOME/bin/checks/<name> -c "{\"base_url\": \",https://\"<traffic_ops_ip>\", \"check_name\": \"<check_name>\"}" -l <log level>
:name: The basename of the extension executable
-:traffic_ops_ip: The IP address or Fully Qualified Domain Name (FQDN) of the Traffic Ops server
+:traffic_ops_ip: The IP address or :abbr:`FQDN (Fully Qualified Domain Name)` of the Traffic Ops server
:check_name: The name of the check e.g. ``CDU``, ``CHR``, ``DSCP``, ``MTU``, etc...
:log_level: A whole number between 1 and 4 (inclusive), with 4 being the most verbose. Implementation of this field is optional
-It is the responsibility of the check extension script to iterate over the servers it wants to check and post the results. An example script might proceed by logging into the Traffic Ops server using the HTTPS ``base_url`` provided on the command line. The script is hard-coded with an authentication token that is also provisioned in the Traffic Ops User database. This token allows the script to obtain a cookie used in later communications with the Traffic Ops API. The script then obtains [...]
+It is the responsibility of the check extension script to iterate over the servers it wants to check and post the results. An example script might proceed by logging into the Traffic Ops server using the HTTPS ``base_url`` provided on the command line. The script is hard-coded with an authentication token that is also provisioned in the Traffic Ops User database. This token allows the script to obtain a cookie used in later communications with the Traffic Ops API. The script then obtains [...]
- Script here.
-
-Currently, the following Check Extensions are available and installed by default:
-
-Cache Disk Usage Check (CDU)
+Check Extensions Installed by Default
+-------------------------------------
+:abbr:`CDU (Cache Disk Usage)`
This check shows how much of the available total cache disk is in use. A "warm" cache should show 100.00.
-Cache Hit Ratio Check (CHR)
+:abbr:`CHR (Cache Hit Ratio)`
The cache hit ratio for the cache in the last 15 minutes (the interval is determined by the ``cron`` entry).
-Differential Services CodePoint Check (DSCP)
- Checks if the returning traffic from the cache has the correct DSCP value as assigned in the delivery service. (Some routers will overwrite DSCP)
+:abbr:`DSCP (Differential Services CodePoint)`
+ Checks if the returning traffic from the cache has the correct :abbr:`DSCP (Differential Services CodePoint Check)` value as assigned in the :term:`Delivery Service`. (Some routers will overwrite :abbr:`DSCP (Differential Services CodePoint)`)
-Maximum Transmission Unit Check (MTU)
+:abbr:`MTU (Maximum Transmission Unit)`
Checks if the Traffic Ops host (if that is the one running the check) can send and receive 8192B packets to the ``ip_address`` of the server in the server table.
-Operational Readiness Check (ORT)
- See :ref:`traffic-ops-ort` for more information on the ORT script. The ORT column shows how many changes the ``traffic_ops_ort.pl`` script would apply if it was run. The number in this column should be 0 for caches that do not have updates pending.
+:abbr:`ORT (Operational Readiness Test)`
+ The ORT column shows how many changes the :term:`ORT` script would apply if it was run. The number in this column should be 0 for caches that do not have updates pending.
-Ping Check - 10G, ILO, 10G6, FQDN
- The ``bin/checks/ToPingCheck.pl`` script checks basic IP connectivity, and in the default setup it checks IP connectivity to the following:
+10G
+ Is the ``ip_address`` (the main IPv4 address) from the server table ping-able?
+:abbr:`ILO (Integrated Lights-Out)`
+ Is the ``ilo_ip_address`` (the lights-out-management IPv4 address) from the server table ping-able?
+10G6
+ Is the ``ip6_address`` (the main IPv6 address) from the server table ping-able?
+:abbr:`FQDN (Fully Qualified Domain Name)`
+ Is the :abbr:`FQDN (Fully Qualified Domain Name)` (the concatenation of ``host_name`` and ``.`` and ``domain_name`` from the server table) ping-able?
- 10G
- Is the ``ip_address`` (the main IPv4 address) from the server table ping-able?
- ILO
- Is the ``ilo_ip_address`` (the lights-out-management IPv4 address) from the server table ping-able?
- 10G6
- Is the ``ip6_address`` (the main IPv6 address) from the server table ping-able?
- FQDN
- Is the Fully Qualified Domain name (the concatenation of ``host_name`` and ``.`` and ``domain_name`` from the server table) ping-able?
-
-Traffic Router Check (RTR)
+:abbr:`RTR (Responds to Traffic Router)`
Checks the state of each cache as perceived by all Traffic Monitors (via Traffic Router). This extension asks each Traffic Router for the state of the cache. A check failure is indicated if one or more monitors report an error for a cache. A cache is only marked as good if all reports are positive. (This is a pessimistic approach, opposite of how TM marks a cache as up, "the optimistic approach")
.. _to-datasource-ext:
@@ -84,9 +79,10 @@ Data Source Extensions work in much the same way as `Check Extensions`_, but are
Example Cron File
=================
-The cron file should be edited by running ``crontab -e`` as the ``traffops`` user, or with ``sudo``. You may need to adjust the path to your ``$TO_HOME`` to match your system.
+The :manpage:`cron(8)` file should be edited by running :manpage:`crontab(1)` as the ``traffops`` user, or with :manpage:`sudo(8)`. You may need to adjust the path to your ``$TO_HOME`` to match your system.
.. code-block:: shell
+ :caption: Example Cron File
PERL5LIB=/opt/traffic_ops/app/local/lib/perl5:/opt/traffic_ops/app/lib
@@ -115,7 +111,7 @@ The cron file should be edited by running ``crontab -e`` as the ``traffops`` us
# DSCP
36 * * * * root /opt/traffic_ops/app/bin/checks/ToDSCPCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"DSCP\", \"cms_interface\": \"eth0\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
- 36 * * * * root /opt/traffic_ops/app/bin/checks/ToDSCPCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"DSCP\", \"name\": \"Delivery Service\", \"cms_interface\": \"eth0\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
+ 36 * * * * root /opt/traffic_ops/app/bin/checks/ToDSCPCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"DSCP\", \"name\": \:term:`Delivery Service`\", \"cms_interface\": \"eth0\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
# RTR
10 * * * * root /opt/traffic_ops/app/bin/checks/ToRTRCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"RTR\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
@@ -130,4 +126,3 @@ The cron file should be edited by running ``crontab -e`` as the ``traffops`` us
# ORT
40 * * * * ssh_key_edge_user /opt/traffic_ops/app/bin/checks/ToORTCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"ORT\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
40 * * * * ssh_key_edge_user /opt/traffic_ops/app/bin/checks/ToORTCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"ORT\", \"name\": \"Operational Readiness Test\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
-
diff --git a/docs/source/admin/traffic_ops/images/topography.png b/docs/source/admin/traffic_ops/images/topography.png
new file mode 100644
index 0000000..c9e31ef
Binary files /dev/null and b/docs/source/admin/traffic_ops/images/topography.png differ
diff --git a/docs/source/admin/traffic_ops/installation.rst b/docs/source/admin/traffic_ops/installation.rst
index 518dc3b..9becaca 100644
--- a/docs/source/admin/traffic_ops/installation.rst
+++ b/docs/source/admin/traffic_ops/installation.rst
@@ -13,9 +13,6 @@
.. limitations under the License.
..
-.. index::
- Traffic Ops - Installing
-
.. _to-install:
************************
@@ -23,29 +20,22 @@ Traffic Ops - Installing
************************
System Requirements
--------------------
+===================
The user must have the following for a successful minimal install:
- CentOS 7+
-- 2 machines or Virtual Machines (VMs), each with at least 2 (v)CPUs, 4GB of RAM, and 20 GB of disk space.
+- Two machines - physical or virtual -, each with at least two (v)CPUs, 4GB of RAM, and 20 GB of disk space.
- Access to CentOS Base and EPEL repositories
- Access to `The Comprehensive Perl Archive Network (CPAN) <http://www.cpan.org/>`_
-As of version 2.0 only PostgreSQL is supported as the database. This documentation assumes CentOS 7.2 and PostgreSQL 9.6.3 for a production install.
-
-.. highlight:: none
-
Installation
-------------
-
-#. Install PostgreSQL Database
+============
+#. Install PostgreSQL Database. For a production install it is best to install PostgreSQL on its own server/VM.
- .. note:: For more information on installing PostgreSQL, see `their documentation <https://www.postgresql.org/docs/>`_.
-
- For a production install it is best to install PostgreSQL on its own server/VM. To install PostgreSQL, on the PostgreSQL host (hostname ``pg`` in example),
- run the following commands as the root user (or with ``sudo``):
+ .. seealso:: For more information on installing PostgreSQL, see `their documentation <https://www.postgresql.org/docs/>`_.
.. code-block:: shell
+ :caption: Example PostgreSQL Install Procedure
yum update -y
yum install -y https://download.postgresql.org/pub/repos/yum/9.6/redhat/rhel-7-x86_64/pgdg-centos96-9.6-3.noarch.rpm
@@ -53,52 +43,42 @@ Installation
su - postgres -c '/usr/pgsql-9.6/bin/initdb -A md5 -W' #-W forces the user to provide a superuser (postgres) password
- Edit ``/var/lib/pgsql/9.6/data/pg_hba.conf`` to allow your Traffic Ops instance to access the PostgreSQL server. For example if you are going to install Traffic Ops on ``99.33.99.1`` add::
-
- host all all 99.33.99.1/32 md5
+#. Edit ``/var/lib/pgsql/9.6/data/pg_hba.conf`` to allow the Traffic Ops instance to access the PostgreSQL server. For example, if the IP address of the machine to be used as the Traffic Ops host is ``99.33.99.1`` add the line ``host all all 99.33.99.1/32 md5`` to the appropriate section of this file.
- to the appropriate section of this file. Edit the ``/var/lib/pgsql/9.6/data/postgresql.conf`` file to add the appropriate listen_addresses or ``listen_addresses = '*'``, set ``timezone = 'UTC'``, and start the database:
+#. Edit the ``/var/lib/pgsql/9.6/data/postgresql.conf`` file to add the appropriate listen_addresses or ``listen_addresses = '*'``, set ``timezone = 'UTC'``, and start the database
.. code-block:: shell
+ :caption: Starting PostgreSQL with :manpage:`systemd(1)`
systemctl enable postgresql-9.6
systemctl start postgresql-9.6
- systemctl status postgresql-9.6
+ systemctl status postgresql-9.6 # Prints the status of the PostgreSQL service, to prove it's running
-#. Build a Traffic Ops ``.rpm`` file using the instructions under the :ref:`dev-building` page.
+#. Build a :file:`traffic_ops-{version string}.rpm` file using the instructions under the :ref:`dev-building` page.
-#. Install PostgreSQL. To install the PostgreSQL 9.6 yum repository, run this command as the root user (or with ``sudo``):
+#. Install a PostgreSQL client on the Traffic Ops host
.. code-block:: shell
+ :caption: Installing PostgreSQL Client from a Hosted Source
yum install -y https://download.postgresql.org/pub/repos/yum/9.6/redhat/rhel-7-x86_64/pgdg-centos96-9.6-3.noarch.rpm
-#. Install the Traffic Ops RPM. The Traffic Ops RPM file should have been built in an earlier step. To install it, simply run the following command as the root user (or with ``sudo``):
+#. Install the Traffic Ops RPM. The Traffic Ops RPM file should have been built in an earlier step.
.. code-block:: shell
+ :caption: Installing a Generated Traffic Ops RPM
- yum install -y ./dist/traffic_ops-2.0.0-xxxx.yyyyyyy.el7.x86_64.rpm
+ yum install -y ./dist/traffic_ops-3.0.0-xxxx.yyyyyyy.el7.x86_64.rpm
.. note:: This will install the PostgreSQL client, ``psql`` as a dependency.
-#. Install Additional Packages. Some packages on which Traffic Ops depends not have been installed as direct dependencies of the ``traffic_ops-<version stuff>.rpm``. To explicitly install these, run the following commands as the root user (or with ``sudo``):
-
- .. code-block:: shell
-
- yum install -y git
- wget -q https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -O go.tar.gz
- tar -C /usr/local -xzf go.tar.gz
- PATH=$PATH:/usr/local/go/bin # go binaries are needed in the path for the 'postinstall' script
- go get bitbucket.org/liamstask/goose/cmd/goose
-
- .. note:: These are for the Traffic Control version 2.0.0 install, this may change, but the explicit installs won't hurt.
-
-#. Login to the Database from the Traffic Ops machine. At this point you should be able to login from the Traffic Ops (hostname ``to`` in the example) host to the PostgreSQL (hostname ``pg`` in the example) host like so:
+#. Login to the Database from the Traffic Ops machine. At this point you should be able to login from the Traffic Ops (hostname ``to`` in the example) host to the PostgreSQL (hostname ``pg`` in the example) host
.. code-block:: psql
+ :caption: Example Login to Traffic Ops Database from Traffic Ops Server
- to-# psql -h 99.33.99.1 -U postgres
+ to-# psql -h pg -U postgres
Password for user postgres:
psql (9.6.3)
Type "help" for help.
@@ -106,9 +86,10 @@ Installation
postgres=#
-#. Create the User and Database. In this example, we use user: ``traffic_ops``, password: ``tcr0cks``, database: ``traffic_ops``:
+#. Create the user and database. By default, Traffic Ops will expect to connect as the ``traffic_ops`` user to the ``traffic_ops`` database.
- .. code-block:: psql
+ .. code-block:: console
+ :caption: Creating the Traffic Ops User and Database
to-# psql -U postgres -h 99.33.99.1 -c "CREATE USER traffic_ops WITH ENCRYPTED PASSWORD 'tcr0cks';"
Password for user postgres:
@@ -117,9 +98,13 @@ Installation
Password:
to-#
-#. Run the ``postinstall`` Script. Now, run the following command as the root user (or with ``sudo``): ``/opt/traffic_ops/install/bin/postinstall``. The ``postinstall`` script will first get all packages needed from CPAN. This may take a while, expect up to 30 minutes on the first install. If there are any prompts in this phase, please just answer with the defaults (some CPAN installs can prompt for install questions). When this phase is complete, you will see ``Complete! Modules were in [...]
+#. Now, run the following command as the root user (or with ``sudo``): ``/opt/traffic_ops/install/bin/postinstall``. The ``postinstall`` script will first get all required Perl packages from :abbr:`CPAN (The Comprehensive Perl Archive Network)`. This may take a while, expect up to 30 minutes on the first install. If there are any prompts in this phase, please just answer with the defaults (some :abbr:`CPAN (The Comprehensive Perl Archive Network)` installs can prompt for install question [...]
- .. code-block:: none
+ .. code-block:: console
+ :caption: Example Output
+
+ to-# /opt/traffic_ops/install/bin/postinstall
+ ...
===========/opt/traffic_ops/app/conf/production/database.conf===========
Database type [Pg]:
@@ -210,7 +195,7 @@ Installation
+----------------------------------------------------+----------------------------------------------------------------------------------------------+
| Database server root (admin) user password | The password for the privileged database user. |
+----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Traffic Ops URL | The URL to connect to this instance of Traffic Ops, usually https://<Traffic Ops host FQDN>/ |
+ | Traffic Ops URL | The URL to connect to this instance of Traffic Ops, usually https://<Traffic Ops host>/ |
+----------------------------------------------------+----------------------------------------------------------------------------------------------+
| Human-readable CDN Name | The name of the first CDN which Traffic Ops will be manage. |
+----------------------------------------------------+----------------------------------------------------------------------------------------------+
@@ -226,20 +211,22 @@ Installation
Traffic Ops is now installed!
-**To complete the Traffic Ops Setup See:** :ref:`default-profiles`
+.. seealso:: :ref:`default-profiles` for initial configuration of the Traffic Ops instance.
Upgrading Traffic Ops
=====================
-To upgrade from older Traffic Ops versions, run the following commands as the root user (or with ``sudo``):
+To upgrade from older Traffic Ops versions, stop the service, use :manpage:`yum(8)` to upgrade to the latest available Traffic Ops package, and use the ``admin`` tool to perform the database upgrade.
- .. code-block:: shell
+.. seealso:: :ref:`database-management` for more details about `admin`.
+
+.. code-block:: shell
+ :caption: Sample Script for Upgrading Traffic Ops
- systemctl stop traffic_ops
- yum upgrade traffic_ops
- pushd /opt/traffic_ops/app/
- ./db/admin --env production upgrade
+ systemctl stop traffic_ops
+ yum upgrade traffic_ops
+ pushd /opt/traffic_ops/app/
+ ./db/admin --env production upgrade
+ popd
-After this completes, see :ref:`to-install` to run the ``postinstall`` script.
-Once the ``postinstall`` script, has finished, run the following command as the root user (or with ``sudo``):
-``systemctl start traffic_ops``
+After this completes, see `Installation`_ for instructions on running the ``postinstall`` script. Once the ``postinstall`` script, has finished, run the following command as the root user (or with ``sudo``): ``systemctl start traffic_ops`` to start the service.
diff --git a/docs/source/admin/traffic_ops/migration_from_10_to_20.rst b/docs/source/admin/traffic_ops/migration_from_10_to_20.rst
deleted file mode 100644
index 7f91fe6..0000000
--- a/docs/source/admin/traffic_ops/migration_from_10_to_20.rst
+++ /dev/null
@@ -1,74 +0,0 @@
-..
-..
-.. Licensed under the Apache License, Version 2.0 (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-..
-
-.. index::
- Traffic Ops - Migrating from Traffic Ops 1.x to Traffic Ops 2.x
-
-.. _ps:
-
-***************************************
-Traffic Ops - Migrating from 1.x to 2.x
-***************************************
-In Traffic Ops 2.x the database used to store CDN information was changed from MySQL to PostgreSQL. PostgreSQL will remain the Traffic Ops database for the foreseeable future.
-A Docker-based migration tool was developed to help with the conversion process using an open-source PostgreSQL tool called `pgloader <http://pgloader.io/>`_.
-The following instructions will help configuring the Migration tool
-
-System Requirements
--------------------
-The user must have the following for a successful minimal install:
-
-* CentOS 7.2+
-* Docker installed [1]_
-* PostgreSQL installed according to :ref:`to-install`
-
-Setup the ``traffic_ops_db`` Directory
---------------------------------------
-#. Modify the permissions of the ``/opt`` directory to make it writable by and owned by the ``postgres`` user and the ``postgres`` group. This can easily be accomplished by running the command ``chmod 755 /opt`` as the root user, or with ``sudo``.
-
-#. Download the Traffic Control 2.0.0 tarball like so
-
- .. code-block:: shell
-
- cd /opt
- wget https://dist.apache.org/repos/dist/release/incubator/trafficcontrol/<tarball_version>
-
-#. Extract the **only** the ``traffic_ops_db`` directory to ``/opt/traffic_ops_db``
-
- .. code-block:: shell
-
- tar -zxvf trafficcontrol-incubating-<version>.tar.gz --strip=1 trafficcontrol-incubating-<version>/traffic_ops_db
- chown -R postgres:postgres /opt/traffic_ops_db
-
-Migration Preparation
----------------------
-Be sure there is connectivity between your MySQL server's IP address/port and your PostgreSQL server's IP address/port.
-
-Navigating the Database Migration
----------------------------------
-Begin the database migration after settings up the ``/opt/traffic_ops_db`` directory
-Switch to the postgres user, so that permissions remain intact.
-
-.. code-block:: shell
-
- su - postgres
- cd /opt/traffic_ops_db/
-
-#. Configure the ``/opt/traffic_ops_db/pg-migration/mysql-to-postgres.env`` file for your source MySQL and target PostgresQL settings. This part ought to be self-explanatory, given the names used in that file.
-
-#. Run the ``migrate.sh`` script, watching the console output for any errors (this may take some time).
-
-Your MySQL data should now be ported into your new instance of PostgreSQL!
-
-.. [1] This migration was tested against version ``docker-engine-selinux-17.05.0.ce-1``
diff --git a/docs/source/admin/traffic_ops/migration_from_20_to_22.rst b/docs/source/admin/traffic_ops/migration_from_20_to_22.rst
deleted file mode 100644
index eaeb357..0000000
--- a/docs/source/admin/traffic_ops/migration_from_20_to_22.rst
+++ /dev/null
@@ -1,148 +0,0 @@
-..
-..
-.. Licensed under the Apache License, Version 2.0 (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-..
-
-***************************************
-Traffic Ops - Migrating from 2.0 to 2.2
-***************************************
-
-Per-DeliveryService Routing Names
----------------------------------
-Before this release, DNS Delivery Services were hard-coded to use the name ``edge``, so that URLs would appear as e.g. ``edge.myds.mycdn.com``, and HTTP Delivery Services use the name ``tr`` [1]_, e.g. ``tr.myds.mycdn.com``. As of Traffic Control version 2.2, DNS routing names will default to ``cdn`` if left unspecified and can be set to any valid hostname, provided it does not contain the ``.`` character.
-
-Prior to Traffic Control 2.2, the HTTP routing name was configurable via the ``http.routing.name`` option in in the Traffic Router ``http.properties`` configuration file. If your CDN uses that option to change the name from ``tr`` to something else, then you will need to perform the following steps for each CDN affected:
-
-#. In Traffic Portal (if possible, else use the legacy Traffic Ops UI), create the following profile parameter ('Configure' -> 'Parameters' -> '+'). Be sure to double-check for typos, trailing spaces, etc.
-
- :name: upgrade_http_routing_name
- :config_file: temp
- :value: Whatever value is used for the affected CDN's ``http.routing.name``
-
-#. Add this parameter to a single profile in the affected CDN
-
-With those profile parameters in place, Traffic Ops can be safely upgraded to 2.2. Before taking a post-upgrade snapshot, make sure to check your Delivery Service example URLs for unexpected routing name changes. Once Traffic Ops has been upgraded to 2.2 and a post-upgrade snapshot has been taken, your Traffic Routers can be upgraded to 2.2 (Traffic Routers must be upgraded after Traffic Ops so that they can work with custom per-Delivery Service routing names).
-
-Apache Traffic Server 7.x (Cachekey Plugin)
--------------------------------------------
-In Traffic Ops 2.2 we have added support for Apache Traffic Server (ATS) 7.x. With 7.x comes support for the new Cachekey Plugin which replaces the now-deprecated Cacheurl Plugin.
-While not needed immediately it is recommended to start replacing Cacheurl usages with Cachekey as soon as possible, because ATS 6.x already supports the new Cachekey Plugin.
-
-It is also recommended to thoroughly vet your Cachekey replacement by comparing with an existing key value. There are inconsistencies in the 6.x version of Cachekey which have been
-fixed in 7.x (or require this patch(`cachekeypatch`_) on 6.x to match 7.x). So to ensure you have a matching key value you should use the XDebug Plugin before fully implementing your Cachekey replacement.
-
-.. _cachekeypatch: https://github.com/apache/trafficserver/commit/244288fab01bdad823f9de19dcece62a7e2a0c11
-
-First, if you are currently using a regular expression for your Delivery Service you will have to remove that existing value. Then you will need to make a new Delivery Service profile and assign parameters to it that use the ``cachekey.config`` file.
-
-Some common parameters are
-
-static-prefix
- This is used for a simple domain replacement.
-
-separator
- Used by Cachekey and in general is always a single space.
-
-remove-path
- Removes path information from the URL.
-
-remove-all-params
- Removes query parameters from the URL.
-
-capture-prefix-uri
- This is usually used in concert with remove-path and remove-all-params parameters. Capture-prefix-uri will let you use your own, full regular expression for non-trivial cases.
-
-Examples of Cacheurl to Cachekey Replacements
----------------------------------------------
-
-Static Prefix Example
-"""""""""""""""""""""
-Original regex value: ::
-
- http://test.net/(.*) http://test-cdn.net/$1
-
-.. table:: Cachekey Parameters
-
- +---------------+-----------------+---------------------------------+
- |Parameter |File |Value |
- +===============+=================+=================================+
- | static-prefix | cachekey.config | ``http://test-cdn.net/`` |
- +---------------+-----------------+---------------------------------+
- | separator | cachekey.config | (empty space) |
- +---------------+-----------------+---------------------------------+
-
-
-Removing Query Parameters and Path Information
-""""""""""""""""""""""""""""""""""""""""""""""
-Original regex value: ::
-
- http://([^?]+)(?:?|$) http://test-cdn.net/$1
-
-.. table:: Cachekey Parameters
-
- +-----------------------+-----------------+-----------------------------------------------------+
- |Parameter |File |Value |
- +=======================+=================+=====================================================+
- | remove-path | cachekey.config | true |
- +-----------------------+-----------------+-----------------------------------------------------+
- | remove-all-params | cachekey.config | true |
- +-----------------------+-----------------+-----------------------------------------------------+
- | separator | cachekey.config | (empty space) |
- +-----------------------+-----------------+-----------------------------------------------------+
- | capture-prefix-uri | cachekey.config | ``/https?:\/\/([^?]*)/http:\/\/test-cdn.net\/$1/`` |
- +-----------------------+-----------------+-----------------------------------------------------+
-
-Also note the ``s?`` used here so that both HTTP and HTTPS requests will end up with the same key value
-
-
-Removing Query Parameters with a Static Prefix
-""""""""""""""""""""""""""""""""""""""""""""""
-Original regex value: ::
-
- http://test.net/([^?]+)(?:\?|$) http://test-cdn.net/$1
-
-.. table:: Cachekey Parameters
-
- +-------------------+-----------------+---------------------------------+
- |Parameter |File |Value |
- +===================+=================+=================================+
- | static-prefix | cachekey.config | ``http://test-cdn.net/`` |
- +-------------------+-----------------+---------------------------------+
- | separator | cachekey.config | (empty space) |
- +-------------------+-----------------+---------------------------------+
- | remove-all-params | cachekey.config | true |
- +-------------------+-----------------+---------------------------------+
-
-.. note:: Further documentation on the Cachekey Plugin can be found at `the Apache Traffic Server Documentation <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cachekey.en.html>`_.
-
-Apache Traffic Server 7.x (Logging)
------------------------------------
-Traffic Server has changed the logging format as of version 7.0. Previously, this was ``logs_xml.config`` - an XML file - and now it is ``logging.config`` - a Lua file. Traffic Control compensates for this
-automatically depending upon the filename used for the logging parameters. The same parameters will work this new file, ``LogFormat.Format``, ``LogFormat.Name``, ``LogObject.Format`` etc.
-
-
-Traffic Ops Profile Modifications
----------------------------------
-When upgrading to ATS 7.x, the Traffic Ops EDGE and MID cache profiles must be modified to provide new configuration values. Traffic Server's recommended parameter changes can be found `on their wiki <https://cwiki.apache.org/confluence/display/TS/Upgrading+to+v7.0>`_.
-
-Most users of Traffic Control have enough profiles to make the task of making these modifications manually a tedious and time-consuming process. A new utility ``traffic_ops/install/bin/convert_profile/convert_profile`` is provided to automatically convert an ATS 6.x profile into an ATS 7.x profile. This utility can be reused in the future for converting ATS 7.x profiles into ATS 8.x profiles.
-
-Usage Example
-"""""""""""""
-#. Use Traffic Portal GUI to export profile to JSON ('Configure' -> 'Profiles' -> Desired profile -> 'More' -> 'Export Profile')
-#. Modify the Traffic Server version numbers to match your current Traffic Server 6.x RPM version and planned Traffic Server 7.x RPM version
-#. Run ``convert_profile -input_profile <exported_file> -rules convert622to713.json -out <new_profile_name>``
-#. Review output messages and make manual updates as needed. If you have modified a default value which the script also wants to change, it will prompt you to make the update manually. You may either do this directly in the JSON file or through the Traffic Portal GUI after import.
-#. Use Traffic Portal GUI to import the newly created profile ('Configure' -> 'Profiles' -> 'More' -> 'Import Profile')
-
-.. [1] Another name previously used for HTTP Delivery Services was ``ccr``
diff --git a/docs/source/admin/traffic_ops/using.rst b/docs/source/admin/traffic_ops/using.rst
index b539b59..32c9e91 100644
--- a/docs/source/admin/traffic_ops/using.rst
+++ b/docs/source/admin/traffic_ops/using.rst
@@ -25,7 +25,8 @@
Traffic Ops - Using
*******************
-.. caution:: The Traffic Ops UI is deprecated, and will be removed entirely in the next major release (4.0). A much better way to interact with the CDN is to :ref:`use Traffic Portal <usingtrafficportal>`, which is the the only UI that will be receiving updates for the foreseeable future.
+.. deprecated:: 3.0
+ The Traffic Ops UI is deprecated, and will be removed entirely in the next major release (4.0). A much better way to interact with the CDN is to :ref:`use Traffic Portal <usingtrafficportal>`, which is the the only UI that will be receiving updates for the foreseeable future.
The Traffic Ops Menu
====================
@@ -66,7 +67,7 @@ Information on the health of the system. Hover over this tab to get to the follo
Delivery Services
-----------------
-The main Delivery Service table. This is where you Create/Read/Update/Delete Delivery Services of all types. Hover over to get the following sub option:
+The main :term:`Delivery Service` table. This is where you Create/Read/Update/Delete :term:`Delivery Service`\ s of all types. Hover over to get the following sub option:
+-------------+--------------------------------------+
| Option | Description |
@@ -79,11 +80,11 @@ Servers
-------
The main Servers table. This is where you Create/Read/Update/Delete servers of all types. Click the main tab to get to the main table, and hover over to get these sub options:
-+-------------------+------------------------------------------------------------------------------------------+
-| Option | Description |
-+===================+==========================================================================================+
-| Upload Server CSV | Bulk add of servers from a csv file. See :ref:`bulkserver` |
-+-------------------+------------------------------------------------------------------------------------------+
++-------------------+--------------------------------------+
+| Option | Description |
++===================+======================================+
+| Upload Server CSV | Bulk add of servers from a CSV file. |
++-------------------+--------------------------------------+
Parameters
----------
@@ -285,10 +286,9 @@ These are the types of servers that can be managed in Traffic Ops:
| INFLUXDB | influxDb server |
+---------------+---------------------------------------------+
-
Delivery Service
================
-The fields in the Delivery Service view are:
+The fields in the :term:`Delivery Service` view are:
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Description |
@@ -327,7 +327,7 @@ The fields in the Delivery Service view are:
| | |
| | See :ref:`signed-urls`. |
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Deep Caching | Enables clients to be routed to the closest possible "deep" edge caches on a per Delivery Service basis. |
+| Deep Caching | Enables clients to be routed to the closest possible "deep" edge caches on a per :term:`Delivery Service` basis. |
| | See `Deep Caching <http://traffic-control-cdn.readthedocs.io/en/latest/admin/traffic_router.html#deep-caching-deep-coverage-zone-topology>`_ |
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Query String Handling | How to treat query strings: |
@@ -378,7 +378,7 @@ The fields in the Delivery Service view are:
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| HTTP Bypass FQDN | Traffic Router will redirect to this FQDN (with the same path) when the Max Bps or Max Tps for this delivery service exceeds. |
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Delivery Service DNS TTL | The Time To Live on the DNS record for the Traffic Router A and AAAA records. Setting too high or too low will result in poor caching performance. |
+| :term:`Delivery Service` DNS TTL | The Time To Live on the DNS record for the Traffic Router A and AAAA records. Setting too high or too low will result in poor caching performance. |
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Fair Queuing Pacing Rate Bps | The maximum bytes per second a cache will delivery on any single TCP connection. This uses the Linux kernel’s Fair Queuing setsockopt (SO_MAX_PACING_RATE) to limit |
| | the rate of delivery. Traffic exceeding this speed will only be rate-limited and not diverted. This option requires net.core.default_qdisc = fq in /etc/sysctl.conf. |
@@ -401,7 +401,7 @@ The fields in the Delivery Service view are:
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Use Multi Site Origin Feature | Set True/False to enable/disable the Multi Site Origin feature for this delivery service. See :ref:`multi-site-origin` |
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Delivery Service Profile | Only used if a delivery service uses configurations that specifically require a profile. Example: MSO configurations or cachekey plugin would require a ds profile to |
+| :term:`Delivery Service` :term:`Profile` | Only used if a delivery service uses configurations that specifically require a profile. Example: MSO configurations or cachekey plugin would require a ds profile to |
| | be used. |
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Geo Miss Default Latitude | Default Latitude for this delivery service. When client localization fails for both Coverage Zone and Geo Lookup, this the client will be routed as if it was at this |
@@ -472,11 +472,8 @@ The fields in the Delivery Service view are:
+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. [1] These fields are not validated by Traffic Ops to be correct syntactically, and can cause Traffic Server to not start if invalid. Please use with caution.
-.. [2] It is not recommended to change the Routing Name of a Delivery Service after deployment because this changes its Delivery FQDN (i.e. ``<routing-name>.<deliveryservice>.<cdn-domain>``), which means that SSL certificates may need to be updated and clients using the Delivery Service will need to be transitioned to the new Delivery URL.
-
+.. [2] It is not recommended to change the Routing Name of a :term:`Delivery Service` after deployment because this changes its Delivery FQDN (i.e. ``<routing-name>.<deliveryservice>.<cdn-domain>``), which means that SSL certificates may need to be updated and clients using the :term:`Delivery Service` will need to be transitioned to the new Delivery URL.
-.. index::
- Delivery Service Type
.. _ds-types:
@@ -508,11 +505,11 @@ One of the most important settings when creating the delivery service is the sel
| ANY_MAP | ANY_MAP is not known to Traffic Router. For this Delivery Sevice, the "Raw Remap Text" field in the input form will be used as the remap line in the cache's :file:`remap.config`. |
| | For more information see `ANY_MAP Raw Remap Text`_ |
+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| STEERING | The Delivery Service will be used to route to other delivery services. The target delivery services and the routing weights for those delivery services will be defined by an admin or steering |
-| | user. For more information see the `steering feature <../traffic_router.html#steering-feature>`_ documentation |
+| STEERING | The :term:`Delivery Service` will be used to route to other delivery services. The target delivery services and the routing weights for those delivery services will be defined by an admin or |
+| | steering user. For more information see the `steering feature <../traffic_router.html#steering-feature>`_ documentation |
+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| CLIENT_STEERING | Similar to STEERING except that a client can send a request to Traffic Router with a query param of `trred=false`, and Traffic Router will return an HTTP 200 response with a body that contains |
-| | a list of Delivery Service URLs that the client can connect to. Therefore, the client is doing the steering, not the Traffic Router. |
+| | a list of :term:`Delivery Service` URLs that the client can connect to. Therefore, the client is doing the steering, not the Traffic Router |
+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. _federations:
@@ -570,14 +567,14 @@ The Raw Remap Text may contain the following special strings that will be replac
ANY_MAP ##OVERRIDE##
""""""""""""""""""""
-.. warning:: The ANY_MAP ``##OVERRIDE##`` special string is a temporary solution and will be deprecated once Delivery Service Versioning is implemented.
+.. warning:: The ANY_MAP ``##OVERRIDE##`` special string is a temporary solution and will be deprecated once :term:`Delivery Service` Versioning is implemented.
-A special ``##OVERRIDE##`` string has been added to allow an ANY_MAP rule to override another Delivery Service's remap rule, implemented by :program:`traffic_ops_ort`. When present, the original Delivery Service remap rule is commented out with an ``##OVERRIDDEN##`` prefix and the ``##OVERRIDE##`` rule is activated in its place.
+A special ``##OVERRIDE##`` string has been added to allow an ANY_MAP rule to override another :term:`Delivery Service`'s remap rule, implemented by :program:`traffic_ops_ort`. When present, the original :term:`Delivery Service` remap rule is commented out with an ``##OVERRIDDEN##`` prefix and the ``##OVERRIDE##`` rule is activated in its place.
:abbr:`ATS (Apache Traffic Server)` `remap.config <https://docs.trafficserver.apache.org/en/7.1.x/admin-guide/files/remap.config.en.html>`_:
.. code-block:: text
- :caption: Delivery Service :file:`remap.config` line:
+ :caption: :term:`Delivery Service` :file:`remap.config` line:
map http://from.com/ http://to.com/
@@ -593,11 +590,11 @@ A special ``##OVERRIDE##`` string has been added to allow an ANY_MAP rule to ove
map http://from.com/ http://to.com/ thundering_herd_mitigation.so
##OVERRIDDEN## map http://from.com/ http://to.com/
-The ANY_MAP ``##OVERRIDE##`` may be used to incrementally deploy plugins by assigning a subset of caches to the ANY_MAP ``##OVERRIDE##`` Delivery Service in addition to the original Delivery Service. This allows Traffic Router to send traffic to edges based on the original Delivery Service but serve them using the ANY_MAP override Raw Remap Text.
+The ANY_MAP ``##OVERRIDE##`` may be used to incrementally deploy plugins by assigning a subset of caches to the ANY_MAP ``##OVERRIDE##`` :term:`Delivery Service` in addition to the original :term:`Delivery Service`. This allows Traffic Router to send traffic to edges based on the original :term:`Delivery Service` but serve them using the ANY_MAP override Raw Remap Text.
.. warning:: The from endpoint must exactly match for this to properly work (ie: trailing URL '/'), otherwise :abbr:`ATS (Apache Traffic Server)` may fail to initialize or reload while processing :file:`remap.config`.
-.. note:: Any of these ANY_MAP ``##OVERRIDE##`` rules **should** be documented in the comment fields of the original Delivery Service to assist with troubleshooting.
+.. note:: Any of these ANY_MAP ``##OVERRIDE##`` rules **should** be documented in the comment fields of the original :term:`Delivery Service` to assist with troubleshooting.
.. index::
Token Based Authentication
@@ -710,13 +707,13 @@ Parameters in the Mid (parent) profile that influence this feature:
Qstring Handling
----------------
-Delivery services have a Query String Handling option that, when set to ignore, will automatically add a regex remap to that delivery service's config. There may be times this is not preferred, or there may be requirements for one delivery service or server(s) to behave differently. When this is required, the psel.qstring_handling parameter can be set in either the delivery service profile or the server profile, but it is important to note that the server profile will override ALL deli [...]
+Delivery services have a Query String Handling option that, when set to ignore, will automatically add a regex remap to that delivery service's config. There may be times this is not preferred, or there may be requirements for one delivery service or server(s) to behave differently. When this is required, the psel.qstring_handling parameter can be set in either the delivery service profile or the server profile, but it is important to note that the server profile will override ALL deli [...]
+-----------------------+---------------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Filename | Default | Description |
+=======================+===============+=========+===================================================================================================================================================================+
| psel.qstring_handling | parent.config | - | Sets qstring handling without the use of regex remap for a delivery service when assigned to a delivery service profile, and overrides qstring handling for all |
-| | | | Delivery Services for associated servers when assigned to a server profile. Value must be "consider" or "ignore". |
+| | | | :term:`Delivery Service`\ s for associated servers when assigned to a server profile. Value must be "consider" or "ignore". |
+-----------------------+---------------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. _multi-site-origin:
@@ -830,8 +827,8 @@ Traffic Router Profile
| api.auth.url | CRConfig.json | The API authentication URL (https://${tmHostname}/api/1.1/user/login); ${tmHostname} is a search and replace token used by Traffic Router to |
| | | construct the correct URL) |
+-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
-| consistent.dns.routing | CRConfig.json | Control whether DNS Delivery Services use consistent hashing on the edge FQDN to select caches for answers. May improve performance if set to |
-| | | true; defaults to false |
+| consistent.dns.routing | CRConfig.json | Control whether DNS :term:`Delivery Service`\ s use consistent hashing on the edge FQDN to select caches for answers. May improve performance if |
+| | | set to true; defaults to false |
+-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
| dnssec.enabled | CRConfig.json | Whether DNSSEC is enabled; this parameter is updated via the DNSSEC administration user interface. |
+-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -884,11 +881,6 @@ The regex remap expression allows to to use a regex and resulting match group(s)
^/([^?]*).* http://origin.example.com/remapped/$1
-.. index::
- HOST_REGEXP
- PATH_REGEXP
- HEADER_REGEXP
- Delivery Service regexp
.. _ds-regexp:
@@ -1027,7 +1019,7 @@ The Deep Coverage Zone File (DCZF) format is similar to the CZF format but adds
Each entry in the ``caches`` list is the hostname of an edge cache registered in Traffic Ops which will be used for "deep" caching in that Deep Coverage Zone. Unlike a regular CZF, coverage zones in the DCZF do not map to a :term:`Cache Group` in Traffic Ops, so currently the deep coverage zone name only needs to be unique.
-If the Traffic Router gets a DCZF "hit" for a requested Delivery Service that has Deep Caching enabled, the client will be routed to an available "deep" cache from that zone's ``caches`` list.
+If the Traffic Router gets a DCZF "hit" for a requested :term:`Delivery Service` that has Deep Caching enabled, the client will be routed to an available "deep" cache from that zone's ``caches`` list.
.. note:: The ``"coordinates"`` section is optional.
@@ -1226,7 +1218,7 @@ To invalidate content:
#. Click **Tools > Invalidate Content**
#. Fill out the form fields:
- - Select the **Delivery Service**
+ - Select the *:term:`Delivery Service`**
- Enter the **Path Regex** - this should be a `PCRE <http://www.pcre.org/>`_ compatible regular expression for the path to match for forcing the revalidation. Be careful to only match on the content you need to remove - revalidation is an expensive operation for many origins, and a simple ``/.*`` can cause an overload condition of the origin.
- Enter the **Time To Live** - this is how long the revalidation rule will be active for. It usually makes sense to make this the same as the ``Cache-Control`` header from the origin which sets the object time to live in cache (by ``max-age`` or ``Expires``). Entering a longer TTL here will make the caches do unnecessary work.
- Enter the **Start Time** - this is the start time when the revalidation rule will be made active. It is pre-populated with the current time, leave as is to schedule ASAP.
@@ -1236,14 +1228,14 @@ To invalidate content:
Manage DNSSEC Keys
==================
-In order to support `DNSSEC <https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions>`_ in Traffic Router, Traffic Ops provides some actions for managing DNSSEC keys for a CDN and associated Delivery Services. DNSSEC Keys consist of a Key Signing Keys (KSK) which are used to sign other DNSKEY records as well as Zone Signing Keys (ZSK) which are used to sign other records. DNSSEC Keys are stored in `Traffic Vault <../../overview/traffic_vault.html>`_ and should only be acce [...]
+In order to support `DNSSEC <https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions>`_ in Traffic Router, Traffic Ops provides some actions for managing DNSSEC keys for a CDN and associated :term:`Delivery Service`\ s. DNSSEC Keys consist of a Key Signing Keys (KSK) which are used to sign other DNSKEY records as well as Zone Signing Keys (ZSK) which are used to sign other records. DNSSEC Keys are stored in `Traffic Vault <../../overview/traffic_vault.html>`_ and should on [...]
To Manage DNSSEC Keys:
1. Click **Tools -> Manage DNSSEC Keys**
2. Choose a CDN and click **Manage DNSSEC Keys**
- If keys have not yet been generated for a CDN, this screen will be mostly blank with just the **CDN** and **DNSSEC Active?** fields being populated.
- - If keys have been generated for the CDN, the Manage DNSSEC Keys screen will show the TTL and Top Level Domain (TLD) KSK Expiration for the CDN as well as DS Record information which will need to be added to the parent zone of the TLD in order for DNSSEC to work.
+ - If keys have been generated for the CDN, the Manage DNSSEC Keys screen will show the TTL and Top Level Domain (TLD) :abbr:`KSK (Key Signing Key)` Expiration for the CDN as well as DS Record information which will need to be added to the parent zone of the TLD in order for DNSSEC to work.
The Manage DNSSEC Keys screen also allows a user to perform the following actions:
@@ -1253,31 +1245,31 @@ Fairly straight forward, this button set the **dnssec.enabled** param to either
Generate Keys
-------------
-Generate Keys will generate DNSSEC keys for the CDN TLD as well as for each Delivery Service in the CDN. It is important to note that this button will create a new KSK for the TLD and, therefore, a new DS Record. Any time a new DS Record is created, it will need to be added to the parent zone of the TLD in order for DNSSEC to work properly. When a user clicks the **Generate Keys** button, they will be presented with a screen with the following fields:
+Generate Keys will generate DNSSEC keys for the CDN TLD as well as for each :term:`Delivery Service` in the CDN. It is important to note that this button will create a new :abbr:`KSK (Key Signing Key)` for the TLD and, therefore, a new DS Record. Any time a new DS Record is created, it will need to be added to the parent zone of the TLD in order for DNSSEC to work properly. When a user clicks the **Generate Keys** button, they will be presented with a screen with the following fields:
- **CDN:** This is not editable and displays the CDN for which keys will be generated
-- **ZSK Expiration (Days):** Sets how long (in days) the Zone Signing Key will be valid for the CDN and associated Delivery Services. The default is 30 days.
-- **KSK Expiration (Days):** Sets how long (in days) the Key Signing Key will be valid for the CDN and associated Delivery Services. The default is 365 days.
+- **ZSK Expiration (Days):** Sets how long (in days) the Zone Signing Key will be valid for the CDN and associated :term:`Delivery Service`\ s. The default is 30 days.
+- **KSK Expiration (Days):** Sets how long (in days) the Key Signing Key will be valid for the CDN and associated :term:`Delivery Service`\ s. The default is 365 days.
- **Effective Date (GMT):** The time from which the new keys will be active. Traffic Router will use this value to determine when to start signing with the new keys and stop signing with the old keys.
Once these fields have been correctly entered, a user can click Generate Keys. The user will be presented with a confirmation screen to help them understand the impact of generating the keys. If a user confirms, the keys will be generated and stored in Traffic Vault.
Regenerate KSK
--------------
-Regenerate KSK will create a new Key Signing Key for the CDN TLD. A new DS Record will also be generated and need to be put into the parent zone in order for DNSSEC to work correctly. The **Regenerate KSK** button is only available if keys have already been generated for a CDN. The intent of the button is to provide a mechanism for generating a new KSK when a previous one expires or if necessary for other reasons such as a security breach. When a user goes to generate a new KSK they ar [...]
+Regenerate :abbr:`KSK (Key Signing Key)` will create a new Key Signing Key for the CDN TLD. A new DS Record will also be generated and need to be put into the parent zone in order for DNSSEC to work correctly. The **Regenerate KSK** button is only available if keys have already been generated for a CDN. The intent of the button is to provide a mechanism for generating a new :abbr:`KSK (Key Signing Key)` when a previous one expires or if necessary for other reasons such as a security bre [...]
:CDN: This is not editable and displays the CDN for which keys will be generated
-:KSK Expiration (Days): Sets how long (in days) the Key Signing Key will be valid for the CDN and associated Delivery Services. The default is 365 days.
-:Effective Date (GMT): The time from which the new KSK and DS Record will be active. Since generating a new KSK will generate a new DS Record that needs to be added to the parent zone, it is very important to make sure that an effective date is chosen that allows for time to get the DS Record into the parent zone. Failure to get the new DS Record into the parent zone in time could result in DNSSEC errors when Traffic Router tries to sign responses.
+:KSK Expiration (Days): Sets how long (in days) the Key Signing Key will be valid for the CDN and associated :term:`Delivery Service`\ s. The default is 365 days.
+:Effective Date (GMT): The time from which the new :abbr:`KSK (Key Signing Key)` and DS Record will be active. Since generating a new :abbr:`KSK (Key Signing Key)` will generate a new DS Record that needs to be added to the parent zone, it is very important to make sure that an effective date is chosen that allows for time to get the DS Record into the parent zone. Failure to get the new DS Record into the parent zone in time could result in DNSSEC errors when Traffic Router tries to sig [...]
-Once these fields have been correctly entered, a user can click Generate KSK. The user will be presented with a confirmation screen to help them understand the impact of generating the KSK. If a user confirms, the KSK will be generated and stored in Traffic Vault.
+Once these fields have been correctly entered, a user can click Generate KSK. The user will be presented with a confirmation screen to help them understand the impact of generating the KSK. If a user confirms, the :abbr:`KSK (Key Signing Key)` will be generated and stored in Traffic Vault.
-Additionally, Traffic Ops also performs some systematic management of DNSSEC keys. This management is necessary to help keep keys in sync for Delivery Services in a CDN as well as to make sure keys do not expire without human intervention.
+Additionally, Traffic Ops also performs some systematic management of :abbr:`DNSSEC (DNS Security Extensions)` keys. This management is necessary to help keep keys in sync for :term:`Delivery Service`\ s in a CDN as well as to make sure keys do not expire without human intervention.
Generation of keys for new Delivery Services
--------------------------------------------
-If a new Delivery Service is created and added to a CDN that has DNSSEC enabled, Traffic Ops will create DNSSEC keys for the Delivery Service and store them in Traffic Vault.
+If a new :term:`Delivery Service` is created and added to a CDN that has :abbr:`DNSSEC (DNS Security Extensions)` enabled, Traffic Ops will create :abbr:`DNSSEC (DNS Security Extensions)` keys for the :term:`Delivery Service` and store them in Traffic Vault.
Regeneration of expiring keys for a Delivery Service
----------------------------------------------------
-Traffic Ops has a process, controlled by cron, to check for expired or expiring keys and re-generate them. The process runs at 5 minute intervals to check and see if keys are expired or close to expiring (withing 10 minutes by default). If keys are expired for a Delivery Service, traffic ops will regenerate new keys and store them in Traffic Vault. This process is the same for the CDN TLD ZSK, however Traffic Ops will not re-generate the CDN TLD KSK systematically. The reason is that [...]
+Traffic Ops has a process, controlled by :manpage:`cron(8)`, to check for expired or expiring keys and re-generate them. The process runs at 5 minute intervals to check and see if keys are expired or close to expiring (withing 10 minutes by default). If keys are expired for a :term:`Delivery Service`, Traffic Ops will regenerate new keys and store them in Traffic Vault. This process is the same for the CDN :abbr:`TLD (Top-Level Domain)` :abbr:`ZSK (Zone Signing Key)`, however Traffic Ops [...]
diff --git a/docs/source/admin/traffic_portal/default_profiles.rst b/docs/source/admin/traffic_portal/default_profiles.rst
index 1a2c2c9..42fa2e6 100644
--- a/docs/source/admin/traffic_portal/default_profiles.rst
+++ b/docs/source/admin/traffic_portal/default_profiles.rst
@@ -13,9 +13,6 @@
.. limitations under the License.
..
-.. index::
- Default Profiles
-
.. _default-profiles:
****************
@@ -25,25 +22,25 @@ Traffic Ops has the concept of :ref:`working-with-profiles`, which are an integr
.. _to-profiles-min-needed:
-Minimum Traffic Ops Profiles needed
------------------------------------
+Minimum Traffic Ops Profiles Needed
+===================================
-- EDGE_ATS_<version>_<platform>_PROFILE.traffic_ops
-- MID_ATS_<version>_<platform>_PROFILE.traffic_ops
-- TRAFFIC_MONITOR_PROFILE.traffic_ops
-- TRAFFIC_ROUTER_PROFILE.traffic_ops
-- TRAFFIC_STATS_PROFILE.traffic_ops
-- EDGE_GROVE_PROFILE.traffic_ops
+- :file:`EDGE_ATS_{version}_{platform}_PROFILE.traffic_ops`
+- :file:`MID_ATS_{version}_{platform}_PROFILE.traffic_ops`
+- :file:`TRAFFIC_MONITOR_PROFILE.traffic_ops`
+- :file:`TRAFFIC_ROUTER_PROFILE.traffic_ops`
+- :file:`TRAFFIC_STATS_PROFILE.traffic_ops`
+- :file:`EDGE_GROVE_PROFILE.traffic_ops`
.. note:: Despite that these have the ``.traffic_ops`` extension, they use JSON to store data. If your syntax highlighting doesn't work in some editor or viewer, try changing the extension to ``.json``.
.. warning:: These profiles will likely need to be modified to suit your system. Many of them contain hardware-specific parameters and parameter values.
Steps to Import a Profile
--------------------------
+=========================
#. Sign into Traffic Portal
-#. Under the 'Configure' menu, select 'Profiles'
-#. From the 'More' drop-down menu, click on 'Import Profile'
+#. Navigate to :menuselection:`Configure --> Profiles`
+#. Click on :menuselection:`More --> Import Profile`
#. Drag and drop your desired profile into the upload pane
-#. Click 'Import'
-#. Continue these steps for each of the :ref:`to-profiles-min-needed`.
+#. Click :guilabel:`Import`
+#. Continue these steps for each of the `Minimum Traffic Ops Profiles Needed`_.
diff --git a/docs/source/admin/traffic_portal/installation.rst b/docs/source/admin/traffic_portal/installation.rst
index afed69d..e357caf 100644
--- a/docs/source/admin/traffic_portal/installation.rst
+++ b/docs/source/admin/traffic_portal/installation.rst
@@ -16,49 +16,45 @@
*****************************
Traffic Portal Administration
*****************************
-Traffic Portal is only supported on CentOS Linux distributions version 7.x. It runs on NodeJS and requires version 6.0 or higher.
+Traffic Portal is only supported on CentOS Linux distributions version 7.x. It runs on `NodeJS <https://nodejs.org/>`_ and requires version 6.0 or higher.
Installing Traffic Portal
=========================
-#. Download the Traffic Portal RPM from `Apache Jenkins <https://builds.apache.org/job/trafficcontrol-master-build/>`_ or build the Traffic Portal RPM from source (e.g. by running ``./pkg -v traffic_portal_build`` as the root user or with ``sudo`` from the top level of the source repository).
+#. Download the Traffic Portal RPM from `Apache Jenkins <https://builds.apache.org/job/trafficcontrol-master-build/>`_ or build the Traffic Portal RPM from source using the instructions in :ref:`dev-building`.
#. Copy the Traffic Portal RPM to your server
-#. Install NodeJS. This can be done by building it from source, installing with ``yum install nodejs`` if it happens to be in your available repositories (at version 6.0+), or using the NodeSource setup script like so:
+#. Install NodeJS. This can be done by building it from source, installing with :manpage:`yum(8)` if it happens to be in your available repositories (at version 6.0+), or using the NodeSource setup script.
.. code-block:: bash
+ :caption: Installing NodeJS using the NodeSource Setup Script
curl --silent --location https://rpm.nodesource.com/setup_6.x | sudo bash -
-#. Install the Traffic Portal RPM e.g. by running ``yum install path/to/traffic_portal.rpm`` as the root user or with ``sudo``.
+#. Install the Traffic Portal RPM with :manpage:`yum(8)` or :manpage:`rpm(8)` e.g. by running ``yum install path/to/traffic_portal.rpm`` as the root user or with :manpage:`sudo(8)`.
Configuring Traffic Portal
==========================
-
-- update /etc/traffic_portal/conf/config.js (if upgrade, reconcile config.js with config.js.rpmnew and then delete config.js.rpmnew)
-- update /opt/traffic_portal/public/traffic_portal_properties.json (if upgrade, reconcile traffic_portal_properties.json with traffic_portal_properties.json.rpmnew and then delete traffic_portal_properties.json.rpmnew)
-- [OPTIONAL] update /opt/traffic_portal/public/resources/assets/css/custom.css (to customize traffic portal skin)
+- update :file:`/etc/traffic_portal/conf/config.js` (if Traffic Portal is being upgraded, reconcile :file:`config.js` with :file:`config.js.rpmnew` and then delete :file:`config.js.rpmnew`)
+- update :file:`/opt/traffic_portal/public/traffic_portal_properties.json` (if Traffic Portal is being upgraded, reconcile :file:`traffic_portal_properties.json` with :file:`traffic_portal_properties.json.rpmnew` and then delete :file:`traffic_portal_properties.json.rpmnew`)
+- Optional: update :file:`/opt/traffic_portal/public/resources/assets/css/custom.css` to customize Traffic Portal styling.
Starting Traffic Portal
=======================
+The Traffic Portal RPM comes with a :manpage:`systemd(1)` unit file, so under normal circumstances Traffic Portal may be started with :manpage:`systemctl(1)`.
-The Traffic Portal RPM comes with a systemd unit file, so under normal circumstances all that is necessary is to run
-
- .. code-block:: bash
-
- systemctl start traffic_portal
+.. code-block:: bash
+ :caption: Starting Traffic Portal
-as the root user or with ``sudo``.
+ systemctl start traffic_portal
Stopping Traffic Portal
=======================
+The Traffic Portal RPM comes with a :manpage:`systemd(1)` unit file, so under normal circumstances Traffic Portal may be stopped with :manpage:`systemctl(1)`.
-If Traffic Portal was started using ``systemctl``, simply run
-
- .. code-block:: bash
-
- systemctl stop traffic_portal
+.. code-block:: bash
+ :caption: Stopping Traffic Portal
-as the root user, or with ``sudo``.
+ systemctl stop traffic_portal
diff --git a/docs/source/admin/traffic_portal/usingtrafficportal.rst b/docs/source/admin/traffic_portal/usingtrafficportal.rst
index ec00d5d..692b573 100644
--- a/docs/source/admin/traffic_portal/usingtrafficportal.rst
+++ b/docs/source/admin/traffic_portal/usingtrafficportal.rst
@@ -29,7 +29,6 @@ Traffic Portal is the official Traffic Control UI. Traffic Portal typically runs
Dashboard
=========
-
The Dashboard is the default landing page for Traffic Portal. It provides a real-time view into the main performance indicators of the CDNs managed by Traffic Control. It also displays various statistics about the overall health of your CDN.
Current Bandwidth
@@ -39,28 +38,29 @@ Current Connections
The current number of connections to all of your CDNs.
Healthy Caches
- Displays the number of healthy caches across all CDNs. Click the link to view the healthy caches on the cache stats page.
+ Displays the number of healthy caches across all CDNs. Click the link to view the healthy caches on the cache stats page.
Unhealthy Caches
- Displays the number of unhealthy caches across all CDNs. Click the link to view the unhealthy caches on the cache stats page.
+ Displays the number of unhealthy caches across all CDNs. Click the link to view the unhealthy caches on the cache stats page.
Online Caches
- Displays the number of cache servers with ONLINE status. Traffic Monitor will not monitor the state of ONLINE servers. For more information, see :ref:`health-proto`.
+ Displays the number of :term:`cache server` s with ONLINE status. Traffic Monitor will not monitor the state of ONLINE servers [1]_.
Reported Caches
- Displays the number of cache servers with REPORTED status. For more information, see :ref:`health-proto`.
+ Displays the number of :term:`cache server` s with REPORTED status [1]_.
Offline Caches
- Displays the number of cache servers with OFFLINE status. For more information, see :ref:`health-proto`.
+ Displays the number of :term:`cache server` s with OFFLINE status [1]_.
Admin Down Caches
- Displays the number of caches with ADMIN_DOWN status. For more information, see :ref:`health-proto`.
+ Displays the number of caches with ADMIN_DOWN status [1]_.
+
+Each component of this view is updated on the intervals defined in the :file:`traffic_portal_properties.json` configuration file.
-Each component of this view is updated on the intervals defined in the ``tp.domain.com/traffic_portal_properties.json`` configuration file.
+.. [1] For more information, see :ref:`health-proto`.
CDNs
====
-
A table of CDNs with the following columns:
:Name: The name of the CDN
@@ -77,14 +77,13 @@ CDN management includes the ability to (where applicable):
- create a CDN snapshot
- manage a CDN's DNSSEC keys
- manage a CDN's federations
-- view Delivery Services of a CDN
+- view :term:`Delivery Service`\ s of a CDN
- view CDN profiles
- view servers within a CDN
Monitor
=======
-
-The 'Monitor' section of Traffic Portal is used to display statistics regarding the various cache servers within all CDNs visible to the user. It retrieves this information through the Traffic Ops API from Traffic Monitor instances.
+The :guilabel:`Monitor` section of Traffic Portal is used to display statistics regarding the various :term:`cache server` s within all CDNs visible to the user. It retrieves this information through the Traffic Ops API from Traffic Monitor instances.
.. figure:: ./images/tp_menu_monitor.png
:align: center
@@ -95,42 +94,46 @@ The 'Monitor' section of Traffic Portal is used to display statistics regarding
Cache Checks
------------
-A real-time view into the status of each cache.
-
-The cache checks page is intended to give an overview of the caches managed by Traffic Control as well as their status.
+A real-time view into the status of each cache. The :menuselection:`Monitor --> Cache Checks` page is intended to give an overview of the caches managed by Traffic Control as well as their status.
:Hostname: Cache host name
:Profile: The name of the profile applied to the cache
:Status: The status of the cache (one of: ONLINE, REPORTED, ADMIN_DOWN, OFFLINE)
-:UPD: Configuration updates pending for an EDGE or MID
+
+ .. seealso:: :ref:`health-proto`
+
+:UPD: Configuration updates pending for an Edge-tier or Mid-tier :term:`cache server`
:RVL: Content invalidation requests are pending for this server and/or its parent(s)
-:ILO: Ping the iLO interface for EDGE or MID servers
-:10G: Ping the IPv4 address of the EDGE or MID servers
+:ILO: Ping the iLO interface for Edge-tier or Mid-tier :term:`cache server` s
+:10G: Ping the IPv4 address of the Edge-tier or Mid-tier :term:`cache server` s
:FQDN: DNS check that matches what the DNS servers responds with compared to what Traffic Ops has
-:DSCP: Checks the DSCP value of packets from the EDGE server to the Traffic Ops server
-:10G6: Ping the IPv6 address of the EDGE or MID servers
-:MTU: Ping the EDGE or MID using the configured MTU from Traffic Ops
-:RTR: Content Router checks. Checks the health of the Content Routers. Checks the health of the caches using the Content Routers
+:DSCP: Checks the :abbr:`DSCP (Differentiated Services Code Point)` value of packets from the Edge-tier :term:`cache server` to the Traffic Ops server
+:10G6: Ping the IPv6 address of the Edge-tier or Mid-tier :term:`cache server` s
+:MTU: Ping the Edge-tier or Mid-tier using the configured :abbr:`MTU (Maximum Transmission Unit)` from Traffic Ops
+:RTR: Content Router checks. Checks the health of the Traffic Router servers. Also checks the health of the :term:`cache server` s using the Traffic Routers
:CHR: Cache Hit Ratio percent
:CDU: Total Cache Disk Usage percent
-:ORT: Operational Readiness Test - uses the ORT script on the EDGE and MID servers to determine if the configuration in Traffic Ops matches the configuration on the EDGE or MID. The user that this script runs as must have an SSH key on the EDGE servers.
+:ORT: Operational Readiness Test - uses the :term:`ORT` script on the Edge-tier and Mid-tier :term:`cache server` s to determine if the configuration in Traffic Ops matches the configuration on the Edge-tier or Mid-tier. The user as whom this script runs must have an SSH key on the Edge-tier servers.
Cache Stats
-----------
-A table showing the results of the periodic check extension scripts that are run. These can be grouped by :term:`Cache Group` and/or Profile.
+A table showing the results of the periodic :ref:`to-check-ext` that are run. These can be grouped by :term:`Cache Group` and/or :term:`Profile`.
-:Profile: Name of the profile applied to the Edge-tier or Mid-tier cache server
-:Host: 'ALL' for entries grouped by :term:`Cache Group`, or the hostname of a particular cache server
+:Profile: Name of the :term:`Profile` applied to the Edge-tier or Mid-tier :term:`cache server`
+:Host: 'ALL' for entries grouped by :term:`Cache Group`, or the hostname of a particular :term:`cache server`
:Cache Group: Name of the :term:`Cache Group` to which this server belongs, or the name of the :term:`Cache Group` that is grouped for entries grouped by :term:`Cache Group`
-:Healthy: True/False as determined by Traffic Monitor (See :ref:`health-proto`)
-:Status: Status of the cache or :term:`Cache Group`
-:Connections: Number of connections to this cache server or :term:`Cache Group`
-:MbpsOut: Data flow outward (toward client) in Megabits per second
+:Healthy: True/False as determined by Traffic Monitor
+
+ .. seealso:: :ref:`health-proto`
+
+:Status: Status of the :term:`cache server` or :term:`Cache Group`
+:Connections: Number of connections to this :term:`cache server` or :term:`Cache Group`
+:MbpsOut: Data flow rate outward from the CDN (toward client) in Megabits per second
Services
========
-'Services' groups the functionality to modify Delivery Services - for those users with the necessary permissions - or make Requests for such changes - for uses without necessary permissions.
+:guilabel:`Services` groups the functionality to modify :term:`Delivery Service`\ s - for those users with the necessary permissions - or make Requests for such changes - for uses without necessary permissions.
.. figure:: images/tp_table_ds_requests.png
:align: center
@@ -138,19 +141,19 @@ Services
Table of Delivery Service Requests
-Delivery Services
+Delivery Service
-----------------
-This page contains a table displaying all Delivery Services visible to the user. Each entry in this table has the following fields:
+This page contains a table displaying all :term:`Delivery Service`\ s visible to the user. Each entry in this table has the following fields:
-:Key (XML ID): A unique string that identifies this Delivery Service
-:Tenant: The tenant to which the Delivery Service is assigned
-:Origin: The Origin Server's base URL. This includes the protocol (HTTP or HTTPS). Example: ``http://movies.origin.com``
-:Active: When this is set to 'false', Traffic Router will not serve DNS or HTTP responses for this Delivery Service
-:Type: The type of content routing this Delivery Service will use
+:Key (XML ID): A unique string that identifies this :term:`Delivery Service`
+:Tenant: The tenant to which the :term:`Delivery Service` is assigned
+:Origin: The Origin Server's base URL. This includes the protocol (HTTP or HTTPS). Example: ``http://movies.origin.com``
+:Active: When this is set to 'false', Traffic Router will not serve DNS or HTTP responses for this :term:`Delivery Service`
+:Type: The type of content routing this :term:`Delivery Service` will use
.. seealso:: :ref:`ds-types`
-:Protocol: The protocol which which this Delivery Service serves clients. Its value is one of:
+:Protocol: The protocol which which this :term:`Delivery Service`\ serves clients. Its value is one of:
HTTP
Only insecure requests will be serviced
@@ -161,45 +164,45 @@ This page contains a table displaying all Delivery Services visible to the user.
HTTP to HTTPS
Insecure requests will be redirected to secure locations and secure requests are serviced normally
-:CDN: The CDN to which the Delivery Service belongs
-:IPv6 Enabled: When set to 'true', the Traffic Router will respond to AAAA DNS requests for the routed name of this Delivery Service, Otherwise, only A records will be served
-:DSCP: The Differentiated Services Code Point (DSCP) value with which to mark IP packets sent to the client
-:Signing Algorithm: See :ref:`signed-urls`
-:Query String Handling: Describes how the Delivery Service treats query strings. It has one of the following possible values:
+:CDN: The CDN to which the :term:`Delivery Service` belongs
+:IPv6 Enabled: When set to 'true', the Traffic Router will respond to AAAA DNS requests for the routed name of this :term:`Delivery Service`, Otherwise, only A records will be served
+:DSCP: The :abbr:`DSCP (Differentiated Services Code Point)` value with which to mark IP packets sent to the client
+:Signing Algorithm: See :ref:`signed-urls`
+:Query String Handling: Describes how the :term:`Delivery Service` treats query strings. It has one of the following possible values:
USE
- The query string will be used in the Apache Traffic Server (ATS) 'cache key' and is passed in requests to the origin (each unique query string is treated as a unique URL)
+ The query string will be used in the :abbr:`ATS (Apache Traffic Server)` `'cache key' <https://docs.trafficserver.apache.org/en/7.1.x/appendices/glossary.en.html#term-cache-key>`_ and is passed in requests to the origin (each unique query string is treated as a unique URL)
IGNORE
- The query string will *not* be used in the ATS 'cache key', but *will* be passed in requests to the origin
+ The query string will *not* be used in the :abbr:`ATS (Apache Traffic Server)` `'cache key' <https://docs.trafficserver.apache.org/en/7.1.x/appendices/glossary.en.html#term-cache-key>`_, but *will* be passed in requests to the origin
DROP
- The query string is stripped from the request URL at the Edge-tier cache, and so is not used in the ATS 'cache key', and is not passed in requests to the origin
+ The query string is stripped from the request URL at the Edge-tier cache, and so is not used in the :abbr:`ATS (Apache Traffic Server)` `'cache key' <https://docs.trafficserver.apache.org/en/7.1.x/appendices/glossary.en.html#term-cache-key>`_, and is not passed in requests to the origin
.. seealso:: :ref:`qstring-handling`
-:Last Updated: Timestamp when the Delivery Service was last updated. |
-
-Delivery Service management includes the ability to (where applicable):
-
-- create a new Delivery Service
-- clone an existing Delivery Service
-- update an existing Delivery Service
-- delete an existing Delivery Service
-- compare Delivery Services
-- manage Delivery Service SSL keys
-- manage Delivery Service URL signature keys
-- manage Delivery Service URI signing keys
-- view and assign Delivery Service servers
-- create, update and delete Delivery Service regular expressions
-- view and create Delivery Service invalidate content jobs
+:Last Updated: The time at which the :term:`Delivery Service` was last updated
+
+:term:`Delivery Service` management includes the ability to (where applicable):
+
+- create a new :term:`Delivery Service`
+- clone an existing :term:`Delivery Service`
+- update an existing :term:`Delivery Service`
+- delete an existing :term:`Delivery Service`
+- compare :term:`Delivery Service`\ s
+- manage :term:`Delivery Service` SSL keys
+- manage :term:`Delivery Service` URL signature keys
+- manage :term:`Delivery Service` URI signing keys
+- view and assign :term:`Delivery Service`\ servers
+- create, update and delete :term:`Delivery Service` regular expressions
+- view and create :term:`Delivery Service` invalidate content jobs
- manage steering targets
Delivery Service Requests
-------------------------
-If enabled in the ``tp.domain.com/traffic_portal_properties.json``, all Delivery Service changes (create, update and delete) are captured as a Delivery Service Request and must be reviewed before fulfillment/deployment.
+If enabled in the :file:`traffic_portal_properties.json` configuration file, all :term:`Delivery Service` changes (create, update and delete) are captured as a Delivery Service Request and must be reviewed before fulfillment/deployment.
-:Delivery Service: A unique string that identifies the Delivery Service that with which the request is associated. This unique string is also known (and ofter referred to within documentation and source code) as a 'Delivery Service key' or 'XML ID'. |
-:Type: The type of Delivery Service Request: 'create', 'update', or 'delete' according to what was requested
-:Status: The status of the Delivery Service Request. Has the following possible values:
+:term:`Delivery Service`: A unique string that identifies the :term:`Delivery Service` with which the request is associated. This unique string is also known (and ofter referred to within documentation and source code) as a :term:`Delivery Service` key' or 'XML ID'/'xml_id'/'xmlid'
+:Type: The type of Delivery Service Request: 'create', 'update', or 'delete' according to what was requested
+:Status: The status of the Delivery Service Request. Has the following possible values:
draft
The Delivery Service Request is *not* ready for review and fulfillment
@@ -212,11 +215,11 @@ If enabled in the ``tp.domain.com/traffic_portal_properties.json``, all Delivery
complete
The Delivery Service Request has been fulfilled and the changes have been deployed
-:Author: The user responsible for creating the Delivery Service Request
-:Assignee: The user responsible for fulfilling the Delivery Service Request. Currently, the operations role or above is required to assign Delivery Service Requests
+:Author: The user responsible for creating the Delivery Service Request
+:Assignee: The user responsible for fulfilling the Delivery Service Request. Currently, the operations role or above is required to assign Delivery Service Requests
:Last Edited By: The last user to edit the Delivery Service Request
-:Created: Relative time indicating when the Delivery Service Request was created
-:Actions: Actions that can be performed on a Delivery Service Request. The following actions are provided:
+:Created: Relative time indicating when the Delivery Service Request was created
+:Actions: Actions that can be performed on a Delivery Service Request. The following actions are provided:
fulfill
Implement the changes captured in the Delivery Service Request
@@ -225,22 +228,22 @@ If enabled in the ``tp.domain.com/traffic_portal_properties.json``, all Delivery
delete
Delete the Delivery Service Request
-Delivery service request management includes the ability to (where applicable):
+Delivery Service Request management includes the ability to (where applicable):
-- create a new delivery service request
-- update an existing delivery service request
-- delete an existing delivery service request
-- update the status of a delivery service request
-- assign a delivery service request
-- reject a delivery service request
-- fulfill a delivery service request
-- complete a delivery service request
+- create a new Delivery Service Request
+- update an existing Delivery Service Request
+- delete an existing Delivery Service Request
+- update the status of a Delivery Service Request
+- assign a Delivery Service Request
+- reject a Delivery Service Request
+- fulfill a Delivery Service Request
+- complete a Delivery Service Request
.. seealso:: :ref:`ds_requests`
Configure
=========
-Interfaces for managing the various components of Traffic Control and how they interact are grouped under 'Configure'.
+Interfaces for managing the various components of Traffic Control and how they interact are grouped under :guilabel:`Configure`.
.. figure:: ./images/tp_menu_configure.png
:align: center
@@ -248,21 +251,26 @@ Interfaces for managing the various components of Traffic Control and how they i
The 'Configure' Menu
+.. _tp-servers-page:
+
Servers
-------
-A table of all servers (of all kinds) across all Delivery Services visible to the user, with functionality to create, update, and delete them. It has the following columns:
-
-:UPD: 'true' when updates to the server's configuration are pending, 'false' otherwise
-:Host: The hostname of the server
-:Domain: The server's domain. (The FQDN of the server is given by 'Host.Domain')
-:IP: The server's IPv4 address
-:IPv6: The server's IPv6 address
-:Status: The server's status (see :ref:`health-proto`)
-:Type: The type of server e.g. EDGE for an Edge-tier cache
-:Profile: The name of the server's profile
-:CDN: The name of the CDN to which this server is assigned (if any)
+A table of all servers (of all kinds) across all :term:`Delivery Service`\ s and CDNs visible to the user. It has the following columns:
+
+:UPD: 'true' when updates to the server's configuration are pending, 'false' otherwise
+:Host: The hostname of the server
+:Domain: The server's domain. (The :abbr:`FQDN (Fully Qualified Domain Name)` of the server is given by 'Host.Domain')
+:IP: The server's IPv4 address
+:IPv6: The server's IPv6 address
+:Status: The server's status
+
+ .. seealso:: :ref:`health-proto`
+
+:Type: The type of server e.g. EDGE for an Edge-tier :term:`cache server`
+:Profile: The name of the server's :term:`Profile`
+:CDN: The name of the CDN to which this server is assigned (if any)
:Cache Group: The name of the :term:`Cache Group` to which this server belongs
-:ILO: If not empty, this is the IPv4 address of the server's Integrated Lights-Out (ILO) interface
+:ILO: If not empty, this is the IPv4 address of the server's :abbr:`ILO (Integrated Lights-Out)` interface
.. seealso:: `Hewlett Packard ILO Wikipedia Page <https://en.wikipedia.org/wiki/HP_Integrated_Lights-Out>`_
@@ -273,94 +281,90 @@ Server management includes the ability to (where applicable):
- delete an existing server
- queue/clear updates on a server
- update server status
-- view server delivery services
+- view server :term:`Delivery Service`\ s
- view server configuration files
-- clone delivery service assignments
-- assign delivery services to server
+- clone :term:`Delivery Service` assignments
+- assign :term:`Delivery Service`\ s to server
+.. _tp-profiles-page:
Profiles
--------
-A table of all profiles. From here you can see parameters, servers and Delivery Services assigned to each profile, as well as the ability to create, update, delete, import and export profiles.
-Each entry in the table has these fields:
-
-:Name: The name of the profile
-:Type: The type of this profile, which indicates the kinds of objects to which the profile may be assigned
-:Routing Disabled: For profiles applied to cache servers (Edge-tier or Mid-tier) this indicates that Traffic Router will refuse to provide routes to these machines
-:Description: A user-defined description of the profile, typically indicating its purpose
-:CDN: The CDN to which this profile is restricted. To use the same profile across multiple CDNs, clone the profile and change the clone's CDN field.
-
-Profile management includes the ability to (where applicable):
-
-- create a new profile
-- update an existing profile
-- delete an existing profile
-- clone a profile
-- export a profile
-- view profile parameters
-- view profile delivery services
-- view profile servers
+A table of all :term:`Profile`\ s. From here you can see :term:`Parameter`\ s, servers and :term:`Delivery Service`\ s assigned to each :term:`Profile`. Each entry in the table has these fields:
-.. seealso:: :ref:`working-with-profiles`
+:Name: The name of the :term:`Profile`
+:Type: The type of this :term:`Profile`, which indicates the kinds of objects to which the :term:`Profile` may be assigned
+:Routing Disabled: For :term:`Profile`\ s applied to :term:`cache server` s (Edge-tier or Mid-tier) this indicates that Traffic Router will refuse to provide routes to these machines
+:Description: A user-defined description of the :term:`Profile`, typically indicating its purpose
+:CDN: The CDN to which this :term:`Profile` is restricted. To use the same :term:`Profile` across multiple CDNs, clone the :term:`Profile` and change the clone's CDN field.
+:term:`Profile` management includes the ability to (where applicable):
+
+- create a new :term:`Profile`
+- update an existing :term:`Profile`
+- delete an existing :term:`Profile`
+- clone a :term:`Profile`
+- export a :term:`Profile`
+- view :term:`Profile` :term:`Parameter`\ s
+- view :term:`Profile` :term:`Delivery Service`\ s
+- view :term:`Profile` servers
+
+.. seealso:: :ref:`working-with-profiles`
Parameters
----------
-Allows for the creation, update, and deletion of parameters, as well as modification of their assignment to servers and Delivery Services.
-This page displays a table of parameters with the following columns:
-
-:Name: The name of the parameter
-:Config File: The configuration file where this parameter is stored, possibly the special value ``location``, indicating that this parameter actually names the location of a configuration file rather than its contents, or ``package`` to indicate that this parameter specifies a package to be installed rather than anything to do with configuration files
-:Value: The value of the parameter. The meaning of this depends on the value of 'Config File'
-:Secure: When this is 'true', a user requesting to see this parameter will see the value ``********`` instead of its actual value if the user's permission level isn't 'admin'
-:Profiles: The number of profiles currently using this parameter
+This page displays a table of :term:`Parameter`\ s from all :term:`Profile`\ s with the following columns:
-Parameter management includes the ability to (where applicable):
+:Name: The name of the :term:`Parameter`
+:Config File: The configuration file where this :term:`Parameter` is stored, possibly the special value ``location``, indicating that this :term:`Parameter` actually names the location of a configuration file rather than its contents, or ``package`` to indicate that this :term:`Parameter` specifies a package to be installed rather than anything to do with configuration files
+:Value: The value of the :term:`Parameter`. The meaning of this depends on the value of 'Config File'
+:Secure: When this is 'true', a user requesting to see this :term:`Parameter` will see the value ``********`` instead of its actual value if the user's permission role isn't 'admin'
+:Profiles: The number of :term:`Profile`\ s currently using this :term:`Parameter`
-- create a new parameter
-- update an existing parameter
-- delete an existing parameter
-- view parameter profiles
+:term:`Parameter` management includes the ability to (where applicable):
+- create a new :term:`Parameter`
+- update an existing :term:`Parameter`
+- delete an existing :term:`Parameter`
+- view :term:`Parameter` :term:`Profile`\ s
+- manage assignments of a :term:`Parameter` to one or more :term:`Profile`\ s and/or :term:`Delivery Service`\ s
.. _tp-configure-types:
Types
-----
-'Types' groups Delivery Services, servers and :term:`Cache Group`\ s for various purposes. Each entry in the table shown on this page has the following fields:
+:term:`Type`\ s group :term:`Delivery Service`\ s, servers and :term:`Cache Group`\ s for various purposes. Each entry in the table shown on this page has the following fields:
-:Name: The name of the Type
-:Use In Table: States the use of this Type, e.g. ``server`` indicates this is a Type assigned to servers
-:Description: A short, usually user-defined, description of the Type
+:Name: The name of the :term:`Type`
+:Use In Table: States the use of this :term:`Type`, e.g. ``server`` indicates this is a :term:`Type` assigned to servers
+:Description: A short, usually user-defined, description of the :term:`Type`
-Type management includes the ability to (where applicable):
-
-- create a new type
-- update an existing type
-- delete an existing type
-- view delivery services assigned to a type
-- view servers assigned to a type
-- view :term:`Cache Group`\ s assigned to a type
+:term:`Type` management includes the ability to (where applicable):
+- create a new :term:`Type`
+- update an existing :term:`Type`
+- delete an existing :term:`Type`
+- view :term:`Delivery Service`\ s assigned to a :term:`Type`
+- view servers assigned to a :term:`Type`
+- view :term:`Cache Group`\ s assigned to a :term:`Type`
Statuses
--------
-A table of all possible server statuses, with the ability to create, update, and delete statuses. This page shows a table of statuses with the following columns:
-
-:Name: The name of this status
-:Description: A short, usually user-defined, description of this status
+This page shows a table of :term:`Status`\ es with the following columns:
-Status management includes the ability to (where applicable):
+:Name: The name of this :term:`Status`
+:Description: A short, usually user-defined, description of this :term:`Status`
-- create a new status
-- update an existing status
-- delete an existing status
-- view status servers
+:term:`Status` management includes the ability to (where applicable):
+- create a new :term:`Status`
+- update an existing :term:`Status`
+- delete an existing :term:`Status`
+- view :term:`Status`\ es
Topology
========
-'Topology' groups views and functionality that deal with how CDNs and their Traffic Control components are grouped and distributed, both on a logical level as well as a physical level.
+:guilabel:`Topology` groups views and functionality that deal with how CDNs and their Traffic Control components are grouped and distributed, both on a logical level as well as a physical level.
.. figure:: ./images/tp_menu_topology.png
:align: center
@@ -371,14 +375,13 @@ Topology
Cache Groups
------------
-':term:`Cache Group`\ s' are sets of cache servers, typically grouped by geographic proximity. This menu allows user to add or remove caches from :term:`Cache Group`\ s as well as creating, updating and deleting :term:`Cache Group`\ s themselves. Each entry in the table of :term:`Cache Group`\ s on this page has the following fields:
+This page is a table of :term:`Cache Group`\ s, each entry of which has the following fields:
-:Name: The full name of this :term:`Cache Group`
-:Short Name: A shorter, more human-friendly name for this :term:`Cache Group`
-:Type: The Type of this Cache Group (see :ref:`tp-configure-types`)
-:Latitude: A geographic latitude assigned to this :term:`Cache Group`
-:Longitude: A geographic longitude assigned to this :term:`Cache Group`
-:Failover Cache Groups: A list of :term:`Cache Group`\ s to fallback to in case of failure. Fallback to Geo Failover allows fallback geographically in case of failure.
+:Name: The full name of this :term:`Cache Group`
+:Short Name: A shorter, more human-friendly name for this :term:`Cache Group`
+:Type: The :term:`Type` of this :term:`Cache Group`
+:Latitude: A geographic latitude assigned to this :term:`Cache Group`
+:Longitude: A geographic longitude assigned to this :term:`Cache Group`
:term:`Cache Group` management includes the ability to (where applicable):
@@ -386,14 +389,16 @@ Cache Groups
- update an existing :term:`Cache Group`
- delete an existing :term:`Cache Group`
- queue/clear updates for all servers in a :term:`Cache Group`
-- view :term:`Cache Group` ASNs
-- view and assign :term:`Cache Group` parameters
-- view :term:`Cache Group` servers
+- view :term:`Cache Group` :abbr:`ASN (Autonomous System Number)`\ s
+
+ .. seealso:: `The Wikipedia page on Autonomous System Numbers <https://en.wikipedia.org/wiki/Autonomous_System_Number>`_
+- view and assign :term:`Cache Group` :term:`Parameter`\ s
+- view :term:`Cache Group` servers
Coordinates
-----------
-'Coordinates' allows a label to be given to a set of geographic coordinates for ease of use. Each entry in the table on this page has the following fields:
+:menuselection:`Topology --> Coordinates` allows a label to be given to a set of geographic coordinates for ease of use. Each entry in the table on this page has the following fields:
:Name: The name of this coordinate pair
:Latitude: The geographic latitude part of the coordinate pair
@@ -405,68 +410,69 @@ Coordination management includes the ability to (where applicable):
- update an existing coordinate pair
- delete an existing coordinate pair
-
Phys Locations
--------------
-A table of physical locations which may be assigned to servers and :term:`Cache Group`\ s, typically for the purpose of optimizing client routing. Here they can be created, updated deleted and assigned. Each entry has the following columns:
+A table of :term:`Physical Location`\ s which may be assigned to servers and :term:`Cache Group`\ s, typically for the purpose of optimizing client routing. Each entry has the following columns:
-:Name: The full name of the physical location
-:Short Name: A shorter, more human-friendly name for this physical location
-:Address: The location's street address (street number and name)
-:City: The city within which the location resides
-:State: The state within which the location's city lies
-:Region: The Region to which this physical location has been assigned
+:Name: The full name of the :term:`Physical Location`
+:Short Name: A shorter, more human-friendly name for this :term:`Physical Location`
+:Address: The :term:`Physical Location`'s street address (street number and name)
+:City: The city within which the :term:`Physical Location` resides
+:State: The state within which the :term:`Physical Location`'s city lies
+:Region: The :term:`Region` to which this :term:`Physical Location` has been assigned
-Physical location management includes the ability to (where applicable):
-
-- create a new physical location
-- update an existing physical location
-- delete an existing physical location
-- view physical location servers
+:term:`Physical Location` management includes the ability to (where applicable):
+- create a new :term:`Physical Location`
+- update an existing :term:`Physical Location`
+- delete an existing :term:`Physical Location`
+- view :term:`Physical Location` servers
Divisions
---------
-Here Divisions may be created and deleted, and their constituent Regions may be viewed. Each entry in the table on this page has the following fields:
+Each entry in the table of :term:`Division`\ s on this page has the following fields:
-:Name: The name of the Division
+:Name: The name of the :term:`Division`
-Division management includes the ability to (where applicable):
+:term:`Division` management includes the ability to (where applicable):
+- create a new :term:`Division`
+- delete an existing :term:`Division`
+- modify an existing :term:`Division`
+- view :term:`Region`\ s within a :term:`Division`
Regions
-------
-Regions are groups of :term:`Cache Group`\ s, and are themselves grouped into Divisions. Each entry in the table on this page has the following fields:
-
-:Name: The name of this Region
-:Division: The Division to which this Region is assigned
+Each entry in the table of :term:`Region`\ s on this page has the following fields:
-Region management includes the ability to (where applicable):
+:Name: The name of this :term:`Region`
+:Division: The :term:`Division` to which this :term:`Region` is assigned
-- create a new Region
-- update an existing Region
-- delete an existing Region
-- view Region physical locations
+:term:`Region` management includes the ability to (where applicable):
+- create a new :term:`Region`
+- update an existing :term:`Region`
+- delete an existing :term:`Region`
+- view :term:`Physical Location`\ s within a :term:`Region`
ASNs
----
-Manage Autonomous System Numbers (ASNs). Each entry in the table on this page has the following fields:
+Manage :abbr:`ASN (Autonomous System Number)`\ s. Each entry in the table on this page has the following fields:
-:ASN: The actual ASN
-:Cache Group: The :term:`Cache Group` to which this ASN is assigned
+:ASN: The actual :abbr:`ASN (Autonomous System Number)`
+:Cache Group: The :term:`Cache Group` to which this :abbr:`ASN (Autonomous System Number)` is assigned
-ASN management includes the ability to (where applicable):
+:abbr:`ASN (Autonomous System Number)` management includes the ability to (where applicable):
-- create a new ASN
-- update an existing ASN
-- delete an existing ASN
+- create a new :abbr:`ASN (Autonomous System Number)`
+- update an existing :abbr:`ASN (Autonomous System Number)`
+- delete an existing :abbr:`ASN (Autonomous System Number)`
.. seealso:: `Autonomous System (Internet) Wikipedia Page <https://en.wikipedia.org/wiki/Autonomous_system_(Internet)>`_
-
Tools
=====
+:guilabel:`Tools` contains various tools that don't directly relate to manipulating Traffic Control components or their groupings.
.. figure:: ./images/tp_menu_tools.png
:align: center
@@ -474,15 +480,13 @@ Tools
The 'Tools' Menu
-'Tools' contains various tools that don't directly relate to manipulating Traffic Control components or their groupings.
-
Invalidate Content
------------------
-Here, specific assets can be invalidated in all caches of a Delivery Service, forcing content to be updated from the origin. Specifically, this *doesn't* mean that cache servers will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the Invalidate Content Job's Time To Live (TTL) expires. Each entry in the table on this page has the following fields:
+Here, specific assets can be invalidated in all caches of a :term:`Delivery Service`, forcing content to be updated from the origin. Specifically, this *doesn't* mean that :term:`cache server` s will immediately remove items from their caches, but rather will fetch new copies whenever a request is made matching the 'Asset URL' regular expression. This behavior persists until the Invalidate Content Job's :abbr:`TTL (Time To Live)` expires. Each entry in the table on this page has the foll [...]
-:Delivery Service: The Delivery Service to which to apply this Invalidate Content Job
+:term:`Delivery Service`: The :term:`Delivery Service` to which to apply this Invalidate Content Job
:Asset URL: A URL or regular expression which describes the asset(s) to be invalidated
-:Parameters: So far, the only use for this is setting a TTL over which the Invalidate Content Job shall remain active
+:Parameters: So far, the only use for this is setting a :abbr:`TTL (Time To Live)` over which the Invalidate Content Job shall remain active
:Start: An effective start time until which the job is delayed
:Created By: The user name of the person who created this Invalidate Content Job
@@ -497,7 +501,7 @@ Generates a boot-able system image for any of the servers in the Servers table (
Copy Server Attributes From
Optional. This option lets the user choose a server from the Traffic Ops database and will auto-fill the other fields as much as possible based on that server's properties
OS Version
- This list is populated by modifying the ``osversions.cfg`` file on the Traffic Ops server. This file maps OS names to the name of a directory under ``app/public/iso/`` directory within the Traffic Ops install directory
+ This list is populated by modifying the :file:`osversions.cfg` file on the Traffic Ops server. This file maps OS names to the name of a directory under ``app/public/iso/`` directory within the Traffic Ops install directory
Hostname
The desired hostname of the resultant system
Domain
@@ -513,7 +517,7 @@ DHCP
The system's network gateway's IPv4 Address
Network MTU
- The system's network's Maximum Transmission Unit (MTU). Despite being a text field, this can only be 1500 or 9000 - it should almost always be 1500
+ The system's network's :abbr:`MTU (Maximum Transmission Unit)`. Despite being a text field, this can only be 1500 or 9000 - it should almost always be 1500
.. seealso:: `The Maximum transmission unit Wikipedia Page <https://en.wikipedia.org/wiki/Maximum_transmission_unit>`_
@@ -524,17 +528,15 @@ Root Password
Confirm Root Password
Repeat the 'Root Password' to be sure it's right
Interface Name
- Optional. The name of the resultant system's network interface. Typical values are bond0, eth4, etc. If bond0 is entered, a Link Aggregation Control Protocol bonding configuration will be written
+ Optional. The name of the resultant system's network interface. Typical values are ``bond0``, ``eth4``, etc. If ``bond0`` is entered, a Link Aggregation Control Protocol bonding configuration will be written
.. seealso:: `The Link aggregation Wikipedia Page <https://en.wikipedia.org/wiki/Link_aggregation>`_
Stream ISO
If this is 'yes', then the download will start immediately as the ISO is written directly to the socket connection to Traffic Ops. If this is 'no', then the download will begin only *after* the ISO has finished being generated. For almost all use cases, this should be 'yes'.
-
User Admin
==========
-
This section offers administrative functionality for users and their permissions.
.. figure:: ./images/tp_menu_user_admin.png
@@ -550,47 +552,46 @@ This page lists all the users that are visible to the user (so, for 'admin' user
:Full Name: The user's full, real name
:Username: The user's username
:Email: The user's email address
-:Tenant: The user's Tenant
-:Role: The user's Role
+:Tenant: The user's :term:`Tenant`
+:Role: The user's :term:`Role`
User management includes the ability to (where applicable):
- register a new user
- create a new user
- update an existing user
-- view delivery services visible to a user
-
+- view :term:`Delivery Service`\ s visible to a user
Tenants
-------
-A 'Tenant' essentially groups users with the Delivery Services about which they're allowed to know. Each entry in the table on this page has the following entries:
+Each entry in the table of :term:`Tenant`\ s on this page has the following entries:
-:Name: The name of the Tenant
-:Active: If 'true' users of this Tenant group are allowed to login and have active Delivery Services
-:Parent: The parent of this Tenant. The default is the 'root' Tenant, which has no users.
+:Name: The name of the :term:`Tenant`
+:Active: If 'true' users of this :term:`Tenant` group are allowed to login and have active :term:`Delivery Service`\ s
+:Parent: The parent of this :term:`Tenant`. The default is the 'root' :term:`Tenant`, which has no users.
-Tenant management includes the ability to (where applicable):
+:term:`Tenant` management includes the ability to (where applicable):
-- create a new tenant
-- update an existing tenant
-- delete an existing tenant
-- view users assigned to a tenant
-- view delivery services assigned to a tenant
+- create a new :term:`Tenant`
+- update an existing :term:`Tenant`
+- delete an existing :term:`Tenant`
+- view users assigned to a :term:`Tenant`
+- view :term:`Delivery Service`\ s assigned to a :term:`Tenant`
Roles
-----
-'Roles' grant a user permissions to do certain things. Each entry in the table on this page has the following fields:
+Each entry in the table of :term:`Role`\ s on this page has the following fields:
-:Name: The name of the role
-:Privilege Level: The privilege level of this role. This is a whole number that actually controls what a user is allowed to do. Higher numbers correspond to higher permission levels
-:Description: A short description of the role and what it is allowed to do
+:Name: The name of the :term:`Role`
+:Privilege Level: The privilege level of this :term:`Role`. This is a whole number that actually controls what a user is allowed to do. Higher numbers correspond to higher permission levels
+:Description: A short description of the :term:`Role` and what it is allowed to do
Role management includes the ability to (where applicable):
-- view all roles
-- create new roles
+- view all :term:`Role`\ s
+- create new :term:`Role`
-.. note:: Roles cannot be deleted through the Traffic Portal UI
+.. note:: :term:`Role`\ s cannot be deleted through the Traffic Portal UI
Other
=====
@@ -608,4 +609,4 @@ This is just a link to `the Traffic Control Documentation <https://trafficcontro
Custom Menu Items
-----------------
-This section is configurable in the ``tp.domain.com/traffic_portal_properties.json`` configuration file, in the ``customMenu`` section.
+This section is configurable in the :file:`traffic_portal_properties.json` configuration file, in the ``customMenu`` section.
diff --git a/docs/source/admin/traffic_router.rst b/docs/source/admin/traffic_router.rst
index 9cf9f8b..b44abd3 100644
--- a/docs/source/admin/traffic_router.rst
+++ b/docs/source/admin/traffic_router.rst
@@ -13,17 +13,14 @@
.. limitations under the License.
..
+.. _tr-admin:
+
*****************************
Traffic Router Administration
*****************************
-.. contents::
- :depth: 2
- :backlinks: top
-
-Installing Traffic Router
-==========================
-The following are requirements to ensure an accurate set up:
+Requirements
+============
* CentOS 7
* 4 CPUs
* 8GB of RAM
@@ -33,157 +30,183 @@ The following are requirements to ensure an accurate set up:
.. Note:: Hardware requirements are generally doubled if :ref:`tr-DNSSEC` is enabled
-#. If no suitable profile exists, create a new profile for Traffic Router ('Configure' -> 'Profiles' -> '+').
+Installing Traffic Router
+=========================
+#. If no suitable :term:`Profile` exists, create a new :term:`Profile` for Traffic Router via the :guilabel:`+` button on the :ref:`tp-profiles-page` page in Traffic Portal
.. warning:: Traffic Ops will *only* recognize a profile as assignable to a Traffic Router if its name starts with the prefix ``ccr-``. The reason for this is a legacy limitation related to the old name for Traffic Router (Comcast Cloud Router), and will (hopefully) be rectified in the future as the old Perl parts of Traffic Ops are re-written in Go.
-#. Enter the Traffic Router server into Traffic Portal (or via the Traffic Ops API), assign to it a Traffic Router profile, and ensure that its status is set to ``ONLINE``.
-#. Ensure the Fully Qualified Domain Name (FQDN) of the Traffic Router is resolvable in DNS. This FQDN must be resolvable by the clients expected to use this CDN.
-#. Install a Traffic Router server package, either from source or via ``yum install traffic_router`` if it happens to be in your repositories (check with ``yum whatprovides traffic_router``).
+#. Enter the Traffic Router server into Traffic Portal on the :ref:`tp-servers-page` (or via the :ref:`to-api`), assign to it a Traffic Router :term:`Profile`, and ensure that its status is set to ``ONLINE``.
+#. Ensure the :abbr:`FQDN (Fully Qualified Domain Name)` of the Traffic Router is resolvable in DNS. This :abbr:`FQDN (Fully Qualified Domain Name)` must be resolvable by the clients expected to use this CDN.
+#. Install a Traffic Router server package, either from source or using a :file:`traffic_router-{version string}.rpm` package generated using the instructions in :ref:`dev-building`.
- .. Note:: As of Traffic Control version 3.0, Traffic Router depends upon a package called ``tomcat``. This package should have been created when you built Traffic Router. If you get an error while installing the ``traffic_router`` package make sure that the ``tomcat`` package is available in your package repositories.
+ .. versionchanged:: 3.0
+ As of version 3.0, Traffic Router depends upon a package called ``tomcat``. This package should have been created when Traffic Router was built. If installing the ``traffic_router`` produces a depenedency error, make sure that the ``tomcat`` package is available in an accessible :manpage:`yum(8)` repository.
-#. Edit ``/opt/traffic_router/conf/traffic_monitor.properties`` and specify the correct online Traffic Monitor(s) for your CDN. See :ref:`tr-config-files`
+#. Edit :file:`/opt/traffic_router/conf/traffic_monitor.properties` and specify the correct online Traffic Monitor(s) for your CDN.
- ``traffic_monitor.properties``
- URL that should normally point to this file. e.x. ``traffic_monitor.properties=file:/opt/traffic_router/conf/traffic_monitor.properties``
- ``traffic_monitor.properties.reload.period``
- Period to wait (in milliseconds) between reloading this file. e.x. ``traffic_monitor.properties.reload.period=60000``
+ .. seealso:: :ref:`tr-config-files`
-#. Start Traffic Router. This can be done by running ``systemctl start traffic_router`` as the root user (or with ``sudo``), and test DNS lookups against that server with e.g. ``dig`` or ``curl``. To restart Traffic Router, run ``systemctl restart traffic_router`` as the root user (or with ``sudo``). Also, because previously received CRConfigs will be cached, they need to be removed manually to actually be reloaded. This file should be located at ``/opt/traffic_router/db/cr-config.json``.
+ :file:`traffic_monitor.properties`
+ URL that should normally point to this file, e.g. ``traffic_monitor.properties=file:/opt/traffic_router/conf/traffic_monitor.properties``
+ :file:`traffic_monitor.properties.reload.period`
+ Period to wait (in milliseconds) between reloading this file, e.g. ``traffic_monitor.properties.reload.period=60000``
-#. Snapshot CRConfig; See :ref:`snapshot-crconfig`
+#. Start Traffic Router. This is normally done by starting its :manpage:`systemd(1)` service. ``systemctl start traffic_router`` , and test DNS lookups against that server to be sure it's resolving properly. with e.g. ``dig`` or ``curl``. Also, because previously taken CDN :term:`Snapshot`\ s will be cached, they need to be removed manually to actually be reloaded. This file should be located at :file:`/opt/traffic_router/db/cr-config.json`. This should be done before starting or restart [...]
- .. Note:: Once the CRConfig is 'snapshotted', live traffic will be sent to the new Traffic Routers provided that their status has been set to ``ONLINE``.
+ .. code-block:: console
+ :caption: Starting and Testing Traffic Router
-#. Ensure that the parent domain (e.g.: ``cdn.local``) for the CDN's top level domain (e.g.: ``ciab.cdn.local``) contains a delegation (Name Server records) for the new Traffic Router, and that the value specified matches the FQDN used in above.
+ [root@trafficrouter /]# systemctl start traffic_router
+ [root@trafficrouter /]# dig @localhost mycdn.ciab.test
-Configuring Traffic Router
-==========================
+ ; <<>> DiG 9.9.4-RedHat-9.9.4-72.el7 <<>> @localhost mycdn.ciab.test
+ ; (2 servers found)
+ ;; global options: +cmd
+ ;; Got answer:
+ ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 27109
+ ;; flags: qr aa rd; QUERY: 1, ANSWER: 0, AUTHORITY: 1, ADDITIONAL: 0
+ ;; WARNING: recursion requested but not available
-.. Note:: Starting with Traffic Router 1.5, many of the configuration files under ``/opt/traffic_router/conf`` are only needed to override the default configuration values for Traffic Router. Most of the given default values will work well for any CDN. Critical values that must be changed are hostnames and credentials for communicating with other Traffic Control components such as Traffic Ops and Traffic Monitor.
+ ;; QUESTION SECTION:
+ ;mycdn.ciab.test. IN A
-.. Note:: Pre-existing installations that store configuration files under ``/opt/traffic_router/conf`` will still be used and honored for Traffic Router 1.5 onward.
+ ;; AUTHORITY SECTION:
+ mycdn.ciab.test. 30 IN SOA trafficrouter.infra.ciab.test. twelve_monkeys.mycdn.ciab.test. 2019010918 28800 7200 604800 30
-.. Note:: Traffic Router 3.0 has been converted to a formal Tomcat instance, meaning that is now installed separately from the Tomcat servlet engine. The Traffic Router installation package contains all of the Traffic Router-specific software, configuration and startup scripts including some additional configuration files needed for Tomcat. These new configuration files can all be found in the ``/opt/traffic_router/conf`` directory and generally serve to override Tomcat's default settings.
+ ;; Query time: 28 msec
+ ;; SERVER: ::1#53(::1)
+ ;; WHEN: Wed Jan 09 21:27:57 UTC 2019
+ ;; MSG SIZE rcvd: 104
-For the most part, the configuration files and parameters that follow are used to get Traffic Router online and communicating with various Traffic Control components. Once Traffic Router is successfully communicating with Traffic Control, configuration should mostly be performed in Traffic Portal, and will be distributed throughout Traffic Control via the CRConfig snapshot process. See :ref:`snapshot-crconfig` for more information. Please see the parameter documentation for Traffic Route [...]
+#. Perform a CDN :term:`Snapshot`.
-.. _tr-config-files:
+ .. SeeAlso:: :ref:`snapshot-crconfig`
+
+ .. Note:: Once the :term:`Snapshot` is taken, live traffic will be sent to the new Traffic Routers provided that their status has been set to ``ONLINE``.
+
+#. Ensure that the parent domain (e.g.: ``cdn.local``) for the CDN's top level domain (e.g.: ``ciab.cdn.local``) contains a delegation (Name Server records) for the new Traffic Router, and that the value specified matches the :abbr:`FQDN (Fully Qualified Domain Name)` of the Traffic Router.
+
+Configuring Traffic Router
+==========================
+.. versionchanged:: 1.5
+ Many of the configuration files under :file:`/opt/traffic_router/conf` are now only needed to override the default configuration values for Traffic Router. Most of the given default values will work well for any CDN. Critical values that must be changed are hostnames and credentials for communicating with other Traffic Control components such as Traffic Ops and Traffic Monitor. Pre-existing installations that store configuration files under ``/opt/traffic_router/conf`` will still be use [...]
-Configuration files
--------------------
-
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| File name | Parameter | Description | Default Value |
-+============================+===========================================+=======================================================================================+====================================================+
-| traffic_monitor.properties | traffic_monitor.bootstrap.hosts | Semicolon-delimited Traffic Monitor FQDNs - with port numbers as necessary | N/A |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | traffic_monitor.bootstrap.local | Use only the Traffic Monitors specified in local configuration files | ``false`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | traffic_monitor.properties | Path to the ``traffic_monitor.properties`` file; used internally to monitor the file | ``/opt/traffic_router/traffic_monitor.properties`` |
-| | | for changes | |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | traffic_monitor.properties.reload.period | The interval in milliseconds for Traffic Router to wait between reloading this | ``60000`` |
-| | | configuration file | |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| dns.properties | dns.tcp.port | TCP port that Traffic Router will use for incoming DNS requests | ``53`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | dns.tcp.backlog | Maximum length of the queue for incoming TCP connection requests | ``0`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | dns.udp.port | UDP port that Traffic Router will use for incoming DNS requests | ``53`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | dns.max-threads | Maximum number of threads used to process incoming DNS requests | ``1000`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | dns.zones.dir | Path to automatically generated zone files for reference | ``/opt/traffic_router/var/auto-zones`` |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| traffic_ops.properties | traffic_ops.username | Username with which to access the APIs in Traffic Ops (must be in the ``admin`` role) | ``admin`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | traffic_ops.password | Password for the user specified in ``traffic_ops.username`` | N/A |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| cache.properties | cache.geolocation.database | Full path to the local copy of a GeoIP2 (usually MaxMind) binary database file | ``/opt/traffic_router/db/GeoIP2-City.mmdb`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.geolocation.database.refresh.period | The interval in milliseconds for Traffic Router to wait between polling for changes | ``604800000`` |
-| | | to the GeoIP2 database | |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.czmap.database | Full path to the local copy of the coverage zone file | ``/opt/traffic_router/db/czmap.json`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.czmap.database.refresh.period | The interval in milliseconds for Traffic Router to wait between polling for a new | ``10800000`` |
-| | | coverage zone file | |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.dczmap.database | Full path to the local copy of the deep coverage zone file | ``/opt/traffic_router/db/dczmap.json`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.dczmap.database.refresh.period | The interval in milliseconds for Traffic Router to wait between polling for a new | ``10800000`` |
-| | | deep coverage zone file | |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.health.json | Full path to the local copy of the health state | ``/opt/traffic_router/db/health.json`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.health.json.refresh.period | The interval in milliseconds which Traffic Router will poll for a new health state | ``1000`` |
-| | | file | |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.config.json | Full path to the local copy of the CRConfig | ``/opt/traffic_router/db/cr-config.json`` |
-| +-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| | cache.config.json.refresh.period | The interval in milliseconds which Traffic Router will poll for a new CRConfig | ``60000`` |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| startup.properties | various parameters | This configuration is used by ``systemctl`` to set environment variables when the | N/A |
-| | | ``traffic_router`` service is started. It primarily consists of command line settings | |
-| | | for the Java process | |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| log4j.properties | various parameters | Configuration of ``log4j`` is | N/A |
-| | | `documented on their site <http://logging.apache.org/log4j/2.x/index.html>`_; adjust | |
-| | | as needed | |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| server.xml | various parameters | Traffic Router specific configuration for Apache Tomcat. See the | N/A |
-| | | `Apache Tomcat documentation <https://tomcat.apache.org/tomcat-8.5-doc/index.html>`_. | |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
-| web.xml | various parameters | Default settings for all Web Applications running in the Traffic Router instance of | N/A |
-| | | Tomcat | |
-+----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
+.. versionchanged:: 3.0
+ Traffic Router 3.0 has been converted to a formal Tomcat instance, meaning that is now installed separately from the Tomcat servlet engine. The Traffic Router installation package contains all of the Traffic Router-specific software, configuration and startup scripts including some additional configuration files needed for Tomcat. These new configuration files can all be found in the :file:`/opt/traffic_router/conf` directory and generally serve to override Tomcat's default settings.
+
+For the most part, the configuration files and :term:`Parameter`\ s used by Traffic Router are used to bring it online and start communicating with various Traffic Control components. Once Traffic Router is successfully communicating with Traffic Control, configuration should mostly be performed in Traffic Portal, and will be distributed throughout Traffic Control via CDN :term:`Snapshot` process. See :ref:`snapshot-crconfig` for more information. Please see the :term:`Parameter` documen [...]
+
+.. _tr-config-files:
+.. table:: Traffic Router Parameters
+
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | ConfigFile | Parameter Name | Description | Default Value |
+ +============================+===========================================+==================================================================================+====================================================+
+ | traffic_monitor.properties | traffic_monitor.bootstrap.hosts | Semicolon-delimited Traffic Monitor | N/A |
+ | | | :abbr:`FQDN (Fully Qualified Domain Name)`\ s with port numbers as necessary | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | traffic_monitor.bootstrap.local | Use only the Traffic Monitors specified in local configuration files | ``false`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | traffic_monitor.properties | Path to file:`traffic_monitor.properties`; used internally to monitor the file | ``/opt/traffic_router/traffic_monitor.properties`` |
+ | | | for changes | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | traffic_monitor.properties.reload.period | The interval in milliseconds for Traffic Router to wait between reloading this | ``60000`` |
+ | | | configuration file | |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | dns.properties | dns.tcp.port | TCP port that Traffic Router will use for incoming DNS requests | ``53`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | dns.tcp.backlog | Maximum length of the queue for incoming TCP connection requests | ``0`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | dns.udp.port | UDP port that Traffic Router will use for incoming DNS requests | ``53`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | dns.max-threads | Maximum number of threads used to process incoming DNS requests | ``1000`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | dns.zones.dir | Path to automatically generated zone files for reference | ``/opt/traffic_router/var/auto-zones`` |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | traffic_ops.properties | traffic_ops.username | Username with which to access the :ref:`to-api` | ``admin`` |
+ | | | (must have the ``admin`` :term:`Role`) | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | traffic_ops.password | Password for the user specified in ``traffic_ops.username`` | N/A |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | cache.properties | cache.geolocation.database | Full path to the local copy of a geographic IP mapping database | ``/opt/traffic_router/db/GeoIP2-City.mmdb`` |
+ | | | (usually MaxMind's GeoIP2) | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.geolocation.database.refresh.period | The interval in milliseconds for Traffic Router to wait between polling for | ``604800000`` |
+ | | | changes to the GeoIP2 database | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.czmap.database | Full path to the local copy of the coverage zone file | ``/opt/traffic_router/db/czmap.json`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.czmap.database.refresh.period | The interval in milliseconds for Traffic Router to wait between polling for a | ``10800000`` |
+ | | | new coverage zone file | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.dczmap.database | Full path to the local copy of the deep coverage zone file | ``/opt/traffic_router/db/dczmap.json`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.dczmap.database.refresh.period | The interval in milliseconds for Traffic Router to wait between polling for a | ``10800000`` |
+ | | | new deep coverage zone file | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.health.json | Full path to the local copy of the health state | ``/opt/traffic_router/db/health.json`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.health.json.refresh.period | The interval in milliseconds which Traffic Router will poll for a new health | ``1000`` |
+ | | | state file | |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.config.json | Full path to the locally cached copy of the CDN :term:`Snapshot` | ``/opt/traffic_router/db/cr-config.json`` |
+ | +-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | | cache.config.json.refresh.period | The interval in milliseconds which Traffic Router will poll for a new | ``60000`` |
+ | | | :term:`Snapshot` | |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | startup.properties | various parameters | This configuration is used by :manpage:`systemd(1)` to set environment variables | N/A |
+ | | | when the ``traffic_router`` service is started. It primarily consists of command | |
+ | | | line settings for the Java process | |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | log4j.properties | various parameters | Configuration of ``log4j`` is documented on | N/A |
+ | | | `their site <http://logging.apache.org/log4j/2.x/index.html>`_; adjust as needed | |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | server.xml | various parameters | Traffic Router specific configuration for Apache Tomcat. See the Apache Tomcat | N/A |
+ | | | `documentation <https://tomcat.apache.org/tomcat-8.5-doc/index.html>`_ | |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
+ | web.xml | various parameters | Default settings for all Web Applications running in the Traffic Router instance | N/A |
+ | | | of Tomcat | |
+ +----------------------------+-------------------------------------------+----------------------------------------------------------------------------------+----------------------------------------------------+
.. _tr-dnssec:
DNSSEC
======
+.. seealso:: `The Wikipedia page on Domain Name Security Extensions <https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions>`_
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 (: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.
+:abbr:`DNSSEC (Domain Name System Security Extensions)` 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 (: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 administe [...]
Operation
---------
-Upon startup or a configuration change, Traffic Router obtains keys from the 'keystore' API in Traffic Ops which returns key signing keys (KSK) and zone signing keys (ZSK) for each Delivery Service that is a sub-domain of the CDN's Top Level Domain (TLD) in addition to the keys for the CDN TLD itself. Each key has timing information that allows Traffic Router to determine key validity (expiration, inception, and effective dates) in addition to the appropriate Time To Live (TTL) to use fo [...]
+Upon startup or a configuration change, Traffic Router obtains keys from the 'keystore' API in Traffic Ops which returns :abbr:`KSK (Key Signing Key)`\ s and :abbr:`ZSK (Zone Signing Key)`\ s for each :term:`Delivery Service` that is a sub-domain of the CDN's :abbr:`TLD (Top Level Domain)` in addition to the keys for the CDN :abbr:`TLD (Top Level Domain)` itself. Each key has timing information that allows Traffic Router to determine key validity (expiration, inception, and effective dat [...]
-Once Traffic Router obtains the key data from the API, it converts each public key into the appropriate record types (DNSKEY, DS) to place in zones and uses the private key to sign zones. DNSKEY records are added to each Delivery Service's zone (e.g.: mydeliveryservice.ciab.cdn.local) for every valid key that exists, in addition to the CDN TLD's zone. A DS record is generated from each zone's KSK and is placed in the CDN TLD's zone (e.g.: ciab.cdn.local); the DS record for the CDN TLD mu [...]
+Once Traffic Router obtains the key data from the API, it converts each public key into the appropriate record types (DNSKEY, DS) to place in zones and uses the private key to sign zones. DNSKEY records are added to each :term:`Delivery Service`'s zone (e.g.: ``demo1.mycdn.ciab.test``) for every valid key that exists, in addition to the CDN :abbr:`TLD (Top Level Domain)`'s zone. A DS record is generated from each zone's :abbr:`KSK (Key Signing Key)` and is placed in the CDN :abbr:`TLD (T [...]
-The DNSKEY to DS record relationship allows resolvers to validate signatures across zone delegation points. With Traffic Control, we control all delegation points below the CDN's TLD, **however, the DS record for the CDN TLD must be placed in the parent zone (e.g.: cdn.local), which is not managed by Traffic Control**. As such, the DS record must be placed in the parent zone prior to enabling DNSSEC, and prior to generating a new CDN KSK. Based on your deployment's DNS configuration, thi [...]
+The DNSKEY to DS record relationship allows resolvers to validate signatures across zone delegation points. With Traffic Control, we control all delegation points below the CDN's :abbr:`TLD (Top Level Domain)`, **however, the DS record for the CDN** :abbr:`TLD (Top Level Domain)` **must be placed in the parent zone** (e.g.: ``ciab.test``), **which is not managed by Traffic Control**. As such, the DS record must be placed in the parent zone prior to enabling :abbr:`DNSSEC (Domain Name Sys [...]
-To enable DNSSEC for a CDN in Traffic Portal, Go to 'CDNs' from the sidebar and click on the desired CDN, then toggle the 'DNSSEC Enabled' field to 'true', and click on the green 'Update' button to save the changes.
+To enable :abbr:`DNSSEC (Domain Name System Security Extensions)` for a CDN in Traffic Portal, Go to :guilabel:`CDNs` from the sidebar and click on the desired CDN, then toggle the 'DNSSEC Enabled' field to 'true', and click on the green :guilabel:`Update` button to save the changes.
Rolling Zone Signing Keys
-------------------------
-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.
+Traffic Router currently follows the :abbr:`ZSK (Zone Signing Key)` pre-publishing operational best practice described in :rfc:`6781#section-4.1.1.1`. Once :abbr:`DNSSEC (Domain Name System Security Extensions)` 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 :abbr:`ZSK (Zone Signing Keys)`\ s based on the expiration information returned from the 'keystore' API of Traffic Ops.
.. _tr-logs:
Troubleshooting and Log Files
=============================
-Traffic Router log files can be found under ``/opt/traffic_router/var/log`` and ``/opt/tomcat/logs``. Initialization and shutdown logs are in ``/opt/tomcat/logs/catalina[date].out``. Application related logging is in ``/opt/traffic_router/var/log/traffic_router.log``, while access logs are written to ``/opt/traffic_router/var/log/access.log``.
+Traffic Router log files can be found under :file:`/opt/traffic_router/var/log` and :file:`/opt/tomcat/logs`. Initialization and shutdown logs are in :file:`/opt/tomcat/logs/catalina{date}.out`. Application related logging is in :file:`/opt/traffic_router/var/log/traffic_router.log`, while access logs are written to :file:`/opt/traffic_router/var/log/access.log`.
Event Log File Format
---------------------
Summary
"""""""
+All access events to Traffic Router are logged to the file :file:`/opt/traffic_router/var/log/access.log`. This file grows up to 200MB and gets rolled into older log files, ten log files total are kept (total of up to 2GB of logged events per Traffic Router instance)
-All access events to Traffic Router are logged to the file ``/opt/traffic_router/var/log/access.log``
-This file grows up to 200MB and gets rolled into older log files, 10 log files total are kept (total of up to 2GB of logged events per Traffic Router instance)
-
-Traffic Router logs access events in a format that largely following `ATS event logging format
-<https://docs.trafficserver.apache.org/en/6.0.x/admin/event-logging-formats.en.html>`_
+Traffic Router logs access events in a format that largely follows :abbr:`ATS (Apache Traffic Service)` `event logging format <https://docs.trafficserver.apache.org/en/6.0.x/admin/event-logging-formats.en.html>`_.
Message Format
""""""""""""""
@@ -195,41 +218,43 @@ Message Format
.. Note:: Any value that is a single dash character or a dash character enclosed in quotes represents an empty value
+.. table:: Fields Always Present
+
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+ | Name | Description | Data |
+ +=======+==================================================================================+=====================================================================================+
+ | qtype | Whether the request was for DNS or HTTP | Always "DNS" or "HTTP" |
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+ | chi | The IP address of the requester | Depends on whether this was a DNS or HTTP request, see other sections |
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+ | ttms | The amount of time in milliseconds it took Traffic Router to process the request | A number greater than or equal to zero |
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+ | rtype | Routing result type | One of ERROR, CZ, DEEP_CZ, GEO, MISS, STATIC_ROUTE, DS_REDIRECT, DS_MISS, INIT, FED |
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+ | rloc | GeoLocation of result | Latitude and longitude in degrees as floating point numbers |
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+ | rdtl | Result details Associated with unusual conditions | One of DS_NOT_FOUND, DS_NO_BYPASS, DS_BYPASS, DS_CZ_ONLY, DS_CZ_BACKUP_CG |
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+ | rerr | Message about an internal Traffic Router error | String |
+ +-------+----------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+
+
+.. seealso:: If `Regional Geo-Blocking <regionalgeo-qht>`_ is enabled on the :term:`Delivery Service`, an additional field (``rgb``) will appear.
+
Sample Message
""""""""""""""
+Items within brackets are detailed under the HTTP and DNS sections
-Items within brackets below are detailed under the HTTP and DNS sections::
-
- 144140678.000 qtype=DNS chi=192.168.10.11 ttms=789 [Fields Specific to the DNS request] rtype=CZ rloc="40.252611,58.439389" rdtl=- rerr="-" [Fields Specific to the DNS result]
- 144140678.000 qtype=HTTP chi=192.168.10.11 ttms=789 [Fields Specific to the HTTP request] rtype=GEO rloc="40.252611,58.439389" rdtl=- rerr="-" [Fields Specific to the HTTP result]
-
-.. Note:: The above message samples contain fields that are always present for every single access event to Traffic Router
+.. code-block:: text
+ :caption: Example Logfile Lines
+ 144140678.000 qtype=DNS chi=192.168.10.11 ttms=789 [Fields Specific to the DNS request] rtype=CZ rloc="40.252611,58.439389" rdtl=- rerr="-" [Fields Specific to the DNS result]
+ 144140678.000 qtype=HTTP chi=192.168.10.11 ttms=789 [Fields Specific to the HTTP request] rtype=GEO rloc="40.252611,58.439389" rdtl=- rerr="-" [Fields Specific to the HTTP result]
-Fields Always Present
-"""""""""""""""""""""
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-|Name |Description |Data |
-+======+=================================================================================+====================================================================================+
-|qtype |Whether the request was for DNS or HTTP |Always DNS or HTTP |
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-|chi |The IP address of the requester |Depends on whether this was a DNS or HTTP request, see below sections |
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-|ttms |The amount of time in milliseconds it took Traffic Router to process the request |A number greater than or equal to zero |
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-|rtype |Routing Result Type |One of ERROR, CZ, DEEP_CZ, GEO, MISS, STATIC_ROUTE, DS_REDIRECT, DS_MISS, INIT, FED |
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-|rloc |GeoLocation of result |Latitude and Longitude in Decimal Degrees |
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-|rdtl |Result Details Associated with unusual conditions |One of DS_NOT_FOUND, DS_NO_BYPASS, DS_BYPASS, DS_CZ_ONLY, DS_CZ_BACKUP_CG |
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-|rerr |Message about internal Traffic Router Error |String |
-+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
+.. Note:: These samples contain fields that are always present for every single access event to Traffic Router
-.. seealso:: If `Regional Geo-Blocking <regionalgeo-qht>`_ is enabled on the Delivery Service, an additional field (``rgb``) will appear.
``rtype`` Meanings
-^^^^^^^^^^^^^^^^^^
+""""""""""""""""""
``-``
The request was not redirected. This is usually a result of a DNS request to the Traffic Router or an explicit denial for that request
ANON_BLOCK
@@ -239,41 +264,41 @@ CZ
DEEP_CZ
The result was derived from Deep Coverage Zone data based on the address in the ``chi`` field
DS_MISS
- _*HTTP Only*_ No HTTP Delivery Service supports either this request's URL path or headers
+ _*HTTP Only*_ No HTTP :term:`Delivery Service`\ supports either this request's URL path or headers
DS_REDIRECT
- The result is using the Bypass Destination configured for the matched Delivery Service when that Delivery Service is unavailable or does not have the requested resource
+ The result is using the Bypass Destination configured for the matched :term:`Delivery Service` when that :term:`Delivery Service` is unavailable or does not have the requested resource
ERROR
An internal error occurred within Traffic Router, more details may be found in the ``rerr`` field
FED
- _*DNS Only*_ The result was obtained through federated coverage zone data outside of any Delivery Service
+ _*DNS Only*_ The result was obtained through federated coverage zone data outside of any :term:`Delivery Service`\ s
GEO
The result was derived from geolocation service based on the address in the ``chi`` field
GEO_REDIRECT
- The request was redirected based on the National Geo blocking (Geo Limit Redirect URL) configured on the Delivery Service
+ The request was redirected based on the National Geo blocking (Geo Limit Redirect URL) configured on the :term:`Delivery Service`
MISS
Traffic Router was unable to resolve a DNS request or find a cache for the requested resource
RGALT
- The request was redirected to the `Regional Geo-Blocking <regionalgeo-qht>`_ URL. Regional Geo blocking is enabled on the Delivery Service and is configured through the ``regional_geoblock.polling.url`` setting for the Traffic Router profile
+ The request was redirected to the `Regional Geo-Blocking <regionalgeo-qht>`_ URL. Regional Geo blocking is enabled on the :term:`Delivery Service` and is configured through the ``regional_geoblock.polling.url`` :term:`Parameter` on the Traffic Router :term:`Profile`
RGDENY
- _*DNS Only*_ The result was obtained through federated coverage zone data outside of any Delivery Service The request was regionally blocked because there was no rule for the request made
+ _*DNS Only*_ The result was obtained through federated coverage zone data outside of any :term:`Delivery Service` - the request was regionally blocked because there was no rule for the request made
STATIC_ROUTE
- _*DNS Only*_ No DNS Delivery Service supports the hostname portion of the requested url
+ _*DNS Only*_ No DNS :term:`Delivery Service`\ supports the hostname portion of the requested URL
``rdtl`` Meanings
-^^^^^^^^^^^^^^^^^
+"""""""""""""""""
``-``
The request was not redirected. This is usually a result of a DNS request to the Traffic Router or an explicit denial for that request
DS_BYPASS
- Used Bypass Destination for Redirect of Delivery Service
+ Used a bypass destination for redirection of the :term:`Delivery Service`
DS_CLIENT_GEO_UNSUPPORTED
Traffic Router did not find a resource supported by coverage zone data and was unable to determine the geographic location of the requesting client
DS_CZ_BACKUP_CG
- Traffic Router found a backup cache via fall-back (CRconfig's ``edgeLocation``) or via coordinates (CZF) configuration
+ Traffic Router found a backup cache via fall-back (CRconfig's ``edgeLocation``) or via coordinates (:abbr:`CZF (Coverage Zone File)`) configuration
DS_CZ_ONLY
- The selected Delivery Service only supports resource lookup based on Coverage Zone data
+ The selected :term:`Delivery Service` only supports resource lookup based on coverage zone data
DS_NO_BYPASS
- No valid Bypass Destination is configured for the matched Delivery Service and the Delivery Service does not have the requested resource
+ No valid bypass destination is configured for the matched :term:`Delivery Service` and the :term:`Delivery Service` does not have the requested resource
DS_NOT_FOUND
Always goes with ``rtypes`` STATIC_ROUTE and DS_MISS
GEO_NO_CACHE_FOUND
@@ -283,46 +308,43 @@ NO_DETAILS
REGIONAL_GEO_ALTERNATE_WITHOUT_CACHE
This goes with the ``rtype`` RGDENY. The URL is being regionally blocked
REGIONAL_GEO_NO_RULE
- The request was blocked because there was no rule in the Delivery Service for the request
+ The request was blocked because there was no rule in the :term:`Delivery Service` for the request
HTTP Specifics
--------------
+.. code-block:: text
+ :caption: Sample Message
-Sample Message
-::
-
- 1452197640.936 qtype=HTTP chi=69.241.53.218 url="http://foo.mm-test.jenkins.cdnlab.comcast.net/some/asset.m3u8" cqhm=GET cqhv=HTTP/1.1 rtype=GEO rloc="40.252611,58.439389" rdtl=- rerr="-" pssc=302 ttms=0 rurl="http://odol-atsec-sim-114.mm-test.jenkins.cdnlab.comcast.net:8090/some/asset.m3u8" rh="Accept: */*" rh="myheader: asdasdasdasfasg"
+ 1452197640.936 qtype=HTTP chi=69.241.53.218 url="http://foo.mm-test.jenkins.cdnlab.comcast.net/some/asset.m3u8" cqhm=GET cqhv=HTTP/1.1 rtype=GEO rloc="40.252611,58.439389" rdtl=- rerr="-" pssc=302 ttms=0 rurl="http://odol-atsec-sim-114.mm-test.jenkins.cdnlab.comcast.net:8090/some/asset.m3u8" rh="Accept: */*" rh="myheader: asdasdasdasfasg"
.. table:: Request Fields
- +-----+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
- |Name |Description |Data |
- +=====+=========================================================================================================================================+=============================================+
- |url |Requested URL with query string |A URL String |
- +-----+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
- |cqhm |Http Method |e.g ``GET``, ``POST`` |
- +-----+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
- |cqhv |Http Protocol Version |e.g. ``HTTP/1.1`` |
- +-----+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
- |rh |One or more of these key value pairs may exist in a logged event and are controlled by the configuration of the matched Delivery Service |Key/value pair of the format ``name: value`` |
- +-----+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
+ +------+--------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------+
+ | Name | Description | Data |
+ +======+==================================================================================================================================================+==============================================+
+ | url | Requested URL with query string | A URL String |
+ +------+--------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------+
+ | cqhm | Http Method | e.g ``GET``, ``POST`` |
+ +------+--------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------+
+ | cqhv | Http Protocol Version | e.g. ``HTTP/1.1`` |
+ +------+--------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------+
+ | rh | One or more of these key value pairs may exist in a logged event and are controlled by the configuration of the matched :term:`Delivery Service` | Key/value pair of the format ``name: value`` |
+ +------+---------------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
.. table:: Response Fields
- +-----+----------------------------------------------------------+------------+
- |Name |Description |Data |
- +=====+==========================================================+============+
- |rurl |The resulting URL of the resource requested by the client |A URL String|
- +-----+----------------------------------------------------------+------------+
-
+ +------+-----------------------------------------------------------+
+ | Name | Description |
+ +======+===========================================================+
+ | rurl | The resulting URL of the resource requested by the client |
+ +------+-----------------------------------------------------------+
DNS Specifics
-------------
+.. code-block:: text
+ :caption: Sample Message
-Sample Message
-::
-
- 144140678.000 qtype=DNS chi=192.168.10.11 ttms=123 xn=65535 fqdn=www.example.com. type=A class=IN ttl=12345 rcode=NOERROR rtype=CZ rloc="40.252611,58.439389" rdtl=- rerr="-" ans="192.168.1.2 192.168.3.4 0:0:0:0:0:ffff:c0a8:102 0:0:0:0:0:ffff:c0a8:304"
+ 144140678.000 qtype=DNS chi=192.168.10.11 ttms=123 xn=65535 fqdn=www.example.com. type=A class=IN ttl=12345 rcode=NOERROR rtype=CZ rloc="40.252611,58.439389" rdtl=- rerr="-" ans="192.168.1.2 192.168.3.4 0:0:0:0:0:ffff:c0a8:102 0:0:0:0:0:ffff:c0a8:304"
.. _qname: http://www.zytrax.com/books/dns/ch15/#qname
@@ -330,20 +352,20 @@ Sample Message
.. table:: Request Fields
- +------+------------------------------------------------------------------+--------------------------------------------------------+
- |Name |Description |Data |
- +======+==================================================================+========================================================+
- |xn |The ID from the client DNS request header |a whole number between 0 and 65535 (inclusive) |
- +------+------------------------------------------------------------------+--------------------------------------------------------+
- |fqdn |The qname field from the client DNS request message (i.e. The |A series of DNS labels/domains separated by '.' |
- | |fully qualified domain name the client is requesting be resolved) |characters and ending with a '.' character (see qname_) |
- +------+------------------------------------------------------------------+--------------------------------------------------------+
- |type |The qtype field from the client DNS request message (i.e. |Examples are A (IpV4), AAAA (IpV6), NS (Name Service), |
- | |the type of resolution that's requested such as IPv4, IPv6) |SOA (Start of Authority), and CNAME, (see qtype_) |
- +------+------------------------------------------------------------------+--------------------------------------------------------+
- |class |The qclass field from the client DNS request message (i.e. The |Either IN (Internet resource) or ANY (Traffic router |
- | |class of resource being requested) |rejects requests with any other value of class) |
- +------+------------------------------------------------------------------+--------------------------------------------------------+
+ +-------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------+
+ | Name | Description | Data |
+ +=======+=================================================================================+===================================================================================================+
+ | xn | The ID from the client DNS request header | a whole number between 0 and 65535 (inclusive) |
+ +-------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------+
+ | fqdn | The qname field from the client DNS request message (i.e. the | A series of DNS labels/domains separated by '.' characters and ending with a '.' character |
+ | | :abbr:`FQDN (Fully Qualified Domain Name)` the client is requesting be | |
+ +-------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------+
+ | type | The qtype field from the client DNS request message (i.e. the typeof resolution | Examples are A (IpV4), AAAA (IpV6), :abbr:`NS (Name Service)`, :abbr:`SOA (Start of Authority)`, |
+ | | that's requested such as IPv4, IPv6) | and :abbr:`CNAME (Canonical Name)`, (see qtype_) |
+ +-------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------+
+ | class | The qclass field from the client DNS request message (i.e. the class of | Either :abbr:`IN (Internet resource)` or ANY (Traffic Router rejects requests with any other |
+ | | resource being requested) | value of class) |
+ +-------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------+
.. table:: Response Fields
@@ -367,33 +389,29 @@ GeoLimit Failure Redirect Feature
Overview
--------
+This feature is also called :abbr:`NGB (National GeoBlock)`.
-This feature is also called 'National GeoBlock' (NGB).
-
-In the past, if the Geolimit check fails (for example, the client IP is not in the 'US' region but the Geolimit is set to 'CZF + US'), the router will respond with ``503 Service Unavailable``, but with this feature, when the check fails, it will respond with ``302 Found`` if the redirect URL is set in the Delivery Service.
+In the past, if the Geolimit check fails (for example, the client IP is not in the ``US`` :term:`Region` but the Geolimit is set to 'CZF + US'), Traffic Router will respond with ``503 Service Unavailable``, but with this feature, when the check fails, it will respond with ``302 Found`` if the redirect URL is set in the :term:`Delivery Service`.
The Geolimit check will fail in the following scenarios:
- When the GeoLimit is set to 'CZF + only' and the client IP is not in the the CZ file
- When the GeoLimit is set to any region e.g. 'CZF + US' and the client IP is not in such region, and the client IP is not in the CZ file
-
Configuration
-------------
-
-To enable the NGB feature, the DS must be configured with the proper redirect URL. The setting for this can be found by clicking on 'Advanced Options' at the bottom of a Delivery Service details page, and is specified by the 'Geo Limit Redirect URL' field. An individual Delivery Service details page can be viewed by clicking on the desired Delivery Service under 'Services' -> 'Delivery Services'. If no URL is put in this field, the feature is disabled.
+To enable the :abbr:`NGB (National GeoBlock)` feature, the :term:`Delivery Service` must be configured with the proper redirect URL. The setting for this can be found by clicking on :guilabel:`Advanced Options` at the bottom of a :term:`Delivery Service` details page, and is specified by the 'Geo Limit Redirect URL' field. An individual :term:`Delivery Service` details page can be viewed by clicking on the desired :term:`Delivery Service` under :menuselection:`Services --> Delivery Servi [...]
The URL has 3 kinds of formats, which have different meanings:
URL with no domain
- If no domain is in the URL (e.g. 'vod/dance.mp4'), Traffic Router will try to find a proper cache server within the Delivery Service and return the redirect URL in the format: ``http://[cache server name].[Delivery Service's FQDN]/[configured relative path]``
+ If no domain is in the URL (e.g. ``vod/dance.mp4``), Traffic Router will try to find a proper :term:`cache server` within the :term:`Delivery Service` and return the redirect URL in the format: ``http://[cache server name]. :term:`Delivery Service`'s Fully Qualified Domain]/[configured relative path]``
-URL with domain that matches with the Delivery Service
- For this URL, Traffic Router will also try to find a proper cache server within the Delivery Service and return a redirect URL in the format: ``http://[cache server name].[Delivery Service's FQDN]/[configured relative path]``
+URL with domain that matches with the :term:`Delivery Service`
+ For this URL, Traffic Router will also try to find a proper :term:`cache server` within the :term:`Delivery Service` and return a redirect URL in the format: ``http://[cache server name]. :term:`Delivery Service`'s Fully Qualified Domain Name]/[configured relative path]``
-URL with domain that doesn't match with the Delivery Service
+URL with domain that doesn't match with the :term:`Delivery Service`
Traffic Router will return the configured URL directly to the client.
-
.. _deep-cache:
Deep Caching - Deep Coverage Zone Topology
@@ -401,28 +419,22 @@ Deep Caching - Deep Coverage Zone Topology
Overview
--------
+Deep Caching is a feature that enables clients to be routed to the closest possible "deep" Edge-tier :term:`cache server` s on a per-:term:`Delivery Service` basis. The term "deep" is used in the networking sense, meaning that the Edge-tier :term:`cache server` s are located deep in the network where the number of network hops to a client is as minimal. This deep caching topology is desirable because storing content closer to the client gives better bandwidth savings, and sometimes the c [...]
-Deep Caching is a feature that enables clients to be routed to the closest possible "deep" Edge-tier caches on a per-Delivery Service basis. The term "deep" is used in the networking sense, meaning that the Edge-tier caches are located deep in the network where the number of network hops to a client is as minimal. This deep caching topology is desirable because storing content closer to the client gives better bandwidth savings, and sometimes the cost of bandwidth usage in the network ou [...]
-
-Getting Started
----------------
-
-What you need:
-
-#. Edge caches deployed in "deep" locations and registered in Traffic Ops
-#. A Deep Coverage Zone File (DCZF) mapping these deep cache hostnames to specific network prefixes (see :ref:`deep-czf` for details)
+What You Need
+-------------
+#. Edge cache deployed in "deep" locations and registered in Traffic Ops
+#. A :abbr:`DCZF (Deep Coverage Zone File)` mapping these deep cache hostnames to specific network prefixes (see :ref:`deep-czf` for details)
#. Deep caching parameters in the Traffic Router Profile (see :ref:`ccr-profile` for details):
- - ``deepcoveragezone.polling.interval``
- - ``deepcoveragezone.polling.url``
+ - ``deepcoveragezone.polling.interval``
+ - ``deepcoveragezone.polling.url``
-#. Deep Caching enabled on one or more HTTP Delivery Services (i.e. 'Deep Caching' field on the Delivery Service details page (under 'Advanced Options') set to ALWAYS)
+#. Deep Caching enabled on one or more HTTP :term:`Delivery Service`\ s (i.e. 'Deep Caching' field on the :term:`Delivery Service` details page (under :guilabel:`Advanced Options`) set to ``ALWAYS``)
How it Works
------------
-
-Deep Coverage Zone routing is very similar to that of regular Coverage Zone routing, except that the DCZF is preferred over the regular CZF for Delivery Services with Deep Caching (DC) enabled. If the client requests a DC-enabled Delivery Service and their IP address gets a "hit" in the DCZF, Traffic Router will attempt to route that client to one of the available deep caches in the client's corresponding zone. If there are no deep caches available for a client's request, Traffic Router [...]
-
+Deep Coverage Zone routing is very similar to that of regular Coverage Zone routing, except that the :abbr:`DCZF (Deep Coverage Zone File)` is preferred over the regular :abbr:`CZF (Coverage Zone File)` for :term:`Delivery Service`\ s with Deep Caching enabled. If the client requests a Deep Caching-enabled :term:`Delivery Service` and their IP address gets a "hit" in the :abbr:`DCZF (Deep Coverage Zone File)`, Traffic Router will attempt to route that client to one of the available "deep [...]
.. _tr-steering:
@@ -431,63 +443,58 @@ Steering Feature
Overview
--------
-A Steering Delivery Service is a Delivery Service that is used to route a client to another Delivery Service. The Type of a Steering Delivery Service is either STEERING or CLIENT_STEERING. A Steering Delivery Service will have target Delivery Services configured for it with weights assigned to them. Traffic Router uses the weights to make a consistent hash ring which it then uses to make sure that requests are routed to a target based on the configured weights. This consistent hash ring [...]
-
-Special regular expressions - referred to as 'filters' - can also be configured for target Delivery Services to pin traffic to a specific Delivery Service. For example, if a filter called ``.*/news/.*`` for a target called 'target-ds-1' is created, any requests to Traffic Router with 'news' in them will be routed to 'target-ds-1'. This will happen regardless of the configured weights.
+A Steering :term:`Delivery Service` is a :term:`Delivery Service` that is used to route a client to another :term:`Delivery Service`. The :term:`Type` of a Steering :term:`Delivery Service` is either STEERING or CLIENT_STEERING. A Steering :term:`Delivery Service` will have target :term:`Delivery Service`\ s configured for it with weights assigned to them. Traffic Router uses the weights to make a consistent hash ring which it then uses to make sure that requests are routed to a target b [...]
-Some other points of interest:
+Special regular expressions - referred to as 'filters' - can also be configured for target :term:`Delivery Service`\ s to pin traffic to a specific :term:`Delivery Service`. For example, if the filter :regexp:`.*/news/.*` for a target called ``target-ds-1`` is created, any requests to Traffic Router with "news" in them will be routed to ``target-ds-1``. This will happen regardless of the configured weights.
-- Steering is currently only available for HTTP Delivery Services that are a part of the same CDN.
-- A new role called STEERING has been added to the Traffic Ops database. Only users with Admin or Steering privileges can modify steering assignments for a Delivery Service.
-- A new API has been created in Traffic Ops under ``/internal``. A Steering user can either directly access this API to modify assignments, or use the Traffic Portal UI ('View Targets' under the 'More' drop-down menu on a Steering Delivery Service's details page), however a filter can only be created via the API.
+Some other points of interest
+"""""""""""""""""""""""""""""
+- Steering is currently only available for HTTP :term:`Delivery Service`\ s that are a part of the same CDN.
+- A new role called STEERING has been added to the Traffic Ops database. Only users with the Steering :term:`Role` or higher can modify steering assignments for a :term:`Delivery Service`.
+- A new API has been created in Traffic Ops under ``/internal``. A Steering user can either directly access this API to modify assignments, or use the Traffic Portal UI (:menuselection:`More --> View Targets` on a Steering :term:`Delivery Service`'s details page), however a filter can only be created via the API.
- Traffic Router uses the steering API in Traffic Ops to poll for steering assignments, the assignments are then used when routing traffic.
A couple simple use-cases for Steering are:
-- Migrating traffic from one Delivery Service to another over time.
-- Trying out new functionality for a subset of traffic with an experimental Delivery Service.
-- Load balancing between Delivery Services.
-
+- Migrating traffic from one :term:`Delivery Service` to another over time.
+- Trying out new functionality for a subset of traffic with an experimental :term:`Delivery Service`.
+- Load balancing between :term:`Delivery Service`\ s
The Difference Between STEERING and CLIENT_STEERING
---------------------------------------------------
-
-The only difference between the STEERING and CLIENT_STEERING Delivery Service Types is that CLIENT_STEERING explicitly allows a client to bypass Steering by choosing a destination Delivery Service. A client can accomplish this by providing the ``X-TC-Steering-Option`` HTTP header with a value of the ``xml_id`` of the target Delivery Service to which they desire to be routed. When Traffic Router receives this header it will route to the requested target Delivery Service regardless of weig [...]
-
+The only difference between the STEERING and CLIENT_STEERING :term:`Delivery Service` :term:`Type`\ s is that CLIENT_STEERING explicitly allows a client to bypass Steering by choosing a destination :term:`Delivery Service`. A client can accomplish this by providing the ``X-TC-Steering-Option`` HTTP header with a value of the ``xml_id`` of the target :term:`Delivery Service` to which they desire to be routed. When Traffic Router receives this header it will route to the requested target : [...]
Configuration
-------------
-
The following needs to be completed for Steering to work correctly:
-#. Two target Delivery Services are created in Traffic Ops. They must both be HTTP Delivery Services part of the same CDN.
-#. A Delivery Service with type STEERING or CLIENT_STEERING is created in Traffic Portal.
-#. Target Delivery Services are assigned to the Steering Delivery Service using Traffic Portal.
+#. Two target :term:`Delivery Service`\ s are created in Traffic Ops. They must both be HTTP :term:`Delivery Service`\ s part of the same CDN.
+#. A :term:`Delivery Service` with type STEERING or CLIENT_STEERING is created in Traffic Portal.
+#. Target :term:`Delivery Service`\ s are assigned to the Steering :term:`Delivery Service` using Traffic Portal.
#. A user with the role of Steering is created.
-#. The Steering user assigns weights to the target Delivery Services.
-#. If desired, the Steering user can create filters for the target Delivery Services.
+#. The Steering user assigns weights to the target :term:`Delivery Service`\ s.
+#. If desired, the Steering user can create filters for the target :term:`Delivery Service`\ s.
-For more information see the `Steering how-to guide <quick_howto/steering.html>`_.
+.. seealso:: For more information see the `Steering how-to guide <quick_howto/steering.html>`_.
HTTPS for HTTP Delivery Services
================================
+.. versionadded:: 1.7
+ Traffic Router now has the ability to allow HTTPS traffic between itself and clients on a per-HTTP :term:`Delivery Service` basis.
-Starting with version 1.7 Traffic Router added the ability to allow HTTPS traffic between itself and clients on a per-HTTP Delivery Service basis.
-
-.. Note:: As of version 3.0 Traffic Router has been integrated with native OpenSSL. This makes establishing HTTPS connections to Traffic Router much less expensive than previous versions. However establishing an HTTPS connection is more computationally demanding than an HTTP connection. Since each client will in turn get redirected to ATS, Traffic Router is most always creating a new HTTPS connection for all HTTPS traffic. It is likely to mean that an existing Traffic Router may have som [...]
+.. Note:: As of version 3.0 Traffic Router has been integrated with native OpenSSL. This makes establishing HTTPS connections to Traffic Router much less expensive than previous versions. However establishing an HTTPS connection is more computationally demanding than an HTTP connection. Since each client will in turn get redirected to an :abbr:`ATS (Apache Traffic Server)` instance, Traffic Router is most always creating a new HTTPS connection for all HTTPS traffic. It is likely to mean [...]
The HTTPS set up process is:
-#. Select one of '1 - HTTPS', '2 - HTTP AND HTTPS', or '3 - HTTP TO HTTPS' for the Delivery Service
-#. Generate private keys for the Delivery Service using a wildcard domain such as ``*.my-delivery-service.my-cdn.example.com``
+#. Select one of '1 - HTTPS', '2 - HTTP AND HTTPS', or '3 - HTTP TO HTTPS' for the :term:`Delivery Service`
+#. Generate private keys for the :term:`Delivery Service` using a wildcard domain such as ``*.my-delivery-service.my-cdn.example.com``
#. Obtain and import signed certificate chain
-#. Snapshot CRConfig
+#. Perform a CDN :term:`Snapshot`
-Clients may make HTTPS requests to Delivery Services only after Traffic Router receives the certificate chain from Traffic Ops and the new CRConfig.
+Clients may make HTTPS requests to :term:`Delivery Service`\ s only after the CDN :term:`Snapshot` propagates to Traffic Router and it receives the certificate chain from Traffic Ops.
Protocol Options
----------------
-
HTTP
Any secure client will get an SSL handshake error. Non-secure clients will experience the same behavior as prior to 1.7
HTTPS
@@ -495,67 +502,63 @@ HTTPS
HTTP AND HTTPS
Traffic Router will redirect both secure and non-secure clients
HTTP TO HTTPS
- Traffic Router will redirect non-secure clients with a ``302 Found`` response and a location that is secure (i.e. an ``https://`` URL instead of an ``http://`` URL), while secure clients will be redirected immediately to an appropriate target or cache server.
+ Traffic Router will redirect non-secure clients with a ``302 Found`` response and a location that is secure (i.e. an ``https://`` URL instead of an ``http://`` URL), while secure clients will be redirected immediately to an appropriate target or :term:`cache server`.
Certificate Retrieval
---------------------
-
-.. Warning:: If you have HTTPS Delivery Services in your CDN, Traffic Router will not accept **any** connections until it is able to fetch certificates from Traffic Ops and load them into memory. Traffic Router does not persist certificates to the Java Keystore or anywhere else.
+.. Warning:: If you have HTTPS :term:`Delivery Service`\ s in your CDN, Traffic Router will not accept **any** connections until it is able to fetch certificates from Traffic Ops and load them into memory. Traffic Router does not persist certificates to the Java Keystore or anywhere else.
Traffic Router fetches certificates into memory:
* At startup time
-* When it receives a new CRConfig
+* When it receives a new CDN :term:`Snapshot`
* Once an hour starting whenever the most recent of the last of the above occurred
-.. Note:: To adjust the frequency at which Traffic Router fetches certificates add the parameter ``certificates.polling.interval`` to CRConfig and set it to the desired duration in milliseconds.
+.. Note:: To adjust the frequency at which Traffic Router fetches certificates add the :term:`Parameter` ``certificates.polling.interval`` with the ConfigFile "CRConfig.json" and set it to the desired duration in milliseconds.
-.. Note:: Taking a snapshot of CRConfig may be used at times to avoid waiting the entire polling cycle for a new set of certificates.
+.. Note:: Taking a CDN :term:`Snapshot` may be used at times to avoid waiting the entire polling cycle for a new set of certificates.
-.. Warning:: If a snapshot of CRConfig is made that involves a Delivery Service missing its certificates, Traffic Router will ignore **ALL** changes in that CRConfig until one of the following occurs:
+.. Warning:: If a CDN :term:`Snapshot` is taken that involves a :term:`Delivery Service` missing its certificates, Traffic Router will ignore **ALL** changes in that CDN :term:`Snapshot` until one of the following occurs:
- * It receives certificates for that Delivery Service
- * Another snapshot of CRConfig is created and the Delivery Service without certificates is changed so its HTTP protocol is set to 'http'
+ * It receives certificates for that :term:`Delivery Service`
+ * Another CDN :term:`Snapshot` is taken and the :term:`Delivery Service` without certificates is changed such that its HTTP protocol is set to 'http'
Certificate Chain Ordering
--------------------------
-
The ordering of certificates within the certificate bundle matters. It must be:
#. Primary Certificate (e.g. the one created for ``*.my-delivery-service.my-cdn.example.com``)
#. Intermediate Certificate(s)
-#. Root Certificate from a Certificate Authority (CA) (optional)
+#. Root Certificate from a :abbr:`CA (Certificate Authority)` (optional)
.. Warning:: If something is wrong with the certificate chain (e.g. the order of the certificates is backwards or for the wrong domain) the client will get an SSL handshake. Inspection of ``/opt/tomcat/logs/catalina.log`` is likely to yield information to reveal this.
-To see the ordering of certificates you may have to manually split up your certificate chain and use ``openssl`` on each individual certificate
+To see the ordering of certificates you may have to manually split up your certificate chain and use :manpage:`openssl(1ssl)` on each individual certificate
Suggested Way of Setting up an HTTPS Delivery Service
-----------------------------------------------------
+Assuming you have already created a :term:`Delivery Service` which you plan to modify to use HTTPS, do the following in Traffic Portal:
-Assuming you have already created a Delivery Service which you plan to modify to use HTTPS, do the following in Traffic Portal:
-
-#. Select one of '1 - HTTPS', '2 - HTTP AND HTTPS', or '3 - HTTP TO HTTPS' for the protocol field of a Delivery Service and click the 'Update' button
-#. Under the 'More' drop-down menu, click 'Manage SSL Keys'
-#. Again under the 'More' drop-down menu, click 'Generate SSL Keys'
-#. Fill out the form and click on the green 'Generate Keys' button, then confirm that you want to make these changes
+#. Select one of '1 - HTTPS', '2 - HTTP AND HTTPS', or '3 - HTTP TO HTTPS' for the protocol field of a :term:`Delivery Service` and click the :guilabel:`Update` button
+#. Go to :menuselection:`More --> Manage SSL Keys`
+#. Click on :menuselection:`More --> Generate SSL Keys`
+#. Fill out the form and click on the green :guilabel:`Generate Keys` button, then confirm that you want to make these changes
#. Copy the contents of the Certificate Signing Request field and save it locally
-#. Go back and select 'HTTP' for the protocol field of the Delivery Service and click 'Save' (to avoid preventing other CRConfig updates from being blocked by Traffic Router)
-#. Follow your standard procedure for obtaining your signed certificate chain from a CA
+#. Go back and select 'HTTP' for the protocol field of the :term:`Delivery Service` and click :guilabel:`Save` (to avoid preventing other CDN :term:`Snapshot` updates from being blocked by Traffic Router)
+#. Follow your standard procedure for obtaining your signed certificate chain from a :abbr:`CA (Certificate Authority)`
#. After receiving your certificate chain import it into Traffic Ops
-#. Edit the Delivery Service
-#. Restore your original choice for the protocol field and click save
-#. Click 'Manage SSL Keys'
+#. Edit the :term:`Delivery Service`
+#. Restore your original choice for the protocol field and click :guilabel:`Save`
+#. Click :menuselection:`More --> Manage SSL Keys`
#. Paste your key information into the appropriate fields
-#. Click the green 'Update Keys' button
-#. Take a new snapshot of CRConfig
+#. Click the green :guilabel:`Update Keys` button
+#. Take a new CDN :term:`Snapshot`
-Once this is done you should be able to verify that you are being correctly redirected by Traffic Router using e.g. ``curl`` commands to HTTPS destinations on your Delivery Service.
+Once this is done you should be able to verify that you are being correctly redirected by Traffic Router using e.g. :manpage:`curl(1)` commands to HTTPS destinations on your :term:`Delivery Service`.
Router Load Testing
===================
-
-The Traffic Router load testing tool is located in the `Traffic Control repository under ``test/router`` <https://github.com/apache/trafficcontrol/tree/master/test/router>`_. It can be used to simulate a mix of HTTP and HTTPS traffic for a CDN by choosing the number of HTTP Delivery Services and the number HTTPS Delivery Services the test will exercise.
+The Traffic Router load testing tool is located in the `Traffic Control repository under test/router <https://github.com/apache/trafficcontrol/tree/master/test/router>`_. It can be used to simulate a mix of HTTP and HTTPS traffic for a CDN by choosing the number of HTTP :term:`Delivery Service`\ s and the number HTTPS :term:`Delivery Service` the test will exercise.
There are 2 parts to the load test:
@@ -564,9 +567,8 @@ There are 2 parts to the load test:
Running the Load Tests
----------------------
-
#. First, clone the `Traffic Control repository <https://github.com/apache/trafficcontrol>`_.
-#. You will need to make sure you have a CA file on your machine
+#. You will need to make sure you have a :abbr:`CA (Certificate Authority)` file on your machine
#. The web server is a Go program, set your ``GOPATH`` environment variable appropriately (we suggest ``$HOME/go`` or ``$HOME/src``)
#. Open a terminal emulator and navigate to the ``test/router/server`` directory inside of the cloned repository
#. Execute the server binary by running ``go run server.go``
@@ -574,24 +576,23 @@ Running the Load Tests
#. Authenticate against a Traffic Ops host - this should be a nearly instantaneous operation - you can watch the output from ``server.go`` for feedback
#. Enter the Traffic Ops host in the second form and click the button to get a list of CDN's
#. Wait for the web page to show a list of CDN's under the above form, this may take several seconds
-#. The List of CDN's will display the number of HTTP- and HTTPS-capable Delivery Services that may be exercised
+#. The List of CDN's will display the number of HTTP- and HTTPS-capable :term:`Delivery Service`\ s that may be exercised
#. Choose the CDN you want to exercise from the drop-down menu
-#. Fill out the rest of the form, enter appropriate numbers for each HTTP and HTTPS delivery services
-#. Click Run Test
+#. Fill out the rest of the form, enter appropriate numbers for each HTTP and HTTPS :term:`Delivery Service`\ s
+#. Click :guilabel:`Run Test`
#. As the test runs the web page will occasionally report results including running time, latency, and throughput
Tuning Recommendations
======================
-
-The following is an example of the command line parameters set in ``/opt/traffic_router/conf/startup.properties`` that has been tested on a multi-core server running under HTTPS load test requests. This is following the general recommendation to use the G1 garbage collector for JVM applications running on multi-core machines. In addition to using the G1 garbage collector the ``InitiatingHeapOccupancyPercent`` was lowered to run garbage collection more frequently which improved overall th [...]
-set in ``/lib/systemd/system/traffic_router.service``.
+The following is an example of the command line parameters set in :file:`/opt/traffic_router/conf/startup.properties` that has been tested on a multi-core server running under HTTPS load test requests. This is following the general recommendation to use the G1 garbage collector for :abbr:`JVM (Java Virtual Machine)` applications running on multi-core machines. In addition to using the G1 garbage collector the ``InitiatingHeapOccupancyPercent`` was lowered to run garbage collection more f [...]
.. code-block:: bash
+ :caption: Example CATALINA_OPTS Configuration
CATALINA_OPTS="\
- -server -Xms2g -Xmx8g \
- -Dlog4j.configuration=file://$CATALINA_BASE/conf/log4j.properties \
- -Djava.library.path=/usr/lib64 \
- -XX:+UseG1GC \
- -XX:+UnlockExperimentalVMOptions \
- -XX:InitiatingHeapOccupancyPercent=30"
+ -server -Xms2g -Xmx8g \
+ -Dlog4j.configuration=file://$CATALINA_BASE/conf/log4j.properties \
+ -Djava.library.path=/usr/lib64 \
+ -XX:+UseG1GC \
+ -XX:+UnlockExperimentalVMOptions \
+ -XX:InitiatingHeapOccupancyPercent=30"
diff --git a/docs/source/admin/traffic_router/migrationto2-3.rst b/docs/source/admin/traffic_router/migrationto2-3.rst
index 8d10c54..f23f08b 100644
--- a/docs/source/admin/traffic_router/migrationto2-3.rst
+++ b/docs/source/admin/traffic_router/migrationto2-3.rst
@@ -17,54 +17,53 @@
Traffic Router - Migrating to 3.0
*********************************
.. contents::
- :depth: 2
- :backlinks: top
+ :depth: 2
+ :backlinks: top
Release Notes v3.0
-==========================
-* Replaced custom Java SNI implementation with a native implementation using tomcat-native, apr (Apache Portable Runtime) and OpenSSL
- This should significantly improve the performance of routing 'https' delivery services.
+==================
+* Replaced custom Java :abbr:`SNI (Server Name Indication)` implementation with a native implementation using tomcat-native, :abbr:`APR (Apache Portable Runtime)` and OpenSSL. This should significantly improve the performance of routing HTTPS :term:`Delivery Service`\ s.
+
+ .. seealso:: `The Server Name Indication Wikipedia page <https://en.wikipedia.org/wiki/Server_Name_Indication>`_, `The Apache Portable Runtime project site <https://apr.apache.org/>`_ and/or `the OpenSSL project site <https://www.openssl.org/>`_
+
* Upgraded to Tomcat 8.5.30
-* Separated the Traffic Router installation from the Tomcat deployment and created a new 'tomcat' package for installing Tomcat.
- Traffic Router and Tomcat can now be upgraded independently
-* Converted Traffic Router to a 'systemd' service
-* Modified the development test and dev deployment processes to be more consistent with production
+* Separated the Traffic Router installation from the Tomcat deployment and created a new 'tomcat' package for installing Tomcat. Traffic Router and Tomcat can now be upgraded independently
+* Converted Traffic Router to a :manpage:`systemd(1)` service
+* Modified the development test and deployment processes to be more consistent with production
System Requirements
-==========================
+===================
* Centos 7.2
* OpenSSL >= 1.0.2 installed
-* JDK >= 8.0 installed or available in Yum repository
-* APR (Apache Portable Runtime) >= 1.4.8-3 installed or available in Yum repository
-* Tomcat Native >= 1.2.16 installed or available in Yum repository
-* tomcat >= 8.5-30 installed or available in Yum repository (This package is created automatically by the Traffic Router build process)
+* JDK >= 8.0 installed or available in an accessible :manpage:`yum(8)` repository
+* :abbr:`APR (Apache Portable Runtime)` >= 1.4.8-3 installed or available in an accessible :manpage:`yum(8)` repository
+* Tomcat Native >= 1.2.16 installed or available in an accessible :manpage:`yum(8)` repository
+* tomcat >= 8.5-30 installed or available in an accessible :manpage:`yum(8)` repository (This package is created automatically by the Traffic Router build process)
Upgrade Procedure
-==========================
-* upload tomcat.rpm to a Yum repository
-* update the traffic_router package
+=================
+* upload the :file:`dist/tomcat-{version string}.rpm` file generated as a part of the build instructions outlined in :ref:`dev-building` to an accessible :manpage:`yum(8)` repository
+* update the ``traffic_router`` package with :manpage:`yum(8)`
* restore property files
Upload tomcat.rpm
-----------------
-The 'tomcat' package gets created when you build Traffic Router. You must either add it to the yum repo where you keep all of the Traffic Control packages, or manually copy it to the servers where you will be installing Traffic Router and run ``yum install [path to package]``
-It is preferable that you add it to your Yum repository because then it will be installed automatically when you perform the Traffic Router update.
+The :file:`term-{version string}.rpm` package should have been created when Traffic Router was built according to the instructions in :ref:`dev-building`. It must must either be added to an accessible :manpage:`yum(8)` repository, or manually copied to the servers where Traffic Router will be installed. It is generally better that it be added to a :manpage:`yum(8)` repository because then it will be installed automatically when Traffic Router is updated.
Update the traffic_router Package
---------------------------------
-If openssl, apr, tomcat-native, java-1.8.0-openjdk, java-1.8.0-openjdk-devel and tomcat_tr packages are all in an available repository then you just need to run: ``yum update traffic_router``.
-This will first cause the apr, tomcat-native, java-1.8.0-openjdk, java-1.8.0-openjdk-devel and tomcat packages to be installed. When the 'tomcat' package runs, it will cause any older versions of traffic_router or tomcat to be uninstalled. This is because the previous versions of the traffic_router package included an untracked installation of tomcat.
-
+If ``openssl``, ``apr``, ``tomcat-native``, ``java-1.8.0-openjdk``, ``java-1.8.0-openjdk-devel`` and ``tomcat_tr`` packages are all in an available :manpage:`yum(8)` repository then an upgrade can be performed by running ``yum update traffic_router`` as the root user or with :manpage:`sudo(8)`. This will first cause the ``apr``, ``tomcat-native``, ``java-1.8.0-openjdk``, ``java-1.8.0-openjdk-devel`` and ``tomcat`` packages to be installed. When the ``tomcat`` package runs, it will cause [...]
Restore Property Files
-------------------------------
-The install process does not override or replace any of the files in the /opt/traffic_router/conf directory. Previous versions of the traffic_ops.properties, traffic_monitor.properties and startup.properties should still be good. On a new install replace the Traffic Router properties files with the correct ones for the CDN.
+----------------------
+The install process does not override or replace any of the files in the :file:`/opt/traffic_router/conf` directory. Previous versions of the :file:`traffic_ops.properties`, :file:`traffic_monitor.properties` and :file:`startup.properties` should still be good. On a new install replace the Traffic Router properties files with the correct ones for the CDN.
Development Environment Upgrade
===============================
+If a development environment is already set up for the previous version of Traffic Router, then ``openssl``, ``apr`` and ``tomcat-native`` will need to be manually installed with :manpage:`yum(8)` or :manpage:`rpm(8)`. Also, whenever either ``mvn clean verify`` or ``TrafficRouterStart`` is/are run, the location of the ``tomcat-native`` libraries will need to be made known to the :abbr:`JVM (Java Virtual Machine)` via command line arguments.
-If you already have a development environment set up for the previous version of Traffic Router, then you will need to get and install these libraries on your workstation: openssl, apr and tomcat-native.
-Also, whenever you run either 'mvn clean verify' or 'TrafficRouterStart' you will need to pass a command line parameter telling Java where to look for the 'tomcat-native' libraries:
-``mvn clean verify -Djava.library.path=[tomcat native library path on your box]``
-``java -Djava.library.path=[tomcat native library path on your box] TrafficRouterStart``
+.. code-block:: shell
+ :caption: Example Commands Specifying a Path to the tomcat-native Library
+ mvn clean verify -Djava.library.path=[tomcat native library path on your box]
+ java -Djava.library.path=[tomcat native library path on your box] TrafficRouterStart
diff --git a/docs/source/admin/traffic_server.rst b/docs/source/admin/traffic_server.rst
index 373a559..fae57ee 100644
--- a/docs/source/admin/traffic_server.rst
+++ b/docs/source/admin/traffic_server.rst
@@ -19,115 +19,94 @@ Traffic Server Administration
Installing Traffic Server
=========================
-#. Build the Traffic Server RPM. The best way to do this is to follow the `Apache Traffic Server documentation <https://docs.trafficserver.apache.org/en/latest/getting-started/index.en.html#installation>`_.
+#. Build the Traffic Server RPM. The best way to do this is to follow the `Apache Traffic Server documentation <https://docs.trafficserver.apache.org/en/7.1.x/getting-started/index.en.html#installation>`_.
-#. Build the astats RPM using the appropriate version number Sample link: https://github.com/apache/trafficcontrol/tree/master/traffic_server
+#. Build the astats RPM using the appropriate version number - ours are built `here <https://github.com/apache/trafficcontrol/tree/master/traffic_server>`_
-.. note:: The ``astats`` plugin is bundled as a part of Apache Traffic Server as of version 7.2.
+ .. note:: The ``astats`` plugin is bundled as a part of Apache Traffic Server as of version 7.2.
#. Install Traffic Server and astats
- The easiest way to accomplish this is by running this command as the root user (or with ``sudo``):
-
.. code-block:: bash
+ :caption: Apache Traffic Server Installation Using :manpage:`yum(8)`
yum -y install trafficserver-*.rpm astats_over_http*.rpm
#. Add the server using the Traffic Portal UI:
- #. Under 'Configure', select 'Servers'.
- #. Click on the '+' button at the top of the page.
+ #. Go to :menuselection:`Configure --> Servers`
+ #. Click on the :guilabel:`+` button at the top of the page.
#. Complete the form. Be sure to fill out all fields marked 'Required'
+
* Set 'Interface Name' to the name of the network interface device from which Apache Traffic Server delivers content.
* Set 'Type' to 'MID' or 'EDGE'.
* If you wish for the server to immediately be polled by the :ref:`health-proto`, set 'Status' to 'REPORTED'.
- #. Click on the 'Create' button to submit the form.
+
+ #. Click on the :guilabel:`Create` button to submit the form.
#. Verify that the server status is now listed as **Reported**
-#. Install the ORT script and run it in 'BADASS' mode to create the initial configuration, see :ref:`traffic-ops-ort`
+#. Install the :term:`ORT` script and run it in 'BADASS' mode to create the initial configuration
-#. Start the service by running ``systemctl start trafficserver`` as the root user (or with ``sudo``)
+ .. seealso:: :ref:`traffic-ops-ort`
-#. Configure traffic server to start automatically: ``sudo systemctl enable trafficserver``
+#. Start :abbr:`ATS (Apache Traffic Server)`
-#. Verify that the installation is good:
+ .. code-block:: bash
+ :caption: Starting :abbr:`ATS (Apache Traffic Server)` with :manpage:`systemd(1)`
- #. Make sure that the service is running: ``sudo systemctl status trafficserver``
+ systemctl start trafficserver
- #. Assuming a traffic monitor is already installed, browse to it, i.e. http://<trafficmonitorURL>, and verify that the traffic server appears in the "Cache States" table, in white.
+#. (Optional) Configure :abbr:`ATS (Apache Traffic Server)` to start automatically when the system powers on
+ .. code-block:: bash
+ :caption: Configuring :abbr:`ATS (Apache Traffic Server)` to Start Automatically Using :manpage:`systemd(1)`
-.. _traffic-ops-ort:
+ systemctl enable trafficserver
-Configuring Traffic Server
-==========================
-All of the Traffic Server application configuration files are generated by Traffic Ops and installed by way of the traffic_ops_ort.pl script.
-The ``traffic_ops_ort.pl`` file should be installed on all caches (See :ref:`installing-ort`), usually in ``/opt/ort``. It is used to do the initial install of the configuration files when the cache is being deployed, and to keep the confiurationg files up to date when the cache is already in service. The usage message of the script is shown below: ::
+#. Verify that the installation is working
- $ sudo /opt/ort/traffic_ops_ort.pl
- ====-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-====
- Usage: ./traffic_ops_ort.pl <Mode> <Log_Level> <Traffic_Ops_URL> <Traffic_Ops_Login> [optional flags]
- <Mode> = interactive - asks questions during config process.
- <Mode> = report - prints config differences and exits.
- <Mode> = badass - attempts to fix all config differences that it can.
- <Mode> = syncds - syncs delivery services with what is configured in Traffic Ops.
- <Mode> = revalidate - checks for updated revalidations in Traffic Ops and applies them. Requires Traffic Ops 2.1.
+ #. Make sure that the service is running
- <Log_Level> => ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, NONE
+ .. code-block:: bash
+ :caption: Checking that :abbr:`ATS (Apache Traffic Server)` is Running Using :manpage:`systemd(1)`
- <Traffic_Ops_URL> = URL to Traffic Ops host. Example: https://trafficops.company.net
+ systemctl status trafficserver
- <Traffic_Ops_Login> => Example: 'username:password'
+ #. Assuming a Traffic Monitor is already installed somewhere, check the "Cache States" table in its Web UI to verify that the :abbr:`ATS (Apache Traffic Server)` server appears.
- [optional flags]:
- dispersion=<time> => wait a random number between 0 and <time> before starting. Default = 300.
- login_dispersion=<time> => wait a random number between 0 and <time> before login. Default = 0.
- retries=<number> => retry connection to Traffic Ops URL <number> times. Default = 3.
- wait_for_parents=<0|1> => do not update if parent_pending = 1 in the update json. Default = 1, wait for parents.
- ====-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-====
- $
+.. _traffic-ops-ort:
-.. _installing-ort:
+Configuring Traffic Server
+==========================
+All of the :abbr:`ATS (Apache Traffic Server)` application configuration files are generated by Traffic Ops and installed by :term:`ORT`. The :file:`traffic_ops_ort.pl` file should be installed on all :term:`cache server` s (See `Installing the ORT Script`_), usually in ``/opt/ort``. It is used to do the initial install of the configuration files when the :term:`cache server` is being deployed, and to keep the configuration files up-to-date when the :term:`cache server` is already in service.
-Installing the ORT script
---------------------------
+.. _installing-ort:
-#. Build the ORT script RPM from the `Apache Build Server <https://builds.apache.org/view/S-Z/view/TrafficControl/>`_ and install it. Assuming you've named the file you downloaded ``traffic_ops_ort.rpm``, this can be installed simply by running this command as the root user (or with ``sudo``):
+Installing the ORT Script
+-------------------------
+#. Build the :term:`ORT` script RPM by following the instructions in :ref:`dev-building` and install it with :manpage:`rpm(8)` or :manpage:`yum(8)`.
+#. Install modules required by :term:`ORT` if needed
.. code-block:: bash
+ :caption: Example Installation of Perl Packages Occasionally Missing from Install
- yum install -y traffic_ops_ort.rpm
-
-#. Install modules required by ORT if needed: ``sudo yum install -y perl-JSON perl-Crypt-SSLeay``
-
-#. For initial configuration or when major changes (like a Profile change) need to be made, run the script in "badass mode". All required rpm packages will be installed, all Traffic Server configuration files will be fetched and installed, and (if needed) the Traffic Server application will be restarted.
-
- Example usage: ::
+ yum install -y perl-JSON perl-Crypt-SSLeay
- $ sudo /opt/ort/traffic_ops_ort.pl --dispersion=0 BADASS WARN https://ops.$tcDomain admin:admin123
+#. For initial configuration or when major changes (like a :term:`Profile` change) need to be made, run the script in "BADASS". All required RPM packages will be installed, all :abbr:`ATS (Apache Traffic Server)` configuration files will be fetched and installed, and (if needed) the :abbr:`ATS (Apache Traffic Server)` service will be restarted.
- .. Note:: First run gives a lot of state errors that are expected. The BADASS mode fixes these issue s. Run it a second time, this should be cleaner. Also, note that many ERROR messages emitted by ORT are actually information messages. Do not panic.
+ .. Note:: The first run gives a lot of state errors that are expected. The "BADASS" mode fixes these issues. If you run it a second time, this should be cleaner. Also, note that many "ERROR" messages emitted by :term:`ORT` are actually information messages. Do not panic.
+#. Create a :manpage:`cron(8)` entry for running :term:`ORT` in "SYNCDS" mode every 15 minutes. This makes Traffic Control check periodically if the server has updates pending, and if so get the updated configuration.
-#. Create a cron entry for running ORT in 'SYNCDS' mode every 15 minutes. This makes Traffic Control check periodically if 'Queue Updates' was run on Traffic Portal or on Traffic Ops, and if so get the updated configuration.
+ .. Note:: By default, running :term:`ORT` on an Edge-tier :term:`cache server` will cause it to first wait for its parents (usually Mid-tier :term:`cache server` s) to download their configuration before downloading its own configuration. Because of this, scheduling :term:`ORT` for running every 15 minutes (with 5 minutes default dispersion) means that it might take up to ~35 minutes for queued updates to affect all :term:`cache server` s. To customize this dispersion time, use the comm [...]
- This can be done by running ``crontab -e`` as the root user (or with ``sudo``) and adding the following line ::
+ .. Note:: In "SYNCDS" mode, the :term:`ORT` script updates only configurations that might be changed as part of normal operations, such as:
- */15 * * * * /opt/ort/traffic_ops_ort.pl SYNCDS WARN https://traffops.kabletown.net admin:password --login_dispersion=30 --dispersion=180 > /tmp/ort/syncds.log 2>&1
-
- Changing ``https://traffops.kabletown.net``, ``admin``, and ``password`` to your CDN URL and credentials.
-
- .. Note:: By default, running ORT on an Edge-tier cache server will cause it to first wait for its parents (usually Mid-tier cache servers) to download their configuration before downloading its own configuration. Because of this, scheduling ORT for running every 15 minutes (with 5 minutes default dispersion) means that it might take up to ~35 minutes for a "Queue Updates" operation to affect all cache servers. To customize this dispersion time, use the command line option ``--dispersio [...]
-
- .. Note:: In SYNCDS mode, the ORT script updates only configurations that might be changed as part of normal operations, such as:
-
- * Delivery Services
+ * :term:`Delivery Service`\ s
* SSL certificates
* Traffic Monitor IP addresses
* Logging configuration
- * Revalidation requests (By default. If Rapid Revalidate is enabled, this will only be checked by using a separate revalidate command in ORT.)
-
+ * Revalidation requests (By default - if "Rapid Revalidate" is enabled, this will only be checked by using a separate revalidate command in :term:`ORT`)
-#. If Rapid Revalidate is enabled in Traffic Ops, create a second cron job for revalidation checks. ORT will not check revalidation files if Rapid Revalidate is enabled. This setting allows for a separate check to be performed every 60 seconds to verify if a revalidation update has been made. This can be done by running ``crontab -e`` as the root user (or with ``sudo``) and adding the following line ::
- */1 * * * * /opt/ort/traffic_ops_ort.pl REVALIDATE WARN https://traffops.kabletown.net admin:password --login_dispersion=30 > /tmp/ort/syncds.log 2>&1
+#. If "Rapid Revalidate" is enabled in Traffic Ops, create a second :manpage:`cron(8)` job for revalidation checks by running :term:`ORT` in "REVALIDATE" mode. :term:`ORT` will not check revalidation files if "Rapid Revalidate" is enabled. This setting allows for a separate check to be performed every 60 seconds to verify if a revalidation update has been made.
diff --git a/docs/source/admin/traffic_stats.rst b/docs/source/admin/traffic_stats.rst
index 343dda6..4695139 100644
--- a/docs/source/admin/traffic_stats.rst
+++ b/docs/source/admin/traffic_stats.rst
@@ -13,39 +13,39 @@
.. limitations under the License.
..
+.. _ts-admin:
+
****************************
Traffic Stats Administration
****************************
-
-Traffic Stats consists of three seperate components: Traffic Stats, InfluxDB, and Grafana. See below for information on installing and configuring each component as well as configuring the integration between the three and Traffic Ops.
+Traffic Stats consists of three separate components: Traffic Stats, InfluxDB, and Grafana. See below for information on installing and configuring each component as well as configuring the integration between the three and Traffic Ops.
Installation
-========================
+============
Installing Traffic Stats
------------------------
- See the `downloads <https://trafficcontrol.apache.org/downloads/index.html>`_ page for Traffic Control to get the latest release.
-- Follow our build `intructions <https://github.com/apache/trafficcontrol/tree/master/build>`_ to generate an RPM.
+- Follow the instructions in :ref:`dev-building` to generate an RPM.
- Copy the RPM to your server
-- Perform the following command: ``sudo rpm -ivh <traffic_stats rpm>``
+- Install the generated Traffic Stats RPM with :manpage:`yum(8)` or :manpage:`rpm(8)`
Installing InfluxDB
-------------------
.. Note::As of Traffic Stats 1.8.0, InfluxDB 1.0.0 or higher is required. For InfluxDB versions less than 1.0.0 use Traffic Stats 1.7.x
-In order to store traffic stats data you will need to install `InfluxDB <https://docs.influxdata.com/influxdb/latest/introduction/installation/>`_. While not required, it is recommended to use some sort of high availability option like `Influx enterprise <https://portal.influxdata.com/>`_, `InfluxDB Relay <https://github.com/influxdata/influxdb-relay>`_, or another `high availability option <https://www.influxdata.com/high-availability/>`_.
+In order to store Traffic Stats data you will need to install `InfluxDB <https://docs.influxdata.com/influxdb/latest/introduction/installation/>`_. While not required, it is recommended to use some sort of high availability option like `Influx enterprise <https://portal.influxdata.com/>`_, `InfluxDB Relay <https://github.com/influxdata/influxdb-relay>`_, or another `high availability option <https://www.influxdata.com/high-availability/>`_.
Installing Grafana
------------------
Grafana is used to display Traffic Stats/InfluxDB data in Traffic Ops. Grafana is typically run on the same server as Traffic Stats but this is not a requirement. Grafana can be installed on any server that can access InfluxDB and can be accessed by Traffic Ops. Documentation on installing Grafana can be found on the `Grafana website <http://docs.grafana.org/installation/>`__.
Configuration
-=========================
+=============
Configuring Traffic Stats
-------------------------
-Traffic Stats' configuration file can be found in ``/opt/traffic_stats/conf/traffic_stats.cfg``.
-The following values need to be configured:
+Traffic Stats's configuration file can be found in :file:`/opt/traffic_stats/conf/traffic_stats.cfg`. The following values need to be configured:
toUser
The user used to connect to Traffic Ops
@@ -62,13 +62,13 @@ pollingInterval
statusToMon
The status of Traffic Monitor to poll (poll ONLINE or OFFLINE traffic monitors)
seelogConfig
- The absolute path of the seelong configuration file
+ The absolute path of the seelog configuration file
dailySummaryPollingInterval
The interval, in seconds, at which Traffic Stats checks to see if daily stats need to be computed and stored.
cacheRetentionPolicy
The default retention policy for cache stats
dsRetentionPolicy
- The default retention policy for Delivery Service stats
+ The default retention policy for :term:`Delivery Service`\ stats
dailySummaryRetentionPolicy
The retention policy to be used for the daily stats
influxUrls
@@ -78,38 +78,39 @@ Configuring InfluxDB
--------------------
As mentioned above, it is recommended that InfluxDB be running in some sort of high availability configuration. There are several ways to achieve high availability so it is best to consult the high availability options on the `InfuxDB website <https://www.influxdata.com/high-availability/>`_.
-Once InfluxDB is installed and configured, databases and retention policies need to be created. Traffic Stats writes to three different databases: cache_stats, deliveryservice_stats, and daily_stats. More information about the databases and what data is stored in each can be found on the `overview <../overview/traffic_stats.html>`_ page.
+Once InfluxDB is installed and configured, databases and retention policies need to be created. Traffic Stats writes to three different databases: cache_stats, deliveryservice_stats, and daily_stats. More information about the databases and what data is stored in each can be found in the `Traffic Stats Overview <tc-ts>`_.
-To easily create databases, retention policies, and continuous queries, run create_ts_databases from the ``/opt/traffic_stats/influxdb_tools`` directory on your Traffic Stats server. See the `InfluxDB Tools <traffic_stats.html#influxdb-tools>`_ section below for more information.
+To easily create databases, retention policies, and continuous queries, run :program:`create_ts_databases` from the :file:`/opt/traffic_stats/influxdb_tools` directory on your Traffic Stats server. See the `InfluxDB Tools`_ section for more information.
Configuring Grafana
-------------------
-In Traffic Portal the Other -> Grafana menu item can be configured to display Grafana graphs using InfluxDB data. In order for this to work correctly, you will need two things:
+In Traffic Portal the :menuselection:`Other --> Grafana` menu item can be configured to display Grafana graphs using InfluxDB data. In order for this to work correctly, you will need two things:
-#. A parameter with the graph URL (more information below)
+#. A :term:`Parameter` with the graph URL (more information below)
#. The graphs created in Grafana. See below for how to create some simple graphs in Grafana. These instructions assume that InfluxDB has been configured and that data has been written to it. If this is not true, you will not see any graphs.
To create a graph in Grafana, you can follow these basic steps:
-#. Login to Grafana as an administrative user at e.g. ``http://grafana_url:3000/login``
-#. Choose Data Sources and then Add New
+#. Login to Grafana as an administrative user
+#. Click on :menuselection:`Data Sources --> Add New`
#. Enter the necessary information to configure your data source
-#. Click on the 'Home' drop-down menu at the top of the screen and choose 'New' at the bottom
-#. Click on the green menu bar (with 3 lines) at the top and choose Add Panel -> Graph
-#. Where it says 'No Title (click here)' click and choose edit
+#. Click on :menuselection:`Home --> New` at the bottom
+#. Click on :menuselection:`"Collapsed Menu Icon" Button --> Add Panel --> Graph`
+#. Where it says :guilabel:`No Title (click here)` click and choose edit
#. Choose your data source at the bottom
-#. You can have Grafana help you create a query, or you can create your own. Here is a sample query:
+#. You can have Grafana help you create a query, or you can create your own.
.. code-block:: postgresql
+ :caption: Sample Query
SELECT sum(value)*1000 FROM "monthly"."bandwidth.cdn.1min" GROUP BY time(60s), cdn;
-#. Once you have the graph the way you want it, click the 'Save Dashboard' button at the top
+#. Once you have the graph the way you want it, click the :guilabel:`Save Dashboard` button at the top
#. You should now have a new saved graph
In order for Traffic Portal users to see Grafana graphs, Grafana will need to allow anonymous access. Information on how to configure anonymous access can be found on the configuration page of the `Grafana Website <http://docs.grafana.org/installation/configuration/#authanonymous>`_.
-Traffic Portal uses custom dashboards to display information about individual Delivery Services or :term:`Cache Group`\ s. In order for the custom graphs to display correctly, the `traffic_ops_*.js <https://github.com/apache/trafficcontrol/blob/master/traffic_stats/grafana/>`_ files need to be in the ``/usr/share/grafana/public/dashboards/`` directory on the Grafana server. If your Grafana server is the same as your Traffic Stats server the RPM install process will take care of putting t [...]
+Traffic Portal uses custom dashboards to display information about individual :term:`Delivery Service`\ s or :term:`Cache Group`\ s. In order for the custom graphs to display correctly, the `traffic_ops_*.js <https://github.com/apache/trafficcontrol/blob/master/traffic_stats/grafana/>`_ files need to be in the ``/usr/share/grafana/public/dashboards/`` directory on the Grafana server. If your Grafana server is the same as your Traffic Stats server the RPM install process will take care of [...]
More information on custom scripted graphs can be found in the `scripted dashboards <http://docs.grafana.org/reference/scripting/>`_ section of the Grafana documentation.
@@ -117,95 +118,120 @@ Configuring Traffic Portal for Traffic Stats
--------------------------------------------
- The InfluxDB servers need to be added to Traffic Portal with profile = InfluxDB. Make sure to use port 8086 in the configuration.
- The traffic stats server should be added to Traffic Ops with profile = Traffic Stats.
-- Parameters for which stats will be collected are added with the release, but any changes can be made via parameters that are assigned to the Traffic Stats profile.
-
-.. Note::The legacy Traffic Ops UI also supports viewing Grafana graphs from its Health -> Graphs tab.
+- :term:`Parameter`\ s for which stats will be collected are added with the release, but any changes can be made via parameters that are assigned to the Traffic Stats profile.
Configuring Traffic Portal to use Grafana Dashboards
----------------------------------------------------
-To configure Traffic Portal to use Grafana Dashboards, you need to enter the following parameters and assign them to the GLOBAL profile. This assumes you followed the above instructions to install and configure InfluxDB and Grafana. You will need to place 'cdn-stats','deliveryservice-stats', and 'daily-summary' with the name of your dashboards.
-
-+---------------------------+------------------------------------------------------------------------------------------------+
-| parameter name | parameter value |
-+===========================+================================================================================================+
-| all_graph_url | https://<grafana_url>/dashboard/db/deliveryservice-stats |
-+---------------------------+------------------------------------------------------------------------------------------------+
-| cachegroup_graph_url | https://<grafanaHost>/dashboard/script/traffic_ops_cachegroup.js?which= |
-+---------------------------+------------------------------------------------------------------------------------------------+
-| deliveryservice_graph_url | https://<grafanaHost>/dashboard/script/traffic_ops_devliveryservice.js?which= |
-+---------------------------+------------------------------------------------------------------------------------------------+
-| server_graph_url | https://<grafanaHost>/dashboard/script/traffic_ops_server.js?which= |
-+---------------------------+------------------------------------------------------------------------------------------------+
-| visual_status_panel_1 | https://<grafanaHost>/dashboard-solo/db/cdn-stats?panelId=2&fullscreen&from=now-24h&to=now-60s |
-+---------------------------+------------------------------------------------------------------------------------------------+
-| visual_status_panel_2 | https://<grafanaHost>/dashboard-solo/db/cdn-stats?panelId=1&fullscreen&from=now-24h&to=now-60s |
-+---------------------------+------------------------------------------------------------------------------------------------+
-| daily_bw_url | https://<grafanaHost>/dashboard-solo/db/daily-summary?panelId=1&fullscreen&from=now-3y&to=now |
-+---------------------------+------------------------------------------------------------------------------------------------+
-| daily_served_url | https://<grafanaHost>/dashboard-solo/db/daily-summary?panelId=2&fullscreen&from=now-3y&to=now |
-+---------------------------+------------------------------------------------------------------------------------------------+
+To configure Traffic Portal to use Grafana Dashboards, you need to enter the following :term:`Parameter`\ s and assign them to the GLOBAL profile. This assumes you followed the above instructions to install and configure InfluxDB and Grafana. You will need to place 'cdn-stats','deliveryservice-stats', and 'daily-summary' with the name of your dashboards.
+
+.. table:: Traffic Stats Parameters
+
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | parameter name | parameter value |
+ +===========================+====================================================================================================+
+ | all_graph_url | ``https://<grafana_url>/dashboard/db/deliveryservice-stats`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | cachegroup_graph_url | ``https://<grafanaHost>/dashboard/script/traffic_ops_cachegroup.js?which=`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | deliveryservice_graph_url | ``https://<grafanaHost>/dashboard/script/traffic_ops_devliveryservice.js?which=`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | server_graph_url | ``https://<grafanaHost>/dashboard/script/traffic_ops_server.js?which=`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | visual_status_panel_1 | ``https://<grafanaHost>/dashboard-solo/db/cdn-stats?panelId=2&fullscreen&from=now-24h&to=now-60s`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | visual_status_panel_2 | ``https://<grafanaHost>/dashboard-solo/db/cdn-stats?panelId=1&fullscreen&from=now-24h&to=now-60s`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | daily_bw_url | ``https://<grafanaHost>/dashboard-solo/db/daily-summary?panelId=1&fullscreen&from=now-3y&to=now`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
+ | daily_served_url | ``https://<grafanaHost>/dashboard-solo/db/daily-summary?panelId=2&fullscreen&from=now-3y&to=now`` |
+ +---------------------------+----------------------------------------------------------------------------------------------------+
InfluxDB Tools
-=========================
+==============
+Under the Traffic Stats source directory there is a directory called ``influxdb_tools``. These tools are meant to be used as one-off scripts to help a user quickly get new databases and continuous queries setup in InfluxDB. They are specific for Traffic Stats and are not meant to be generic to InfluxDB. Below is an brief description of each script along with how to use it.
-Under the Traffic Stats source directory there is a directory called ``influxdb_tools``. These tools are meant to be used as one-off scripts to help a user quickly get new databases and continuous queries setup in InfluxDB.
-They are specific for traffic stats and are not meant to be generic to InfluxDB. Below is an brief description of each script along with how to use it.
+.. _create_ts_databases:
+
+.. program:: create_ts_databases
create/create_ts_databases.go
-----------------------------
-This script creates all `databases <https://docs.influxdata.com/influxdb/latest/concepts/key_concepts/#database>`_, `retention policies <https://docs.influxdata.com/influxdb/latest/concepts/key_concepts/#retention-policy>`_, and `continuous queries <https://docs.influxdata.com/influxdb/v0.11/query_language/continuous_queries/>`_ required by traffic stats.
+This program creates all `databases <https://docs.influxdata.com/influxdb/latest/concepts/key_concepts/#database>`_, `retention policies <https://docs.influxdata.com/influxdb/latest/concepts/key_concepts/#retention-policy>`_, and `continuous queries <https://docs.influxdata.com/influxdb/v0.11/query_language/continuous_queries/>`_ required by Traffic Stats.
+
+Pre-Requisites
+""""""""""""""
+* Go 1.7 or later
+* Configured ``$GOPATH`` environment variable
+
+Options and Arguments
+"""""""""""""""""""""
+.. option:: --help
+
+ (Optional) Print usage information and exit (with a failure exit code for some reason)
+
+.. option:: --password password
+
+ The password that will be used by the user defined by :option:`--user` to authenticate.
+
+.. option:: --replication N
+
+ (Optional) The number of nodes in the cluster (default: 3)
+
+.. option:: --url URL
+
+ The InfluxDB server's root URL - including port number, if required (default: ``http://localhost:8086``)
+
+.. option:: --user username
+
+ The name of the user to use when connecting to InfluxDB
+
+.. _sync_ts_databases:
+
+.. program:: sync_ts_databases
+
+sync/sync_ts_databases.go
+-------------------------
+This program is used to sync one InfluxDB environment to another. Only data from continuous queries is synced as it is down-sampled data and much smaller in size than syncing raw data. Possible use cases are syncing from production to development or syncing a new cluster once brought online.
+
+Pre-Requisites
+""""""""""""""
+* Go 1.7 or later
+* Configured ``$GOPATH`` environment variable
+
+Options and Arguments
+"""""""""""""""""""""
+.. option:: --database database_name
+
+ (Optional) Specify the name of a specific database to sync (default: all databases)
+
+.. option:: --days N
-How to Use ``create_ts_databases``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Pre-Requisites:
+ The number of days in the past to sync. ``0`` means 'all'
- 1. Go 1.7 or later
- 2. Configured $GOPATH (e.g. export GOPATH=~/go)
+.. option:: --help
-Using ``create_ts_databases.go``
+ (Optional) Print usage information and exit
- 1. Go to the traffic_stats/influxdb_tools/create directory
- 2. Build it by running ``go build create_ts_databases.go`` or simply ``go build``
- 3. Run it:
- - ``./create_ts_databases -help`` or ``./create -help``
- - optional flags:
- - ``url`` - The InfluxDB url and port
- - ``replication`` - The number of nodes in the cluster
- - ``user`` - The user to use
- - ``password`` - The password to use
- - example: ``./create_ts_databases -url=localhost:8086 -replication=3 -user=joe -password=mysecret`` or ``./create -url=localhost:8086 -replication=3 -user=joe -password=mysecret``
+.. option:: --source-password password
-``sync_ts_databases``
----------------------
-This script is used to sync one InfluxDB environment to another. Only data from continuous queries is synced as it is downsampled data and much smaller in size than syncing raw data. Possible use cases are syncing from Production to Development or Syncing a new cluster once brought online.
+ The password of the user named by :option:`--source-user`
-How to Use ``sync_ts_databases``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Pre-Requisites:
+.. option:: --source-url URL
- 1. Go 1.7 or later
- 2. Configured ``$GOPATH`` (e.g. ``export GOPATH=~/go``)
+ (Optional) The URL of the InfluxDB instance _from_ which data will be copied (default: ``http://localhost:8086``)
-Using sync_ts_databases.go:
+.. option:: --source-user username
- 1. Go to the traffic_stats/influxdb_tools/create directory
- 2. Build it by running ``go build sync_ts_databases.go`` or simply ``go build``
- 3. Run it
+ The name of the user as whom the utility will connect to the source InfluxDB instance
- - ``./sync_ts_databases -help`` or ``./sync -help``
- - required flags:
+.. option:: --target-password password
- - ``source-url`` - The URL of the source database
- - ``target-url`` - The URL of the target database
+ The password of the user named by :option:`--target-user`
- - optional flags:
+.. option:: --target-url URL
- - ``database`` - The database to sync (default = sync all databases)
- - ``days`` - Days in the past to sync (default = sync all data)
- - ``source-user`` - The user of the source database
- - ``source-pass`` - The password for the source database
- - ``target-user`` - The user of the target database
- - ``target-pass`` - The password for the target database
+ (Optional) The URL of the InfluxDB instance _to_ which data will be copied (default: ``http://localhost:8086``)
- - example: ``./sync -source-url=http://idb-01.foo.net:8086 -target-url=http://idb-01.foo.net:8086 -database=cache_stats -days=7 -source-user=admin source-pass=mysecret``
+.. option:: --target-user username
+ The name of the user as whom the utility will connect to the target InfluxDB instance
diff --git a/docs/source/admin/traffic_vault.rst b/docs/source/admin/traffic_vault.rst
index 945900a..59633ca 100644
--- a/docs/source/admin/traffic_vault.rst
+++ b/docs/source/admin/traffic_vault.rst
@@ -18,21 +18,15 @@ Traffic Vault Administration
****************************
Installing Traffic Vault
========================
-In order to successfully store private keys you will need to install Riak.
-The latest version of Riak can be downloaded on the Riak `website <http://docs.basho.com/riak/latest/downloads/>`_.
-The installation instructions for Riak can be found `here <http://docs.basho.com/riak/latest/ops/building/installing/>`__.
-
-Based on experience, version 2.0.5 of Riak is recommended, but the latest version should suffice.
+In order to successfully store private keys you will need to install Riak. The latest version of Riak can be downloaded on `the Riak website <http://docs.basho.com/riak/latest/downloads/>`_. The installation instructions for Riak can be found `here <http://docs.basho.com/riak/latest/ops/building/installing/>`__. Based on experience, version 2.0.5 of Riak is recommended, but the latest version should suffice.
Configuring Traffic Vault
=========================
The following steps were taken to configure Riak in Comcast production environments.
-
Self Signed Certificate configuration
-------------------------------------
-
-.. note:: Self Signed Certificates are not recommended for production use. Intended for dev or learning purposes only. Modify subject as necessary.
+.. note:: Self-signed certificates are not recommended for production use. Intended for development or learning purposes only. Modify subject as necessary.
.. code-block:: shell
:caption: Self-Signed Certificate Configuration
@@ -52,159 +46,188 @@ Self Signed Certificate configuration
mv -f ca-bundle.crt /etc/pki/tls/certs/.
-Riak configuration file configuration
--------------------------------------
-
+Riak Configuration File
+-----------------------
The following steps need to be performed on each Riak server in the cluster:
-* Log into Riak server as root
+#. Log into Riak server as root
+#. Update the following in :file:`riak.conf` to reflect your IP, hostname, and CDN domains and sub-domains:
-* ``cd /etc/riak/``
+ * ``nodename = riak@a-host.sys.kabletown.net``
+ * ``listener.http.internal = a-host.sys.kabletown.net:8098`` (port can be 80 - This endpoint will not work over HTTPS)
+ * ``listener.protobuf.internal = a-host.sys.kabletown.net:8087`` (can be different port if you want)
+ * ``listener.https.internal = a-host.sys.kabletown.net:8088`` (port can be 443)
-* Update the following in ``riak.conf`` to reflect your IP, hostname and CDN domains/sub-domains:
- - ``nodename = riak@a-host.sys.kabletown.net``
- - ``listener.http.internal = a-host.sys.kabletown.net:8098`` (port can be 80 - This endpoint will not work with sec enabled)
- - ``listener.protobuf.internal = a-host.sys.kabletown.net:8087`` (can be different port if you want)
- - ``listener.https.internal = a-host.sys.kabletown.net:8088`` (port can be 443)
+#. Update the following in :file:`riak.conf` file to point to your SSL certificate files
-* Updated the following conf file to point to your cert files
- ``ssl.certfile = /etc/riak/certs/server.crt``
- ``ssl.keyfile = /etc/riak/certs/server.key``
- ``ssl.cacertfile = /etc/pki/tls/certs/ca-bundle.crt``
-* Add a line at the bottom of the configuration file for TLSv1
- - ``tls_protocols.tlsv1 = on``
+#. Add a line at the bottom of the :file:`riak.conf` for TLSv1 by setting ``tls_protocols.tlsv1 = on``
+#. Once the configuration file has been updated restart Riak
+#. Consult the `Riak documentation <http://docs.basho.com/riak/kv/2.2.3/setup/installing/verify/>`_ for instructions on how to verify the installed service
-* Once the configuration file has been updated restart Riak
- - ``/etc/init.d/riak restart``
-
-* Validate server is running by going to the following URL:
- - ``https://<serverHostname>:8088/ping``
-
-``riak-admin`` configuration
+``riak-admin`` Configuration
----------------------------
+``riak-admin`` is a command line utility used to configure Riak that needs to be run as root on a server in the Riak cluster.
-``riak-admin`` is a command line utility that needs to be run as root on a server in the Riak cluster.
-
-Assumptions:
- * Riak 2.0.2 or greater is installed
- * SSL Certificates have been generated (signed or self-signed)
- * Root access to Riak servers
-
-Add ``admin`` user and ``riakuser`` to Riak
- * ``admin`` user will be a super user
- * ``riakuser`` will be the application user
+.. seealso:: `The riak-admin documentation <http://docs.basho.com/riak/kv/2.2.3/using/admin/riak-admin/>`_
-Login to one of the riak servers in the cluster as root (any will do)
-
- 1. Enable security
-
- ``riak-admin security enable``
-
- 2. Add groups
-
- ``riak-admin security add-group admins``
-
- ``riak-admin security add-group keysusers``
- 3. Add users
-
- .. Note:: User name and password should be stored in ``/opt/traffic_ops/app/conf/<environment>/riak.conf``
-
- ``riak-admin security add-user admin password=<AdminPassword> groups=admins``
+.. code-block:: shell
+ :caption: Traffic Vault Setup with ``riak-admin``
+
+ # This script need only be run on any *one* Riak server in the cluster
+
+ # Enable security and secure access groups
+ riak-admin security enable
+ riak-admin security add-group admins
+ riak-admin security add-group keysusers
+
+ # User name and password should be stored in
+ # /opt/traffic_ops/app/conf/<environment>/riak.conf on the Traffic Ops
+ # server
+ # In this example, we assume the usernames 'admin' and 'riakuser' with
+ # respective passwords stored in the ADMIN_PASSWORD and RIAK_USER_PASSWORD
+ # environment variables
+ riak-admin security add-user admin password=$ADMIN_PASSWORD groups=admins
+ riak-admin security add-user riakuser password=$RIAK_USER_PASSWORD groups=keysusers
+ riak-admin security add-source riakuser 0.0.0.0/0 password
+ riak-admin security add-source admin 0.0.0.0/0 password
+
+ # Grant privileges to the admins group for everything
+ riak-admin security grant riak_kv.list_buckets,riak_kv.list_keys,riak_kv.get,riak_kv.put,riak_kv.delete on any to admins
+
+ # Grant privileges to keysusers group for SSL, DNSSEC, and url_sig_keys buckets only
+ riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default ssl to keysusers
+ riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default dnssec to keysusers
+ riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default url_sig_keys to keysusers
+ riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default cdn_uri_sig_keys to keysusers
- ``riak-admin security add-user riakuser password=<RiakUserPassword> groups=keysusers``
+.. seealso:: For more information on security in Riak, see the `Riak Security documentation <http://docs.basho.com/riak/2.0.4/ops/advanced/security/>`_.
+.. seealso:: For more information on authentication and authorization in Riak, see the `Riak Authentication and Authorization documentation <http://docs.basho.com/riak/2.0.4/ops/running/authz/>`_.
- 4. Grant access for ``admin`` and ``riakuser``
- ``riak-admin security add-source riakuser 0.0.0.0/0 password``
+Traffic Ops Configuration
+-------------------------
+Before a fully set-up Traffic Vault instance may be used, it must be added as a server to Traffic Ops. The easiest way to accomplish this is via Traffic Portal at :menuselection:`Configure --> Servers`, though :ref:`to-api-servers` may also be used by low-level tools and/or scripts. The Traffic Ops configuration file :file:`/opt/traffic_ops/app/conf/{environment}/riak.conf` for the appropriate environment must also be updated to reflect the correct username and password for accessing the [...]
- ``riak-admin security add-source admin 0.0.0.0/0 password``
+Configuring Riak Search
+=======================
+In order to more effectively support retrieval of SSL certificates by Traffic Router and :term:`ORT`, Traffic Vault uses `Riak search <http://docs.basho.com/riak/kv/latest/using/reference/search/>`_. Riak Search uses `Apache Solr <http://lucene.apache.org/solr>`_ for indexing and searching of records. This section explains how to enable, configure, and validate Riak Search.
- 5. Grant privileges to the ``admins`` group for everything
+Riak Configuration
+------------------
+On each Traffic Vault server follow these steps.
- ``riak-admin security grant riak_kv.list_buckets,riak_kv.list_keys,riak_kv.get,riak_kv.put,riak_kv.delete on any to admins``
+#. If Java (JDKv1.8+) is not already installed on your Riak server, install Java
- 6. Grant privileges to ``keysusers`` group for SSL, DNSSEC, and ``url_sig_keys`` buckets only
+ .. code-block:: shell
+ :caption: Check if Java is Installed, Then Install if Needed
- ``riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default ssl to keysusers``
+ # Ensure that this outputs a Java version that is at least 1.8
+ java -version
- ``riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default dnssec to keysusers``
+ # If it didn't, or produced an error because `java` doesn't exist,
+ # install the correct version
+ # (OpenJDK is used here because of its permissive license, though OracleJDK
+ # should work with some tinkering)
- ``riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default url_sig_keys to keysusers``
+ # On CentOS/RedHat/Fedora (recommended)
+ yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel
- ``riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default cdn_uri_sig_keys to keysusers``
+ # On Ubuntu/Debian/Linux Mint
+ apt install -y openjdk-8-jdk
-.. seealso:: For more information on security in Riak, see the `Riak Security documentation <http://docs.basho.com/riak/2.0.4/ops/advanced/security/>`_.
-.. seealso:: For more information on authentication and authorization in Riak, see the `Riak Authentication and Authorization documentation <http://docs.basho.com/riak/2.0.4/ops/running/authz/>`_.
+ # Arch/Manjaro
+ pacman -Sy jdk8-openjdk
+#. Enable search in :file:`riak.conf` by changing the ``search = off`` setting to ``search = on``
+#. Restart Riak to propagate configuration changes
-Traffic Ops Configuration
--------------------------
+ .. code-block:: bash
+ :caption: Restarting Riak on :manpage:`systemd(1)` Systems
-There are a couple configurations that are necessary in Traffic Ops.
+ systemctl restart riak
-1. Database Updates
- * The servers in the Riak cluster need to be added to the server table (TCP Port = 8088, type = RIAK, profile = RIAK_ALL)
+One-time Configuration
+""""""""""""""""""""""
+After Riak has been configured to use Riak Search, permissions still need need to be updated to allow users to utilize this feature. Unlike actually setting up Riak Search, the permissions step need only be done on any *one* of the Riak servers in the cluster.
-2. Configuration updates
- * ``/opt/traffic_ops/app/conf/<environment>/riak.conf`` needs to be updated to reflect the correct username and password for accessing riak.
+#. Use ``riak-admin`` to grant ``search.admin`` permissions to the "admin" user and ``search.query`` permissions to **both** the "admin" user and the "riakuser" user. The "admin" user will also require ``search.admin`` permissions on the ``schema`` (in addition to ``index``) and ``riak_core.set_bucket`` permissions on ``any``.
-Configuring Riak Search
-=======================
+ .. code-block:: bash
+ :caption: Setting up Riak Search Permissions
-In order to more effectively support retrieval of SSL certificates by Traffic Router and Traffic Ops ORT, Traffic Vault uses `Riak search <http://docs.basho.com/riak/kv/latest/using/reference/search/>`_. Riak Search uses `Apache Solr <http://lucene.apache.org/solr>`_ for indexing and searching of records. The following explains how to enable, configure, and validate Riak Search.
+ riak-admin security grant search.admin on schema to admin
+ riak-admin security grant search.admin on index to admin
+ riak-admin security grant search.query on index to admin
+ riak-admin security grant search.query on index sslkeys to admin
+ riak-admin security grant search.query on index to riakuser
+ riak-admin security grant search.query on index sslkeys to riakuser
+ riak-admin security grant riak_core.set_bucket on any to admin
-Riak Configuration
-------------------
+#. Add the search schema to Riak. This schema is a simple Apache Solr configuration file which will index all records on CDN, hostname, and :term:`Delivery Service`. The file can be found at :file:`traffic_ops/app/config/misc/riak_search/sslkeys.xml` in the Traffic Control repository.
-On Each Riak Server:
+ .. code-block:: bash
+ :caption: Adding the GitHub-hosted Search Schema to Riak
-1. If Java (JDKv1.8+) is not already installed on your Riak server, install Java
- * To see if Java is already installed: ``java -version``
- * To install Java: ``yum install -y java-1.8.0-openjdk java-1.8.0-openjdk-devel`` (CentOS/RedHat/Fedora), ``apt-get install -y openjdk-8-jdk`` (Ubuntu/Debian/Linux Mint), ``pacman -Sy jdk8-openjdk`` (Arch/Manjaro)
+ # Obtain the configuration file - in this example by downloading it from GitHub
+ wget https://raw.githubusercontent.com/apache/trafficcontrol/master/traffic_ops/app/conf/misc/riak_search/sslkeys.xml
-2. Enable search in riak.conf
- * ``$EDITOR /etc/riak/riak.conf``
- * look for search and change ``search = off`` to ``search = on``
+ # Upload the schema to the Riak server using its API
+ # Note that the assumptions made here are that the "admin" user's password is "pass"
+ # and the server is accessible at port 8088 on the hostname "trafficvault.infra.ciab.test"
+ curl -kvsX PUT "https://admin:pass@trafficvault.infra.ciab.test:8088/search/schema/sslkeys" -H "Content-Type: application/xml" -d @sslkeys.xml
-3. Restart Riak so search is on
- * ``systemctl restart riak`` (systemD-based systems)
+#. Add the search index to Riak.
-One time configuration:
+ .. code-block:: bash
+ :caption: Adding the Search Index to Riak Via its API
-1. On one of the Riak servers in the cluster run the following riak-admin commands:
+ # Note that the assumptions made here are that the "admin" user's password is "pass"
+ # and the server is accessible at port 8088 on the hostname "trafficvault.infra.ciab.test"
+ curl -kvsX PUT "https://admin:pass@trafficvault.infra.ciab.test:8088/search/index/sslkeys" -H 'Content-Type: application/json' -d '{"schema":"sslkeys"}'
- - ``riak-admin security grant search.admin on schema to admin``
+4. Associate the ``sslkeys`` index to the ``ssl`` bucket in Riak
- - ``riak-admin security grant search.admin on index to admin``
+ .. code-block:: bash
+ :caption: Using the Riak API to Create an Index-to-Bucket Association for ``sslkeys``
- - ``riak-admin security grant search.query on index to admin``
+ # Note that the assumptions made here are that the "admin" user's password is "pass"
+ # and the server is accessible at port 8088 on the hostname "trafficvault.infra.ciab.test"
+ curl -kvs -XPUT "https://admin:pass@trafficvault.infra.ciab.test:8088/buckets/ssl/props" -H'content-type:application/json' -d'{"props":{"search_index":"sslkeys"}}'
- - ``riak-admin security grant search.query on index sslkeys to admin``
+Adding Newly Indexed Fields to Existing Records
+"""""""""""""""""""""""""""""""""""""""""""""""
+Riak Search (using Apache Solr) will now index all **new** records that are added to the ``ssl`` bucket. The ``cdn``, ``deliveryservice``, and ``hostname`` fields are indexed. When a search is performed Riak will return the indexed fields along with the certificate and key values for a SSL record. In order to add the indexed fields to current records and to get the current records added, the :file:`traffic_ops/app/script/update_riak_for_search.pl` script needs to be run. This does not ne [...]
- - ``riak-admin security grant search.query on index to riakuser``
+.. code-block:: bash
+ :caption: Example Usage of :file:`traffic_ops/app/script/update_riak_for_search.pl`
- - ``riak-admin security grant search.query on index sslkeys to riakuser``
+ ### Note that the following steps should be done on the Traffic VAULT server ###
- - ``riak-admin security grant riak_core.set_bucket on any to admin``
+ # Obtain the script - in this example by downloading it from GitHub
+ wget https://raw.githubusercontent.com/apache/trafficcontrol/master/traffic_ops/app/script/update_riak_for_search.pl
-2. Add the search schema to Riak. This schema is a simple Apache Solr configuration file which will index all records on CDN, hostname, and Delivery Service.
- * Get the schema file by either cloning the project and going to ``traffic_ops/app/config/misc/riak_search`` or from `Github <https://github.com/apache/trafficcontrol/tree/master/traffic_ops/app/conf/misc/riak_search>`_.
- * Use cURL to add the schema to Riak: ``curl -kvs -XPUT "https://admin:pass@riakserver:8088/search/schema/sslkeys" -H 'Content-Type:application/xml' -d @sslkeys.xml``
+ # Assuming Traffic Ops is hosted at trafficops.infra.ciab.test, with username 'admin' and password 'twelve!'
+ # the script should be run like so:
-3. Add search index to Riak
- * run the following cURL command: ``curl -kvs -XPUT "https://admin:pass@riakserver:8088/search/index/sslkeys" -H 'Content-Type: application/json' -d '{"schema":"sslkeys"}'``
+ ./update_riak_for_search.pl -to_url=https://trafficops.infra.ciab.test -to_un=admin -to_pw="twelve!"
-4. Associate the ``sslkeys`` index to the ``ssl`` bucket in Riak
- * run the following curl command: ``curl -kvs -XPUT "https://admin:pass@riakserver:8088/buckets/ssl/props" -H'content-type:application/json' -d'{"props":{"search_index":"sslkeys"}}'``
+To validate the search is working run a query against the Riak database server, or use the Traffic Ops API endpoint: :ref:`to-api-cdns-name-name-sslkeys`
-Riak Search (using Apache Solr) will now index all **new** records that are added to the ``ssl`` bucket. The ``cdn``, ``deliveryservice``, and ``hostname`` fields are indexed. When a search is performed Riak will return the indexed fields along with the certificate and key values for a SSL record. In order to add the indexed fields to current records and to get the current records added, a standalone script needs to be run. This does not need to be done on new installs. The following exp [...]
+.. code-block:: bash
+ :caption: Validate Riak Search is Working
-1. Get script from Github either by cloning the project and going to ``traffic_ops/app/script`` or from `here <https://github.com/apache/trafficcontrol/blob/master/traffic_ops/app/script/update_riak_for_search.pl>`_
-2. Run the script by performing the following command ``./update_riak_for_search.pl -to_url=https://traffic-ops.kabletown.net -to_un=user -to_pw=password`` (with the appropriate URL substituted for your Traffic Ops server{.})
+ # Note that the assumptions made here are that the "admin" user's password is
+ # "pass", the Traffic Vault server's Riak database is accessible at port 8088 on
+ # the hostname "trafficvault.infra.ciab.test", $COOKIE contains a valid
+ # Mojolicious cookie for a Traffic Ops user with proper permissions, and the
+ # Traffic Ops server is available at the hostname "trafficops.infra.ciab.test"
-Validate the search is working by querying against Riak directly:
-``curl -kvs "https://admin:password@riakserver:8088/search/query/sslkeys?wt=json&q=cdn:mycdn"``
+ # Verify by querying Riak directly
+ curl -kvs "https://admin:password@trafficvault.infra.ciab.test:8088/search/query/sslkeys?wt=json&q=cdn:CDN-in-a-Box"
-Validation can also be done by querying Traffic Ops:
-``curl -Lvs -H "Cookie: $COOKIE" https://traffic-ops.kabletown.net/api/1.2/cdns/name/mycdn/sslkeys.json``
+ # Verify using the Traffic Ops API
+ curl -Lvs -H "Cookie: $COOKIE" https://trafficops.infra.ciab.test/api/1.4/cdns/name/mycdn/sslkeys
diff --git a/docs/source/api/cache_stats.rst b/docs/source/api/cache_stats.rst
index 4cc610b..658c7b6 100644
--- a/docs/source/api/cache_stats.rst
+++ b/docs/source/api/cache_stats.rst
@@ -25,7 +25,7 @@ Retrieves detailed, aggregated statistics for caches configured in Traffic Ops.
.. versionadded:: 1.2
-.. seealso:: This gives an aggregate of statistics for *all caches* within a particular CDN and time range. For statistics basic statistics from all caches regardless of CDN and at the current time, use :ref:`to-api-caches_stats`.
+.. seealso:: This gives an aggregate of statistics for *all caches* within a particular CDN and time range. For statistics basic statistics from all caches regardless of CDN and at the current time, use :ref:`to-api-caches-stats`.
``GET``
-------
diff --git a/docs/source/api/cachegroupparameters.rst b/docs/source/api/cachegroupparameters.rst
index 9fd32ec..a847175 100644
--- a/docs/source/api/cachegroupparameters.rst
+++ b/docs/source/api/cachegroupparameters.rst
@@ -68,7 +68,7 @@ Response Structure
``POST``
========
-Assign parameter(s) to :term:`Cache Group`(s).
+Assign parameter(s) to :term:`Cache Group`\ (s).
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
diff --git a/docs/source/api/cachegroups_id_deliveryservices.rst b/docs/source/api/cachegroups_id_deliveryservices.rst
index 208e39d..45f83aa 100644
--- a/docs/source/api/cachegroups_id_deliveryservices.rst
+++ b/docs/source/api/cachegroups_id_deliveryservices.rst
@@ -21,7 +21,7 @@
``POST``
========
-Assigns a :term:`Cache Group` to one or more Delivery Services
+Assigns a :term:`Cache Group` to one or more :term:`Delivery Service`\ s
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -37,7 +37,7 @@ Request Structure
| ID | The integral, unique identifier of the :term:`Cache Group` being assigned |
+------+---------------------------------------------------------------------------+
-:deliveryServices: The integral, unique identifiers of the Delivery Services to which the :term:`Cache Group` is being assigned
+:deliveryServices: The integral, unique identifiers of the :term:`Delivery Service`\ s to which the :term:`Cache Group` is being assigned
.. code-block:: http
:caption: Request Example
@@ -54,7 +54,7 @@ Request Structure
Response Structure
------------------
-:deliveryServices: An array of *all* Delivery Services to which the :term:`Cache Group` is assigned (**not** just the one(s) to which it was assigned via the request)
+:deliveryServices: An array of *all* :term:`Delivery Service`\ s to which the :term:`Cache Group` is assigned (**not** just the one(s) to which it was assigned via the request)
:id: The :term:`Cache Group`\ 's ID
:serverNames: An array of the (short) hostnames of all servers in the :term:`Cache Group`
diff --git a/docs/source/api/cdns_name_configs_monitoring.rst b/docs/source/api/cdns_name_configs_monitoring.rst
index ff50cf6..b3e1665 100644
--- a/docs/source/api/cdns_name_configs_monitoring.rst
+++ b/docs/source/api/cdns_name_configs_monitoring.rst
@@ -62,14 +62,14 @@ Response Structure
:tm.healthParams.polling.url: The URL from which a list of health-polling parameters can be obtained
:tm.polling.interval: The interval at which to poll for configuration updates
-:deliveryServices: An array of objects representing each Delivery Service provided by this CDN
+:deliveryServices: An array of objects representing each :term:`Delivery Service` provided by this CDN
- :status: The Delivery Service's status
- :totalKbpsThreshold: A threshold rate of data transfer this Delivery Service is configured to handle, in Kilobits per second
- :totalTpsThreshold: A threshold amount of transactions per second that this Delivery Service is configured to handle
+ :status: The :term:`Delivery Service`'s status
+ :totalKbpsThreshold: A threshold rate of data transfer this :term:`Delivery Service` is configured to handle, in Kilobits per second
+ :totalTpsThreshold: A threshold amount of transactions per second that this :term:`Delivery Service` is configured to handle
:xmlId: An integral, unique identifier for this Deliver Service (named "xmlId" for legacy reasons)
-:profiles: An array of the profiles in use by the cache servers and Delivery Services belonging to this CDN
+:profiles: An array of the profiles in use by the :term:`cache server` s and :term:`Delivery Service`\ s belonging to this CDN
:name: The profile's name
:parameters: An array of the parameters in this profile that relate to monitoring configuration. This can be ``null`` if the servers using this profile cannot be monitored (e.g. Traffic Routers)
@@ -96,9 +96,9 @@ Response Structure
:trafficServers: An array of objects that represent the caches being monitored within this CDN
:cacheGroup: The Cache Group to which this cache belongs
- :fqdn: A Fully Qualified Domain Name (FQDN) that resolves to the cache server's IP (or IPv6) address
- :hashId: The short name for the cache server - named "hashId" for legacy reasons
- :hostName: The (short) hostname of the cache server
+ :fqdn: A Fully Qualified Domain Name (FQDN) that resolves to the :term:`cache server`'s IP (or IPv6) address
+ :hashId: The short name for the :term:`cache server` - named "hashId" for legacy reasons
+ :hostName: The (short) hostname of the :term:`cache server`
:interfacename: The name of the network interface device being used by the cache's HTTP proxy
:ip6: The cache's IPv6 address - when applicable
:ip: The cache's IP address
diff --git a/docs/source/api/cdns_name_federations.rst b/docs/source/api/cdns_name_federations.rst
index beb63fa..2526c20 100644
--- a/docs/source/api/cdns_name_federations.rst
+++ b/docs/source/api/cdns_name_federations.rst
@@ -49,10 +49,10 @@ Request Structure
Response Structure
------------------
:cname: The Canonical Name (CNAME) used by the federation
-:deliveryService: An object with keys that provide identifying information for the Delivery Service using this federation
+:deliveryService: An object with keys that provide identifying information for the :term:`Delivery Service` using this federation
- :id: The integral, unique identifier for the Delivery Service
- :xmlId: The Delivery Service's uniquely identifying 'xml_id'
+ :id: The integral, unique identifier for the :term:`Delivery Service`
+ :xmlId: The :term:`Delivery Service`'s uniquely identifying 'xml_id'
:description: An optionally-present field containing a description of the field
diff --git a/docs/source/api/cdns_name_federations_id.rst b/docs/source/api/cdns_name_federations_id.rst
index fa4f183..3d3c9b4 100644
--- a/docs/source/api/cdns_name_federations_id.rst
+++ b/docs/source/api/cdns_name_federations_id.rst
@@ -51,10 +51,10 @@ Request Structure
Response Structure
------------------
:cname: The Canonical Name (CNAME) used by the federation
-:deliveryService: An object with keys that provide identifying information for the Delivery Service using this federation
+:deliveryService: An object with keys that provide identifying information for the :term:`Delivery Service` using this federation
- :id: The integral, unique identifer for the Delivery Service
- :xmlId: The Delivery Service's uniquely identifying 'xml_id'
+ :id: The integral, unique identifer for the :term:`Delivery Service`
+ :xmlId: The :term:`Delivery Service`'s uniquely identifying 'xml_id'
:description: An optionally-present field containing a description of the field
diff --git a/docs/source/api/cdns_name_name_dnsseckeys.rst b/docs/source/api/cdns_name_name_dnsseckeys.rst
index 2f050fe..6577859 100644
--- a/docs/source/api/cdns_name_name_dnsseckeys.rst
+++ b/docs/source/api/cdns_name_name_dnsseckeys.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Gets a list of DNSSEC keys for CDN and all associated Delivery Services. Before returning response to user, this will make sure DNSSEC keys for all delivery services exist and are not expired. If they don't exist or are expired, they will be (re-)generated.
+Gets a list of DNSSEC keys for CDN and all associated :term:`Delivery Service`\ s. Before returning response to user, this will make sure DNSSEC keys for all delivery services exist and are not expired. If they don't exist or are expired, they will be (re-)generated.
:Auth. Required: Yes
:Roles Required: "admin"
@@ -39,7 +39,7 @@ Request Structure
Response Structure
------------------
-:name: The name of the CDN or Delivery Service to which the enclosed keys belong
+:name: The name of the CDN or :term:`Delivery Service` to which the enclosed keys belong
:zsk: The short-term Zone-Signing Key (ZSK)
diff --git a/docs/source/api/cdns_name_name_dnsseckeys_delete.rst b/docs/source/api/cdns_name_name_dnsseckeys_delete.rst
index 5693839..86e13e2 100644
--- a/docs/source/api/cdns_name_name_dnsseckeys_delete.rst
+++ b/docs/source/api/cdns_name_name_dnsseckeys_delete.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Delete DNSSEC keys for a CDN and all associated Delivery Services.
+Delete DNSSEC keys for a CDN and all associated :term:`Delivery Service`\ s.
:Auth. Required: Yes
:Roles Required: "admin"
diff --git a/docs/source/api/cdns_name_name_sslkeys.rst b/docs/source/api/cdns_name_name_sslkeys.rst
index 7ffaf56..54027c7 100644
--- a/docs/source/api/cdns_name_name_sslkeys.rst
+++ b/docs/source/api/cdns_name_name_sslkeys.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Returns SSL certificates for all Delivery Services that are a part of the CDN.
+Returns SSL certificates for all :term:`Delivery Service`\ s that are a part of the CDN.
:Auth. Required: Yes
:Roles Required: "admin"
@@ -39,12 +39,12 @@ Request Structure
Response Structure
------------------
-:certificate: An object representing The SSL keys used for the Delivery Service identified by ``deliveryservice``
+:certificate: An object representing The SSL keys used for the :term:`Delivery Service` identified by ``deliveryservice``
:key: Base 64-encoded private key for SSL certificate
:crt: Base 64-encoded SSL certificate
-:deliveryservice: The ``xml_id`` of the Delivery Service using the SSL key within ``certificate``
+:deliveryservice: The ``xml_id`` of the :term:`Delivery Service` using the SSL key within ``certificate``
.. code-block:: json
:caption: Response Example
diff --git a/docs/source/api/cdns_name_snapshot.rst b/docs/source/api/cdns_name_snapshot.rst
index 2e00eba..6603ad8 100644
--- a/docs/source/api/cdns_name_snapshot.rst
+++ b/docs/source/api/cdns_name_snapshot.rst
@@ -106,7 +106,7 @@ Response Structure
:zonemanager.cache.maintenance.interval: A configuration option for the ZoneManager Java class of Traffic Router
:zonemanager.threadpool.scale: A configuration option for the ZoneManager Java class of Traffic Router
-:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for Delivery Services in this CDN
+:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for :term:`Delivery Service`\ s in this CDN
:api.port: A string containing the port number on which the :ref:`tr-api` is served by this Traffic Router
:fqdn: This Traffic Router's Fully Qualified Domain Name (FQDN)
@@ -120,61 +120,61 @@ Response Structure
.. seealso:: :ref:`health-proto`
-:contentServers: An object containing keys which are the (short) hostnames of the Edge-Tier cache servers in the CDN; the values corresponding to those keys are routing information for said servers
+:contentServers: An object containing keys which are the (short) hostnames of the Edge-Tier :term:`cache server` s in the CDN; the values corresponding to those keys are routing information for said servers
:cacheGroup: The name of the Cache Group to which the server belongs
- :deliveryServices: An object containing keys which are the names of Delivery Services to which this cache server is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this cache server
+ :deliveryServices: An object containing keys which are the names of :term:`Delivery Service`\ s to which this :term:`cache server` is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this :term:`cache server`
- .. note:: Only Edge-tier cache servers can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``.
+ .. note:: Only Edge-tier :term:`cache server` s can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``.
:fqdn: The server's Fully Qualified Domain Name (FQDN)
:hashCount: The number of servers to be placed into a single "hash ring" in Traffic Router
:hashId: A unique string to be used as the key for hashing servers - as of version 3.0.0 of Traffic Control, this is always the same as the server's (short) hostname and only still exists for legacy compatibility reasons
- :httpsPort: The port on which the cache server listens for incoming HTTPS requests
- :interfaceName: The name of the main network interface device used by this cache server
+ :httpsPort: The port on which the :term:`cache server` listens for incoming HTTPS requests
+ :interfaceName: The name of the main network interface device used by this :term:`cache server`
:ip6: The server's IPv6 address
:ip: The server's IPv4 address
:locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons
- :port: The port on which this cache server listens for incoming HTTP requests
- :profile: The name of the profile used by the cache server
- :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this cache server; one of:
+ :port: The port on which this :term:`cache server` listens for incoming HTTP requests
+ :profile: The name of the profile used by the :term:`cache server`
+ :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this :term:`cache server`; one of:
0
Do not route traffic to this server
1
Route traffic to this server normally
- :status: This cache server's status
+ :status: This :term:`cache server`'s status
.. seealso:: :ref:`health-proto`
- :type: The type of this cache server; one of:
+ :type: The type of this :term:`cache server`; one of:
EDGE
- This is an Edge-tier cache server
+ This is an Edge-tier :term:`cache server`
MID
- This is a Mid-tier cache server
+ This is a Mid-tier :term:`cache server`
-:deliveryServices: An object containing keys which are the 'xml_id's of all of the Delivery Services within the CDN
+:deliveryServices: An object containing keys which are the 'xml_id's of all of the :term:`Delivery Service`\ s within the CDN
- :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this Delivery Service; one of:
+ :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this :term:`Delivery Service`; one of:
"true"
- Anonymized IP addresses are blocked by this Delivery Service
+ Anonymized IP addresses are blocked by this :term:`Delivery Service`
"false"
- Anonymized IP addresses are not blocked by this Delivery Service
+ Anonymized IP addresses are not blocked by this :term:`Delivery Service`
.. seealso:: :ref:`anonymous_blocking-qht`
- :coverageZoneOnly: A string containing a boolean that tells whether or not this Delivery Service routes traffic based only on its Coverage Zone file
- :deepCachingType: A string that tells when Deep Caching is used by this Delivery Service; one of:
+ :coverageZoneOnly: A string containing a boolean that tells whether or not this :term:`Delivery Service` routes traffic based only on its Coverage Zone file
+ :deepCachingType: A string that tells when Deep Caching is used by this :term:`Delivery Service`; one of:
"ALWAYS"
- Deep Caching is always used by this Delivery Service
+ Deep Caching is always used by this :term:`Delivery Service`
"NEVER"
- Deep Caching is never used by this Delivery Service
+ Deep Caching is never used by this :term:`Delivery Service`
- :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the Delivery Service
+ :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the :term:`Delivery Service`
:limit: The maximum number of caches in which the response to a single request URL will be stored
@@ -187,38 +187,38 @@ Response Structure
"true"
Caches will be chosen at random
- :domains: An array of domains served by this Delivery Service
+ :domains: An array of domains served by this :term:`Delivery Service`
:geolocationProvider: The name of a provider for IP-to-geographic-location mapping services - currently the only valid value is ``"maxmindGeolocationService"``
- :ip6RoutingEnabled: A string containing a boolean that tells whether IPv6 traffic can be routed on this Delivery Service; one of:
+ :ip6RoutingEnabled: A string containing a boolean that tells whether IPv6 traffic can be routed on this :term:`Delivery Service`; one of:
"false"
- IPv6 traffic will not be routed by this Delivery Service
+ IPv6 traffic will not be routed by this :term:`Delivery Service`
"true"
- IPv6 traffic will be routed by this Delivery Service
+ IPv6 traffic will be routed by this :term:`Delivery Service`
- :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+ :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
:missLocation: An object representing the default geographic coordinates to use for a client when lookup of their IP has failed in both the Coverage Zone file(s) and the IP-to-geographic-location database
:lat: Geographic latitude
:long: Geographic longitude
- :protocol: An object that describes how the Delivery Service ought to handle HTTP requests both with and without TLS encryption
+ :protocol: An object that describes how the :term:`Delivery Service` ought to handle HTTP requests both with and without TLS encryption
- :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this Delivery Service; one of:
+ :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this :term:`Delivery Service`; one of:
"false"
Refuse to service HTTPS requests
@@ -232,17 +232,17 @@ Response Structure
"true"
Respond to HTTP requests with instructions to use HTTPS instead
- :regionalGeoBlocking: A string containing a boolean that tells whether Regional Geographic Blocking is enabled on this Delivery Service; one of:
+ :regionalGeoBlocking: A string containing a boolean that tells whether Regional Geographic Blocking is enabled on this :term:`Delivery Service`; one of:
"false"
- Regional Geographic Blocking is not used by this Delivery Service
+ Regional Geographic Blocking is not used by this :term:`Delivery Service`
"true"
- Regional Geographic Blocking is used by this Delivery Service
+ Regional Geographic Blocking is used by this :term:`Delivery Service`
.. seealso:: :ref:`regionalgeo-qht`
- :routingName: The highest-level part of the FQDNs serviced by this Delivery Service
- :soa: An object defining the Start of Authority (SOA) record for the Delivery Service's TLDs (defined in ``domains``)
+ :routingName: The highest-level part of the FQDNs serviced by this :term:`Delivery Service`
+ :soa: An object defining the Start of Authority (SOA) record for the :term:`Delivery Service`'s TLDs (defined in ``domains``)
:admin: The name of the administrator for this zone - i.e. the RNAME
@@ -257,12 +257,12 @@ Response Structure
.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
- :sslEnabled: A string containing a boolean that tells whether this Delivery Service uses SSL; one of:
+ :sslEnabled: A string containing a boolean that tells whether this :term:`Delivery Service` uses SSL; one of:
"false"
- SSL is not used by this Delivery Service
+ SSL is not used by this :term:`Delivery Service`
"true"
- SSL is used by this Delivery Service
+ SSL is used by this :term:`Delivery Service`
:ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid
@@ -537,4 +537,4 @@ Response Structure
}
}}
-.. [1] These only apply to HTTP-routed Delivery Services
+.. [1] These only apply to HTTP-routed :term:`Delivery Service`\ s
diff --git a/docs/source/api/cdns_name_snapshot_new.rst b/docs/source/api/cdns_name_snapshot_new.rst
index d981f3c..486510b 100644
--- a/docs/source/api/cdns_name_snapshot_new.rst
+++ b/docs/source/api/cdns_name_snapshot_new.rst
@@ -105,7 +105,7 @@ Response Structure
:zonemanager.cache.maintenance.interval: A configuration option for the ZoneManager Java class of Traffic Router
:zonemanager.threadpool.scale: A configuration option for the ZoneManager Java class of Traffic Router
-:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for Delivery Services in this CDN
+:contentRouters: An object containing keys which are the (short) hostnames of the Traffic Routers that serve requests for :term:`Delivery Service`\ s in this CDN
:api.port: A string containing the port number on which the :ref:`tr-api` is served by this Traffic Router
:fqdn: This Traffic Router's Fully Qualified Domain Name (FQDN)
@@ -119,61 +119,61 @@ Response Structure
.. seealso:: :ref:`health-proto`
-:contentServers: An object containing keys which are the (short) hostnames of the Edge-Tier cache servers in the CDN; the values corresponding to those keys are routing information for said servers
+:contentServers: An object containing keys which are the (short) hostnames of the Edge-Tier :term:`cache server` s in the CDN; the values corresponding to those keys are routing information for said servers
:cacheGroup: The name of the Cache Group to which the server belongs
- :deliveryServices: An object containing keys which are the names of Delivery Services to which this cache server is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this cache server
+ :deliveryServices: An object containing keys which are the names of :term:`Delivery Service`\ s to which this :term:`cache server` is assigned; the values corresponding to those keys are arrays of FQDNs that resolve to this :term:`cache server`
- .. note:: Only Edge-tier cache servers can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``.
+ .. note:: Only Edge-tier :term:`cache server` s can be assigned to a Delivery SErvice, and therefore this field will only be present when ``type`` is ``"EDGE"``.
:fqdn: The server's Fully Qualified Domain Name (FQDN)
:hashCount: The number of servers to be placed into a single "hash ring" in Traffic Router
:hashId: A unique string to be used as the key for hashing servers - as of version 3.0.0 of Traffic Control, this is always the same as the server's (short) hostname and only still exists for legacy compatibility reasons
- :httpsPort: The port on which the cache server listens for incoming HTTPS requests
- :interfaceName: The name of the main network interface device used by this cache server
+ :httpsPort: The port on which the :term:`cache server` listens for incoming HTTPS requests
+ :interfaceName: The name of the main network interface device used by this :term:`cache server`
:ip6: The server's IPv6 address
:ip: The server's IPv4 address
:locationId: This field is exactly the same as ``cacheGroup`` and only exists for legacy compatibility reasons
- :port: The port on which this cache server listens for incoming HTTP requests
- :profile: The name of the profile used by the cache server
- :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this cache server; one of:
+ :port: The port on which this :term:`cache server` listens for incoming HTTP requests
+ :profile: The name of the profile used by the :term:`cache server`
+ :routingDisabled: An integer representing the boolean concept of whether or not Traffic Routers should route client traffic this :term:`cache server`; one of:
0
Do not route traffic to this server
1
Route traffic to this server normally
- :status: This cache server's status
+ :status: This :term:`cache server`'s status
.. seealso:: :ref:`health-proto`
- :type: The type of this cache server; one of:
+ :type: The type of this :term:`cache server`; one of:
EDGE
- This is an Edge-tier cache server
+ This is an Edge-tier :term:`cache server`
MID
- This is a Mid-tier cache server
+ This is a Mid-tier :term:`cache server`
-:deliveryServices: An object containing keys which are the 'xml_id's of all of the Delivery Services within the CDN
+:deliveryServices: An object containing keys which are the 'xml_id's of all of the :term:`Delivery Service`\ s within the CDN
- :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this Delivery Service; one of:
+ :anonymousBlockingEnabled: A string containing a boolean that tells whether or not Anonymized IP Addresses are blocked by this :term:`Delivery Service`; one of:
"true"
- Anonymized IP addresses are blocked by this Delivery Service
+ Anonymized IP addresses are blocked by this :term:`Delivery Service`
"false"
- Anonymized IP addresses are not blocked by this Delivery Service
+ Anonymized IP addresses are not blocked by this :term:`Delivery Service`
.. seealso:: :ref:`anonymous_blocking-qht`
- :coverageZoneOnly: A string containing a boolean that tells whether or not this Delivery Service routes traffic based only on its Coverage Zone file
- :deepCachingType: A string that tells when Deep Caching is used by this Delivery Service; one of:
+ :coverageZoneOnly: A string containing a boolean that tells whether or not this :term:`Delivery Service` routes traffic based only on its Coverage Zone file
+ :deepCachingType: A string that tells when Deep Caching is used by this :term:`Delivery Service`; one of:
"ALWAYS"
- Deep Caching is always used by this Delivery Service
+ Deep Caching is always used by this :term:`Delivery Service`
"NEVER"
- Deep Caching is never used by this Delivery Service
+ Deep Caching is never used by this :term:`Delivery Service`
- :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the Delivery Service
+ :dispersion: An object describing the "dispersion" - or number of caches within a single Cache Group across which the same content is spread - within the :term:`Delivery Service`
:limit: The maximum number of caches in which the response to a single request URL will be stored
@@ -186,38 +186,38 @@ Response Structure
"true"
Caches will be chosen at random
- :domains: An array of domains served by this Delivery Service
+ :domains: An array of domains served by this :term:`Delivery Service`
:geolocationProvider: The name of a provider for IP-to-geographic-location mapping services - currently the only valid value is ``"maxmindGeolocationService"``
- :ip6RoutingEnabled: A string containing a boolean that tells whether IPv6 traffic can be routed on this Delivery Service; one of:
+ :ip6RoutingEnabled: A string containing a boolean that tells whether IPv6 traffic can be routed on this :term:`Delivery Service`; one of:
"false"
- IPv6 traffic will not be routed by this Delivery Service
+ IPv6 traffic will not be routed by this :term:`Delivery Service`
"true"
- IPv6 traffic will be routed by this Delivery Service
+ IPv6 traffic will be routed by this :term:`Delivery Service`
- :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+ :matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
:missLocation: An object representing the default geographic coordinates to use for a client when lookup of their IP has failed in both the Coverage Zone file(s) and the IP-to-geographic-location database
:lat: Geographic latitude
:long: Geographic longitude
- :protocol: An object that describes how the Delivery Service ought to handle HTTP requests both with and without TLS encryption
+ :protocol: An object that describes how the :term:`Delivery Service` ought to handle HTTP requests both with and without TLS encryption
- :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this Delivery Service; one of:
+ :acceptHttps: A string containing a boolean that tells whether HTTPS requests should be normally serviced by this :term:`Delivery Service`; one of:
"false"
Refuse to service HTTPS requests
@@ -231,17 +231,17 @@ Response Structure
"true"
Respond to HTTP requests with instructions to use HTTPS instead
- :regionalGeoBlocking: A string containing a boolean that tells whether Regional Geographic Blocking is enabled on this Delivery Service; one of:
+ :regionalGeoBlocking: A string containing a boolean that tells whether Regional Geographic Blocking is enabled on this :term:`Delivery Service`; one of:
"false"
- Regional Geographic Blocking is not used by this Delivery Service
+ Regional Geographic Blocking is not used by this :term:`Delivery Service`
"true"
- Regional Geographic Blocking is used by this Delivery Service
+ Regional Geographic Blocking is used by this :term:`Delivery Service`
.. seealso:: :ref:`regionalgeo-qht`
- :routingName: The highest-level part of the FQDNs serviced by this Delivery Service
- :soa: An object defining the Start of Authority (SOA) record for the Delivery Service's TLDs (defined in ``domains``)
+ :routingName: The highest-level part of the FQDNs serviced by this :term:`Delivery Service`
+ :soa: An object defining the Start of Authority (SOA) record for the :term:`Delivery Service`'s TLDs (defined in ``domains``)
:admin: The name of the administrator for this zone - i.e. the RNAME
@@ -256,12 +256,12 @@ Response Structure
.. seealso:: `The Wikipedia page on Start of Authority records <https://en.wikipedia.org/wiki/SOA_record>`_.
- :sslEnabled: A string containing a boolean that tells whether this Delivery Service uses SSL; one of:
+ :sslEnabled: A string containing a boolean that tells whether this :term:`Delivery Service` uses SSL; one of:
"false"
- SSL is not used by this Delivery Service
+ SSL is not used by this :term:`Delivery Service`
"true"
- SSL is used by this Delivery Service
+ SSL is used by this :term:`Delivery Service`
:ttls: An object that contains keys which are types of DNS records that have values which are strings containing integers that specify the time for which a response to the specific type of record request should remain valid
@@ -540,4 +540,4 @@ Response Structure
}
}}
-.. [1] These only apply to HTTP-routed Delivery Services
+.. [1] These only apply to HTTP-routed :term:`Delivery Service`\ s
diff --git a/docs/source/api/deliveryservice_server_dsid_serverid.rst b/docs/source/api/deliveryservice_server_dsid_serverid.rst
index f8b60eb..1edf16f 100644
--- a/docs/source/api/deliveryservice_server_dsid_serverid.rst
+++ b/docs/source/api/deliveryservice_server_dsid_serverid.rst
@@ -21,7 +21,7 @@
``DELETE``
==========
-Removes a cache server from a Delivery Service.
+Removes a :term:`cache server` from a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -31,15 +31,15 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +----------+----------+-------------------------------------------------------+
- | Name | Required | Description |
- +==========+==========+=======================================================+
- | dsId | yes | An integral, unique identifier for a Delivery Service |
- +----------+----------+-------------------------------------------------------+
- | serverID | yes | An integral, unique identifier for a server |
- +----------+----------+-------------------------------------------------------+
+ +----------+----------+---------------------------------------------------------------+
+ | Name | Required | Description |
+ +==========+==========+===============================================================+
+ | dsId | yes | An integral, unique identifier for a :term:`Delivery Service` |
+ +----------+----------+---------------------------------------------------------------+
+ | serverID | yes | An integral, unique identifier for a server |
+ +----------+----------+---------------------------------------------------------------+
-.. note:: The server identified by ``serverID`` must be a cache server, or the assignment will fail.
+.. note:: The server identified by ``serverID`` must be a :term:`cache server`, or the assignment will fail.
Response Structure
------------------
@@ -65,4 +65,4 @@ Response Structure
}
]}
-.. [1] Users with the "admin" or "operations" roles will be able to delete *any* Delivery Service, whereas other users will only be able to delete Delivery Services that their tenant has permissions to delete.
+.. [1] Users with the "admin" or "operations" roles will be able to delete *any*:term:`Delivery Service`, whereas other users will only be able to delete :term:`Delivery Service`\ s that their tenant has permissions to delete.
diff --git a/docs/source/api/deliveryservice_stats.rst b/docs/source/api/deliveryservice_stats.rst
index 501f17c..1bb265b 100644
--- a/docs/source/api/deliveryservice_stats.rst
+++ b/docs/source/api/deliveryservice_stats.rst
@@ -27,7 +27,7 @@
``GET``
=======
-Retrieves time-aggregated statistics on a specific Delivery Service.
+Retrieves time-aggregated statistics on a specific :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None
@@ -40,20 +40,20 @@ Request Structure
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
| Name | Required | Description |
+======================+==========+====================================================================================================================+
- | deliveryServiceName | yes | The name of the Delivery Service for which statistics will be aggregated |
+ | deliveryServiceName | yes | The name of the :term:`Delivery Service` for which statistics will be aggregated |
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------+
| metricType | yes | The metric type being reported - one of: |
| | | |
| | | kbps |
- | | | The total traffic rate in kilobytes per second served by the Delivery Service |
+ | | | The total traffic rate in kilobytes per second served by the :term:`Delivery Service` |
| | | out_bytes |
- | | | The total number of bytes sent out to clients through the Delivery Service |
+ | | | The total number of bytes sent out to clients through the :term:`Delivery Service` |
| | | status_4xx |
| | | The amount of requests that were serviced with 400-499 HTTP status codes |
| | | status_5xx |
| | | The amount of requests that were serviced with 500-599 HTTP status codes |
| | | tps_total |
- | | | The total traffic rate in transactions per second served by the Delivery Service |
+ | | | The total traffic rate in transactions per second served by the :term:`Delivery Service` |
| | | tps_2xx |
| | | The total traffic rate in transactions per second serviced with 200-299 HTTP status codes |
| | | tps_3xx |
diff --git a/docs/source/api/deliveryservice_user.rst b/docs/source/api/deliveryservice_user.rst
index bfa908a..fe1e2a9 100644
--- a/docs/source/api/deliveryservice_user.rst
+++ b/docs/source/api/deliveryservice_user.rst
@@ -21,7 +21,7 @@
``POST``
========
-Assigns one or more Delivery Services to a user.
+Assigns one or more :term:`Delivery Service`\ s to a user.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -29,8 +29,8 @@ Assigns one or more Delivery Services to a user.
Request Structure
-----------------
-:userId: An integral, unique identifier for the user to whom the Delivery Service(s) identified in ``deliveryServices`` will be assigned
-:deliveryServices: An array of integral, unique identifiers for the Delivery Service(s) being assigned to the user identified by ``userId``
+:userId: An integral, unique identifier for the user to whom the :term:`Delivery Service`\ (s) identified in ``deliveryServices`` will be assigned
+:deliveryServices: An array of integral, unique identifiers for the :term:`Delivery Service`\ (s) being assigned to the user identified by ``userId``
:replace: An optional field which, when present and ``true`` will replace existing user/ds assignments? (true|false)
.. code-block:: http
@@ -48,9 +48,9 @@ Request Structure
Response Structure
------------------
-:userId: The integral, unique identifier of the user to whom the Delivery Service(s) identified in ``deliveryServices`` are assigned
-:deliveryServices: An array of integral, unique identifiers of Delivery Services assigned to the user identified by ``userId``
-:replace: If ``true``, any and all existing, conflicting Delivery Service assignments were overwritten by this assignment operation
+:userId: The integral, unique identifier of the user to whom the :term:`Delivery Service`\ (s) identified in ``deliveryServices`` are assigned
+:deliveryServices: An array of integral, unique identifiers of :term:`Delivery Service`\ s assigned to the user identified by ``userId``
+:replace: If ``true``, any and all existing, conflicting :term:`Delivery Service` assignments were overwritten by this assignment operation
.. code-block:: http
:caption: Response Example
diff --git a/docs/source/api/deliveryservice_user_dsid_userid.rst b/docs/source/api/deliveryservice_user_dsid_userid.rst
index 0fbec63..b5e1e3d 100644
--- a/docs/source/api/deliveryservice_user_dsid_userid.rst
+++ b/docs/source/api/deliveryservice_user_dsid_userid.rst
@@ -21,7 +21,7 @@
``DELETE``
==========
-Removes a Delivery Service from a user.
+Removes a :term:`Delivery Service` from a user.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -31,13 +31,13 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +--------+---------------------------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +========+=================================================================================================================================+
- | dsId | An integral, unique identifier for the Delivery Service which should no longer be assigned to the user identified by ``userID`` |
- +--------+---------------------------------------------------------------------------------------------------------------------------------+
- | userId | An integral, unique identifier for the user to whom the Delivery Service identified by ``dsID`` should no longer be assigned |
- +--------+---------------------------------------------------------------------------------------------------------------------------------+
+ +--------+-----------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +========+=========================================================================================================================================+
+ | dsId | An integral, unique identifier for the :term:`Delivery Service` which should no longer be assigned to the user identified by ``userID`` |
+ +--------+-----------------------------------------------------------------------------------------------------------------------------------------+
+ | userId | An integral, unique identifier for the user to whom the :term:`Delivery Service` identified by ``dsID`` should no longer be assigned |
+ +--------+-----------------------------------------------------------------------------------------------------------------------------------------+
Response Structure
------------------
diff --git a/docs/source/api/deliveryservices.rst b/docs/source/api/deliveryservices.rst
index 7ed7e7b..3eb804e 100644
--- a/docs/source/api/deliveryservices.rst
+++ b/docs/source/api/deliveryservices.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves all Delivery Services
+Retrieves all :term:`Delivery Service`\ s
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -31,43 +31,43 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description |
- +=============+==========+============================================================================================================================+
- | cdn | no | Show only the Delivery Services belonging to the CDN identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | id | no | Show only the Delivery Service that has this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | logsEnabled | no | If true, return only Delivery Services with logging enabled, otherwise return only Delivery Services with logging disabled |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | profile | no | Return only Delivery Services using the profile identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | tenant | no | Show only the Delivery Services belonging to the tenant identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | type | no | Return only Delivery Services of the Delivery Service type identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=============+==========+================================================================================================================================================+
+ | cdn | no | Show only the :term:`Delivery Service`\ s belonging to the CDN identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | id | no | Show only the :term:`Delivery Service` that has this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | logsEnabled | no | If true, return only :term:`Delivery Service`\ s with logging enabled, otherwise return only :term:`Delivery Service`\ s with logging disabled |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | profile | no | Return only :term:`Delivery Service`\ s using the :term:`Profile` identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | tenant | no | Show only the :term:`Delivery Service`\ s belonging to the :term:`Tenant` identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only :term:`Delivery Service`\ s of the :term:`Delivery Service` type identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
Response Structure
------------------
-:active: ``true`` if the Delivery Service is active, ``false`` otherwise
-:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:active: ``true`` if the :term:`Delivery Service` is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the :term:`Delivery Service`, ``false`` otherwise
:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
-:cdnName: Name of the CDN to which the Delivery Service belongs
-:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
-:displayName: The display name of the Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [4]_
+:cdnId: The integral, unique identifier of the CDN to which the :term:`Delivery Service` belongs
+:cdnName: Name of the CDN to which the :term:`Delivery Service` belongs
+:checkPath: The path portion of the URL to check connections to this :term:`Delivery Service`'s origin server
+:displayName: The display name of the :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active\ [4]_
:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see ``man tc-fc_codel`` for more information) - Linux only
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
0
@@ -79,7 +79,7 @@ Response Structure
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
@@ -88,47 +88,47 @@ Response Structure
1
Neustar
-:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
-:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:id: An integral, unique identifier for this Delivery Service
-:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:globalMaxMbps: The maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: The maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS :term:`Delivery Service`\ s and to the httpBypassFqdn for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:id: An integral, unique identifier for this :term:`Delivery Service`
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_
:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
-:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: A description of the Delivery Service
+:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: A description of the :term:`Delivery Service`
:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
-:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
:maxDnsAnswers: The maximum number of IPs to put in responses to A/AAAA DNS record requests (0 means all available)\ [4]_
:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
-:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [3]_
+:orgServerFqdn: The URL of the :term:`Delivery Service`'s origin server for use in retrieving content from the origin server
.. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
-:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
-:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
-:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+:profileDescription: The description of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this :term:`Delivery Service` is associated
+:profileName: The name of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server` s\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
0
HTTP
@@ -155,37 +155,37 @@ Response Structure
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: A regular expression remap rule to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
:remapText: Additional, raw text to add to the remap line for caches
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signed: ``true`` if token-based authentication is enabled for this :term:`Delivery Service`, ``false`` otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
-:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This integer indicates the generation of keys in use by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:tenantId: The integral, unique identifier of the tenant who owns this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
-:type: The name of the routing type of this Delivery Service e.g. "HTTP"
-:typeId: The integral, unique identifier of the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:type: The name of the routing type of this :term:`Delivery Service` e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons
.. code-block:: http
:caption: Response Example
@@ -272,14 +272,14 @@ Response Structure
"tenant": "root"
}]}
-.. [1] Users with the roles "admin" and/or "operations" will be able to see *all* Delivery Services, whereas any other user will only see the Delivery Services their Tenant is allowed to see.
-.. [2] This only applies to HTTP-routed Delivery Services
+.. [1] Users with the roles "admin" and/or "operations" will be able to see *all* :term:`Delivery Service`\ s, whereas any other user will only see the :term:`Delivery Service`\ s their Tenant is allowed to see.
+.. [2] This only applies to HTTP-routed :term:`Delivery Service`\ s
.. [3] See :ref:`multi-site-origin`
-.. [4] This only applies to DNS-routed Delivery Services
+.. [4] This only applies to DNS-routed :term:`Delivery Service`\ s
``POST``
========
-Allows users to create Delivery Service.
+Allows users to create :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -287,31 +287,31 @@ Allows users to create Delivery Service.
Request Structure
-----------------
-:active: If ``true``, the Delivery Service will immediately become active and serves traffic
-:anonymousBlockingEnabled: An optional field which, if defined and ``true`` will cause :ref:`Anonymous Blocking <anonymous_blocking-qht>` to be used with the new Delivery Service
+:active: If ``true``, the :term:`Delivery Service` will immediately become active and serves traffic
+:anonymousBlockingEnabled: An optional field which, if defined and ``true`` will cause :ref:`Anonymous Blocking <anonymous_blocking-qht>` to be used with the new :term:`Delivery Service`
:cacheurl: An optional setting for a deprecated feature of now-unsupported Trafficserver versions (read: "Don't use this")
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
:ccrDnsTtl: The Time To Live (TTL) in seconds of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier for the CDN to which this Delivery Service shall be assigned
-:checkPath: The path portion of the URL which will be used to check connections to this Delivery Service's origin server
-:deepCachingType: A string describing when to do Deep Caching for this Delivery Service:
+:cdnId: The integral, unique identifier for the CDN to which this :term:`Delivery Service`\ shall be assigned
+:checkPath: The path portion of the URL which will be used to check connections to this :term:`Delivery Service`'s origin server
+:deepCachingType: A string describing when to do Deep Caching for this :term:`Delivery Service`:
NEVER
- Deep Caching will never be used by this Delivery Service (default)
+ Deep Caching will never be used by this :term:`Delivery Service` (default)
ALWAYS
- Deep Caching will always be used by this Delivery Service
+ Deep Caching will always be used by this :term:`Delivery Service`
-:displayName: The human-friendly name for this Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active
+:displayName: The human-friendly name for this :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active
:dscp: The Differentiated Services Code Point (DSCP) with which to mark downstream (EDGE -> customer) traffic. This should be zero in most cases
:edgeHeaderRewrite: An optional string which, if present, defines rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: An optional integer which, if present, sets the Fair-Queuing Pacing Rate in bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only, defaults to 0 meaning "disabled"
+:fqPacingRate: An optional integer which, if present, sets the Fair-Queuing Pacing Rate in bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see ``man tc-fc_codel`` for more information) - Linux only, defaults to 0 meaning "disabled"
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
0
@@ -323,7 +323,7 @@ Request Structure
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service\ [5]_
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`\ [5]_
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed\ [5]_
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
@@ -332,28 +332,28 @@ Request Structure
1
Neustar
-:globalMaxMbps: An optional integer that will set the maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: An optional integer that will set the maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBpassIp`` (and/or ``dnsBypassIp6``)for DNS Delivery Services and to the ``httpBypassFqdn`` for HTTP Delivery Services
-:httpBypassFqdn: An optional Fully Qualified Domain Name (FQDN) to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [2]_
-:infoUrl: An optional string which, if present, is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:globalMaxMbps: An optional integer that will set the maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: An optional integer that will set the maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the ``dnsBpassIp`` (and/or ``dnsBypassIp6``)for DNS :term:`Delivery Service`\ s and to the ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: An optional Fully Qualified Domain Name (FQDN) to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [2]_
+:infoUrl: An optional string which, if present, is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_\ [6]_
-:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection - optional for ANY_MAP Delivery Services
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: An optional description of the Delivery Service
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection - optional for ANY_MAP :term:`Delivery Service`\ s
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: An optional description of the :term:`Delivery Service`
:longDesc1: An optional field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: An optional field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
:maxDnsAnswers: An optional field which, when present, specifies the maximum number of IPs to put in responses to A/AAAA DNS record requests - defaults to 0, meaning "no limit"\ [4]_
:midHeaderRewrite: An optional string containing rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_\ [7]_
-:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server\ [7]_
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [3]_\ [7]_
+:orgServerFqdn: The URL of the :term:`Delivery Service`'s origin server for use in retrieving content from the origin server\ [7]_
.. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This optional field is a string of FQDNs to use as origin shields, delimited by ``|``
-:profileId: An optional, integral, unique identifier for the Traffic Router profile with which this Delivery Service shall be associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers - this is an (optional for ANY_MAP Delivery Services) integer on the interval [0,2] where the values have these meanings:
+:profileId: An optional, integral, unique identifier for the Traffic Router profile with which this :term:`Delivery Service`\ shall be associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server` s - this is an (optional for ANY_MAP :term:`Delivery Service`\ s) integer on the interval [0,2] where the values have these meanings:
0
HTTP
@@ -380,39 +380,39 @@ Request Structure
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: An optional, regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: An optional, regular expression remap rule to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
:remapText: Optional, raw text to add to the remap line for caches
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:routingName: The routing name of this Delivery Service, used as the top-level part of the FQDN used by clients to request content from the Delivery Service e.g. ``routingName.xml_id.CDNName.com``
-:signed: An optional field which should be ``true`` if token-based authentication will be enabled for this Delivery Service, ``false`` (default) otherwise
+:routingName: The routing name of this :term:`Delivery Service`, used as the top-level part of the FQDN used by clients to request content from the :term:`Delivery Service` e.g. ``routingName.xml_id.CDNName.com``
+:signed: An optional field which should be ``true`` if token-based authentication will be enabled for this :term:`Delivery Service`, ``false`` (default) otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
-:sslKeyVersion: This optional integer indicates the generation of keys to be used by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This optional integer indicates the generation of keys to be used by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenantId: An optional, integral, unique identifier of the tenant who will own this Delivery Service
+:tenantId: An optional, integral, unique identifier of the tenant who will own this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
-:typeId: The integral, unique identifier for the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:typeId: The integral, unique identifier for the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons
- .. note:: This should almost never be different from the Delivery Service's ``displayName``
+ .. note:: This should almost never be different from the :term:`Delivery Service`'s ``displayName``
.. code-block:: http
@@ -443,7 +443,7 @@ Request Structure
"ipv6RoutingEnabled": false,
"lastUpdated": "2018-11-14 18:21:17+00",
"logsEnabled": true,
- "longDesc": "A Delivery Service created expressly for API documentation examples",
+ "longDesc": "A :term:`Delivery Service` created expressly for API documentation examples",
"missLat": -1,
"missLong": -1,
"multiSiteOrigin": false,
@@ -461,30 +461,30 @@ Request Structure
}
.. [5] These fields must be defined if and only if ``geoLimit`` is non-zero
-.. [6] These fields are required for HTTP-routed Delivery Services, and optional for all others
-.. [7] These fields are required for HTTP-routed and DNS-routed Delivery Services, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP Delivery Services
+.. [6] These fields are required for HTTP-routed :term:`Delivery Service`\ s, and optional for all others
+.. [7] These fields are required for HTTP-routed and DNS-routed :term:`Delivery Service`\ s, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP :term:`Delivery Service`\ s
Response Structure
------------------
-:active: ``true`` if the Delivery Service is active, ``false`` otherwise
-:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:active: ``true`` if the :term:`Delivery Service` is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the :term:`Delivery Service`, ``false`` otherwise
:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
-:cdnName: Name of the CDN to which the Delivery Service belongs
-:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
-:displayName: The display name of the Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [4]_
+:cdnId: The integral, unique identifier of the CDN to which the :term:`Delivery Service` belongs
+:cdnName: Name of the CDN to which the :term:`Delivery Service` belongs
+:checkPath: The path portion of the URL to check connections to this :term:`Delivery Service`'s origin server
+:displayName: The display name of the :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active\ [4]_
:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see ``man tc-fc_codel`` for more information) - Linux only
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
0
@@ -496,7 +496,7 @@ Response Structure
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
@@ -505,47 +505,47 @@ Response Structure
1
Neustar
-:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
-:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:id: An integral, unique identifier for this Delivery Service
-:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:globalMaxMbps: The maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: The maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS :term:`Delivery Service`\ s and to the httpBypassFqdn for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:id: An integral, unique identifier for this :term:`Delivery Service`
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_
:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
-:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: A description of the Delivery Service
+:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: A description of the :term:`Delivery Service`
:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
-:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
:maxDnsAnswers: The maximum number of IPs to put in responses to A/AAAA DNS record requests (0 means all available)\ [4]_
:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
-:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [3]_
+:orgServerFqdn: The URL of the :term:`Delivery Service`'s origin server for use in retrieving content from the origin server
.. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
-:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
-:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
-:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+:profileDescription: The description of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this :term:`Delivery Service` is associated
+:profileName: The name of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server` s\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
0
HTTP
@@ -572,37 +572,37 @@ Response Structure
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: A regular expression remap rule to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
:remapText: Additional, raw text to add to the remap line for caches
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signed: ``true`` if token-based authentication is enabled for this :term:`Delivery Service`, ``false`` otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
-:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This integer indicates the generation of keys in use by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:tenantId: The integral, unique identifier of the tenant who owns this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
-:type: The name of the routing type of this Delivery Service e.g. "HTTP"
-:typeId: The integral, unique identifier of the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:type: The name of the routing type of this :term:`Delivery Service` e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons
.. code-block:: http
:caption: Response Example
@@ -654,7 +654,7 @@ Response Structure
"ipv6RoutingEnabled": false,
"lastUpdated": "2018-11-19 19:45:49+00",
"logsEnabled": true,
- "longDesc": "A Delivery Service created expressly for API documentation examples",
+ "longDesc": "A :term:`Delivery Service` created expressly for API documentation examples",
"longDesc1": null,
"longDesc2": null,
"matchList": [
diff --git a/docs/source/api/deliveryservices_dnsseckeys_generate.rst b/docs/source/api/deliveryservices_dnsseckeys_generate.rst
index 797cf3e..583ff2b 100644
--- a/docs/source/api/deliveryservices_dnsseckeys_generate.rst
+++ b/docs/source/api/deliveryservices_dnsseckeys_generate.rst
@@ -21,7 +21,7 @@
``POST``
========
-Generates Zone-Signing Key (ZSK) and Key-Signing Key (KSK) keypairs for a CDN and all associated Delivery Services.
+Generates Zone-Signing Key (ZSK) and Key-Signing Key (KSK) keypairs for a CDN and all associated :term:`Delivery Service`\ s.
:Auth. Required: Yes
:Roles Required: "admin"
diff --git a/docs/source/api/deliveryservices_hostname_name_sslkeys.rst b/docs/source/api/deliveryservices_hostname_name_sslkeys.rst
index 4c48b88..72141c5 100644
--- a/docs/source/api/deliveryservices_hostname_name_sslkeys.rst
+++ b/docs/source/api/deliveryservices_hostname_name_sslkeys.rst
@@ -29,11 +29,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+----------------------------------------------+
- | Name | Description |
- +======+==============================================+
- | name | The hostname of the desired Delivery Service |
- +------+----------------------------------------------+
+ +------+--------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+====================================================================================================================+
+ | name | The hostname of the desired :term:`Delivery Service` - has the form ``{{routing name}}.{{xml_id}}.{{CDN domain}}`` |
+ +------+--------------------------------------------------------------------------------------------------------------------+
.. table:: Request Query Parameters
@@ -43,47 +43,64 @@ Request Structure
| version | no | The version number of SSL keys which shall be retrieved |
+---------+----------+---------------------------------------------------------+
+.. code-block:: http
+ :caption: Request Example
+
+GET /api/1.4/deliveryservices/hostname/video.demo1.mycdn.ciab.test/sslkeys HTTP/1.1
+Host: trafficops.infra.ciab.test
+User-Agent: curl/7.47.0
+Accept: */*
+Cookie: mojolicious=...
+
Response Structure
------------------
:businessUnit: An optional field which, if present, contains the business unit entered by the user when generating the SSL certificate\ [1]_
:certificate: An object containing the actual generated key, certificate, and signature of the SSL keys
- :crt: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) certificate for the Delivery Service identified by ``deliveryservice``
- :csr: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) csr file for the Delivery Service identified by ``deliveryservice``
- :key: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) private key for the Delivery Service identified by ``deliveryservice``
+ :crt: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) certificate for the :term:`Delivery Service` identified by ``deliveryservice``
+ :csr: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) csr file for the :term:`Delivery Service` identified by ``deliveryservice``
+ :key: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) private key for the :term:`Delivery Service` identified by ``deliveryservice``
.. caution:: There's almost certainly no good reason to request the private key! Even when "base 64-encoded" do not let **ANYONE** see this who would be unable to request it themselves!
-:cdn: The CDN of the Delivery Service for which the certs were generated
+:cdn: The CDN of the :term:`Delivery Service` for which the certs were generated
:city: An optional field which, if present, contains the city entered by the user when generating the SSL certificate\ [1]_
:country: An optional field which, if present, contains the country entered by the user when generating the SSL certificate\ [1]_
-:deliveryservice: The 'xml_id' of the Delivery Service for which the certificate was generated
-:hostname: The hostname generated by Traffic Ops that is used as the common name when generating the certificate - this will be a Fully Qualified Domain Name (FQDN) for DNS Delivery Services and a wildcard URL for HTTP Delivery Services
+:deliveryservice: The 'xml_id' of the :term:`Delivery Service` for which the certificate was generated
+:hostname: The hostname generated by Traffic Ops that is used as the common name when generating the certificate - this will be an :abbr:`FQDN (Fully Qualified Domain Name)` for DNS :term:`Delivery Service`\ s and a wildcard URL for HTTP :term:`Delivery Service`\ s
:organization: An optional field which, if present, contains the organization entered by the user when generating certificate\ [1]_
:state: An optional field which, if present, contains the state entered by the user when generating certificate\ [1]_
-:version: The version of the certificate record in Riak
+:version: The version of the certificate record in Traffic Vault
.. code- block:: http
:caption: Response Example
HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: eXZMeGFYSJgjg/rC1JtHpqMHNEvxGZwbKCXs5mOFF+oU74UXmRKl/2KF+kLyNfHGTScEZ07m/qqpwDLgvlGOEg==
+ X-Server-Name: traffic_ops_golang/
+ Date: Thu, 31 Jan 2019 19:44:21 GMT
+ Transfer-Encoding: chunked
{ "response": {
+ "cdn": "CDN-in-a-Box",
+ "deliveryservice": "demo1",
+ "hostname": "*.demo1.mycdn.ciab.test",
+ "key": "demo1",
+ "version": 1,
"certificate": {
- "crt": "crt",
- "key": "key",
- "csr": "csr"
- },
- "deliveryservice": "my-ds",
- "cdn": "qa",
- "businessUnit": "CDN_Eng",
- "city": "Denver",
- "organization": "KableTown",
- "hostname": "foober.com",
- "country": "US",
- "state": "Colorado",
- "version": "1"
+ "crt": "...",
+ "key": "...",
+ "csr": "..."
+ }
}}
+.. note:: The response example uses abbreviated values for the ``crt``, ``key``, and ``csr``, as these will generally be very large, base64-encoded SSL keys and certificates. Note that in general the output of this request should **not** be made available, as the ``key`` field contains the *private* SSL key corresponding to the certificate.
+
+
.. [1] These optional fields will be present in the response if and only if they were specified during key generation; they are optional during key generation and thus cannot be guaranteed to exist or not exist.
diff --git a/docs/source/api/deliveryservices_id.rst b/docs/source/api/deliveryservices_id.rst
index 1398a65..3f4f51b 100644
--- a/docs/source/api/deliveryservices_id.rst
+++ b/docs/source/api/deliveryservices_id.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves a specific Delivery Service
+Retrieves a specific :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -33,27 +33,27 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description |
- +=============+==========+============================================================================================================================+
- | cdn | no | Show only the Delivery Services belonging to the CDN identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | logsEnabled | no | If true, return only Delivery Services with logging enabled, otherwise return only Delivery Services with logging disabled |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | profile | no | Return only Delivery Services using the profile identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | tenant | no | Show only the Delivery Services belonging to the tenant identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
- | type | no | Return only Delivery Services of the Delivery Service type identified by this integral, unique identifier |
- +-------------+----------+----------------------------------------------------------------------------------------------------------------------------+
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=============+==========+================================================================================================================================================+
+ | cdn | no | Show only the :term:`Delivery Service`\ s belonging to the CDN identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | logsEnabled | no | If true, return only :term:`Delivery Service`\ s with logging enabled, otherwise return only :term:`Delivery Service`\ s with logging disabled |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | profile | no | Return only :term:`Delivery Service`\ s using the profile identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | tenant | no | Show only the :term:`Delivery Service`\ s belonging to the tenant identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only :term:`Delivery Service`\ s of the :term:`Delivery Service` type identified by this integral, unique identifier |
+ +-------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------+
.. table:: Request Path Parameters
- +------+----------------------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +======+============================================================================================================================+
- | ID | The integral, unique identifier of the Delivery Service to be retrieved |
- +------+----------------------------------------------------------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=================================================================================+
+ | ID | The integral, unique identifier of the :term:`Delivery Service` to be retrieved |
+ +------+---------------------------------------------------------------------------------+
Response Structure
@@ -61,90 +61,90 @@ Response Structure
.. versionchanged:: 1.3
Removed ``fqPacingRate`` field, added fields: ``deepCachingType``, ``signingAlgorithm``, and ``tenant``.
-:active: ``true`` if the Delivery Service is active, ``false`` otherwise
-:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:active: ``true`` if the :term:`Delivery Service` is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the :term:`Delivery Service`, ``false`` otherwise
:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
-:cdnName: Name of the CDN to which the Delivery Service belongs
-:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
-:deepCachingType: A string that describes when "Deep Caching" will be used by this Delivery Service - one of:
+:cdnId: The integral, unique identifier of the CDN to which the :term:`Delivery Service` belongs
+:cdnName: Name of the CDN to which the :term:`Delivery Service` belongs
+:checkPath: The path portion of the URL to check connections to this :term:`Delivery Service`'s origin server
+:deepCachingType: A string that describes when "Deep Caching" will be used by this :term:`Delivery Service` - one of:
ALWAYS
- "Deep Caching" will always be used with this Delivery Service
+ "Deep Caching" will always be used with this :term:`Delivery Service`
NEVER
- "Deep Caching" will never be used with this Delivery Service
+ "Deep Caching" will never be used with this :term:`Delivery Service`
.. versionadded:: 1.3
-:displayName: The display name of the Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active
-:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
-:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:displayName: The display name of the :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active
+:dscp: The :abbr:`FQDN (Differentiated Services Code Point)` with which to mark traffic as it leaves the CDN and reaches clients
+:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite :abbr:`ATS (Apache Traffic Server)` plugin
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see ``man tc-fc_codel`` for more information) - Linux only
.. deprecated:: 1.3
This field is only present/available in API versions 1.2 and lower - it has been removed in API version 1.3
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
0
None - no limitations
1
- Only route when the client's IP is found in the Coverage Zone File (CZF)
+ Only route when the client's IP is found in the :term:`Coverage Zone File`
2
- Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+ Only route when the client's IP is found in the :term:`Coverage Zone File`, or when the client can be determined to be from the United States of America
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only ``0`` - which represents MaxMind - is supported
-:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the dnsByPassIp* for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
-:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:id: An integral, unique identifier for this Delivery Service
-:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:globalMaxMbps: The maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: The maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the dnsByPassIp* for DNS :term:`Delivery Service`\ s and to the httpBypassFqdn for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:id: An integral, unique identifier for this :term:`Delivery Service`
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1
:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
-:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: A description of the Delivery Service
+:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: A description of the :term:`Delivery Service`
:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
-:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
-:maxDnsAnswers: The maximum number of IPs to put in a A/AAAA response for a DNS Delivery Service (0 means all available)
+:maxDnsAnswers: The maximum number of IPs to put in a A/AAAA response for a DNS :term:`Delivery Service` (0 means all available)
:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [3]_
:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
:orgServerFqdn: The origin server's Fully Qualified Domain Name (FQDN) - including the protocol (e.g. http:// or https://) - for use in retrieving content from the origin server
-:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
-:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
-:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+:profileDescription: The description of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this :term:`Delivery Service` is associated
+:profileName: The name of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server` s\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
0
HTTP
@@ -171,43 +171,43 @@ Response Structure
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: A regular expression remap rule to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
:remapText: Additional, raw text to add to the remap line for caches
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signed: ``true`` if token-based authentication is enabled for this :term:`Delivery Service`, ``false`` otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, NOT the latest.
.. versionadded:: 1.3
-:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This integer indicates the generation of keys in use by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenant: The name of the tenant who owns this Delivery Service
+:tenant: The name of the tenant who owns this :term:`Delivery Service`
.. versionadded:: 1.3
-:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:tenantId: The integral, unique identifier of the tenant who owns this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
-:type: The name of the routing type of this Delivery Service e.g. "HTTP"
-:typeId: The integral, unique identifier of the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:type: The name of the routing type of this :term:`Delivery Service` e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons
.. code-block:: http
:caption: Response Example
@@ -296,14 +296,14 @@ Response Structure
]}
-.. [1] Users with the roles "admin" and/or "operation" will be able to see *all* Delivery Services, whereas any other user will only see the Delivery Services their Tenant is allowed to see.
-.. [2] This only applies to HTTP Delivery Services
+.. [1] Users with the roles "admin" and/or "operation" will be able to see *all* :term:`Delivery Service`\ s, whereas any other user will only see the :term:`Delivery Service`\ s their Tenant is allowed to see.
+.. [2] This only applies to HTTP :term:`Delivery Service`\ s
.. [3] See :ref:`multi-site-origin`
-.. [4] This only applies to DNS-routed Delivery Services
+.. [4] This only applies to DNS-routed :term:`Delivery Service`\ s
``PUT``
=======
-Allows users to edit an existing Delivery Service.
+Allows users to edit an existing :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [10]_
@@ -311,31 +311,31 @@ Allows users to edit an existing Delivery Service.
Request Structure
-----------------
-:active: If ``true``, the Delivery Service will immediately become active and serves traffic
-:anonymousBlockingEnabled: An optional field which, if defined and ``true`` will cause :ref:`Anonymous Blocking <anonymous_blocking-qht>` to be used with the new Delivery Service
+:active: If ``true``, the :term:`Delivery Service` will immediately become active and serves traffic
+:anonymousBlockingEnabled: An optional field which, if defined and ``true`` will cause :ref:`Anonymous Blocking <anonymous_blocking-qht>` to be used with the new :term:`Delivery Service`
:cacheurl: An optional setting for a deprecated feature of now-unsupported Trafficserver versions (read: "Don't use this")
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
:ccrDnsTtl: The Time To Live (TTL) in seconds of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier for the CDN to which this Delivery Service shall be assigned
-:checkPath: The path portion of the URL which will be used to check connections to this Delivery Service's origin server
-:deepCachingType: A string describing when to do Deep Caching for this Delivery Service:
+:cdnId: The integral, unique identifier for the CDN to which this :term:`Delivery Service`\ shall be assigned
+:checkPath: The path portion of the URL which will be used to check connections to this :term:`Delivery Service`'s origin server
+:deepCachingType: A string describing when to do Deep Caching for this :term:`Delivery Service`:
NEVER
- Deep Caching will never be used by this Delivery Service (default)
+ Deep Caching will never be used by this :term:`Delivery Service` (default)
ALWAYS
- Deep Caching will always be used by this Delivery Service
+ Deep Caching will always be used by this :term:`Delivery Service`
-:displayName: The human-friendly name for this Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active
+:displayName: The human-friendly name for this :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active
:dscp: The Differentiated Services Code Point (DSCP) with which to mark downstream (EDGE -> customer) traffic. This should be zero in most cases
:edgeHeaderRewrite: An optional string which, if present, defines rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: An optional integer which, if present, sets the Fair-Queuing Pacing Rate in bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only, defaults to 0 meaning "disabled"
+:fqPacingRate: An optional integer which, if present, sets the Fair-Queuing Pacing Rate in bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see ``man tc-fc_codel`` for more information) - Linux only, defaults to 0 meaning "disabled"
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
0
@@ -347,7 +347,7 @@ Request Structure
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service\ [5]_
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`\ [5]_
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed\ [5]_
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
@@ -356,28 +356,28 @@ Request Structure
1
Neustar
-:globalMaxMbps: An optional integer that will set the maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: An optional integer that will set the maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBpassIp`` (and/or ``dnsBypassIp6``)for DNS Delivery Services and to the ``httpBypassFqdn`` for HTTP Delivery Services
-:httpBypassFqdn: An optional Fully Qualified Domain Name (FQDN) to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [2]_
-:infoUrl: An optional string which, if present, is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:globalMaxMbps: An optional integer that will set the maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: An optional integer that will set the maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the ``dnsBpassIp`` (and/or ``dnsBypassIp6``)for DNS :term:`Delivery Service`\ s and to the ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: An optional Fully Qualified Domain Name (FQDN) to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [2]_
+:infoUrl: An optional string which, if present, is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_\ [6]_
-:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection - optional for ANY_MAP Delivery Services
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: An optional description of the Delivery Service
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection - optional for ANY_MAP :term:`Delivery Service`\ s
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: An optional description of the :term:`Delivery Service`
:longDesc1: An optional field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: An optional field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
:maxDnsAnswers: An optional field which, when present, specifies the maximum number of IPs to put in responses to A/AAAA DNS record requests - defaults to 0, meaning "no limit"\ [4]_
:midHeaderRewrite: An optional string containing rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup\ [7]_
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_\ [7]_
-:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server\ [7]_
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [3]_\ [7]_
+:orgServerFqdn: The URL of the :term:`Delivery Service`'s origin server for use in retrieving content from the origin server\ [7]_
.. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This optional field is a string of FQDNs to use as origin shields, delimited by ``|``
-:profileId: An optional, integral, unique identifier for the Traffic Router profile with which this Delivery Service shall be associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers - this is an (optional for ANY_MAP Delivery Services) integer on the interval [0,2] where the values have these meanings:
+:profileId: An optional, integral, unique identifier for the Traffic Router profile with which this :term:`Delivery Service`\ shall be associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server` s - this is an (optional for ANY_MAP :term:`Delivery Service`\ s) integer on the interval [0,2] where the values have these meanings:
0
HTTP
@@ -404,39 +404,39 @@ Request Structure
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: An optional, regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: An optional, regular expression remap rule to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
:remapText: Optional, raw text to add to the remap line for caches
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:routingName: The routing name of this Delivery Service, used as the top-level part of the FQDN used by clients to request content from the Delivery Service e.g. ``routingName.xml_id.CDNName.com``
-:signed: An optional field which should be ``true`` if token-based authentication\ [8]_ will be enabled for this Delivery Service, ``false`` (default) otherwise
+:routingName: The routing name of this :term:`Delivery Service`, used as the top-level part of the FQDN used by clients to request content from the :term:`Delivery Service` e.g. ``routingName.xml_id.CDNName.com``
+:signed: An optional field which should be ``true`` if token-based authentication\ [8]_ will be enabled for this :term:`Delivery Service`, ``false`` (default) otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs\ [8]_, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
-:sslKeyVersion: This optional integer indicates the generation of keys to be used by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This optional integer indicates the generation of keys to be used by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenantId: An optional, integral, unique identifier of the tenant who will own this Delivery Service
+:tenantId: An optional, integral, unique identifier of the tenant who will own this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
-:typeId: The integral, unique identifier for the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:typeId: The integral, unique identifier for the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons
- .. note:: While this field **must** be present, it is **not** allowed to change; this must be the same as the ``xml_id`` the Delivery Service already has. This should almost never be different from the Delivery Service's ``displayName``.
+ .. note:: While this field **must** be present, it is **not** allowed to change; this must be the same as the ``xml_id`` the :term:`Delivery Service` already has. This should almost never be different from the :term:`Delivery Service`'s ``displayName``.
.. code-block:: http
@@ -467,7 +467,7 @@ Request Structure
"ipv6RoutingEnabled": false,
"lastUpdated": "2018-11-14 18:21:17+00",
"logsEnabled": true,
- "longDesc": "A Delivery Service created expressly for API documentation examples",
+ "longDesc": "A :term:`Delivery Service` created expressly for API documentation examples",
"missLat": -1,
"missLong": -1,
"multiSiteOrigin": false,
@@ -485,8 +485,8 @@ Request Structure
}
.. [5] These fields must be defined if and only if ``geoLimit`` is non-zero
-.. [6] These fields are required for HTTP-routed Delivery Services, and optional for all others
-.. [7] These fields are required for HTTP-routed and DNS-routed Delivery Services, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP Delivery Services
+.. [6] These fields are required for HTTP-routed :term:`Delivery Service`\ s, and optional for all others
+.. [7] These fields are required for HTTP-routed and DNS-routed :term:`Delivery Service`\ s, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP :term:`Delivery Service`\ s
.. [8] See "token-based-auth" TODO --- wat for more information
Response Structure
@@ -507,11 +507,11 @@ Response Structure
Content-Type: text/plain; charset=utf-8
-.. [10] Users with the roles "admin" and/or "operation" will be able to edit *all* Delivery Services, whereas any other user will only be able to edit the Delivery Services their Tenant is allowed to edit.
+.. [10] Users with the roles "admin" and/or "operation" will be able to edit *all* :term:`Delivery Service`\ s, whereas any other user will only be able to edit the :term:`Delivery Service`\ s their Tenant is allowed to edit.
``DELETE``
==========
-Deletes the target Delivery Service
+Deletes the target :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [11]_
@@ -521,11 +521,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+----------------------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +======+============================================================================================================================+
- | ID | The integral, unique identifier of the Delivery Service to be retrieved |
- +------+----------------------------------------------------------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=================================================================================+
+ | ID | The integral, unique identifier of the :term:`Delivery Service` to be retrieved |
+ +------+---------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -561,4 +561,4 @@ Response Structure
}
]}
-.. [11] Users with the roles "admin" and/or "operation" will be able to delete *all* Delivery Services, whereas any other user will only be able to delete the Delivery Services their Tenant is allowed to delete.
+.. [11] Users with the roles "admin" and/or "operation" will be able to delete *all* :term:`Delivery Service`\ s, whereas any other user will only be able to delete the :term:`Delivery Service`\ s their Tenant is allowed to delete.
diff --git a/docs/source/api/deliveryservices_id_capacity.rst b/docs/source/api/deliveryservices_id_capacity.rst
index 741e1db..5070c3f 100644
--- a/docs/source/api/deliveryservices_id_capacity.rst
+++ b/docs/source/api/deliveryservices_id_capacity.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves the usage percentages of a servers associated with a Delivery Service
+Retrieves the usage percentages of a servers associated with a :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -33,18 +33,18 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+----------------------------------------------------------------------+
- | Name | Description |
- +======+======================================================================+
- | ID | The integral, unique identifier for the Delivery Service of interest |
- +------+----------------------------------------------------------------------+
+ +------+------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+==============================================================================+
+ | ID | The integral, unique identifier for the :term:`Delivery Service` of interest |
+ +------+------------------------------------------------------------------------------+
Response Structure
------------------
-:availablePercent: The percent of servers assigned to this Delivery Service that is available - the allowed traffic level in terms of data per time period for all cache servers that remains unused
-:unavailablePercent: The percent of servers assigned to this Delivery Service that is unavailable - the allowed traffic level in terms of data per time period for all cache servers that can't be used because the servers are deemed unhealthy
-:utilizedPercent: The percent of servers assigned to this Delivery Service that is currently in use - the allowed traffic level in terms of data per time period that is currently devoted to servicing requests
-:maintenancePercent: The percent of servers assigned to this Delivery Service that is unavailable due to server maintenance - the allowed traffic level in terms of data per time period that is unavailable because servers have intentionally been marked offline by administrators
+:availablePercent: The percent of servers assigned to this :term:`Delivery Service` that is available - the allowed traffic level in terms of data per time period for all :term:`cache server`\ s that remains unused
+:unavailablePercent: The percent of servers assigned to this :term:`Delivery Service` that is unavailable - the allowed traffic level in terms of data per time period for all :term:`cache server`\ s that can't be used because the servers are deemed unhealthy
+:utilizedPercent: The percent of servers assigned to this :term:`Delivery Service` that is currently in use - the allowed traffic level in terms of data per time period that is currently devoted to servicing requests
+:maintenancePercent: The percent of servers assigned to this :term:`Delivery Service` that is unavailable due to server maintenance - the allowed traffic level in terms of data per time period that is unavailable because servers have intentionally been marked offline by administrators
.. code-block:: http
:caption: Response Example
@@ -70,4 +70,4 @@ Response Structure
"maintenancePercent": 0
}}
-.. [1] Users with the roles "admin" and/or "operations" will be able to see details for *all* Delivery Services, whereas any other user will only see details for the Delivery Services their Tenant is allowed to see.
+.. [1] Users with the roles "admin" and/or "operations" will be able to see details for *all* :term:`Delivery Service`\ s, whereas any other user will only see details for the :term:`Delivery Service`\ s their Tenant is allowed to see.
diff --git a/docs/source/api/deliveryservices_id_health.rst b/docs/source/api/deliveryservices_id_health.rst
index 2eda5cd..73666fe 100644
--- a/docs/source/api/deliveryservices_id_health.rst
+++ b/docs/source/api/deliveryservices_id_health.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves the health of all :term:`Cache Group`\ s assigned to a particular Delivery Service
+Retrieves the health of all :term:`Cache Group`\ s assigned to a particular :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -42,14 +42,14 @@ Request Structure
Response Structure
------------------
-:cachegroups: An array of objects that represent the health of each :term:`Cache Group` assigned to this Delivery Service
+:cachegroups: An array of objects that represent the health of each :term:`Cache Group` assigned to this :term:`Delivery Service`
:name: The name of the :term:`Cache Group` represented by this object
- :offline: The number of offline cache servers within this :term:`Cache Group`
- :online: The number of online cache servers within this :term:`Cache Group`
+ :offline: The number of offline :term:`cache server`\ s within this :term:`Cache Group`
+ :online: The number of online :term:`cache server`\ s within this :term:`Cache Group`
-:totalOffline: Total number of offline cache servers assigned to this Delivery Service
-:totalOnline: Total number of online cache servers assigned to this Delivery Service
+:totalOffline: Total number of offline :term:`cache server`\ s assigned to this :term:`Delivery Service`
+:totalOnline: Total number of online :term:`cache server`\ s assigned to this :term:`Delivery Service`
.. code-block:: http
:caption: Response Example
@@ -80,4 +80,4 @@ Response Structure
]
}}
-.. [1] Users with the roles "admin" and/or "operations" will be able to the see :term:`Cache Group`\ s associated with *any* Delivery Services, whereas any other user will only be able to see the :term:`Cache Group`\ s associated with Delivery Services their Tenant is allowed to see.
+.. [1] Users with the roles "admin" and/or "operations" will be able to the see :term:`Cache Group`\ s associated with *any* :term:`Delivery Service`\ s, whereas any other user will only be able to see the :term:`Cache Group`\ s associated with :term:`Delivery Service`\ s their Tenant is allowed to see.
diff --git a/docs/source/api/deliveryservices_id_regexes.rst b/docs/source/api/deliveryservices_id_regexes.rst
index 80dad49..48255c8 100644
--- a/docs/source/api/deliveryservices_id_regexes.rst
+++ b/docs/source/api/deliveryservices_id_regexes.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves routing regular expressions for a specific Delivery Service.
+Retrieves routing regular expressions for a specific :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -31,11 +31,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+-------------------------------------------------------------------------+
- | Name | Description |
- +======+=========================================================================+
- | ID | The integral, unique identifier of the Delivery Service being inspected |
- +------+-------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=================================================================================+
+ | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected |
+ +------+---------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -52,7 +52,7 @@ Response Structure
:pattern: The actual regular expression - ``\``\ s are escaped
:setNumber: The order in which the regular expression is evaluated against requests
:type: The integral, unique identifier of the type of this regular expression
-:typeName: The type of regular expression - determines that against which it will be evaluated
+:typeName: The :term:`Type` of regular expression - determines that against which it will be evaluated
.. code-block:: http
:caption: Response Example
@@ -79,11 +79,11 @@ Response Structure
}
]}
-.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by Delivery Services their tenant has permissions to see.
+.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by :term:`Delivery Service`\ s their tenant has permissions to see.
``POST``
========
-Creates a routing regular expression for a Delivery Service.
+Creates a routing regular expression for a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [2]_
@@ -93,11 +93,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+-------------------------------------------------------------------------+
- | Name | Description |
- +======+=========================================================================+
- | ID | The integral, unique identifier of the Delivery Service being inspected |
- +------+-------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=================================================================================+
+ | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected |
+ +------+---------------------------------------------------------------------------------+
:pattern: The actual regular expression
@@ -161,4 +161,4 @@ Response Structure
}}
-.. [2] If tenancy is used, then users (regardless of role) will only be able to edit the routing regular expressions used by Delivery Services their tenant has permissions to edit. Assuming tenancy is satisfied, a routing regular expression can only be created by a user with the "admin" or "operations" role.
+.. [2] If tenancy is used, then users (regardless of role) will only be able to edit the routing regular expressions used by :term:`Delivery Service`\ s their tenant has permissions to edit. Assuming tenancy is satisfied, a routing regular expression can only be created by a user with the "admin" or "operations" role.
diff --git a/docs/source/api/deliveryservices_id_regexes_rid.rst b/docs/source/api/deliveryservices_id_regexes_rid.rst
index 3e5f1c9..94e4c15 100644
--- a/docs/source/api/deliveryservices_id_regexes_rid.rst
+++ b/docs/source/api/deliveryservices_id_regexes_rid.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves a specific routing regular expression for a specific Delivery Service.
+Retrieves a specific routing regular expression for a specific :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -34,7 +34,7 @@ Request Structure
+------+-----------------------------------------------------------------------------------+
| Name | Description |
+======+===================================================================================+
- | ID | The integral, unique identifier of the Delivery Service being inspected |
+ | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected |
+------+-----------------------------------------------------------------------------------+
| rID | The integral, unique identifier of the routing regular expression being inspected |
+------+-----------------------------------------------------------------------------------+
@@ -81,7 +81,7 @@ Response Structure
}
]}
-.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by Delivery Services their tenant has permissions to see.
+.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by :term:`Delivery Service`\ s their tenant has permissions to see.
``PUT``
@@ -99,7 +99,7 @@ Request Structure
+------+-----------------------------------------------------------------------------------+
| Name | Description |
+======+===================================================================================+
- | ID | The integral, unique identifier of the Delivery Service being inspected |
+ | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected |
+------+-----------------------------------------------------------------------------------+
| rID | The integral, unique identifier of the routing regular expression being inspected |
+------+-----------------------------------------------------------------------------------+
@@ -166,7 +166,7 @@ Response Structure
}}
-.. [2] If tenancy is used, then users (regardless of role) will only be able to edit the routing regular expressions used by Delivery Services their tenant has permissions to edit. Assuming tenancy is satisfied, a routing regular expression can only be edited by a user with the "admin" or "operations" role.
+.. [2] If tenancy is used, then users (regardless of role) will only be able to edit the routing regular expressions used by :term:`Delivery Service`\ s their tenant has permissions to edit. Assuming tenancy is satisfied, a routing regular expression can only be edited by a user with the "admin" or "operations" role.
``DELETE``
==========
@@ -183,7 +183,7 @@ Request Structure
+------+-----------------------------------------------------------------------------------+
| Name | Description |
+======+===================================================================================+
- | ID | The integral, unique identifier of the Delivery Service being inspected |
+ | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected |
+------+-----------------------------------------------------------------------------------+
| rID | The integral, unique identifier of the routing regular expression being inspected |
+------+-----------------------------------------------------------------------------------+
@@ -221,4 +221,4 @@ Response Structure
}
]}
-.. [3] If tenancy is used, then users (regardless of role) will only be able to delete the routing regular expressions used by Delivery Services their tenant has permissions to delete. Assuming tenancy is satisfied, a routing regular expression can only be deleted by a user with the "admin" or "operations" role.
+.. [3] If tenancy is used, then users (regardless of role) will only be able to delete the routing regular expressions used by :term:`Delivery Service`\ s their tenant has permissions to delete. Assuming tenancy is satisfied, a routing regular expression can only be deleted by a user with the "admin" or "operations" role.
diff --git a/docs/source/api/deliveryservices_id_routing.rst b/docs/source/api/deliveryservices_id_routing.rst
index 8b01929..5f1bcb0 100644
--- a/docs/source/api/deliveryservices_id_routing.rst
+++ b/docs/source/api/deliveryservices_id_routing.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves routing method statistics for a particular Delivery Service
+Retrieves routing method statistics for a particular :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -31,11 +31,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+----------------------------------------------------------------------+
- | Name | Description |
- +======+======================================================================+
- | ID | The integral, unique identifier for the Delivery Service of interest |
- +------+----------------------------------------------------------------------+
+ +------+------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+==============================================================================+
+ | ID | The integral, unique identifier for the :term:`Delivery Service` of interest |
+ +------+------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -48,15 +48,15 @@ Request Structure
Response Structure
------------------
-:cz: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by a coverage zone file (CZF)
-:dsr: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by sending the client to an overflow Delivery Service
-:err: The percent of requests to the Traffic Router for this Delivery Service that resulted in an error
-:fed: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by sending the client to a federated CDN
-:geo: The percent of requests to the Traffic Router for this Delivery Service that were satisfied using 3rd party geographic IP mapping
-:miss: The percent of requests to the Traffic Router for this Delivery Service that could not be satisfied
-:regionalAlternate: The percent of requests to the Traffic Router for this Delivery Service that were satisfied by sending the client to the alternate, Regional Geo-blocking URL
-:regionalDenied: The percent of Traffic Router requests for this Delivery Service that were denied due to geographic location policy
-:staticRoute: The percent of requests to the Traffic Router for this Delivery Service that were satisfied with pre-configured DNS entries
+:cz: The percent of requests to the Traffic Router for this :term:`Delivery Service` that were satisfied by a coverage zone file (CZF)
+:dsr: The percent of requests to the Traffic Router for this :term:`Delivery Service` that were satisfied by sending the client to an overflow :term:`Delivery Service`
+:err: The percent of requests to the Traffic Router for this :term:`Delivery Service` that resulted in an error
+:fed: The percent of requests to the Traffic Router for this :term:`Delivery Service` that were satisfied by sending the client to a federated CDN
+:geo: The percent of requests to the Traffic Router for this :term:`Delivery Service` that were satisfied using 3rd party geographic IP mapping
+:miss: The percent of requests to the Traffic Router for this :term:`Delivery Service` that could not be satisfied
+:regionalAlternate: The percent of requests to the Traffic Router for this :term:`Delivery Service` that were satisfied by sending the client to the alternate, Regional Geo-blocking URL
+:regionalDenied: The percent of Traffic Router requests for this :term:`Delivery Service` that were denied due to geographic location policy
+:staticRoute: The percent of requests to the Traffic Router for this :term:`Delivery Service` that were satisfied with pre-configured DNS entries
.. code-block:: http
:caption: Response Example
@@ -88,4 +88,4 @@ Response Structure
"miss": 0
}}
-.. [1] Users with the roles "admin" and/or "operations" will be able to see details for *all* Delivery Services, whereas any other user will only see details for the Delivery Services their Tenant is allowed to see.
+.. [1] Users with the roles "admin" and/or "operations" will be able to see details for *all* :term:`Delivery Service`\ s, whereas any other user will only see details for the :term:`Delivery Service`\ s their Tenant is allowed to see.
diff --git a/docs/source/api/deliveryservices_id_safe.rst b/docs/source/api/deliveryservices_id_safe.rst
index ac00fea..71a1b01 100644
--- a/docs/source/api/deliveryservices_id_safe.rst
+++ b/docs/source/api/deliveryservices_id_safe.rst
@@ -21,7 +21,7 @@
``PUT``
=======
-Allows a user to edit metadata fields of a Delivery Service.
+Allows a user to edit metadata fields of a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -31,15 +31,15 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+------------------------------------------------------------------------+
- | Name | Description |
- +======+========================================================================+
- | ID | The integral, unique identifier of the Delivery Service being modified |
- +------+------------------------------------------------------------------------+
+ +------+--------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+================================================================================+
+ | ID | The integral, unique identifier of the :term:`Delivery Service` being modified |
+ +------+--------------------------------------------------------------------------------+
-:displayName: The human-friendly name for this Delivery Service
-:infoUrl: A string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
-:longDesc: A description of the Delivery Service
+:displayName: The human-friendly name for this :term:`Delivery Service`
+:infoUrl: A string which is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
+:longDesc: A description of the :term:`Delivery Service`
:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
@@ -59,7 +59,7 @@ Request Structure
{
"displayName": "demo",
"infoUrl": "www.info.com",
- "longDesc": "A Delivery Service created for the CDN-in-a-Box project",
+ "longDesc": "A :term:`Delivery Service` created for the CDN-in-a-Box project",
"longDesc1": null,
"longDesc2": null
}
@@ -70,40 +70,40 @@ Response Structure
.. versionchanged:: 1.3
Removed ``fqPacingRate`` field, added fields: ``deepCachingType``, ``signingAlgorithm``, and ``tenant``.
-:active: ``true`` if the Delivery Service is active, ``false`` otherwise
-:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:active: ``true`` if the :term:`Delivery Service` is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the :term:`Delivery Service`, ``false`` otherwise
:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
-:cdnName: Name of the CDN to which the Delivery Service belongs
-:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
-:deepCachingType: A string that describes when "Deep Caching" will be used by this Delivery Service - one of:
+:cdnId: The integral, unique identifier of the CDN to which the :term:`Delivery Service` belongs
+:cdnName: Name of the CDN to which the :term:`Delivery Service` belongs
+:checkPath: The path portion of the URL to check connections to this :term:`Delivery Service`'s origin server
+:deepCachingType: A string that describes when "Deep Caching" will be used by this :term:`Delivery Service` - one of:
ALWAYS
- "Deep Caching" will always be used with this Delivery Service
+ "Deep Caching" will always be used with this :term:`Delivery Service`
NEVER
- "Deep Caching" will never be used with this Delivery Service
+ "Deep Caching" will never be used with this :term:`Delivery Service`
.. versionadded:: 1.3
-:displayName: The display name of the Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [4]_
+:displayName: The display name of the :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active\ [4]_
:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see ``man tc-fc_codel`` for more information) - Linux only
.. deprecated:: 1.3
This field is only present/available in API versions 1.2 and lower - it has been removed in API version 1.3
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
0
@@ -116,44 +116,44 @@ Response Structure
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only ``0`` - which represents MaxMind - is supported
-:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the dnsByPassIp* for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
-:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:id: An integral, unique identifier for this Delivery Service
-:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:globalMaxMbps: The maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: The maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the dnsByPassIp* for DNS :term:`Delivery Service`\ s and to the httpBypassFqdn for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:id: An integral, unique identifier for this :term:`Delivery Service`
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1
:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
-:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: A description of the Delivery Service
+:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: A description of the :term:`Delivery Service`
:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
-:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
-:maxDnsAnswers: The maximum number of IPs to put in a A/AAAA response for a DNS Delivery Service (0 means all available)\ [4]_
+:maxDnsAnswers: The maximum number of IPs to put in a A/AAAA response for a DNS :term:`Delivery Service` (0 means all available)\ [4]_
:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [3]_
:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
:orgServerFqdn: The origin server's Fully Qualified Domain Name (FQDN) - including the protocol (e.g. http:// or https://) - for use in retrieving content from the origin server
-:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
-:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
-:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+:profileDescription: The description of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this :term:`Delivery Service` is associated
+:profileName: The name of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server`\ s\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
0
HTTP
@@ -180,43 +180,43 @@ Response Structure
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: A regular expression remap rule to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
:remapText: Additional, raw text to add to the remap line for caches
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signed: ``true`` if token-based authentication is enabled for this :term:`Delivery Service`, ``false`` otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, NOT the latest.
.. versionadded:: 1.3
-:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This integer indicates the generation of keys in use by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenant: The name of the tenant who owns this Delivery Service
+:tenant: The name of the tenant who owns this :term:`Delivery Service`
.. versionadded:: 1.3
-:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:tenantId: The integral, unique identifier of the tenant who owns this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
-:type: The name of the routing type of this Delivery Service e.g. "HTTP"
-:typeId: The integral, unique identifier of the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:type: The name of the routing type of this :term:`Delivery Service` e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons
.. code-block:: http
:caption: Response Example
@@ -267,7 +267,7 @@ Response Structure
"geoLimitCountries": null,
"missLat": 42,
"anonymousBlockingEnabled": 0,
- "longDesc": "A Delivery Service created for the CDN-in-a-Box project",
+ "longDesc": "A :term:`Delivery Service` created for the CDN-in-a-Box project",
"matchList": [
{
"pattern": ".*\\.demo1\\..*",
@@ -314,8 +314,8 @@ Response Structure
]}
-.. [1] Users with the "admin" or "operations" roles will be able to edit *any* Delivery Service, whereas other users will only be able to edit Delivery Services that their tenant has permissions to edit.
-.. [2] This only applies to HTTP-routed Delivery Services
+.. [1] Users with the "admin" or "operations" roles will be able to edit *any*:term:`Delivery Service`, whereas other users will only be able to edit :term:`Delivery Service`\ s that their tenant has permissions to edit.
+.. [2] This only applies to HTTP-routed :term:`Delivery Service`\ s
.. [3] See :ref:`multi-site-origin`
-.. [4] This only applies to DNS-routed Delivery Services
-.. [5] These fields are required for HTTP-routed and DNS-routed Delivery Services, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP Delivery Services
+.. [4] This only applies to DNS-routed :term:`Delivery Service`\ s
+.. [5] These fields are required for HTTP-routed and DNS-routed :term:`Delivery Service`\ s, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP :term:`Delivery Service`\ s
diff --git a/docs/source/api/deliveryservices_id_server_types_type_metric_types_start_date_start_end_date_end.rst b/docs/source/api/deliveryservices_id_server_types_type_metric_types_start_date_start_end_date_end.rst
index 812e056..2ce22bd 100644
--- a/docs/source/api/deliveryservices_id_server_types_type_metric_types_start_date_start_end_date_end.rst
+++ b/docs/source/api/deliveryservices_id_server_types_type_metric_types_start_date_start_end_date_end.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves detailed and summary metrics for Mid-tier and Edge-tier caches assigned to a Delivery Service.
+Retrieves detailed and summary metrics for Mid-tier and Edge-tier caches assigned to a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None
diff --git a/docs/source/api/deliveryservices_id_servers.rst b/docs/source/api/deliveryservices_id_servers.rst
index 84d60c1..bf421e9 100644
--- a/docs/source/api/deliveryservices_id_servers.rst
+++ b/docs/source/api/deliveryservices_id_servers.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves properties of Edge-Tier servers assigned to a Delivery Service.
+Retrieves properties of Edge-Tier servers assigned to a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -152,5 +152,5 @@ Response Structure
]}
-.. [1] Users with the roles "admin" and/or "operations" will be able to the see servers associated with *any* Delivery Services, whereas any other user will only be able to see the servers associated with Delivery Services their Tenant is allowed to see.
+.. [1] Users with the roles "admin" and/or "operations" will be able to the see servers associated with *any* :term:`Delivery Service`\ s, whereas any other user will only be able to see the servers associated with :term:`Delivery Service`\ s their Tenant is allowed to see.
.. [2] See `the Wikipedia article on Out-of-Band Management <https://en.wikipedia.org/wiki/Out-of-band_management>`_ for more information.
diff --git a/docs/source/api/deliveryservices_id_servers_eligible.rst b/docs/source/api/deliveryservices_id_servers_eligible.rst
index 996fe8b..7cf42d5 100644
--- a/docs/source/api/deliveryservices_id_servers_eligible.rst
+++ b/docs/source/api/deliveryservices_id_servers_eligible.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves properties of Edge-Tier servers eligible for assignment to a particular Delivery Service.
+Retrieves properties of Edge-Tier servers eligible for assignment to a particular :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -139,5 +139,5 @@ Response Structure
}
]}
-.. [1] Users with the roles "admin" and/or "operations" will be able to the see servers not eligible for assignment to *any* given Delivery Service, whereas any other user will only be able to see the servers not eligible for assignment to a Delivery Service their Tenant is allowed to see. For this particular endpoint,
+.. [1] Users with the roles "admin" and/or "operations" will be able to the see servers not eligible for assignment to *any* given :term:`Delivery Service`, whereas any other user will only be able to see the servers not eligible for assignment to a :term:`Delivery Service` their Tenant is allowed to see. For this particular endpoint,
.. [2] See `the Wikipedia article on Out-of-Band Management <https://en.wikipedia.org/wiki/Out-of-band_management>`_ for more information.
diff --git a/docs/source/api/deliveryservices_id_state.rst b/docs/source/api/deliveryservices_id_state.rst
index efa0c64..59e6fcc 100644
--- a/docs/source/api/deliveryservices_id_state.rst
+++ b/docs/source/api/deliveryservices_id_state.rst
@@ -24,7 +24,7 @@
``GET``
=======
-Retrieves the fail-over state for a Delivery Service.
+Retrieves the fail-over state for a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -34,24 +34,24 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+-------------------------------------------------------------------------+
- | Name | Description |
- +======+=========================================================================+
- | ID | The integral, unique identifier of the Delivery Service being inspected |
- +------+-------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=================================================================================+
+ | ID | The integral, unique identifier of the :term:`Delivery Service` being inspected |
+ +------+---------------------------------------------------------------------------------+
Response Structure
------------------
-:enabled: ``true`` if failover has been enabled for this Delivery Service, ``false`` otherwise
-:failover: An object describing the failover configuration for this Delivery Service
+:enabled: ``true`` if failover has been enabled for this :term:`Delivery Service`, ``false`` otherwise
+:failover: An object describing the failover configuration for this :term:`Delivery Service`
:configured: ``true`` if this failover configuration has been updated by some Traffic Ops user, ``false`` otherwise
- :destination: An object describing the Cache Group within this Delivery Service which will utilize this failover configuration
+ :destination: An object describing the Cache Group within this :term:`Delivery Service` which will utilize this failover configuration
- :location: The integral, unique identifier of a Cache Group within this Delivery Service which will utilize this failover configuration
+ :location: The integral, unique identifier of a Cache Group within this :term:`Delivery Service` which will utilize this failover configuration
:type: The 'type' of the Cache Group identified by ``location``
- :enabled: ``true`` if failover has been enabled for this Delivery Service, ``false`` otherwise
+ :enabled: ``true`` if failover has been enabled for this :term:`Delivery Service`, ``false`` otherwise
:locations: An array of integral, unique identifiers for Cache Groups to use for failover
.. code-block:: http
@@ -83,4 +83,4 @@ Response Structure
-.. [1] If a user does not have either the "admin" nor "operations" role, then only Delivery Services assigned to the user's Tenant will be able to be queried with this endpoint
+.. [1] If a user does not have either the "admin" nor "operations" role, then only :term:`Delivery Service`\ s assigned to the user's Tenant will be able to be queried with this endpoint
diff --git a/docs/source/api/deliveryservices_id_unassigned_servers.rst b/docs/source/api/deliveryservices_id_unassigned_servers.rst
index 59dc70f..fe390a3 100644
--- a/docs/source/api/deliveryservices_id_unassigned_servers.rst
+++ b/docs/source/api/deliveryservices_id_unassigned_servers.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves properties of Edge-tier servers not assigned to a Delivery Service.
+Retrieves properties of Edge-tier servers not assigned to a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -132,5 +132,5 @@ Response Structure
]
}
-.. [1] Users with the roles "admin" and/or "operations" will be able to see servers not assigned to *any* given Delivery Service, whereas any other user will only be able to see the servers not assigned to Delivery Services their Tenant is allowed to see.
+.. [1] Users with the roles "admin" and/or "operations" will be able to see servers not assigned to *any* given :term:`Delivery Service`, whereas any other user will only be able to see the servers not assigned to :term:`Delivery Service`\ s their Tenant is allowed to see.
diff --git a/docs/source/api/deliveryservices_regexes.rst b/docs/source/api/deliveryservices_regexes.rst
index 353aad5..271c827 100644
--- a/docs/source/api/deliveryservices_regexes.rst
+++ b/docs/source/api/deliveryservices_regexes.rst
@@ -22,7 +22,7 @@
``GET``
=======
-Retrieves routing regular expressions for all Delivery Services.
+Retrieves routing regular expressions for all :term:`Delivery Service`\ s.
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -34,7 +34,7 @@ No parameters available
Response Structure
------------------
-:dsName: The name of the Delivery Service represented by this object
+:dsName: The name of the :term:`Delivery Service` represented by this object
:regexes: An array of objects that represent various routing regular expressions used by ``dsName``
:pattern: The actual regular expression - ``\``\ s are escaped
@@ -69,4 +69,4 @@ Response Structure
}
]}
-.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by Delivery Services their tenant has permissions to see.
+.. [1] If tenancy is used, then users (regardless of role) will only be able to see the routing regular expressions used by :term:`Delivery Service`\ s their tenant has permissions to see.
diff --git a/docs/source/api/deliveryservices_request.rst b/docs/source/api/deliveryservices_request.rst
index 902ab06..8c2cf47 100644
--- a/docs/source/api/deliveryservices_request.rst
+++ b/docs/source/api/deliveryservices_request.rst
@@ -33,8 +33,8 @@ Request Structure
-----------------
:details: An object describing the actual parameters for the Delivery Service request
- :customer: Name of the customer associated with the Delivery Service
- :deepCachingType: An optional string describing when to do Deep Caching for this Delivery Service - one of:
+ :customer: Name of the customer associated with the :term:`Delivery Service`
+ :deepCachingType: An optional string describing when to do Deep Caching for this :term:`Delivery Service` - one of:
NEVER
Never use deep caching (default)
@@ -49,39 +49,39 @@ Request Structure
:hasNegativeCachingCustomization: ``true`` if any customization is required for negative caching, ``false`` otherwise
:hasOriginACLWhitelist: ``true`` if access to the origin is restricted using an Access Control List (ACL or "whitelist") of IP addresses
- :hasOriginDynamicRemap: If ``true``, this Delivery Service can dynamically map to multiple origin URLs
- :hasSignedURLs: If ``true``, this Delivery Service's URLs are signed
+ :hasOriginDynamicRemap: If ``true``, this :term:`Delivery Service` can dynamically map to multiple origin URLs
+ :hasSignedURLs: If ``true``, this :term:`Delivery Service`'s URLs are signed
:headerRewriteEdge: An optional string containing a header re-write rule to be used at the Edge tier
:headerRewriteMid: An optional string containing a header re-write rule to be used at the Mid tier
:headerRewriteRedirectRouter: An optional string containing a header re-write rule to be used by the Traffic Router
- :maxLibrarySizeEstimate: A special string that describes the estimated size of the sum total of content available through this Delivery Service
- :negativeCachingCustomizationNote: A note remarking on the use, customization, or complications associated with negative caching for this Delivery Service
+ :maxLibrarySizeEstimate: A special string that describes the estimated size of the sum total of content available through this :term:`Delivery Service`
+ :negativeCachingCustomizationNote: A note remarking on the use, customization, or complications associated with negative caching for this :term:`Delivery Service`
:notes: An optional string containing additional instructions or notes regarding the Request
- :originHeaders: An optional, comma-separated string of header values that must be passed to requests to the Delivery Service's origin
- :originTestFile: A URL path to a test file available on the Delivery Service's origin server
- :originURL: The URL of the Delivery Service's origin server
- :otherOriginSecurity: An optional string describing any and all other origin security measures that need to be considered for access to the Delivery Service's origin
+ :originHeaders: An optional, comma-separated string of header values that must be passed to requests to the :term:`Delivery Service`'s origin
+ :originTestFile: A URL path to a test file available on the :term:`Delivery Service`'s origin server
+ :originURL: The URL of the :term:`Delivery Service`'s origin server
+ :otherOriginSecurity: An optional string describing any and all other origin security measures that need to be considered for access to the :term:`Delivery Service`'s origin
:overflowService: An optional string containing the IP address or URL of an overflow point (used if rate limits are met or exceeded
- :peakBPSEstimate: A special string describing the estimated peak data transfer rate of the Delivery Service in Bytes Per Second (BPS)
- :peakTPSEstimate: A special string describing the estimated peak transaction rate of the Delivery Service in Transactions Per Second (TPS)
- :queryStringHandling: A special string describing how the Delivery Service should treat URLs containing query parameters
- :rangeRequestHandling: A special string describing how the Delivery Service should handle range requests
- :rateLimitingGBPS: An optional field which, if defined, should contain the maximum allowed data transfer rate for the Delivery Service in GigaBytes Per Second (GBPS)
- :rateLimitingTPS: An optional field which, if defined, should contain the maximum allowed transaction rate for the Delivery Service in Transactions Per Second (TPS)
- :routingName: The routing name for the Delivery Service, e.g. ``SomeRoutingName.DeliveryService_xml_id.CDNName.com``
- :routingType: The Delivery Service's routing type, should be one of:
+ :peakBPSEstimate: A special string describing the estimated peak data transfer rate of the :term:`Delivery Service` in Bytes Per Second (BPS)
+ :peakTPSEstimate: A special string describing the estimated peak transaction rate of the :term:`Delivery Service` in Transactions Per Second (TPS)
+ :queryStringHandling: A special string describing how the :term:`Delivery Service`\ should treat URLs containing query parameters
+ :rangeRequestHandling: A special string describing how the :term:`Delivery Service`\ should handle range requests
+ :rateLimitingGBPS: An optional field which, if defined, should contain the maximum allowed data transfer rate for the :term:`Delivery Service` in GigaBytes Per Second (GBPS)
+ :rateLimitingTPS: An optional field which, if defined, should contain the maximum allowed transaction rate for the :term:`Delivery Service` in Transactions Per Second (TPS)
+ :routingName: The routing name for the :term:`Delivery Service`, e.g. ``SomeRoutingName.DeliveryService_xml_id.CDNName.com``
+ :routingType: The :term:`Delivery Service`'s routing type, should be one of:
HTTP
- The Traffic Router re-directs clients to cache servers using the HTTP ``302 REDIRECT`` response code
+ The Traffic Router re-directs clients to :term:`cache server`\ s using the HTTP ``302 REDIRECT`` response code
DNS
- The Traffic Router responds to requests for name resolution of the Delivery Service's routing name with IP addresses of cache servers
+ The Traffic Router responds to requests for name resolution of the :term:`Delivery Service`'s routing name with IP addresses of :term:`cache server`\ s
STEERING
- This Delivery Service routes clients to other Delivery Services - which will in turn (generally) route them to clients
+ This :term:`Delivery Service` routes clients to other :term:`Delivery Service`\ s - which will in turn (generally) route them to clients
ANY_MAP
Some kind of undocumented black magic is used to get clients to... content, probably?
- :serviceAliases: An optional array of aliases for this Delivery Service
- :serviceDesc: A description of the Delivery Service
+ :serviceAliases: An optional array of aliases for this :term:`Delivery Service`
+ :serviceDesc: A description of the :term:`Delivery Service`
:emailTo: The email to which the Delivery Service request will be sent
@@ -126,9 +126,7 @@ Response Structure
.. code-block:: json
:caption: Response Example
- { "alerts": [
- {
- "level": "success",
- "text": "Delivery Service request sent to foo@bar.com."
- }
- ]}
+ { "alerts": [{
+ "level": "success",
+ "text": "Delivery Service request sent to foo@bar.com."
+ }]}
diff --git a/docs/source/api/deliveryservices_sslkeys_add.rst b/docs/source/api/deliveryservices_sslkeys_add.rst
index 93cddee..62f7833 100644
--- a/docs/source/api/deliveryservices_sslkeys_add.rst
+++ b/docs/source/api/deliveryservices_sslkeys_add.rst
@@ -23,7 +23,7 @@
``POST``
========
-Allows user to upload an SSL certificate, csr, and private key for a Delivery Service.
+Allows user to upload an SSL certificate, csr, and private key for a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -31,14 +31,14 @@ Allows user to upload an SSL certificate, csr, and private key for a Delivery Se
Request Structure
-----------------
-:cdn: The name of the CDN to which the Delivery Service belongs
+:cdn: The name of the CDN to which the :term:`Delivery Service` belongs
:certificate: An object that contains the actual components of the SSL key
- :crt: The certificate for the Delivery Service identified by ``key``
- :csr: The csr file for the Delivery Service identified by ``key``
- :key: The private key for the Delivery Service identified by ``key``
+ :crt: The certificate for the :term:`Delivery Service` identified by ``key``
+ :csr: The csr file for the :term:`Delivery Service` identified by ``key``
+ :key: The private key for the :term:`Delivery Service` identified by ``key``
-:key: The 'xml_id' of the Delivery Service to which these keys will be assigned
+:key: The 'xml_id' of the :term:`Delivery Service` to which these keys will be assigned
:version: An integer that defines the "version" of the key - which may be thought of as the sequential generation; that is, the higher the number the more recent the key
.. code-block:: http
diff --git a/docs/source/api/deliveryservices_sslkeys_generate.rst b/docs/source/api/deliveryservices_sslkeys_generate.rst
index 53e1486..20ed278 100644
--- a/docs/source/api/deliveryservices_sslkeys_generate.rst
+++ b/docs/source/api/deliveryservices_sslkeys_generate.rst
@@ -21,7 +21,7 @@
``POST``
========
-Generates an SSL certificate, csr, and private key for a Delivery Service
+Generates an SSL certificate, csr, and private key for a :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -31,11 +31,11 @@ Request Structure
-----------------
:city: An optional field which, if present, will represent the resident city of the generated SSL certificate
:country: An optional field which, if present, will represent the resident country of the generated SSL certificate
-:hostname: The desired hostname of the Delivery Service
+:hostname: The desired hostname of the :term:`Delivery Service`
- .. note:: In most cases, this must be the same as the 'Delivery Service URL'
+ .. note:: In most cases, this must be the same as the :term:`Delivery Service` URL'
-:key: The 'xml_id' of the Delivery Service for which keys will be generated
+:key: The 'xml_id' of the :term:`Delivery Service` for which keys will be generated
:organization: An optional field which, if present, will represent the organization for which the SSL certificate was generated
:state: An optional field which, if present, will represent the resident state or province of the generated SSL certificate
:businessUnit: An optional field which, if present, will represent the business unit for which the SSL certificate was generated
diff --git a/docs/source/api/deliveryservices_xmlid_servers.rst b/docs/source/api/deliveryservices_xmlid_servers.rst
index bcc0ef9..48e7844 100644
--- a/docs/source/api/deliveryservices_xmlid_servers.rst
+++ b/docs/source/api/deliveryservices_xmlid_servers.rst
@@ -23,7 +23,7 @@
``POST``
========
-Assigns cache servers to a Delivery Service.
+Assigns :term:`cache server`\ s to a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
@@ -33,13 +33,13 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +--------+--------------------------------------------------------------------------------+
- | Name | Description |
- +========+================================================================================+
- | xml_id | The 'xml_id' of the Delivery Service whose server assignments are being edited |
- +--------+--------------------------------------------------------------------------------+
+ +--------+----------------------------------------------------------------------------------------+
+ | Name | Description |
+ +========+========================================================================================+
+ | xml_id | The 'xml_id' of the :term:`Delivery Service` whose server assignments are being edited |
+ +--------+----------------------------------------------------------------------------------------+
-:serverNames: An array of hostname of cache servers to assign to this Delivery Service
+:serverNames: An array of hostname of :term:`cache server`\ s to assign to this :term:`Delivery Service`
.. code-block:: http
:caption: Request Example
@@ -56,8 +56,8 @@ Request Structure
Response Structure
------------------
-:xml_id: The 'xml_id' of the Delivery Service to which the servers in ``serverNames`` have been assigned
-:serverNames: An array of hostnames of cache servers assigned to Delivery Service identified by ``xml_id``
+:xml_id: The 'xml_id' of the :term:`Delivery Service` to which the servers in ``serverNames`` have been assigned
+:serverNames: An array of hostnames of :term:`cache server`\ s assigned to :term:`Delivery Service` identified by ``xml_id``
.. code-block:: http
:caption: Response Example
@@ -81,4 +81,4 @@ Response Structure
"xmlId": "test"
}}
-.. [1] Users with the roles "admin" and/or "operation" will be able to edit the server assignments of *all* Delivery Services, whereas any other user will only be able to edit the server assignments of the Delivery Services their Tenant is allowed to edit.
+.. [1] Users with the roles "admin" and/or "operation" will be able to edit the server assignments of *all* :term:`Delivery Service`\ s, whereas any other user will only be able to edit the server assignments of the :term:`Delivery Service`\ s their Tenant is allowed to edit.
diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys.rst b/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys.rst
index ab13f26..e59b056 100644
--- a/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys.rst
+++ b/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves SSL keys for a Delivery Service.
+Retrieves SSL keys for a :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None
@@ -31,11 +31,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +-------+----------------------------------------------+
- | Name | Description |
- +=======+==============================================+
- | XMLID | The 'xml_id' of the desired Delivery Service |
- +-------+----------------------------------------------+
+ +-------+------------------------------------------------------+
+ | Name | Description |
+ +=======+======================================================+
+ | XMLID | The 'xml_id' of the desired :term:`Delivery Service` |
+ +-------+------------------------------------------------------+
.. table:: Request Query Parameters
@@ -58,17 +58,17 @@ Response Structure
:businessUnit: An optional field which, if present, contains the business unit entered by the user when generating the SSL certificate\ [1]_
:certificate: An object containing the actual generated key, certificate, and signature of the SSL keys
- :crt: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) certificate for the Delivery Service identified by ``deliveryservice``
- :csr: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) csr file for the Delivery Service identified by ``deliveryservice``
- :key: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) private key for the Delivery Service identified by ``deliveryservice``
+ :crt: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) certificate for the :term:`Delivery Service` identified by ``deliveryservice``
+ :csr: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) csr file for the :term:`Delivery Service` identified by ``deliveryservice``
+ :key: Base 64-encoded (or not if the ``decode`` query parameter was given and ``true``) private key for the :term:`Delivery Service` identified by ``deliveryservice``
.. caution:: There's almost certainly no good reason to request the private key! Even when "base 64-encoded" do not let **ANYONE** see this who would be unable to request it themselves!
-:cdn: The CDN of the Delivery Service for which the certs were generated
+:cdn: The CDN of the :term:`Delivery Service` for which the certs were generated
:city: An optional field which, if present, contains the city entered by the user when generating the SSL certificate\ [1]_
:country: An optional field which, if present, contains the country entered by the user when generating the SSL certificate\ [1]_
-:deliveryservice: The 'xml_id' of the Delivery Service for which the certificate was generated
-:hostname: The hostname generated by Traffic Ops that is used as the common name when generating the certificate - this will be a FQDN for DNS Delivery Services and a wildcard URL for HTTP Delivery Services
+:deliveryservice: The 'xml_id' of the :term:`Delivery Service` for which the certificate was generated
+:hostname: The hostname generated by Traffic Ops that is used as the common name when generating the certificate - this will be a FQDN for DNS :term:`Delivery Service`\ s and a wildcard URL for HTTP :term:`Delivery Service`\ s
:organization: An optional field which, if present, contains the organization entered by the user when generating certificate\ [1]_
:state: An optional field which, if present, contains the state entered by the user when generating certificate\ [1]_
:version: The version of the certificate record in Riak
diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst b/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst
index 3d9f33a..de9c6ae 100644
--- a/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst
+++ b/docs/source/api/deliveryservices_xmlid_xmlid_sslkeys_delete.rst
@@ -29,11 +29,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +-------+----------+----------------------------------------------+
- | Name | Required | Description |
- +=======+==========+==============================================+
- | xmlId | yes | The 'xml_id' of the desired Delivery Service |
- +-------+----------+----------------------------------------------+
+ +-------+----------+------------------------------------------------------+
+ | Name | Required | Description |
+ +=======+==========+======================================================+
+ | xmlId | yes | The 'xml_id' of the desired :term:`Delivery Service` |
+ +-------+----------+------------------------------------------------------+
.. table:: Request Query Parameters
diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys.rst b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys.rst
index bb15353..3098b51 100644
--- a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys.rst
+++ b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys.rst
@@ -23,9 +23,9 @@
``GET``
=======
-Retrieves URL signing keys for a Delivery Service.
+Retrieves URL signing keys for a :term:`Delivery Service`.
-.. caution:: This method will return the Delivery Service's **PRIVATE** URL signing keys! Be wary of using this endpoint and **NEVER** share the output with anyone who would be unable to see it on their own.
+.. caution:: This method will return the :term:`Delivery Service`'s **PRIVATE** URL signing keys! Be wary of using this endpoint and **NEVER** share the output with anyone who would be unable to see it on their own.
:Auth. Required: Yes
:Roles Required: None
@@ -35,15 +35,15 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +-------+----------------------------------------------+
- | Name | Description |
- +=======+==============================================+
- | xmlid | The 'xml_id' of the desired Delivery Service |
- +-------+----------------------------------------------+
+ +-------+------------------------------------------------------+
+ | Name | Description |
+ +=======+======================================================+
+ | xmlid | The 'xml_id' of the desired :term:`Delivery Service` |
+ +-------+------------------------------------------------------+
Response Structure
------------------
-:key<N>: The private URL signing key for this Delivery Service as a base-64-encoded string, where ``<N>`` is the "generation" of the key e.g. the first key will always be named ``"key0"``. Up to 16 concurrent generations are retained at any time (``<N>`` is always on the interval [0,16])
+:key<N>: The private URL signing key for this :term:`Delivery Service` as a base-64-encoded string, where ``<N>`` is the "generation" of the key e.g. the first key will always be named ``"key0"``. Up to 16 concurrent generations are retained at any time (``<N>`` is always on the interval [0,16])
.. code-block:: json
:caption: Response Example
diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst
index b40c53c..b1c308d 100644
--- a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst
+++ b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_copyfromxmlid_copyfromxmlid.rst
@@ -21,7 +21,7 @@
``POST``
========
-Allows a user to copy URL signing keys from a specified Delivery Service to another Delivery Service.
+Allows a user to copy URL signing keys from a specified :term:`Delivery Service` to another :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -31,13 +31,13 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +-----------------+-----------------------------------------------------------------------+
- | Name | Description |
- +=================+=======================================================================+
- | xml_id | The 'xml_id' of the Delivery Service *to* which keys will be copied |
- +-----------------+-----------------------------------------------------------------------+
- | copyFrom_xml_id | The 'xml_id' of the Delivery Service *from* which keys will be copied |
- +-----------------+-----------------------------------------------------------------------+
+ +-----------------+-------------------------------------------------------------------------------+
+ | Name | Description |
+ +=================+===============================================================================+
+ | xml_id | The 'xml_id' of the :term:`Delivery Service` *to* which keys will be copied |
+ +-----------------+-------------------------------------------------------------------------------+
+ | copyFrom_xml_id | The 'xml_id' of the :term:`Delivery Service` *from* which keys will be copied |
+ +-----------------+-------------------------------------------------------------------------------+
Response Structure
------------------
diff --git a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst
index 2000520..12e9496 100644
--- a/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst
+++ b/docs/source/api/deliveryservices_xmlid_xmlid_urlkeys_generate.rst
@@ -23,7 +23,7 @@
``POST``
========
-Generates URL signing keys for a Delivery Service
+Generates URL signing keys for a :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -33,11 +33,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +--------+----------------------------------------------+
- | Name | Description |
- +========+==============================================+
- | xml_id | The 'xml_id' of the desired Delivery Service |
- +--------+----------------------------------------------+
+ +--------+------------------------------------------------------+
+ | Name | Description |
+ +========+======================================================+
+ | xml_id | The 'xml_id' of the desired :term:`Delivery Service` |
+ +--------+------------------------------------------------------+
Response Structure
------------------
diff --git a/docs/source/api/deliveryserviceserver.rst b/docs/source/api/deliveryserviceserver.rst
index e3d2dc8..996c5c5 100644
--- a/docs/source/api/deliveryserviceserver.rst
+++ b/docs/source/api/deliveryserviceserver.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieve information about the assignment of servers to Delivery Services
+Retrieve information about the assignment of servers to :term:`Delivery Service`\ s
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -59,11 +59,11 @@ Unlike most API endpoints, this will return a JSON response body containing both
:limit: The maximum size of the ``response`` array, also indicative of the number of results per page using the pagination requested by the query parameters (if any) - this should be the same as the ``limit`` query parameter (if given)
:orderby: A string that names the field by which the elements of the ``response`` array are ordered - should be the same as the ``orderby`` request query parameter (if given)
-:response: An array of objects, each of which represents a server's Delivery Service assignment
+:response: An array of objects, each of which represents a server's :term:`Delivery Service` assignment
- :deliveryService: The integral, unique identifier of the Delivery Service to which the server identified by ``server`` is assigned
- :lastUpdated: The date and time at which the server's assignment to a Delivery Service was last updated
- :server: The integral, unique identifier of a server which is assigned to the Delivery Service identified by ``deliveryService``
+ :deliveryService: The integral, unique identifier of the :term:`Delivery Service` to which the server identified by ``server`` is assigned
+ :lastUpdated: The date and time at which the server's assignment to a :term:`Delivery Service` was last updated
+ :server: The integral, unique identifier of a server which is assigned to the :term:`Delivery Service` identified by ``deliveryService``
:size: The page number - if pagination was requested in the query parameters, else ``0`` to indicate no pagination - of the results represented by the ``response`` array. This is named "size" for legacy reasons
@@ -99,7 +99,7 @@ Unlike most API endpoints, this will return a JSON response body containing both
``POST``
========
-Assign a set of one or more servers to a Delivery Service
+Assign a set of one or more servers to a :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [2]_
@@ -107,9 +107,9 @@ Assign a set of one or more servers to a Delivery Service
Request Structure
-----------------
-:deliveryService: The integral, unique identifier of the Delivery Service to which the servers identified in the ``servers`` array will be assigned
+:deliveryService: The integral, unique identifier of the :term:`Delivery Service` to which the servers identified in the ``servers`` array will be assigned
:replace: If ``true``, any existing assignments for a server identified in the ``servers`` array will be overwritten by this request
-:servers: An array of integral, unique identifiers for servers which are to be assigned to the Delivery Service identified by ``deliveryService``
+:servers: An array of integral, unique identifiers for servers which are to be assigned to the :term:`Delivery Service` identified by ``deliveryService``
.. code-block:: http
:caption: Request Example
@@ -126,9 +126,9 @@ Request Structure
Response Structure
------------------
-:deliveryService: The integral, unique identifier of the Delivery Service to which the servers identified by the elements of the ``servers`` array have been assigned
+:deliveryService: The integral, unique identifier of the :term:`Delivery Service` to which the servers identified by the elements of the ``servers`` array have been assigned
:replace: If ``true``, any existing assignments for a server identified in the ``servers`` array have been overwritten by this request
-:servers: An array of integral, unique identifiers for servers which have been assigned to the Delivery Service identified by ``deliveryService``
+:servers: An array of integral, unique identifiers for servers which have been assigned to the :term:`Delivery Service` identified by ``deliveryService``
.. code-block:: http
:caption: Response Example
@@ -158,4 +158,4 @@ Response Structure
}}
-.. [2] Users with the "admin" or "operations" roles will be able to modify ALL server-to-Delivery-Service assignments, whereas all other users can only assign servers to the Delivery Services their Tenant has permissions to edit.
+.. [2] Users with the "admin" or "operations" roles will be able to modify ALL server-to-Delivery-Service assignments, whereas all other users can only assign servers to the :term:`Delivery Service`\ s their Tenant has permissions to edit.
diff --git a/docs/source/api/federations.rst b/docs/source/api/federations.rst
index 1ce319a..46bc41a 100644
--- a/docs/source/api/federations.rst
+++ b/docs/source/api/federations.rst
@@ -33,7 +33,7 @@ No parameters available.
Response Structure
------------------
-:deliveryService: The ``xml_id`` that uniquely identifies the Delivery Service that uses the federation mappings in ``mappings``
+:deliveryService: The ``xml_id`` that uniquely identifies the :term:`Delivery Service` that uses the federation mappings in ``mappings``
:mappings: An array of objects that represent the mapping of a federation's Canonical Name (CNAME) to one or more resolvers
:cname: The actual CNAME used by the federation
@@ -77,9 +77,9 @@ Response Structure
``POST``
========
-Allows a user to create federation resolvers for Delivery Services, providing the Delivery Service is within a CDN that has some associated federation.
+Allows a user to create federation resolvers for :term:`Delivery Service`\ s, providing the :term:`Delivery Service` is within a CDN that has some associated federation.
-.. warning:: Confusingly, this endpoint does **not** create a new federation; to do that, the :ref:`to-api-cdns-name-federations` endpoint must be used. Furthermore, the federation must properly be assigned to a Delivery Service using the :ref:`to-api-federations-id-deliveryservices` and assigned to the user creating resolvers using :ref:`to-api-federations-id-users`.
+.. warning:: Confusingly, this endpoint does **not** create a new federation; to do that, the :ref:`to-api-cdns-name-federations` endpoint must be used. Furthermore, the federation must properly be assigned to a :term:`Delivery Service` using the :ref:`to-api-federations-id-deliveryservices` and assigned to the user creating resolvers using :ref:`to-api-federations-id-users`.
.. seealso:: The :ref:`to-api-federations-id-federation_resolvers` endpoint duplicates this functionality.
@@ -89,13 +89,13 @@ Allows a user to create federation resolvers for Delivery Services, providing th
Request Structure
-----------------
-:federations: The top-level key that must exist - an array of objects that each describe a set of resolvers for a Delivery Service's federation
+:federations: The top-level key that must exist - an array of objects that each describe a set of resolvers for a :term:`Delivery Service`'s federation
- :deliveryService: The 'xml_id' of the Delivery Service which will use the federation resolvers specified in ``mappings``
+ :deliveryService: The 'xml_id' of the :term:`Delivery Service` which will use the federation resolvers specified in ``mappings``
:mappings: An object containing two arrays of IP addresses to use as federation resolvers
- :resolve4: An array of IPv4 addresses that can resolve the Delivery Service's federation
- :resolve6: An array of IPv6 addresses that can resolve the Delivery Service's federation
+ :resolve4: An array of IPv4 addresses that can resolve the :term:`Delivery Service`'s federation
+ :resolve6: An array of IPv6 addresses that can resolve the :term:`Delivery Service`'s federation
.. code-block:: http
:caption: Request Example
@@ -174,7 +174,7 @@ Response Structure
``PUT``
=======
-Replaces **all** federations associated with a user's Delivery Service(s) with those defined inside the request payload.
+Replaces **all** federations associated with a user's :term:`Delivery Service`\ (s) with those defined inside the request payload.
:Auth. Required: Yes
:Roles Required: "admin", "Federation", "operations", "Portal", or "Steering"
@@ -182,13 +182,13 @@ Replaces **all** federations associated with a user's Delivery Service(s) with t
Request Structure
-----------------
-:federations: The top-level key that must exist - an array of objects that each describe a set of resolvers for a Delivery Service's federation
+:federations: The top-level key that must exist - an array of objects that each describe a set of resolvers for a :term:`Delivery Service`'s federation
- :deliveryService: The 'xml_id' of the Delivery Service which will use the federation resolvers specified in ``mappings``
+ :deliveryService: The 'xml_id' of the :term:`Delivery Service` which will use the federation resolvers specified in ``mappings``
:mappings: An object containing two arrays of IP addresses to use as federation resolvers
- :resolve4: An array of IPv4 addresses that can resolve the Delivery Service's federation
- :resolve6: An array of IPv6 addresses that can resolve the Delivery Service's federation
+ :resolve4: An array of IPv4 addresses that can resolve the :term:`Delivery Service`'s federation
+ :resolve6: An array of IPv6 addresses that can resolve the :term:`Delivery Service`'s federation
.. code-block:: http
:caption: Request Example
diff --git a/docs/source/api/federations_id_deliveryservices.rst b/docs/source/api/federations_id_deliveryservices.rst
index 32f76e4..6f19164 100644
--- a/docs/source/api/federations_id_deliveryservices.rst
+++ b/docs/source/api/federations_id_deliveryservices.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves Delivery Services assigned to a federation.
+Retrieves :term:`Delivery Service`\ s assigned to a federation.
:Auth. Required: Yes
:Roles Required: None
@@ -48,10 +48,10 @@ Request Structure
Response Structure
------------------
-:cdn: The CDN to which this Delivery Service Belongs
+:cdn: The CDN to which this :term:`Delivery Service` Belongs
:id: The integral, unique identifier for the Deliver Service
-:type: The routing type used by this Delivery Service
-:xmlId: The 'xml_id' which uniquely identifies this Delivery Service
+:type: The routing type used by this :term:`Delivery Service`
+:xmlId: The 'xml_id' which uniquely identifies this :term:`Delivery Service`
.. code-block:: http
:caption: Response Example
@@ -81,7 +81,7 @@ Response Structure
``POST``
========
-Assigns one or more Delivery Services to a federation.
+Assigns one or more :term:`Delivery Service`\ s to a federation.
:Auth. Required: Yes
:Roles Required: "admin"
@@ -97,7 +97,7 @@ Request Structure
| ID | The integral, unique identifier for the federation to be inspected |
+------+--------------------------------------------------------------------+
-:dsIds: An array of integral, unique identifiers for Delivery Services which will be assigned to this federation
+:dsIds: An array of integral, unique identifiers for :term:`Delivery Service`\ s which will be assigned to this federation
:replace: An optional boolean (default: ``false``) which, if ``true``, will cause any conflicting assignments already in place to be overridden by this request
.. note:: If ``replace`` is not given (and/or not ``true``), then any conflicts with existing assignments will cause the entire operation to fail.
@@ -120,7 +120,7 @@ Request Structure
Response Structure
------------------
-:dsIds: An array of integral, unique identifiers for Delivery Services which are now assigned to this federation
+:dsIds: An array of integral, unique identifiers for :term:`Delivery Service`\ s which are now assigned to this federation
:replace: An optional boolean (default: ``false``) which, if ``true``, means any conflicting assignments already in place were overridden by this request
.. code-block:: http
diff --git a/docs/source/api/federations_id_deliveryservices_id.rst b/docs/source/api/federations_id_deliveryservices_id.rst
index a12f71b..58edb2a 100644
--- a/docs/source/api/federations_id_deliveryservices_id.rst
+++ b/docs/source/api/federations_id_deliveryservices_id.rst
@@ -21,7 +21,7 @@
``DELETE``
==========
-Removes a Delivery Service from a federation. A Delivery Service cannot be removed from a federation if it is the only Delivery Service assigned to said federation
+Removes a :term:`Delivery Service` from a federation. A :term:`Delivery Service` cannot be removed from a federation if it is the only :term:`Delivery Service` assigned to said federation
:Auth. Required: Yes
:Roles Required: "admin"
@@ -31,13 +31,13 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+--------------------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +======+==========================================================================================================================+
- | ID | The integral, unique identifier of the federation from which the Delivery Service identified by ``dsID`` will be removed |
- +------+--------------------------------------------------------------------------------------------------------------------------+
- | dsID | The integral, unique identifier of the Delivery Service which will be removed from the federation identified by ``ID`` |
- +------+--------------------------------------------------------------------------------------------------------------------------+
+ +------+----------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+==================================================================================================================================+
+ | ID | The integral, unique identifier of the federation from which the :term:`Delivery Service` identified by ``dsID`` will be removed |
+ +------+----------------------------------------------------------------------------------------------------------------------------------+
+ | dsID | The integral, unique identifier of the :term:`Delivery Service` which will be removed from the federation identified by ``ID`` |
+ +------+----------------------------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
diff --git a/docs/source/api/jobs.rst b/docs/source/api/jobs.rst
index 363650c..43ffba5 100644
--- a/docs/source/api/jobs.rst
+++ b/docs/source/api/jobs.rst
@@ -33,15 +33,15 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +--------+----------+--------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description |
- +========+==========+==============================================================================================================+
- | dsId | no | Return only invalidation jobs pending on the Delivery Service identified by this integral, unique identifier |
- +--------+----------+--------------------------------------------------------------------------------------------------------------+
- | userId | no | Return only invalidation jobs created by the user identified by this integral, unique identifier |
- +--------+----------+--------------------------------------------------------------------------------------------------------------+
+ +--------+----------+----------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +========+==========+======================================================================================================================+
+ | dsId | no | Return only invalidation jobs pending on the :term:`Delivery Service` identified by this integral, unique identifier |
+ +--------+----------+----------------------------------------------------------------------------------------------------------------------+
+ | userId | no | Return only invalidation jobs created by the user identified by this integral, unique identifier |
+ +--------+----------+----------------------------------------------------------------------------------------------------------------------+
-.. note:: If the ``dsId`` parameter is given, an error will be returned if the thereby identified Delivery Service is not visible to the logged-in user's Tenant
+.. note:: If the ``dsId`` parameter is given, an error will be returned if the thereby identified :term:`Delivery Service` is not visible to the logged-in user's Tenant
.. code-block:: http
:caption: Request Example
@@ -56,7 +56,7 @@ Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon according to ``keyword``
:createdBy: The username of the user who initiated the job
-:deliveryService: The 'xml_id' that uniquely identifies the Delivery Service on which this job operates
+:deliveryService: The 'xml_id' that uniquely identifies the :term:`Delivery Service` on which this job operates
:id: An integral, unique identifier for this job
:keyword: A keyword that represents the operation being performed by the job:
diff --git a/docs/source/api/jobs_id.rst b/docs/source/api/jobs_id.rst
index 7f6c9cf..0151f26 100644
--- a/docs/source/api/jobs_id.rst
+++ b/docs/source/api/jobs_id.rst
@@ -41,7 +41,7 @@ Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon according to ``keyword``
:createdBy: The username of the user who initiated the job
-:deliveryService: The 'xml_id' that uniquely identifies the Delivery Service on which this job operates
+:deliveryService: The 'xml_id' that uniquely identifies the :term:`Delivery Service` on which this job operates
:id: An integral, unique identifier for this job
:keyword: A keyword that represents the operation being performed by the job:
diff --git a/docs/source/api/origins.rst b/docs/source/api/origins.rst
index 8b529d1..ece78f9 100644
--- a/docs/source/api/origins.rst
+++ b/docs/source/api/origins.rst
@@ -22,7 +22,7 @@
``GET``
=======
-Gets all requested origins.
+Gets all requested :term:`origin`\ s.
:Auth. Required: Yes
:Roles Required: None
@@ -32,26 +32,26 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description |
- +=================+==========+======================================================================================================================================================================================+
- | cachegroup | no | Return only origins within the :term:`Cache Group` identified by this integral, unique identifier |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | coordinate | no | Return only origins located at the geographic coordinates identified by this integral, unique identifier |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | deliveryservice | no | Return only origins that belong to the Delivery Service identified by this integral, unique identifier |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | id | no | Return only the origin that has this integral, unique identifier |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | name | no | Return only origins by this name |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | profileId | no | Return only origins which use the profile identified by this integral, unique identifier |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | primary | no | If ``true``, return only origins which are the the primary origin of the Delivery Service to which they belong - if ``false`` return only origins which are *not* the primary origin |
- | | | of the Delivery Service to which they belong |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | tenant | no | Return only origins belonging to the tenant identified by this integral, unique identifier |
- +-----------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +=================+==========+=====================================================================================================================================================================+
+ | cachegroup | no | Return only :term:`origin`\ s within the :term:`Cache Group` identified by this integral, unique identifier |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | coordinate | no | Return only :term:`origin`\ s located at the geographic coordinates identified by this integral, unique identifier |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | deliveryservice | no | Return only :term:`origin`\ s that belong to the :term:`Delivery Service` identified by this integral, unique identifier |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the :term:`origin` that has this integral, unique identifier |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | name | no | Return only :term:`origin`\ s by this name |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only :term:`origin`\ s which use the :term:`Profile` identified by this integral, unique identifier |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | primary | no | If ``true``, return only :term:`origin`\ s which are the the primary :term:`origin` of the :term:`Delivery Service` to which they belong - if ``false`` return only |
+ | | | :term:`origin`\ s which are *not* the primary :term:`origin` of the :term:`Delivery Service` to which they belong |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+ | tenant | no | Return only :term:`origin`\ s belonging to the tenant identified by this integral, unique identifier |
+ +-----------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. note:: Several fields of origin definitions which are filterable by Query Parameters are allowed to be ``null``. ``null`` values in these fields will be filtered *out* appropriately by such Query Parameters, but do note that ``null`` is not a valid value accepted by any of these Query Parameters, and attempting to pass it will result in an error.
@@ -66,25 +66,25 @@ Request Structure
Response Structure
------------------
-:cachegroup: The name of the :term:`Cache Group` to which the origin belongs
-:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the origin belongs
+:cachegroup: The name of the :term:`Cache Group` to which the :term:`origin` belongs
+:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the :term:`origin` belongs
:coordinate: The name of a coordinate pair that defines the origin's geographic location
-:coordinateID: An integral, unique identifier for the coordinate pair that defines the origin's geographic location
-:deliveryService: The 'xml_id' of the Delivery Service to which the origin belongs
-:deliveryServiceId: An integral, unique identifier for the Delivery Service to which the origin belongs
-:fqdn: The FQDN of the origin
-:id: An integral, unique identifier for this origin
-:ip6Address: The IPv6 address of the Origin
-:ipAddress: The IPv4 address of the Origin
-:isPrimary: A boolean value which, when ``true`` specifies this origin as the 'primary' origin served by ``deliveryService``
-:lastUpdated: The date and time at which this origin was last modified
-:name: The name of the origin
-:port: The TCP port on which the origin listens
-:profile: The name of the profile used by this origin
-:profileId: An integral, unique identifier for the profile used by this origin
+:coordinateID: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location
+:deliveryService: The 'xml_id' of the :term:`Delivery Service` to which the :term:`origin` belongs
+:deliveryServiceId: An integral, unique identifier for the :term:`Delivery Service` to which the :term:`origin` belongs
+:fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin`
+:id: An integral, unique identifier for this :term:`origin`
+:ip6Address: The IPv6 address of the :term:`Origin`
+:ipAddress: The IPv4 address of the :term:`Origin`
+:isPrimary: A boolean value which, when ``true`` specifies this :term:`origin` as the 'primary' :term:`origin` served by ``deliveryService``
+:lastUpdated: The date and time at which this :term:`origin` was last modified
+:name: The name of the :term:`origin`
+:port: The TCP port on which the :term:`origin` listens
+:profile: The name of the :term:`Profile` used by this :term:`origin`
+:profileId: An integral, unique identifier for the :term:`Profile` used by this :term:`origin`
:protocol: The protocol used by this origin - will be one of 'http' or 'https'
-:tenant: The name of the tenant that owns this origin
-:tenantId: An integral, unique identifier for the tenant that owns this origin
+:tenant: The name of the :term:`Tenant` that owns this :term:`origin`
+:tenantId: An integral, unique identifier for the :term:`Tenant` that owns this :term:`origin`
.. code-block:: http
:caption: Response Example
@@ -129,7 +129,7 @@ Response Structure
========
Creates a new origin definition.
-.. warning:: At the time of this writing it is possible to create and/or modify origin definitions assigned to STEERING and CLIENT_STEERING Delivery Services - despite that an origin has no meaning in those contexts. In these cases, the API responses may give incorrect output - see `GitHub Issue #3107 <https://github.com/apache/trafficcontrol/issues/3107>`_ for details and updates.
+.. warning:: At the time of this writing it is possible to create and/or modify origin definitions assigned to STEERING and CLIENT_STEERING :term:`Delivery Service`\ s - despite that an origin has no meaning in those contexts. In these cases, the API responses may give incorrect output - see `GitHub Issue #3107 <https://github.com/apache/trafficcontrol/issues/3107>`_ for details and updates.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -137,21 +137,21 @@ Creates a new origin definition.
Request Structure
-----------------
-:cachegroupId: An optional, integral, unique identifier that identifies a :term:`Cache Group` to which the new origin shall belong
-:coordinateID: An optional, integral, unique identifier of a coordinate pair that shall define the origin's geographic location
-:deliveryServiceId: The integral, unique identifier of the Delivery Service to which the new origin shall belong
-:fqdn: The Fully Qualified Domain Name (FQDN) of the origin
-:ip6Address: An optional string containing the IPv6 address of the origin
-:ipAddress: An optional string containing the IPv4 address of the origin
-:isPrimary: An optional boolean which, if ``true`` will set this origin as the 'primary' origin served by the Delivery Service identified by ``deliveryServiceID``
+:cachegroupId: An optional, integral, unique identifier that identifies a :term:`Cache Group` to which the new :term:`origin` shall belong
+:coordinateID: An optional, integral, unique identifier of a coordinate pair that shall define the :term:`origin`'s geographic location
+:deliveryServiceId: The integral, unique identifier of the :term:`Delivery Service` to which the new :term:`origin` shall belong
+:fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin`
+:ip6Address: An optional string containing the IPv6 address of the :term:`origin`
+:ipAddress: An optional string containing the IPv4 address of the :term:`origin`
+:isPrimary: An optional boolean which, if ``true`` will set this :term:`origin` as the 'primary' :term:`origin` served by the :term:`Delivery Service` identified by ``deliveryServiceID``
.. note:: Though not specifying this field in this request will leave it as ``null`` in the output, Traffic Ops will silently coerce that to its default value: ``false``.
-:name: A human-friendly name of the Origin
-:port: An optional port number on which the origin listens for incoming TCP connections
-:profileId: An optional, integral, unique identifier for a profile that the new origin shall use
+:name: A human-friendly name of the :term:`Origin`
+:port: An optional port number on which the :term:`origin` listens for incoming TCP connections
+:profileId: An optional, integral, unique identifier for a :term:`Profile` that the new :term:`origin` shall use
:protocol: The protocol used by the origin - must be one of 'http' or 'https'
-:tenantId: An optional\ [1]_, integral, unique identifier for the tenant which shall own the new origin
+:tenantId: An optional\ [1]_, integral, unique identifier for the :term:`Tenant` which shall own the new :term:`origin`
.. code-block:: http
:caption: Request Example
@@ -177,25 +177,25 @@ Request Structure
Response Structure
------------------
-:cachegroup: The name of the :term:`Cache Group` to which the origin belongs
-:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the origin belongs
+:cachegroup: The name of the :term:`Cache Group` to which the :term:`origin` belongs
+:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the :term:`origin` belongs
:coordinate: The name of a coordinate pair that defines the origin's geographic location
-:coordinateID: An integral, unique identifier for the coordinate pair that defines the origin's geographic location
-:deliveryService: The 'xml_id' of the Delivery Service to which the origin belongs
-:deliveryServiceId: An integral, unique identifier for the Delivery Service to which the origin belongs
-:fqdn: The FQDN of the origin
-:id: An integral, unique identifier for this origin
-:ip6Address: The IPv6 address of the Origin
-:ipAddress: The IPv4 address of the Origin
-:isPrimary: A boolean value which, when ``true`` specifies this origin as the 'primary' origin served by ``deliveryService``
-:lastUpdated: The date and time at which this origin was last modified
-:name: The name of the origin
-:port: The TCP port on which the origin listens
-:profile: The name of the profile used by this origin
-:profileId: An integral, unique identifier for the profile used by this origin
+:coordinateID: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location
+:deliveryService: The 'xml_id' of the :term:`Delivery Service` to which the :term:`origin` belongs
+:deliveryServiceId: An integral, unique identifier for the :term:`Delivery Service` to which the :term:`origin` belongs
+:fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin`
+:id: An integral, unique identifier for this :term:`origin`
+:ip6Address: The IPv6 address of the :term:`Origin`
+:ipAddress: The IPv4 address of the :term:`Origin`
+:isPrimary: A boolean value which, when ``true`` specifies this :term:`origin` as the 'primary' :term:`origin` served by ``deliveryService``
+:lastUpdated: The date and time at which this :term:`origin` was last modified
+:name: The name of the :term:`origin`
+:port: The TCP port on which the :term:`origin` listens
+:profile: The name of the :term:`Profile` used by this :term:`origin`
+:profileId: An integral, unique identifier for the :term:`Profile` used by this :term:`origin`
:protocol: The protocol used by this origin - will be one of 'http' or 'https'
-:tenant: The name of the tenant that owns this origin
-:tenantId: An integral, unique identifier for the tenant that owns this origin
+:tenant: The name of the :term:`Tenant` that owns this :term:`origin`
+:tenantId: An integral, unique identifier for the :term:`Tenant` that owns this :term:`origin`
.. code-block:: http
:caption: Response Example
@@ -242,7 +242,7 @@ Response Structure
``PUT``
=======
-Updates an origin definition.
+Updates an :term:`origin` definition.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -252,24 +252,24 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +------+----------+-----------------------------------------------------------------------+
- | Name | Required | Description |
- +======+==========+=======================================================================+
- | id | yes | The integral, unique identifier of the origin definition being edited |
- +------+----------+-----------------------------------------------------------------------+
-
-:cachegroupId: An optional, integral, unique identifier that identifies a :term:`Cache Group` to which the new origin shall belong
-:coordinateID: An optional, integral, unique identifier of a coordinate pair that shall define the origin's geographic location
-:deliveryServiceId: The integral, unique identifier of the Delivery Service to which the new origin shall belong
-:fqdn: The Fully Qualified Domain Name (FQDN) of the origin
-:ip6Address: An optional string containing the IPv6 address of the origin
-:ipAddress: An optional string containing the IPv4 address of the origin
-:isPrimary: An optional boolean which, if ``true`` will set this origin as the 'primary' origin served by the Delivery Service identified by ``deliveryServiceID``
-:name: A human-friendly name of the Origin
-:port: An optional port number on which the origin listens for incoming TCP connections
-:profileId: An optional, integral, unique identifier for a profile that the new origin shall use
-:protocol: The protocol used by the origin - must be one of 'http' or 'https'
-:tenantId: An optional\ [1]_, integral, unique identifier for the tenant which shall own the new origin
+ +------+----------+-------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+===============================================================================+
+ | id | yes | The integral, unique identifier of the :term:`origin` definition being edited |
+ +------+----------+-------------------------------------------------------------------------------+
+
+:cachegroupId: An optional, integral, unique identifier that identifies a :term:`Cache Group` to which the :term:`origin` shall belong
+:coordinateID: An optional, integral, unique identifier of a coordinate pair that shall define the :term:`origin`'s geographic location
+:deliveryServiceId: The integral, unique identifier of the :term:`Delivery Service` to which the :term:`origin` shall belong
+:fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin`
+:ip6Address: An optional string containing the IPv6 address of the :term:`origin`
+:ipAddress: An optional string containing the IPv4 address of the :term:`origin`
+:isPrimary: An optional boolean which, if ``true`` will set this :term:`origin` as the 'primary' origin served by the :term:`Delivery Service` identified by ``deliveryServiceID``
+:name: A human-friendly name of the :term:`Origin`
+:port: An optional port number on which the :term:`origin` listens for incoming TCP connections
+:profileId: An optional, integral, unique identifier for a :term:`Profile` that the new :term:`origin` shall use
+:protocol: The protocol used by the :term:`origin` - must be one of 'http' or 'https'
+:tenantId: An optional\ [1]_, integral, unique identifier for the :term:`Tenant` which shall own the new :term:`origin`
.. code-block:: http
:caption: Request Example
@@ -295,25 +295,25 @@ Request Structure
Response Structure
------------------
-:cachegroup: The name of the :term:`Cache Group` to which the origin belongs
-:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the origin belongs
+:cachegroup: The name of the :term:`Cache Group` to which the :term:`origin` belongs
+:cachegroupId: An integral, unique identifier for the :term:`Cache Group` to which the :term:`origin` belongs
:coordinate: The name of a coordinate pair that defines the origin's geographic location
-:coordinateID: An integral, unique identifier for the coordinate pair that defines the origin's geographic location
-:deliveryService: The 'xml_id' of the Delivery Service to which the origin belongs
-:deliveryServiceId: An integral, unique identifier for the Delivery Service to which the origin belongs
-:fqdn: The FQDN of the origin
-:id: An integral, unique identifier for this origin
-:ip6Address: The IPv6 address of the Origin
-:ipAddress: The IPv4 address of the Origin
-:isPrimary: A boolean value which, when ``true`` specifies this origin as the 'primary' origin served by ``deliveryService``
-:lastUpdated: The date and time at which this origin was last modified
-:name: The name of the origin
-:port: The TCP port on which the origin listens
-:profile: The name of the profile used by this origin
-:profileId: An integral, unique identifier for the profile used by this origin
+:coordinateID: An integral, unique identifier for the coordinate pair that defines the :term:`origin`'s geographic location
+:deliveryService: The 'xml_id' of the :term:`Delivery Service` to which the :term:`origin` belongs
+:deliveryServiceId: An integral, unique identifier for the :term:`Delivery Service` to which the :term:`origin` belongs
+:fqdn: The :abbr:`FQDN (Fully Qualified Domain Name)` of the :term:`origin`
+:id: An integral, unique identifier for this :term:`origin`
+:ip6Address: The IPv6 address of the :term:`Origin`
+:ipAddress: The IPv4 address of the :term:`Origin`
+:isPrimary: A boolean value which, when ``true`` specifies this :term:`origin` as the 'primary' :term:`origin` served by ``deliveryService``
+:lastUpdated: The date and time at which this :term:`origin` was last modified
+:name: The name of the :term:`origin`
+:port: The TCP port on which the :term:`origin` listens
+:profile: The name of the :term:`Profile` used by this :term:`origin`
+:profileId: An integral, unique identifier for the :term:`Profile` used by this :term:`origin`
:protocol: The protocol used by this origin - will be one of 'http' or 'https'
-:tenant: The name of the tenant that owns this origin
-:tenantId: An integral, unique identifier for the tenant that owns this origin
+:tenant: The name of the :term:`Tenant` that owns this :term:`origin`
+:tenantId: An integral, unique identifier for the :term:`Tenant` that owns this :term:`origin`
.. code-block:: http
:caption: Response Example
@@ -360,7 +360,7 @@ Response Structure
``DELETE``
==========
-Deletes an origin definition.
+Deletes an :term:`origin` definition.
:Auth. Required: Yes
:Roles Required: "admin" or "operations"
@@ -370,11 +370,11 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +------+----------+------------------------------------------------------------------------+
- | Name | Required | Description |
- +======+==========+========================================================================+
- | id | yes | The integral, unique identifier of the origin definition being deleted |
- +------+----------+------------------------------------------------------------------------+
+ +------+----------+--------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +======+==========+================================================================================+
+ | id | yes | The integral, unique identifier of the :term:`origin` definition being deleted |
+ +------+----------+--------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
diff --git a/docs/source/api/servers.rst b/docs/source/api/servers.rst
index 0cb0ad5..614c85f 100644
--- a/docs/source/api/servers.rst
+++ b/docs/source/api/servers.rst
@@ -31,23 +31,23 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
- | Name | Required | Description |
- +============+==========+===========================================================================================================+
- | cachegroup | no | Return only those servers within the cachegroup identified by this integral, unique identifier |
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
- | dsId | no | Return only those servers assigned to the Delivery Service identified by this integral, unique identifier |
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
- | hostName | no | Return only those servers that have this (short) hostname |
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
- | id | no | Return only the server with this integral, unique identifier |
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
- | profileId | no | Return only those servers that are using the profile identified by this integral, unique identifier |
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
- | status | no | Return only those servers with this status - see :ref:`health-proto` |
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
- | type | no | Return only servers of this 'type' |
- +------------+----------+-----------------------------------------------------------------------------------------------------------+
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +============+==========+===================================================================================================================+
+ | cachegroup | no | Return only those servers within the :term:`Cache Group` identified by this integral, unique identifier |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only those servers assigned to the :term:`Delivery Service` identified by this integral, unique identifier |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | hostName | no | Return only those servers that have this (short) hostname |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the server with this integral, unique identifier |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | profileId | no | Return only those servers that are using the profile identified by this integral, unique identifier |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | status | no | Return only those servers with this status - see :ref:`health-proto` |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only servers of this 'type' |
+ +------------+----------+-------------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
diff --git a/docs/source/api/servers_hostname_name_details.rst b/docs/source/api/servers_hostname_name_details.rst
index 2290249..ee8e2aa 100644
--- a/docs/source/api/servers_hostname_name_details.rst
+++ b/docs/source/api/servers_hostname_name_details.rst
@@ -43,7 +43,7 @@ Response Structure
------------------
:cachegroup: The name of the Cache Group to which this server belongs
:cdnName: Name of the CDN to which the server belongs
-:deliveryservices: An array of integral, unique identifiers for Delivery Services to which this server belongs
+:deliveryservices: An array of integral, unique identifiers for :term:`Delivery Service`\ s to which this server belongs
:domainName: The domain part of the server's Fully Qualified Domain Name (FQDN)
:guid: An identifier used to uniquely identify the server
diff --git a/docs/source/api/servers_hostname_update_status.rst b/docs/source/api/servers_hostname_update_status.rst
new file mode 100644
index 0000000..2a4463d
--- /dev/null
+++ b/docs/source/api/servers_hostname_update_status.rst
@@ -0,0 +1,96 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-hostname-update_status:
+
+**************************************
+``servers/{{hostname}}/update_status``
+**************************************
+.. versionadded:: 1.3
+
+.. note:: This endpoint only truly has meaning for :term:`cache server`\ s, though it will return a valid response for any server configured in Traffic Ops.
+
+``GET``
+=======
+Retrieves information regarding pending updates and revalidation jobs for a given server
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: ``undefined`` - this endpoint will return a top-level array containing the response, as opposed to within a ``response`` object
+
+Request Structure
+-----------------
+.. table:: Request Path Parameters
+
+ +----------+----------------------------------------------------+
+ | Name | Description |
+ +==========+====================================================+
+ | hostname | The (short) hostname of the server being inspected |
+ +----------+----------------------------------------------------+
+
+.. code-block:: http
+ :caption: Request Example
+
+ GET /api/1.4/servers/edge/update_status HTTP/1.1
+ Host: trafficops.infra.ciab.test
+ User-Agent: curl/7.47.0
+ Accept: */*
+ Cookie: mojolicious=...
+
+Response Structure
+------------------
+Each object in the returned array\ [1]_ will contain the following fields:
+
+:host_id: The integral, unique identifier for the server for which the other fields in this object represent the pending updates and revalidation status
+:host_name: The (short) hostname of the server for which the other fields in this object represent the pending updates and revalidation status
+:parent_pending: A boolean telling whether or not the :term:`parent`\ s of this server have pending updates
+:parent_reval_pending: A boolean telling whether or not the :term:`parent`\ s of this server have pending revalidation jobs
+:reval_pending: ``true`` if the server has pending revalidation jobs, ``false`` otherwise
+:status: The name of the status of this server
+
+ .. seealso:: :ref:`health-proto` gives more information on how these statuses are used, and the ``GET`` method of the :ref:`to-api-statuses` endpoint can be used to retrieve information about all server statuses configured in Traffic Ops.
+
+:upd_pending: ``true`` if the server has pending updates, ``false`` otherwise
+:use_reval_pending: A boolean which tells :term:`ORT` whether or not this version of Traffic Ops should use pending revalidation jobs
+
+ .. note:: This field was introduced to give :term:`ORT` the ability to work with Traffic Control versions 1.x and 2.x seamlessly - as of Traffic Control v3.0 there is no reason for this field to ever be ``false``.
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
+ Content-Type: application/json
+ Set-Cookie: mojolicious=...; Path=/; HttpOnly
+ Whole-Content-Sha512: R6BjNVrcecHGn3eGDqQ1yDiBnEDGQe7QtOMIsRwlpck9SZR8chRQznrkTF3YdROAZ1l8BxR3fXTIvKHIzK2/dA==
+ X-Server-Name: traffic_ops_golang/
+ Date: Mon, 04 Feb 2019 16:24:01 GMT
+ Content-Length: 174
+
+ [{
+ "host_name": "edge",
+ "upd_pending": false,
+ "reval_pending": false,
+ "use_reval_pending": true,
+ "host_id": 10,
+ "status": "REPORTED",
+ "parent_pending": false,
+ "parent_reval_pending": false
+ }]
+
+.. [1] Despite that the returned object is an array, exactly one server's information is requested and thus returned. That is to say, the array should always have a length of exactly one.
diff --git a/docs/source/api/servers_id_deliveryservices.rst b/docs/source/api/servers_id_deliveryservices.rst
index 4e9e9ac..ae137a6 100644
--- a/docs/source/api/servers_id_deliveryservices.rst
+++ b/docs/source/api/servers_id_deliveryservices.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves all delivery services assigned to a specific server.
+Retrieves all :term:`Delivery Service`\ s assigned to a specific server.
:Auth. Required: Yes
:Roles Required: None
@@ -31,11 +31,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+----------------------------------------------------------------------------------------------------+
- | Name | Description |
- +======+====================================================================================================+
- | ID | The integral, unique identifier of the server for which assigned Delivery Services shall be listed |
- +------+----------------------------------------------------------------------------------------------------+
+ +------+--------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+==============================================================================================================+
+ | ID | The integral, unique identifier of the server for which assigned :term:`Delivery Service`\ s shall be listed |
+ +------+--------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -48,86 +48,88 @@ Request Structure
Response Structure
------------------
-:active: ``true`` if the Delivery Service is active, ``false`` otherwise
-:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
-:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
+:active: ``true`` if the :term:`Delivery Service` is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the :term:`Delivery Service`, ``false`` otherwise
+:cacheurl: A setting for a deprecated feature of now-unsupported :abbr:`ATS (Apache Traffic Server)` versions
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
-:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
-:cdnName: Name of the CDN to which the Delivery Service belongs
-:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
-:displayName: The display name of the Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [3]_
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [3]_
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [3]_
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [3]_
-:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
-:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:ccrDnsTtl: The :abbr:`TTL (Time To Live)` of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
+:cdnId: The integral, unique identifier of the CDN to which the :term:`Delivery Service` belongs
+:cdnName: Name of the CDN to which the :term:`Delivery Service` belongs
+:checkPath: The path portion of the URL to check connections to this :term:`Delivery Service`'s origin server
+:displayName: The display name of the :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [3]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [3]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [3]_
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active\ [3]_
+:dscp: The :abbr:`DSCP (Differentiated Services Code Point)` with which to mark traffic as it leaves the CDN and reaches clients
+:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite :abbr:`ATS (Apache Traffic Server)` plugin
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see :manpage:`tc-fq_codel(8)` for more information) - Linux only
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
0
None - no limitations
1
- Only route when the client's IP is found in the Coverage Zone File (CZF)
+ Only route when the client's IP is found in the :term:`Coverage Zone File`
2
- Only route when the client's IP is found in the CZF, or when the client can be determined to be from the United States of America
+ Only route when the client's IP is found in the :term:`Coverage Zone File`, or when the client can be determined to be from the United States of America
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
0
- The "Maxmind" GeoIP2 database (default)
+ `The "Maxmind" GeoIP2 database (default) <https://www.maxmind.com/en/geoip2-databases>`_
1
- Neustar
-
-:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
-:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:id: An integral, unique identifier for this Delivery Service
-:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
-:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [1]_
-:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [1]_
-:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: A description of the Delivery Service
+ `Neustar GeoPoint IP address database <https://www.security.neustar/digital-performance/ip-intelligence/ip-address-data>`_
+
+ .. warning:: It's not clear whether Neustar databases are actually supported; this is an old option and compatibility may have been broken over time.
+
+:globalMaxMbps: The maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: The maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS :term:`Delivery Service`\ s and to the httpBypassFqdn for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:id: An integral, unique identifier for this :term:`Delivery Service`
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
+:initialDispersion: The number of :term:`cache server`\ s between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [1]_
+:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier :term:`cache server`; if ``false`` all addresses will be IPv4, regardless of the client connection\ [1]_
+:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in a :manpage:`ctime(3)`-like format
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: A description of the :term:`Delivery Service`
:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
-:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The :term:`Type` of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [1]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [1]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
:maxDnsAnswers: The maximum number of IPs to put in responses to A/AAAA DNS record requests (0 means all available)\ [3]_
-:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
-:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [2]_
-:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server
+:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite :abbr:`ATS (Apache Traffic Server)` plugin
+:missLat: The latitude to use when the client cannot be found in the :term:`Coverage Zone File` or a geographic IP lookup
+:missLong: The longitude to use when the client cannot be found in the :term:`Coverage Zone File` or a geographic IP lookup
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [2]_
+:orgServerFqdn: The URL of the :term:`Delivery Service`'s origin server for use in retrieving content from the :term:`origin server`
- .. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
+ .. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's :abbr:`FQDN (Fully Qualified Domain Name)`
-:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
-:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
-:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
-:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [1]_ - this is an integer on the interval [0-2] where the values have these meanings:
+:originShield: An "origin shield" is a forward proxy that sits between Mid-tier :term:`cache server`\ s and the :term:`origin` and performs further caching beyond what's offered by a standard CDN. This field is a string of :abbr:`FQDN (Fully Qualified Domain Name)`\ s to use as origin shields, delimited by ``|``
+:profileDescription: The description of the Traffic Router :term:`Profile` with which this :term:`Delivery Service` is associated
+:profileId: The integral, unique identifier for the Traffic Router :term:`Profile` with which this :term:`Delivery Service` is associated
+:profileName: The name of the Traffic Router :term:`Profile` with which this :term:`Delivery Service` is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server`\ s\ [1]_ - this is an integer on the interval [0-2] where the values have these meanings:
0
HTTP
@@ -136,55 +138,58 @@ Response Structure
2
Both HTTP and HTTPS
-:qstringIgnore: Tells caches whether or not to consider URLs with different query parameter strings to be distinct - this is an integer on the interval [0-2] where the values have these meanings:
+:qstringIgnore: Tells :term:`cache server`\ s whether or not to consider URLs with different query parameter strings to be distinct - this is an integer on the interval [0-2] where the values have these meanings:
0
- URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the origin
+ URLs with different query parameter strings will be considered distinct for caching purposes, and query strings will be passed upstream to the :term:`origin`
1
- URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the origin
+ URLs with different query parameter strings will be considered identical for caching purposes, and query strings will be passed upstream to the :term:`origin`
2
- Query strings are stripped out by Edge-tier caches, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the origin
+ Query strings are stripped out by Edge-tier :term:`cache server`\ s, and thus are neither taken into consideration for caching purposes, nor passed upstream in requests to the :term:`origin`
:rangeRequestHandling: Tells caches how to handle range requests\ [4]_ - this is an integer on the interval [0,2] where the values have these meanings:
0
- Range requests will not be cached, but range requests that request ranges of content already cached will be served from the cache
+ Range requests will not be cached, but range requests that request ranges of content already cached will be served from the :term:`cache server`
1
Use the `background_fetch plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ to service the range request while caching the whole object
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: A regular expression "remap rule" to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
-:remapText: Additional, raw text to add to the remap line for caches
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise
+
+ .. seealso:: See :ref:`regionalgeo-qht` for more information
+
+:remapText: Additional, raw text to add to the line for this :term:`Delivery Service` for :term:`cache server`\ s
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signed: ``true`` if token-based authentication is enabled for this :term:`Delivery Service`, ``false`` otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
-:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This integer indicates the generation of keys in use by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:tenantId: The integral, unique identifier of the :term:`Tenant` who owns this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [1]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [1]_
-:type: The name of the routing type of this Delivery Service e.g. "HTTP"
-:typeId: The integral, unique identifier of the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:type: The name of the routing type of this :term:`Delivery Service` e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons, but is used heavily by Traffic Control components
.. code-block:: http
@@ -261,7 +266,7 @@ Response Structure
}
]}
-.. [1] This only applies to HTTP-routed Delivery Services
+.. [1] This only applies to HTTP-routed :term:`Delivery Service`\ s
.. [2] See :ref:`multi-site-origin`
-.. [3] This only applies to DNS-routed Delivery Services
-.. [4] These fields are required for HTTP-routed and DNS-routed Delivery Services, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP Delivery Services
+.. [3] This only applies to DNS-routed :term:`Delivery Service`\ s
+.. [4] These fields are required for HTTP-routed and DNS-routed :term:`Delivery Service`\ s, but are optional for (and in fact may have no effect on) STEERING and ANY_MAP :term:`Delivery Service`\ s
diff --git a/docs/source/api/servers_status.rst b/docs/source/api/servers_status.rst
new file mode 100644
index 0000000..2d8f155
--- /dev/null
+++ b/docs/source/api/servers_status.rst
@@ -0,0 +1,60 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+.. _to-api-servers-status:
+
+******************
+``servers/status``
+******************
+
+``GET``
+=======
+Retrieves an aggregated view of all server statuses across all CDNs
+
+:Auth. Required: Yes
+:Roles Required: None
+:Response Type: Object
+
+Request Structure
+-----------------
+No parameters available.
+
+Response Structure
+------------------
+:status: Every key in the ``response`` object will be the name of a valid server status, with a value that is the number of servers with that status. If there are no servers with a given status, that status will not appear as a key.
+
+ .. seealso:: :ref:`to-api-statuses` can be queried to retrieve all possible server statuses, as well as to create new statuses or modify existing statuses.
+
+.. code-block:: http
+ :caption: Response Example
+
+ HTTP/1.1 200 OK
+ Access-Control-Allow-Credentials: true
+ Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
+ Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
+ Access-Control-Allow-Origin: *
+ Cache-Control: no-cache, no-store, max-age=0, must-revalidate
+ Content-Type: application/json
+ Date: Mon, 04 Feb 2019 16:22:14 GMT
+ Server: Mojolicious (Perl)
+ Set-Cookie: mojolicious=...; expires=Mon, 04 Feb 2019 20:22:14 GMT; path=/; HttpOnly
+ Vary: Accept-Encoding
+ Whole-Content-Sha512: M072YRXvtNwjnCfntv/W3AsSpOhCl7Cpm0UDznOcXxwwgRYSGXx2MoeovXSNzYim62FJJoQJom1ccRSAW9ZMcA==
+ Content-Length: 38
+
+ { "response": {
+ "REPORTED": 2,
+ "ONLINE": 9
+ }}
diff --git a/docs/source/api/staticdnsentries.rst b/docs/source/api/staticdnsentries.rst
index fe20942..6a3d901 100644
--- a/docs/source/api/staticdnsentries.rst
+++ b/docs/source/api/staticdnsentries.rst
@@ -31,29 +31,29 @@ Request Structure
-----------------
.. table:: Request Query Parameters
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description |
- +===================+==========+====================================================================================================================================+
- | address | no | Return only static DNS entries that operate on this address/Canonical Name (CNAME) |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | cachegroup | no | Return only static DNS entries assigned to this Cache Group |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | cachegroupId | no | Return only static DNS entries assigned to the Cache Group identified by this integral, unique identifier |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | deliveryservice | no | Return only static DNS entries that apply within the domain of the Delivery Service with this 'xml_id' |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | deliveryserviceId | no | Return only static DNS entries that apply within the domain of the Delivery Service identified by this integral, unique identifier |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | host | no | Return only static DNS entries that resolve this Fully Qualified Domain Name (FQDN) |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | id | no | Return only the static DNS entry with this integral, unique identifier |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | ttl | no | Return only static DNS entries with this Time To Live (TTL) |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | type | no | Return only static DNS entries of this type |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
- | typeId | no | Return only static DNS entries of the type identified by this integral, unique identifier |
- +-------------------+----------+------------------------------------------------------------------------------------------------------------------------------------+
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description |
+ +===================+==========+============================================================================================================================================+
+ | address | no | Return only static DNS entries that operate on this address/:abbr:`CNAME (Canonical Name)` |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | cachegroup | no | Return only static DNS entries assigned to this :term:`Cache Group` |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | cachegroupId | no | Return only static DNS entries assigned to the :term:`Cache Group` identified by this integral, unique identifier |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | deliveryservice | no | Return only static DNS entries that apply within the domain of the :term:`Delivery Service` with this 'xml_id' |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | deliveryserviceId | no | Return only static DNS entries that apply within the domain of the :term:`Delivery Service` identified by this integral, unique identifier |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | host | no | Return only static DNS entries that resolve this :abbr:`FQDN (Fully Qualified Domain Name)` |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the static DNS entry with this integral, unique identifier |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | ttl | no | Return only static DNS entries with this :abbr:`TTL (Time To Live)` |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | type | no | Return only static DNS entries of this type |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
+ | typeId | no | Return only static DNS entries of the type identified by this integral, unique identifier |
+ +-------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -75,8 +75,8 @@ Response Structure
.. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons.
-:deliveryservice: The name of a Delivery Service under the domain of which this static DNS entry shall be active
-:deliveryserviceId: The integral, unique identifier of a Delivery Service under the domain of which this static DNS entry shall be active
+:deliveryservice: The name of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
+:deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address``
:id: An integral, unique identifier for this static DNS entry
:ttl: The Time To Live (TTL) of this static DNS entry in seconds
@@ -131,7 +131,7 @@ Request Structure
.. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons.
-:deliveryserviceId: The integral, unique identifier of a Delivery Service under the domain of which this static DNS entry shall be active
+:deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address``
:ttl: The Time To Live (TTL) of this static DNS entry in seconds
:typeId: The integral, unique identifier of the type of this static DNS entry
@@ -166,8 +166,8 @@ Response Structure
.. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons.
-:deliveryservice: The name of a Delivery Service under the domain of which this static DNS entry shall be active
-:deliveryserviceId: The integral, unique identifier of a Delivery Service under the domain of which this static DNS entry shall be active
+:deliveryservice: The name of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
+:deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address``
:id: An integral, unique identifier for this static DNS entry
:ttl: The Time To Live (TTL) of this static DNS entry in seconds
@@ -234,7 +234,7 @@ Request Structure
.. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons.
-:deliveryserviceId: The integral, unique identifier of a Delivery Service under the domain of which this static DNS entry shall be active
+:deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address``
:ttl: The Time To Live (TTL) of this static DNS entry in seconds
:typeId: The integral, unique identifier of the type of this static DNS entry
@@ -269,8 +269,8 @@ Response Structure
.. note:: This field has no effect, and is not used by any part of Traffic Control. It exists for legacy compatibility reasons.
-:deliveryservice: The name of a Delivery Service under the domain of which this static DNS entry shall be active
-:deliveryserviceId: The integral, unique identifier of a Delivery Service under the domain of which this static DNS entry shall be active
+:deliveryservice: The name of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
+:deliveryserviceId: The integral, unique identifier of a :term:`Delivery Service` under the domain of which this static DNS entry shall be active
:host: If ``typeId`` identifies a ``CNAME`` type record, this is an alias for the CNAME of the server, otherwise it is the Fully Qualified Domain Name (FQDN) which shall resolve to ``address``
:id: An integral, unique identifier for this static DNS entry
:ttl: The Time To Live (TTL) of this static DNS entry in seconds
diff --git a/docs/source/api/steering_id_targets.rst b/docs/source/api/steering_id_targets.rst
index 7b1f0ab..1362758 100644
--- a/docs/source/api/steering_id_targets.rst
+++ b/docs/source/api/steering_id_targets.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Get all targets for a steering Delivery Service.
+Get all targets for a steering :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None
@@ -31,19 +31,19 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+--------------------------------------------------------------------------------------------------+
- | Name | Description |
- +======+==================================================================================================+
- | ID | The integral, unique identifier of a steering Delivery Service for which targets shall be listed |
- +------+--------------------------------------------------------------------------------------------------+
+ +------+----------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+==========================================================================================================+
+ | ID | The integral, unique identifier of a steering :term:`Delivery Service` for which targets shall be listed |
+ +------+----------------------------------------------------------------------------------------------------------+
.. table:: Request Query Parameters
- +--------+-----------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +========+=================================================================================================================+
- | target | Return only the target mappings that target the Delivery Service identified by this integral, unique identifier |
- +--------+-----------------------------------------------------------------------------------------------------------------+
+ +--------+-------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +========+=========================================================================================================================+
+ | target | Return only the target mappings that target the :term:`Delivery Service` identified by this integral, unique identifier |
+ +--------+-------------------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Structure
@@ -56,12 +56,12 @@ Request Structure
Response Structure
------------------
-:deliveryService: The 'xml_id' of the steering Delivery Service
-:deliveryServiceId: An integral, unique identifier for the steering Delivery Service
-:target: The 'xml_id' of this target Delivery Service
-:targetId: An integral, unique identifier for this target Delivery Service
-:type: The routing type of this target Delivery Service
-:typeId: An integral, unique identifier for the routing type of this target Delivery Service
+:deliveryService: The 'xml_id' of the steering :term:`Delivery Service`
+:deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service`
+:target: The 'xml_id' of this target :term:`Delivery Service`
+:targetId: An integral, unique identifier for this target :term:`Delivery Service`
+:type: The routing type of this target :term:`Delivery Service`
+:typeId: An integral, unique identifier for the routing type of this target :term:`Delivery Service`
:value: The 'weight' attributed to this steering target
.. code-block:: http
@@ -103,15 +103,15 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+-------------------------------------------------------------------------------------------------+
- | Name | Description |
- +======+=================================================================================================+
- | ID | The integral, unique identifier of a steering Delivery Service to which a target shall be added |
- +------+-------------------------------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+=========================================================================================================+
+ | ID | The integral, unique identifier of a steering :term:`Delivery Service` to which a target shall be added |
+ +------+---------------------------------------------------------------------------------------------------------+
-:targetId: The integral, unique identifier of a Delivery Service which shall be a new steering target for the Delivery Service identified by the ``ID`` path parameter
-:typeId: The integral, unique identifier of the routing type of the new target Delivery Service
-:value: The 'weight' which shall be attributed to the new target Delivery Service
+:targetId: The integral, unique identifier of a :term:`Delivery Service` which shall be a new steering target for the :term:`Delivery Service` identified by the ``ID`` path parameter
+:typeId: The integral, unique identifier of the routing type of the new target :term:`Delivery Service`
+:value: The 'weight' which shall be attributed to the new target :term:`Delivery Service`
.. code-block:: http
:caption: Request Example
@@ -132,12 +132,12 @@ Request Structure
Response Structure
------------------
-:deliveryService: The 'xml_id' of the steering Delivery Service
-:deliveryServiceId: An integral, unique identifier for the steering Delivery Service
-:target: The 'xml_id' of the newly added target Delivery Service
-:targetId: An integral, unique identifier for the newly added target Delivery Service
-:type: The routing type of the newly added target Delivery Service
-:typeId: An integral, unique identifier for the routing type of the newly added target Delivery Service
+:deliveryService: The 'xml_id' of the steering :term:`Delivery Service`
+:deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service`
+:target: The 'xml_id' of the newly added target :term:`Delivery Service`
+:targetId: An integral, unique identifier for the newly added target :term:`Delivery Service`
+:type: The routing type of the newly added target :term:`Delivery Service`
+:typeId: An integral, unique identifier for the routing type of the newly added target :term:`Delivery Service`
:value: The 'weight' attributed to the new steering target
.. code-block:: http
diff --git a/docs/source/api/steering_id_targets_targetID.rst b/docs/source/api/steering_id_targets_targetID.rst
index 69097d0..a8a1525 100644
--- a/docs/source/api/steering_id_targets_targetID.rst
+++ b/docs/source/api/steering_id_targets_targetID.rst
@@ -24,7 +24,7 @@
.. deprecated:: 1.1
Use the ``target`` query parameter of a ``GET`` request to the :ref:`to-api-steering-id-targets` endpoint instead.
-Get a single target for a specific STEERING Delivery Service.
+Get a single target for a specific STEERING :term:`Delivery Service`.
:Auth. Required: Yes
:Roles Required: None
@@ -34,13 +34,13 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +----------+----------------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +==========+======================================================================================================================+
- | ID | The integral, unique identifier of a steering Delivery Service |
- +----------+----------------------------------------------------------------------------------------------------------------------+
- | targetID | The integral, unique identifier of a Delivery Service which is a target of the Delivery Service identified by ``ID`` |
- +----------+----------------------------------------------------------------------------------------------------------------------+
+ +----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +==========+======================================================================================================================================+
+ | ID | The integral, unique identifier of a steering :term:`Delivery Service` |
+ +----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | targetID | The integral, unique identifier of a :term:`Delivery Service` which is a target of the :term:`Delivery Service` identified by ``ID`` |
+ +----------+--------------------------------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -53,12 +53,12 @@ Request Structure
Response Structure
------------------
-:deliveryService: The 'xml_id' of the steering Delivery Service
-:deliveryServiceId: An integral, unique identifier for the steering Delivery Service
-:target: The 'xml_id' of this target Delivery Service
-:targetId: An integral, unique identifier for this target Delivery Service
-:type: The routing type of this target Delivery Service
-:typeId: An integral, unique identifier for the routing type of this target Delivery Service
+:deliveryService: The 'xml_id' of the steering :term:`Delivery Service`
+:deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service`
+:target: The 'xml_id' of this target :term:`Delivery Service`
+:targetId: An integral, unique identifier for this target :term:`Delivery Service`
+:type: The routing type of this target :term:`Delivery Service`
+:typeId: An integral, unique identifier for the routing type of this target :term:`Delivery Service`
:value: The 'weight' attributed to this steering target
.. code-block:: http
@@ -100,16 +100,16 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +----------+----------------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +==========+======================================================================================================================+
- | ID | The integral, unique identifier of a steering Delivery Service |
- +----------+----------------------------------------------------------------------------------------------------------------------+
- | targetID | The integral, unique identifier of a Delivery Service which is a target of the Delivery Service identified by ``ID`` |
- +----------+----------------------------------------------------------------------------------------------------------------------+
+ +----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +==========+======================================================================================================================================+
+ | ID | The integral, unique identifier of a steering :term:`Delivery Service` |
+ +----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | targetID | The integral, unique identifier of a :term:`Delivery Service` which is a target of the :term:`Delivery Service` identified by ``ID`` |
+ +----------+--------------------------------------------------------------------------------------------------------------------------------------+
-:typeId: The integral, unique identifier of the routing type of the target Delivery Service
-:value: The 'weight' which shall be attributed to the target Delivery Service
+:typeId: The integral, unique identifier of the routing type of the target :term:`Delivery Service`
+:value: The 'weight' which shall be attributed to the target :term:`Delivery Service`
.. code-block:: http
:caption: Request Example
@@ -129,12 +129,12 @@ Request Structure
Response Structure
------------------
-:deliveryService: The 'xml_id' of the steering Delivery Service
-:deliveryServiceId: An integral, unique identifier for the steering Delivery Service
-:target: The 'xml_id' of this target Delivery Service
-:targetId: An integral, unique identifier for this target Delivery Service
-:type: The new routing type of this target Delivery Service
-:typeId: An integral, unique identifier for the new routing type of this target Delivery Service
+:deliveryService: The 'xml_id' of the steering :term:`Delivery Service`
+:deliveryServiceId: An integral, unique identifier for the steering :term:`Delivery Service`
+:target: The 'xml_id' of this target :term:`Delivery Service`
+:targetId: An integral, unique identifier for this target :term:`Delivery Service`
+:type: The new routing type of this target :term:`Delivery Service`
+:typeId: An integral, unique identifier for the new routing type of this target :term:`Delivery Service`
:value: The new 'weight' attributed to this steering target
.. code-block:: http
@@ -170,7 +170,7 @@ Response Structure
``DELETE``
==========
-Removes a specific target mapping from a specific Delivery Service
+Removes a specific target mapping from a specific :term:`Delivery Service`
:Auth. Required: Yes
:Roles Required: Portal, Steering, Federation, "operations" or "admin"
@@ -180,13 +180,13 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +----------+------------------------------------------------------------------------------------------------------------------------------------+
- | Name | Description |
- +==========+====================================================================================================================================+
- | ID | The integral, unique identifier of a steering Delivery Service - a target of which shall be deleted |
- +----------+------------------------------------------------------------------------------------------------------------------------------------+
- | targetID | The integral, unique identifier of a Delivery Service which is a target to be removed of the Delivery Service identified by ``ID`` |
- +----------+------------------------------------------------------------------------------------------------------------------------------------+
+ +----------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +==========+====================================================================================================================================================+
+ | ID | The integral, unique identifier of a steering :term:`Delivery Service` - a target of which shall be deleted |
+ +----------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+ | targetID | The integral, unique identifier of a :term:`Delivery Service` which is a target to be removed of the :term:`Delivery Service` identified by ``ID`` |
+ +----------+----------------------------------------------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
diff --git a/docs/source/api/system_info.rst b/docs/source/api/system_info.rst
index 73a47a4..60512d9 100644
--- a/docs/source/api/system_info.rst
+++ b/docs/source/api/system_info.rst
@@ -51,9 +51,9 @@ Response Structure
:use_tenancy: A string containing an integer which represents a boolean value; one of:
"0"
- Do not use tenancy - this effectively disables all ``*tenant*`` endpoints and removes tenancy restrictions on origins and Delivery Services
+ Do not use tenancy - this effectively disables all ``*tenant*`` endpoints and removes tenancy restrictions on origins and :term:`Delivery Service`\ s
"1"
- Use tenancy - this effectively enables all ``*tenant*`` endpoints and enforces tenancy restrictions on origins and Delivery Services
+ Use tenancy - this effectively enables all ``*tenant*`` endpoints and enforces tenancy restrictions on origins and :term:`Delivery Service`\ s
.. code-block:: http
:caption: Response Example
diff --git a/docs/source/api/user_current_jobs.rst b/docs/source/api/user_current_jobs.rst
index cf926bd..c754fbe 100644
--- a/docs/source/api/user_current_jobs.rst
+++ b/docs/source/api/user_current_jobs.rst
@@ -66,7 +66,7 @@ Response Structure
This field still exists, but has no purpose as all assets are now treated as remote files; i.e. it will always be ``"file"``.
:createdBy: The username of the user who initiated the job
-:deliveryService: The 'xml_id' that uniquely identifies the Delivery Service on which this job operates
+:deliveryService: The 'xml_id' that uniquely identifies the :term:`Delivery Service` on which this job operates
:enteredTime: The date and time at which the job was created, in ISO format
:id: An integral, unique identifier for this job
:keyword: A keyword that represents the operation being performed by the job:
@@ -127,11 +127,11 @@ Creates a new content revalidation job.
Request Structure
-----------------
-:dsId: The integral, unique identifier of the Delivery Service on which the revalidation job shall operate
+:dsId: The integral, unique identifier of the :term:`Delivery Service` on which the revalidation job shall operate
:regex: This should be a `PCRE <http://www.pcre.org/>`_-compatible regular expression for the path to match for forcing the revalidation
- .. warning:: This is concatenated directly to the origin URL of the Delivery Service identified by ``dsId`` to make the full regular expression. Thus it is not necessary to restate the URL but it should be noted that if the origin URL does not end with a backslash (``/``) then this should begin with an escaped backslash to ensure proper behavior (otherwise it will match against FQDNs, which leads to undefined behavior in Traffic Control).
+ .. warning:: This is concatenated directly to the origin URL of the :term:`Delivery Service` identified by ``dsId`` to make the full regular expression. Thus it is not necessary to restate the URL but it should be noted that if the origin URL does not end with a backslash (``/``) then this should begin with an escaped backslash to ensure proper behavior (otherwise it will match against FQDNs, which leads to undefined behavior in Traffic Control).
.. note:: Be careful to only match on the content that must be removed - revalidation is an expensive operation for many origins, and a simple ``/.*`` can cause an overload in requests to the origin.
@@ -186,4 +186,4 @@ Response Structure
}
]}
-.. [1] A role is only required if tenancy is not used; if tenancy is used by Traffic Control, then the user will be able to create the content revalidation job on Delivery Services scoped to his or her tenancy regardless of role. This means that **even read-only users can create content invalidation jobs for Delivery Services scoped to their tenancy**. This behavior is considered a bug, and it is tracked by `GitHub Issue #3116 <https://github.com/apache/trafficcontrol/issues/3116>`_.
+.. [1] A role is only required if tenancy is not used; if tenancy is used by Traffic Control, then the user will be able to create the content revalidation job on :term:`Delivery Service`\ s scoped to his or her tenancy regardless of role. This means that **even read-only users can create content invalidation jobs for :term:`Delivery Service`\ s scoped to their tenancy**. This behavior is considered a bug, and it is tracked by `GitHub Issue #3116 <https://github.com/apache/trafficcontrol [...]
diff --git a/docs/source/api/user_id_deliveryservices_available.rst b/docs/source/api/user_id_deliveryservices_available.rst
index 464ad0b..00f3b25 100644
--- a/docs/source/api/user_id_deliveryservices_available.rst
+++ b/docs/source/api/user_id_deliveryservices_available.rst
@@ -19,7 +19,7 @@
``GET``
=======
-Lists identifying information for all of the Delivery Services assigned to a user - **not**, as the name implies, the Delivery Services *available* to be assigned to that user.
+Lists identifying information for all of the :term:`Delivery Service`\ s assigned to a user - **not**, as the name implies, the :term:`Delivery Service`\ s *available* to be assigned to that user.
:Auth. Required: Yes
:Roles Required: None
@@ -29,11 +29,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+-----------------------------------------------------------------------------------------+
- | Name | Description |
- +======+=========================================================================================+
- | ID | The integral, unique identifier of the users whose Delivery Services shall be retrieved |
- +------+-----------------------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+===================================================================================================+
+ | ID | The integral, unique identifier of the users whose :term:`Delivery Service`\ s shall be retrieved |
+ +------+---------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -46,9 +46,9 @@ Request Structure
Response Structure
------------------
-:displayName: This Delivery Service's name
-:id: The integral, unique identifier of this Delivery Service
-:xmlId: The 'xml_id' which (also) uniquely identifies this Delivery Service
+:displayName: This :term:`Delivery Service`'s name
+:id: The integral, unique identifier of this :term:`Delivery Service`
+:xmlId: The 'xml_id' which (also) uniquely identifies this :term:`Delivery Service`
.. code-block:: http
:caption: Response Example
diff --git a/docs/source/api/users_id_deliveryservices.rst b/docs/source/api/users_id_deliveryservices.rst
index aeda4c7..c22f8f8 100644
--- a/docs/source/api/users_id_deliveryservices.rst
+++ b/docs/source/api/users_id_deliveryservices.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieves all Delivery Services assigned to the user.
+Retrieves all :term:`Delivery Service`\ s assigned to the user.
:Auth. Required: Yes
:Roles Required: None\ [1]_
@@ -31,11 +31,11 @@ Request Structure
-----------------
.. table:: Request Path Parameters
- +------+-----------------------------------------------------------------------------------------+
- | Name | Description |
- +======+=========================================================================================+
- | ID | The integral, unique identifier of the users whose Delivery Services shall be retrieved |
- +------+-----------------------------------------------------------------------------------------+
+ +------+---------------------------------------------------------------------------------------------------+
+ | Name | Description |
+ +======+===================================================================================================+
+ | ID | The integral, unique identifier of the users whose :term:`Delivery Service`\ s shall be retrieved |
+ +------+---------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -48,25 +48,25 @@ Request Structure
Response Structure
------------------
-:active: ``true`` if the Delivery Service is active, ``false`` otherwise
-:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the Delivery Service, ``false`` otherwise
+:active: ``true`` if the :term:`Delivery Service` is active, ``false`` otherwise
+:anonymousBlockingEnabled: ``true`` if :ref:`Anonymous Blocking <anonymous_blocking-qht>` has been configured for the :term:`Delivery Service`, ``false`` otherwise
:cacheurl: A setting for a deprecated feature of now-unsupported Trafficserver versions
.. deprecated:: ATCv3.0
This field has been deprecated in Traffic Control 3.x and is subject to removal in Traffic Control 4.x or later
:ccrDnsTtl: The Time To Live (TTL) of the DNS response for A or AAAA record queries requesting the IP address of the Traffic Router - named "ccrDnsTtl" for legacy reasons
-:cdnId: The integral, unique identifier of the CDN to which the Delivery Service belongs
-:cdnName: Name of the CDN to which the Delivery Service belongs
-:checkPath: The path portion of the URL to check connections to this Delivery Service's origin server
-:displayName: The display name of the Delivery Service
-:dnsBypassCname: Domain name to overflow requests for HTTP Delivery Services - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp: The IPv4 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service\ [4]_
-:dnsBypassTtl: The time for which a DNS bypass of this Delivery Service shall remain active\ [4]_
+:cdnId: The integral, unique identifier of the CDN to which the :term:`Delivery Service` belongs
+:cdnName: Name of the CDN to which the :term:`Delivery Service` belongs
+:checkPath: The path portion of the URL to check connections to this :term:`Delivery Service`'s origin server
+:displayName: The display name of the :term:`Delivery Service`
+:dnsBypassCname: Domain name to overflow requests for HTTP :term:`Delivery Service`\ s - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp: The IPv4 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassIp6: The IPv6 IP to use for bypass on a DNS :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`\ [4]_
+:dnsBypassTtl: The time for which a DNS bypass of this :term:`Delivery Service`\ shall remain active\ [4]_
:dscp: The Differentiated Services Code Point (DSCP) with which to mark traffic as it leaves the CDN and reaches clients
:edgeHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
-:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the Delivery Service (see ``man tc-fc_codel`` for more information) - Linux only
+:fqPacingRate: The Fair-Queuing Pacing Rate in Bytes per second set on the all TCP connection sockets in the :term:`Delivery Service` (see ``man tc-fc_codel`` for more information) - Linux only
:geoLimit: The setting that determines how content is geographically limited - this is an integer on the interval [0-2] where the values have these meanings:
0
@@ -78,7 +78,7 @@ Response Structure
.. warning:: This does not prevent access to content or make content secure; it merely prevents routing to the content through Traffic Router
-:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this Delivery Service
+:geoLimitCountries: A string containing a comma-separated list of country codes (e.g. "US,AU") which are allowed to request content through this :term:`Delivery Service`
:geoLimitRedirectUrl: A URL to which clients blocked by :ref:`Regional Geographic Blocking <regionalgeo-qht>` or the ``geoLimit`` settings will be re-directed
:geoProvider: An integer that represents the provider of a database for mapping IPs to geographic locations; currently only the following values are supported:
@@ -87,47 +87,47 @@ Response Structure
1
Neustar
-:globalMaxMbps: The maximum global bandwidth allowed on this Delivery Service. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS Delivery Services and to ``httpBypassFqdn`` for HTTP Delivery Services
-:globalMaxTps: The maximum global transactions per second allowed on this Delivery Service. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS Delivery Services and to the httpBypassFqdn for HTTP Delivery Services
-:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP Delivery Service - bypass starts when the traffic on this Delivery Service exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the Delivery Service
-:id: An integral, unique identifier for this Delivery Service
-:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the Delivery Service. Historically, this has been used to link relevant JIRA tickets
+:globalMaxMbps: The maximum global bandwidth allowed on this :term:`Delivery Service`. If exceeded, traffic will be routed to ``dnsBypassIp`` (or ``dnsBypassIp6`` for IPv6 traffic) for DNS :term:`Delivery Service`\ s and to ``httpBypassFqdn`` for HTTP :term:`Delivery Service`\ s
+:globalMaxTps: The maximum global transactions per second allowed on this :term:`Delivery Service`. When this is exceeded traffic will be sent to the ``dnsBypassIp`` (and/or ``dnsBypassIp6``) for DNS :term:`Delivery Service`\ s and to the httpBypassFqdn for HTTP :term:`Delivery Service`\ s
+:httpBypassFqdn: The HTTP destination to use for bypass on an HTTP :term:`Delivery Service` - bypass starts when the traffic on this :term:`Delivery Service` exceeds ``globalMaxMbps``, or when more than ``globalMaxTps`` is being exceeded within the :term:`Delivery Service`
+:id: An integral, unique identifier for this :term:`Delivery Service`
+:infoUrl: This is a string which is expected to contain at least one URL pointing to more information about the :term:`Delivery Service`. Historically, this has been used to link relevant JIRA tickets
:initialDispersion: The number of caches between which traffic requesting the same object will be randomly split - meaning that if 4 clients all request the same object (one after another), then if this is above 4 there is a possibility that all 4 are cache misses. For most use-cases, this should be 1\ [2]_
:ipv6RoutingEnabled: If ``true``, clients that connect to Traffic Router using IPv6 will be given the IPv6 address of a suitable Edge-tier cache; if ``false`` all addresses will be IPv4, regardless of the client connection\ [2]_
-:lastUpdated: The date and time at which this Delivery Service was last updated, in a ``ctime``-like format
-:logsEnabled: If ``true``, logging is enabled for this Delivery Service, otherwise it is disabled
-:longDesc: A description of the Delivery Service
+:lastUpdated: The date and time at which this :term:`Delivery Service` was last updated, in a ``ctime``-like format
+:logsEnabled: If ``true``, logging is enabled for this :term:`Delivery Service`, otherwise it is disabled
+:longDesc: A description of the :term:`Delivery Service`
:longDesc1: A field used when more detailed information that that provided by ``longDesc`` is desired
:longDesc2: A field used when even more detailed information that that provided by either ``longDesc`` or ``longDesc1`` is desired
-:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this Delivery Service
+:matchList: An array of methods used by Traffic Router to determine whether or not a request can be serviced by this :term:`Delivery Service`
:pattern: A regular expression - the use of this pattern is dependent on the ``type`` field (backslashes are escaped)
:setNumber: An integral, unique identifier for the set of types to which the ``type`` field belongs
- :type: The type of match performed using ``pattern`` to determine whether or not to use this Delivery Service
+ :type: The type of match performed using ``pattern`` to determine whether or not to use this :term:`Delivery Service`
HOST_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``Host:`` HTTP header of an HTTP request\ [2]_
HEADER_REGEXP
- Use the Delivery Service if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
+ Use the :term:`Delivery Service` if ``pattern`` matches an HTTP header (both the name and value) in an HTTP request\ [2]_
PATH_REGEXP
- Use the Delivery Service if ``pattern`` matches the request path of this Delivery Service's URL
+ Use the :term:`Delivery Service` if ``pattern`` matches the request path of this :term:`Delivery Service`'s URL
STEERING_REGEXP
- Use the Delivery Service if ``pattern`` matches the ``xml_id`` of one of this Delivery Service's "Steering" target Delivery Services
+ Use the :term:`Delivery Service` if ``pattern`` matches the ``xml_id`` of one of this :term:`Delivery Service`'s "Steering" target :term:`Delivery Service`\ s
:maxDnsAnswers: The maximum number of IPs to put in responses to A/AAAA DNS record requests (0 means all available)\ [4]_
:midHeaderRewrite: Rewrite operations to be performed on TCP headers at the Edge-tier cache level - used by the Header Rewrite Apache Trafficserver plugin
:missLat: The latitude to use when the client cannot be found in the CZF or a geographic IP lookup
:missLong: The longitude to use when the client cannot be found in the CZF or a geographic IP lookup
-:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this Delivery Service, ``false`` otherwise\ [3]_
-:orgServerFqdn: The URL of the Delivery Service's origin server for use in retrieving content from the origin server
+:multiSiteOrigin: ``true`` if the Multi Site Origin feature is enabled for this :term:`Delivery Service`, ``false`` otherwise\ [3]_
+:orgServerFqdn: The URL of the :term:`Delivery Service`'s origin server for use in retrieving content from the origin server
.. note:: Despite the field name, this must truly be a full URL - including the protocol (e.g. ``http://`` or ``https://``) - **NOT** merely the server's Fully Qualified Domain Name (FQDN)
:originShield: An "origin shield" is a forward proxy that sits between Mid-tier caches and the origin and performs further caching beyond what's offered by a standard CDN. This field is a string of FQDNs to use as origin shields, delimited by ``|``
-:profileDescription: The description of the Traffic Router Profile with which this Delivery Service is associated
-:profileId: The integral, unique identifier for the Traffic Router profile with which this Delivery Service is associated
-:profileName: The name of the Traffic Router Profile with which this Delivery Service is associated
-:protocol: The protocol which clients will use to communicate with Edge-tier cache servers\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
+:profileDescription: The description of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:profileId: The integral, unique identifier for the Traffic Router profile with which this :term:`Delivery Service` is associated
+:profileName: The name of the Traffic Router Profile with which this :term:`Delivery Service` is associated
+:protocol: The protocol which clients will use to communicate with Edge-tier :term:`cache server`\ s\ [2]_ - this is an integer on the interval [0-2] where the values have these meanings:
0
HTTP
@@ -154,37 +154,37 @@ Response Structure
2
Use the `experimental cache_range_requests plugin <https://github.com/apache/trafficserver/tree/master/plugins/experimental/cache_range_requests>`_ to treat unique ranges as unique objects
-:regexRemap: A regular expression remap rule to apply to this Delivery Service at the Edge tier
+:regexRemap: A regular expression remap rule to apply to this :term:`Delivery Service` at the Edge tier
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this Delivery Service, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
+:regionalGeoBlocking: ``true`` if Regional Geo Blocking is in use within this :term:`Delivery Service`, ``false`` otherwise - see :ref:`regionalgeo-qht` for more information
:remapText: Additional, raw text to add to the remap line for caches
.. seealso:: `The Apache Trafficserver documentation for the Regex Remap plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_
-:signed: ``true`` if token-based authentication is enabled for this Delivery Service, ``false`` otherwise
+:signed: ``true`` if token-based authentication is enabled for this :term:`Delivery Service`, ``false`` otherwise
:signingAlgorithm: Type of URL signing method to sign the URLs, basically comes down to one of two plugins or ``null``:
``null``
- Token-based authentication is not enabled for this Delivery Service
+ Token-based authentication is not enabled for this :term:`Delivery Service`
url_sig:
- URL Signing token-based authentication is enabled for this Delivery Service
+ URL Signing token-based authentication is enabled for this :term:`Delivery Service`
uri_signing
- URI Signing token-based authentication is enabled for this Delivery Service
+ URI Signing token-based authentication is enabled for this :term:`Delivery Service`
.. seealso:: `The Apache Trafficserver documentation for the url_sig plugin <https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/url_sig.en.html>`_ and `the draft RFC for uri_signing <https://tools.ietf.org/html/draft-ietf-cdni-uri-signing-16>`_ - note, however that the current implementation of uri_signing uses Draft 12 of that RFC document, **NOT** the latest
-:sslKeyVersion: This integer indicates the generation of keys in use by the Delivery Service - if any - and is incremented by the Traffic Portal client whenever new keys are generated
+:sslKeyVersion: This integer indicates the generation of keys in use by the :term:`Delivery Service` - if any - and is incremented by the Traffic Portal client whenever new keys are generated
.. warning:: This number will not be correct if keys are manually replaced using the API, as the key generation API does not increment it!
-:tenantId: The integral, unique identifier of the tenant who owns this Delivery Service
+:tenantId: The integral, unique identifier of the tenant who owns this :term:`Delivery Service`
:trRequestHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router access logs for requests - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
:trResponseHeaders: If defined, this takes the form of a string of HTTP headers to be included in Traffic Router responses - it's a template where ``__RETURN__`` translates to a carriage return and line feed (``\r\n``)\ [2]_
-:type: The name of the routing type of this Delivery Service e.g. "HTTP"
-:typeId: The integral, unique identifier of the routing type of this Delivery Service
-:xmlId: A unique string that describes this Delivery Service - exists for legacy reasons
+:type: The name of the routing type of this :term:`Delivery Service` e.g. "HTTP"
+:typeId: The integral, unique identifier of the routing type of this :term:`Delivery Service`
+:xmlId: A unique string that describes this :term:`Delivery Service` - exists for legacy reasons
.. code-block:: http
:caption: Response Example
@@ -262,7 +262,7 @@ Response Structure
"tenant": "root"
}]}
-.. [1] Users with the roles "admin" and/or "operations" will be able to see *all* Delivery Services, whereas any other user will only see the Delivery Services their Tenant is allowed to see.
-.. [2] This only applies to HTTP-routed Delivery Services
+.. [1] Users with the roles "admin" and/or "operations" will be able to see *all* :term:`Delivery Service`\ s, whereas any other user will only see the :term:`Delivery Service`\ s their Tenant is allowed to see.
+.. [2] This only applies to HTTP-routed :term:`Delivery Service`\ s
.. [3] See :ref:`multi-site-origin`
-.. [4] This only applies to DNS-routed Delivery Services
+.. [4] This only applies to DNS-routed :term:`Delivery Service`\ s
diff --git a/docs/source/basics/cache_revalidation.rst b/docs/source/basics/cache_revalidation.rst
index 3aa0c48..84e1003 100644
--- a/docs/source/basics/cache_revalidation.rst
+++ b/docs/source/basics/cache_revalidation.rst
@@ -13,14 +13,14 @@
.. limitations under the License.
..
-.. index::
- Cache Control Header
- Revalidation
- HTTP 304
+.. _cache-revalidation:
+**************************************
Cache Control Headers and Revalidation
-======================================
-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
+**************************************
+The HTTP/1.1 specification in :rfc:`2616#section-14.9` 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.
+
+.. note:: The terms "content revalidation" and "content invalidation" are often convoluted when referring to the same behavior. Within the context of Traffic Control, the two should be considered synonymous.
.. code-block:: http
:caption: This Response may Only be Cached for 86400 Seconds
@@ -37,13 +37,19 @@ The HTTP/1.1 spec :rfc:`2616` allows for origin servers and clients to influence
<!DOCTYPE html><html><body>This is a fun file</body></html>
-In the above response, the origin server tells downstream caching systems that the maximum time to cache this response for is 86400 seconds. The origin can also add a ``Expires:`` header, explicitly telling the cache the time this response is to be expired. When a response is expired it usually doesn't get deleted from the cache, but, when a request comes in that would have hit on this response if it was not expired, the cache *revalidates* the response. Instead of requesting the object [...]
+The ``max-age`` directive in the ``Cache-Control`` header tells downstream caching systems that the maximum time for which they are allowed to cache this response is the specified number of seconds. The origin can also add an ``Expires:`` header, explicitly telling the cache the time this response is to be expired. When a response is expired it usually doesn't get deleted from the cache, but, when a request comes in that would have hit on this response if it was not expired, the cache *r [...]
+
+.. code-block:: http
+ :caption: The Cache Server Sends a Request with the Old ``ETag`` Value in the ``If-None-Match`` Header
GET /foo/bar/fun.html HTTP/1.1
If-None-Match: "1aa008f-2d-50a3559482cc0"
Host: www.origin.com
-If the content has changed (meaning, the new response would not have had the same ETag) it will respond with ``200 OK``, like::
+If the content has changed (meaning, the new response would not have had the same ``ETag``) the server MUST respond with the up-to-date content, usually in the body of a ``200 OK`` response.
+
+.. code-block:: http
+ :caption: The Origin Responds with the Modified Content and a New ``ETag``
HTTP/1.1 200 OK
Date: Sun, 18 Dec 2014 3:22:44 GMT
@@ -58,17 +64,15 @@ If the content has changed (meaning, the new response would not have had the sam
<!DOCTYPE html><html><body>This is NOT a fun file</body></html>
-If the Content did not change (meaning, the response would have had the same ETag) it will respond with ``304 Not Modified``, like::
+If the content did not change (meaning, the response would have had the same ``ETag``) the server SHOULD respond with a ``304 Not Modified``. In most cases, the server will also send back an ``ETag`` header, since the client is allowed to send multiple ``ETag`` values in its ``If-None-Match`` header to check against multiple cached versions of the content, and the ``ETag`` will tell it which specifically is the current version. This is a very rare use case, and :abbr:`ATS (Apache Traffic [...]
- 304 Not Modified
+.. code-block:: http
+ :caption: The Content has not been Modified so the Server Indicates the Cached Version is Up-To-Date
+
+ HTTP/1.1 304 Not Modified
Date: Sun, 18 Dec 2014 3:22:44 GMT
Server: Apache/2.2.15 (Red Hat)
Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
ETag: "1aa008f-2d-50a3559482cc0"
Cache-Control: max-age=604800
- Content-Length: 45
Connection: close
- Content-Type: text/html; charset=UTF-8
-
-Note that the 304 response only has headers, not the data.
-
diff --git a/docs/source/basics/caching_proxies.rst b/docs/source/basics/caching_proxies.rst
deleted file mode 100644
index e469f7c..0000000
--- a/docs/source/basics/caching_proxies.rst
+++ /dev/null
@@ -1,217 +0,0 @@
-..
-..
-.. Licensed under the Apache License, Version 2.0 (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-..
-
-.. _caching_proxy:
-
-***************
-Caching Proxies
-***************
-The main function of a CDN is to proxy requests from clients to origin servers and cache the results. To proxy, in the CDN context, is to obtain content using HTTP from an origin server on behalf of a client. To cache is to store the results so they can be reused when other clients are requesting the same content. There are three types of proxies in use on the Internet today:
-
-Reverse Proxy
- Used by Traffic Control for EDGE caches.
-Forward Proxy
- Used by Traffic Control for MID caches.
-Transparent Proxy
- These are not used by Traffic Control. If you are interested you can learn more about transparent proxies on `wikipedia <http://en.wikipedia.org/wiki/Proxy_server#Transparent_proxy>`_.
-
-.. _rev-proxy:
-
-Reverse Proxy
-=============
-A reverse proxy acts on behalf of the origin server. The client is mostly unaware it is communicating with a proxy and not the actual origin. All EDGE caches in a Traffic Control CDN are reverse proxies. To the end user a Traffic Control based CDN appears as a reverse proxy since it retrieves content from the origin server, acting on behalf of that origin server. The client requests a URL that has a hostname which resolves to the reverse proxy's IP address and, in compliance with the HTT [...]
-
-.. seealso:: `ATS documentation on reverse proxy <https://docs.trafficserver.apache.org/en/latest/admin/reverse-proxy-http-redirects.en.html#http-reverse-proxy>`_.
-
-To insert a reverse proxy into the previous HTTP 1.1 example, the reverse proxy requires provisioning
-for ``www.origin.com``. By adding a remap rule to the cache, the reverse proxy then maps requests to
-this origin. The content owner must inform the clients, by updating the URL, to receive the content
-from the cache and not from the origin server directly. For this example, the remap rule on the
-cache is: ``http://www-origin-cache.cdn.com http://www.origin.com``.
-
-.. Note:: In the previous example minimal headers were shown on both the request and response. In the examples that follow, the origin server response is more realistic.
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Date: Sun, 14 Dec 2014 23:22:44 GMT
- Server: Apache/2.2.15 (Red Hat)
- Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
- ETag: "1aa008f-2d-50a3559482cc0"
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
-
- <!DOCTYPE html><html><body>This is a fun file</body></html>
-
-The client is given the URL ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` (note the different hostname) and when attempting to obtain that URL, the following occurs:
-
-#. The client sends a request to the Local Domain Name Server (LDNS) server to resolve the name ``www-origin-cache.cdn.com`` to an IPv4 address.
-
-#. Similar to the previous case, the LDNS server resolves the name ``www-origin-cache.cdn.com`` to an IPv4 address, in this example, this address is 55.44.33.22.
-
-#. The client opens a TCP connection from a random port locally, to port 80 (the HTTP default) on 55.44.33.22, and sends the following:
-
- .. code-block:: http
-
- GET /foo/bar/fun.html HTTP/1.1
- Host: www-origin-cache.cdn.com
-
-#. The reverse proxy looks up ``www-origin-cache.cdn.com`` in its remap rules, and finds the origin is ``www.origin.com``.
-
-#. The proxy checks its cache to see if the response for ``http://www.origin.com/foo/bar/fun.html`` is already in the cache.
-
-#. If the response is not in the cache:
-
- #. The proxy uses DNS to get the IPv4 address for ``www.origin.com``, connect to it on port 80, and sends:
-
- .. code-block:: http
-
- GET /foo/bar/fun.html HTTP/1.1
- Host: www.origin.com
-
- #. The origin server responds with the headers and content as shown:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Date: Sun, 14 Dec 2014 23:22:44 GMT
- Server: Apache/2.2.15 (Red Hat)
- Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
- ETag: "1aa008f-2d-50a3559482cc0"
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
-
- <!DOCTYPE html><html><body>This is a fun file</body></html>
-
- #. The proxy sends the origin response on to the client adding a ``Via:`` header (and maybe others):
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Date: Sun, 14 Dec 2014 23:22:44 GMT
- Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
- ETag: "1aa008f-2d-50a3559482cc0"
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
- Age: 0
- Via: http/1.1 cache01.cdn.kabletown.net (ApacheTrafficServer/4.2.1 [uScSsSfUpSeN:t cCSi p sS])
- Server: ATS/4.2.1
-
- <!DOCTYPE html><html><body>This is a fun file</body></html>
-
- If it *is* in the cache the proxy responds to the client with the previously retrieved result:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Date: Sun, 14 Dec 2014 23:22:44 GMT
- Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
- ETag: "1aa008f-2d-50a3559482cc0"
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
- Age: 39711
- Via: http/1.1 cache01.cdn.kabletown.net (ApacheTrafficServer/4.2.1 [uScSsSfUpSeN:t cCSi p sS])
- Server: ATS/4.2.1
-
- <!DOCTYPE html><html><body>This is a fun file</body></html>
-
-.. _fwd-proxy:
-
-Forward Proxy
-=============
-A forward proxy acts on behalf of the client. The origin server is mostly unaware of the proxy, the client requests the proxy to retrieve content from a particular origin server. All MID caches in a Traffic Control based CDN are forward proxies. In a forward proxy scenario, the client is explicitly configured to use the the proxy's IP address and port as a forward proxy. The client always connects to the forward proxy for content. The content provider does not have to change the URL the [...]
-
-.. seealso:: `ATS documentation on forward proxy <https://docs.trafficserver.apache.org/en/latest/admin/forward-proxy.en.html>`_.
-
-Below is an example of the client retrieving the URL ``http://www.origin.com/foo/bar/fun.html`` through a forward proxy:
-
-#. The client requires configuration to use the proxy, as opposed to the reverse proxy example. Assume the client configuration is through preferences entries or other to use the proxy IP address 99.88.77.66 and proxy port 8080.
-
-#. To retrieve ``http://www.origin.com/foo/bar/fun.html`` URL, the client connects to 99.88.77.66 on port 8080 and sends:
-
- .. code-block:: http
-
- GET http://www.origin.com/foo/bar/fun.html HTTP/1.1
- Host: www.origin.com
-
-
- .. Note:: In this case, the client places the entire URL after ``GET``, including protocol and hostname (``http://www.origin.com``), but in the reverse proxy and direct-to-origin case it puts only the path portion of the URL (``/foo/bar/fun.html``) after the ``GET``.
-
-#. The proxy verifies whether the response for ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` is already in the cache.
-
-#. If it is not in the cache:
-
- #. The proxy uses DNS to obtain the IPv4 address for ``www.origin.com``, connects to it on port 80, and sends:
-
- .. code-block:: http
-
- GET /foo/bar/fun.html HTTP/1.1
- Host: www.origin.com
-
-
- #. The origin server responds with the headers and content as shown below:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Date: Sun, 14 Dec 2014 23:22:44 GMT
- Server: Apache/2.2.15 (Red Hat)
- Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
- ETag: "1aa008f-2d-50a3559482cc0"
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
-
- <!DOCTYPE html><html><body>This is a fun file</body></html>
-
-
- #. The proxy sends this on to the client adding a ``Via:`` header (and maybe others):
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Date: Sun, 14 Dec 2014 23:22:44 GMT
- Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
- ETag: "1aa008f-2d-50a3559482cc0"
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
- Age: 0
- Via: http/1.1 cache01.cdn.kabletown.net (ApacheTrafficServer/4.2.1 [uScSsSfUpSeN:t cCSi p sS])
- Server: ATS/4.2.1
-
- <!DOCTYPE html><html><body>This is a fun file</body></html>
-
-
- If it *is* in the cache the proxy responds to the client with the previously retrieved result:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Date: Sun, 14 Dec 2014 23:22:44 GMT
- Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
- ETag: "1aa008f-2d-50a3559482cc0"
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
- Age: 99711
- Via: http/1.1 cache01.cdn.kabletown.net (ApacheTrafficServer/4.2.1 [uScSsSfUpSeN:t cCSi p sS])
- Server: ATS/4.2.1
-
- <!DOCTYPE html><html><body>This is a fun file</body></html>
diff --git a/docs/source/basics/content_delivery_networks.rst b/docs/source/basics/content_delivery_networks.rst
index 8893610..cecd316 100644
--- a/docs/source/basics/content_delivery_networks.rst
+++ b/docs/source/basics/content_delivery_networks.rst
@@ -13,26 +13,22 @@
.. limitations under the License.
..
-.. index::
- Log File Analysis
- CDN
- Content Delivery Network
-
+*************************
Content Delivery Networks
-=========================
-The vast majority of today's Internet traffic is media files (often video or audio) being sent from a single source (the *Content Provider*) to many thousands or even millions of destinations (the *Content Consumers*). Content Delivery Networks are the technology that make that one-to-many distribution possible in an economical way. A Content Delivery Network (CDN) is a distributed system of servers for delivering content over HTTP. These servers are deployed in multiple locations with t [...]
+*************************
+The vast majority of today's Internet traffic is media files (often video or audio) being sent from a single source (the *Content Provider*) to many thousands or even millions of destinations (the *Content Consumers*). :abbr:`CDN (Content Delivery Network)`\ s are the technology that make that one-to-many distribution efficient. A :abbr:`CDN (Content Delivery Network)` is a distributed system of servers for delivering content over HTTP(S). These servers are deployed in multiple locations [...]
-Caching Proxies
- The proxy (cache or caching proxy) is a server that both proxies the requests and caches the results for reusing.
+:term:`Cache Server`\ s
+ The :dfn:`cache server` is a server that both proxies the requests and caches the results for reuse. Traffic Control uses `Apache Traffic Server <http://trafficserver.apache.org/>`_ to provide :term:`cache server`\ s.
Content Router
- The Content Router ensures that the end user is connected to the optimal cache for the location of the end user and content availability.
+ A :dfn:`content router` ensures that the end user is connected to the optimal :term:`cache server` for the location of the end user and content availability. Traffic Control uses :ref:`tr-overview` as a :dfn:`content router`.
Health Protocol
- The :ref:`health-proto` monitors the usage of the caches and tenants in the CDN.
+ The :ref:`health-proto` monitors the usage of the :term:`cache server`\ s and tenants in the :abbr:`CDN (Content Delivery Network)`.
Configuration Management System
- In many cases a CDN encompasses hundreds of servers across a large geographic area. The Configuration Management System allows an operator to manage these servers.
+ In many cases a :abbr:`CDN (Content Delivery Network)` encompasses hundreds or even thousands of servers across a large geographic area. In such cases, manual configuration of servers becomes impractical, and so a central authority on configuration is used to automate the tasks as much as possible. :ref:`to-overview` is the Traffic Control configuration management system, which is interacted with via :ref:`tp-overview`.
Log File Analysis System
- Every transaction in the CDN gets logged. The Log File Analysis System aggregates all of the log entries from all of the servers to a central location for analysis and troubleshooting.
+ Statistics and analysis are extremely important to the management and administration of a :abbr:`CDN (Content Delivery Network)`. Transaction logs and usage statistics for a Traffic Control :abbr:`CDN (Content Delivery Network)` are gathered into :ref:`ts-overview`.
diff --git a/docs/source/basics/http_11.rst b/docs/source/basics/http_11.rst
index 816c876..3747a68 100644
--- a/docs/source/basics/http_11.rst
+++ b/docs/source/basics/http_11.rst
@@ -13,40 +13,32 @@
.. limitations under the License.
..
-.. index::
- http/1.1
- HTTP
-
+********
HTTP/1.1
... 3246 lines suppressed ...