You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2018/09/26 13:51:13 UTC
[GitHub] mitchell852 closed pull request #2818: Documentation updates
mitchell852 closed pull request #2818: Documentation updates
URL: https://github.com/apache/trafficcontrol/pull/2818
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/docs/Makefile b/docs/Makefile
index 733d70080..786bf19b5 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -19,7 +19,7 @@
#
# You can set these variables from the command line.
-SPHINXOPTS =
+SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER = letter
BUILDDIR = build
@@ -68,7 +68,7 @@ $(BUILDDIR):
-mkdir $(BUILDDIR)
html: $(BUILDDIR)
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ $(SPHINXBUILD) -j 4 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/docs/source/_static/.placeholder b/docs/source/_static/.placeholder
deleted file mode 100644
index 98ba9700e..000000000
--- a/docs/source/_static/.placeholder
+++ /dev/null
@@ -1,3 +0,0 @@
-This file is meant to hold this directory in git.
-
-You can delete once other files are added.
diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
index a00e0b80e..2d48fce56 100644
--- a/docs/source/_static/theme_overrides.css
+++ b/docs/source/_static/theme_overrides.css
@@ -6,9 +6,9 @@
* to you 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
@@ -25,10 +25,10 @@
word-wrap: break-word !important;
}
-.wy-table-responsive {
+/*.wy-table-responsive {
overflow: visible !important;
}
-
+*/
.wy-side-nav-search {
background-color: #000000;
}
@@ -36,20 +36,20 @@
.adminition-title {
background-color: #404040;
}
-.wy-alert.wy-alert-info, .rst-content .note, .rst-content .wy-alert-info.attention, .rst-content .wy-alert-info.caution, .rst-content
-.wy-alert-info.danger, .rst-content .wy-alert-info.error, .rst-content .wy-alert-info.hint, .rst-content .wy-alert-info.important,
+.wy-alert.wy-alert-info, .rst-content .note, .rst-content .wy-alert-info.attention, .rst-content .wy-alert-info.caution, .rst-content
+.wy-alert-info.danger, .rst-content .wy-alert-info.error, .rst-content .wy-alert-info.hint, .rst-content .wy-alert-info.important,
.rst-content .wy-alert-info.tip, .rst-content .wy-alert-info.warning, .rst-content .seealso, .rst-content .wy-alert-info.admonition-todo {
- background: #edf0f2;
+ background: #dde0e2;
}
-.wy-alert.wy-alert-info .wy-alert-title, .rst-content .note .wy-alert-title, .rst-content .wy-alert-info.attention .wy-alert-title,
-.rst-content .wy-alert-info.caution .wy-alert-title, .rst-content .wy-alert-info.danger .wy-alert-title, .rst-content .wy-alert-info.error
-.wy-alert-title, .rst-content .wy-alert-info.hint .wy-alert-title, .rst-content .wy-alert-info.important .wy-alert-title, .rst-content
-.wy-alert-info.tip .wy-alert-title, .rst-content .wy-alert-info.warning .wy-alert-title, .rst-content .seealso .wy-alert-title, .rst-content
-.wy-alert-info.admonition-todo .wy-alert-title, .wy-alert.wy-alert-info .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-info
-.admonition-title, .rst-content .note .admonition-title, .rst-content .wy-alert-info.attention .admonition-title, .rst-content .wy-alert-info.caution
-.admonition-title, .rst-content .wy-alert-info.danger .admonition-title, .rst-content .wy-alert-info.error .admonition-title, .rst-content
-.wy-alert-info.hint .admonition-title, .rst-content .wy-alert-info.important .admonition-title, .rst-content .wy-alert-info.tip .admonition-title,
+.wy-alert.wy-alert-info .wy-alert-title, .rst-content .note .wy-alert-title, .rst-content .wy-alert-info.attention .wy-alert-title,
+.rst-content .wy-alert-info.caution .wy-alert-title, .rst-content .wy-alert-info.danger .wy-alert-title, .rst-content .wy-alert-info.error
+.wy-alert-title, .rst-content .wy-alert-info.hint .wy-alert-title, .rst-content .wy-alert-info.important .wy-alert-title, .rst-content
+.wy-alert-info.tip .wy-alert-title, .rst-content .wy-alert-info.warning .wy-alert-title, .rst-content .seealso .wy-alert-title, .rst-content
+.wy-alert-info.admonition-todo .wy-alert-title, .wy-alert.wy-alert-info .rst-content .admonition-title, .rst-content .wy-alert.wy-alert-info
+.admonition-title, .rst-content .note .admonition-title, .rst-content .wy-alert-info.attention .admonition-title, .rst-content .wy-alert-info.caution
+.admonition-title, .rst-content .wy-alert-info.danger .admonition-title, .rst-content .wy-alert-info.error .admonition-title, .rst-content
+.wy-alert-info.hint .admonition-title, .rst-content .wy-alert-info.important .admonition-title, .rst-content .wy-alert-info.tip .admonition-title,
.rst-content .wy-alert-info.warning .admonition-title, .rst-content .seealso .admonition-title, .rst-content .wy-alert-info.admonition-todo .admonition-title {
background: #404040;
}
@@ -64,6 +64,12 @@
.wy-nav-content {
padding:1.618em 3.236em;
height:100%;
- max-width:1100px;
- margin:auto;
+ /*max-width:1100px;*/
+ max-width: none;
+ /*margin:auto;*/
+}
+
+/* Darker Table borders (they're hard to see imo) */
+.wy-table-responsive > table, .wy-table-responsive > table th, .wy-table-responsive > table td {
+ border-color: #989898 !important;
}
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
new file mode 100644
index 000000000..456a1a641
--- /dev/null
+++ b/docs/source/_templates/layout.html
@@ -0,0 +1,15 @@
+{# 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. #}
+{% extends "!layout.html" %}
+{% block extrahead %}
+ <link href="{{ pathto('_static/theme_overrides.css', True) }}" rel="stylesheet" type="text/css"/>
+{% endblock %}
diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst
index 827777f07..19d535cd2 100644
--- a/docs/source/admin/index.rst
+++ b/docs/source/admin/index.rst
@@ -1,17 +1,17 @@
-..
-..
+..
+..
.. 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.
-..
+..
Administrator's Guide
*********************
@@ -24,30 +24,29 @@ When installing a complete CDN from scratch, a sample recommended order is:
#. Traffic Vault (Riak)
#. Traffic Monitor
#. Apache Traffic Server Mid-Tier Caches
-#. Apache Traffic Server Edge 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), which the Mid-Tier Cache(s) get content from. An Origin server is simply an HTTP(S) server which serves the content you wish to cache on the CDN.
+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
+ :maxdepth: 3
- traffic_ops/installation.rst
- traffic_ops/default_profiles.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_monitor.rst
- traffic_monitor_golang.rst
- traffic_router.rst
- traffic_router/migrationto2-3.rst
- traffic_stats.rst
- traffic_server.rst
- traffic_vault.rst
- quick_howto/index.rst
+ 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_monitor.rst
+ traffic_router.rst
+ traffic_router/migrationto2-3.rst
+ traffic_stats.rst
+ traffic_server.rst
+ traffic_vault.rst
+ quick_howto/index.rst
diff --git a/docs/source/admin/quick_howto/anonymous_blocking.rst b/docs/source/admin/quick_howto/anonymous_blocking.rst
index 4ee0ad5bd..a78cc6e20 100644
--- a/docs/source/admin/quick_howto/anonymous_blocking.rst
+++ b/docs/source/admin/quick_howto/anonymous_blocking.rst
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _rl-anonymous_blocking-qht:
+.. _anonymous_blocking-qht:
**************************************
Configure Anonymous Blocking
@@ -33,14 +33,14 @@ Anonymous Blocking uses a configuration file in JSON format to define blocking r
"name": "Anonymous IP Blocking Policy",
"anonymousIp": { "blockAnonymousVPN": true,
- "blockHostingProvider": true,
+ "blockHostingProvider": true,
"blockPublicProxy": true,
"blockTorExitNode": true},
-
+
"ip4Whitelist": ["192.168.30.0/24", "10.0.2.0/24", "10.1.1.1/32"],
-
+
"ip6Whitelist": ["2001:550:90a::/48", "::1/128"],
-
+
"redirectUrl": "http://youvebeenblocked.com"
}
@@ -59,13 +59,13 @@ The following three new parameters are required to be added into CRConfig.json:
* "anonymousip.polling.url": the HTTP URL of the Anonymous IP Database. Traffic Router will fetch the file from this URL.
* "anonymousip.polling.interval": the interval that Traffic Router polls the Anonymous Blocking configuration file and Anonymous IP Database.
-.. image:: anonymous_blocking01.png
+.. image:: anonymous_blocking/01.png
:scale: 100%
:align: center
3) Enable Anonmyous Blocking for a delivery service
-.. image:: anonymous_blocking02.png
+.. image:: anonymous_blocking/02.png
:scale: 100%
:align: center
@@ -73,7 +73,7 @@ The following three new parameters are required to be added into CRConfig.json:
Go to Tools->Snapshot CRConfig, perform “Diff CRConfig” and click "Write CRConfig".
-.. image:: regionalgeo03.png
+.. image:: regionalgeo/03.png
:scale: 70%
:align: center
@@ -83,5 +83,5 @@ Anonymous Blocking extends the field of "rtype" and adds a new field "ANON_BLOCK
If rtype=ANON_BLOCK then the client's IP was found in the Anonymous IP Database and was blocked.
-
+
diff --git a/docs/source/admin/quick_howto/anonymous_blocking01.png b/docs/source/admin/quick_howto/anonymous_blocking/01.png
similarity index 100%
rename from docs/source/admin/quick_howto/anonymous_blocking01.png
rename to docs/source/admin/quick_howto/anonymous_blocking/01.png
diff --git a/docs/source/admin/quick_howto/anonymous_blocking02.png b/docs/source/admin/quick_howto/anonymous_blocking/02.png
similarity index 100%
rename from docs/source/admin/quick_howto/anonymous_blocking02.png
rename to docs/source/admin/quick_howto/anonymous_blocking/02.png
diff --git a/docs/source/admin/quick_howto/dnssec.rst b/docs/source/admin/quick_howto/dnssec.rst
index d336057a5..3c99a0c7c 100644
--- a/docs/source/admin/quick_howto/dnssec.rst
+++ b/docs/source/admin/quick_howto/dnssec.rst
@@ -1,72 +1,98 @@
-..
-..
+..
+..
.. 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.
-..
+..
-.. _rl-dnssec-qht:
+.. _dnssec-qht:
****************
Configure DNSSEC
****************
+.. seealso:: :ref:`tr-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.
-1) Go to Tools->Manage DNSSEC Keys choose a CDN and click Manage DNSSEC Keys
+#. Go to 'CDNs' and click on the desired CDN.
+
+ .. figure:: dnssec/00.png
+ :width: 60%
+ :align: center
+ :alt: Screenshot of the Traffic Portal UI depicting the CDNs page
+
+ CDNs Page
+
+#. Click on 'Manage DNSSEC Keys' under the 'More' drop-down menu.
+
+ .. figure:: dnssec/01.png
+ :width: 60%
+ :align: center
+ :alt: Screenshot of the Traffic Portal UI depicting the CDN details page
+
+ CDN Details Page
+
+#. Click on the 'Generate DNSSEC Keys' button.
+
+ .. figure:: dnssec/02.png
+ :width: 60%
+ :align: center
+ :alt: Screenshot of the Traffic Portal UI depicting the CDN DNSSEC Key Management page
+
+ DNSSEC Key Management Page
+
+#. A modal will pop up asking you to confirm that you want to proceed.
+
+ .. figure:: dnssec/03.png
+ :width: 30%
+ :align: center
+ :alt: Screenshot of the Traffic Portal UI depicting the CDN DNSSEC Key Generation confirmation modal
-.. image:: dnssec01.png
- :scale: 100%
- :align: center
+ Confirmation Modal
-2) Generate keys for a CDN by clicking Generate Keys then entering the following information:
-
- - Expiration in days for the Zone Signing Key (ZSK)
- - Expiration in days for the Key Signing Key (KSK)
- - Effective Date
+#. Input the required information (reasonable defaults should be generated for you). When done, click on the green 'Generate' button.:
- Once the required information has been entered click on the 'Generate Keys' button.
+ .. note:: Depending upon the number of Delivery Services in the CDN, generating DNSSEC keys may take several seconds.
- Depending upon the number of Delivery Services in the CDN, generating DNSSEC keys may take serveral seconds.
+ .. figure:: dnssec/04.png
+ :width: 50%
+ :align: center
+ :alt: Screenshot of the Traffic Portal UI depicting the CDN DNSSEC Key Generation page
-.. image:: dnssec02.png
- :scale: 100%
- :align: center
+ DNSSEC Key Generation Page
-3) 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 'cdn.kabletown.net' the parent zone is 'kabletown.net').
+#. 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.
- 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.
+ .. figure:: dnssec/05.png
+ :width: 30%
+ :align: center
+ :alt: Screenshot of the Traffic Portal UI depicting the confirmation modal for committing changes to DNSSEC Keys.
-.. image:: dnssec03.png
- :scale: 70%
- :align: center
+ DNSSEC Key Change Confirmation
-4) 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.
-
- Click on Tools -> Manage DNSSEC Keys -> Choose your CDN -> On the Manage DNSSEC Keys page click the activate DNSSEC Keys button.
- This will add a 'dnssec.enabled = "true"' entry to CRConfig for the chosen CDN.
+#. 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.
-.. image:: dnssec04.png
- :scale: 70%
- :align: center
+#. 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.
-5) DNSSEC should now be active on your CDN and Traffic Router should be signing responses.
-
- A dig command with +dnssec added should show you the signed responses.
+ .. figure:: dnssec/06.png
+ :width: 60%
+ :align: center
+ :alt: Screenshot of the Traffic Portal UI depicting the details page for a CDN when changing its 'DNSSEC Enabled' field
- ``dig edge.cdn.kabletown.net. +dnssec``
+ Change 'DNSSEC Enabled' to 'true'
-6) 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.
+#. 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``.
- A new KSK can be generated by clicking the 'Regenerate KSK' button on the Manage DNSSEC Keys screen (see screenshot above).
+#. 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.
diff --git a/docs/source/admin/quick_howto/dnssec/00.png b/docs/source/admin/quick_howto/dnssec/00.png
new file mode 100644
index 000000000..003313f13
Binary files /dev/null and b/docs/source/admin/quick_howto/dnssec/00.png differ
diff --git a/docs/source/admin/quick_howto/dnssec/01.png b/docs/source/admin/quick_howto/dnssec/01.png
new file mode 100644
index 000000000..f4d5cf728
Binary files /dev/null and b/docs/source/admin/quick_howto/dnssec/01.png differ
diff --git a/docs/source/admin/quick_howto/dnssec/02.png b/docs/source/admin/quick_howto/dnssec/02.png
new file mode 100644
index 000000000..adb97661d
Binary files /dev/null and b/docs/source/admin/quick_howto/dnssec/02.png differ
diff --git a/docs/source/admin/quick_howto/dnssec/03.png b/docs/source/admin/quick_howto/dnssec/03.png
new file mode 100644
index 000000000..4d615a573
Binary files /dev/null and b/docs/source/admin/quick_howto/dnssec/03.png differ
diff --git a/docs/source/admin/quick_howto/dnssec/04.png b/docs/source/admin/quick_howto/dnssec/04.png
new file mode 100644
index 000000000..2d56a433f
Binary files /dev/null and b/docs/source/admin/quick_howto/dnssec/04.png differ
diff --git a/docs/source/admin/quick_howto/dnssec/05.png b/docs/source/admin/quick_howto/dnssec/05.png
new file mode 100644
index 000000000..847fee0fa
Binary files /dev/null and b/docs/source/admin/quick_howto/dnssec/05.png differ
diff --git a/docs/source/admin/quick_howto/dnssec/06.png b/docs/source/admin/quick_howto/dnssec/06.png
new file mode 100644
index 000000000..225ac3065
Binary files /dev/null and b/docs/source/admin/quick_howto/dnssec/06.png differ
diff --git a/docs/source/admin/quick_howto/dnssec01.png b/docs/source/admin/quick_howto/dnssec01.png
deleted file mode 100644
index 044538f52..000000000
Binary files a/docs/source/admin/quick_howto/dnssec01.png and /dev/null differ
diff --git a/docs/source/admin/quick_howto/dnssec02.png b/docs/source/admin/quick_howto/dnssec02.png
deleted file mode 100644
index 82fa75a6f..000000000
Binary files a/docs/source/admin/quick_howto/dnssec02.png and /dev/null differ
diff --git a/docs/source/admin/quick_howto/dnssec03.png b/docs/source/admin/quick_howto/dnssec03.png
deleted file mode 100644
index 1fc3cce00..000000000
Binary files a/docs/source/admin/quick_howto/dnssec03.png and /dev/null differ
diff --git a/docs/source/admin/quick_howto/dnssec04.png b/docs/source/admin/quick_howto/dnssec04.png
deleted file mode 100644
index f9b8d3219..000000000
Binary files a/docs/source/admin/quick_howto/dnssec04.png and /dev/null differ
diff --git a/docs/source/admin/quick_howto/ds_requests.rst b/docs/source/admin/quick_howto/ds_requests.rst
index 997935e79..45fb5b6a0 100644
--- a/docs/source/admin/quick_howto/ds_requests.rst
+++ b/docs/source/admin/quick_howto/ds_requests.rst
@@ -18,64 +18,47 @@
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 config updates (aka queue updates) and/or a cdn snapshot. Both of these actions are reserved for users with elevated permissions.
+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 permissions.
-A list of the delivery service requests associated with your tenant can be found here:
+A list of the Delivery Service requests associated with your tenant can be found under 'Services' -> 'Delivery Service Requests'
-``https://traffic-portal.domain.com/#!/delivery-service-requests``
+.. figure:: ../traffic_portal/images/tp_table_ds_requests.png
+ :width: 60%
+ :align: center
+ :alt: A screenshot of the Traffic Portal UI depicting an example list of Delivery Service Requests
-.. image:: ../traffic_portal/images/tp_table_ds_requests.png
+ Example Delivery Service Request Listing
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 role (or above) can create Delivery Service Requests by doing one of three things:
-1. Creating a new delivery service
-2. Updating an existing delivery service
-3. Deleting an exiting delivery service
+- Creating a new Delivery Service
+- Updating an existing Delivery Service
+- Deleting an exiting 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. Only change the status of your request to submitted once the request is ready for review and deployment.
+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.
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:
+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.
-Optional. This will update the "Last Edited By" field to indicate who last updated the request.
-
-Assign or unassign the delivery service request
-***********************************************
-
-Optional. Assignment is currently limited to current user. This is optional as fulfillment will auto-assign the request to the user doing the fulfillment.
-
-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 config 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 config 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``.
-
-
-Delete the delivery service request
-***********************************
-
-Delivery service requests with a status of draft or submitted can always be deleted entirely if appropriate.
+Assign or Unassign the Delivery Service Request
+ Assignment is currently limited to current user. This is optional as fulfillment will auto-assign the request to the user doing the fulfillment.
+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'.
+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'.
+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 a57473ee5..87f6e6ae2 100644
--- a/docs/source/admin/quick_howto/federations.rst
+++ b/docs/source/admin/quick_howto/federations.rst
@@ -1,32 +1,32 @@
-..
-..
+..
+..
.. 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.
-..
+..
-.. _rl-federations-qht:
+.. _federations-qht:
*********************
Configure Federations
*********************
-1) Create a user with a federations role (Misc -> Users -> Add User). This user will have the ability to perform the following actions:
-
+1) Create a user with a federations role (Misc -> Users -> Add User). This user will have the ability to perform the following actions:
+
- Edit the federation
- Delete the federation
- Add IPV4 resolvers
- Add IPV6 resolvers
-.. image:: federation01.png
+.. image:: federations/01.png
:scale: 100%
:align: center
@@ -34,21 +34,21 @@ Configure Federations
3) Choose the Delivery Service for the federation to be mapped to and assign it to the Federation User; click Add.
-.. image:: federation02.png
+.. image:: federations/02.png
:scale: 100%
:align: center
-4) After the Federation is added, Traffic Ops will display the Federation.
+4) 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 user created in step 1.
+ 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 user created in step 1.
- If no further action is necessary, the Close button will close the window and display the list of all Federations.
+ If no further action is necessary, the Close button will close the window and display the list of all Federations.
-.. image:: federation03.png
+.. image:: federations/03.png
:scale: 100%
:align: center
-
+
**The Federation user can now add resolvers to the Federation Mapping in Traffic Ops.**
5) The federation user logs to traffic ops and stores the mojolicious cookie. The mojolicious cookie can be obtained manually using the debug tools on a web browser or via curl.
@@ -73,19 +73,19 @@ Configure Federations
{"alerts":[{"level":"success","text":"Successfully logged in."}]}
6) The federation user sends a request to Traffic Ops to add IPV4 and/or IPV6 resolvers
-
+
Example::
$ curl -ki -H "Cookie: mojolicious=eyJleHBpcmVzIjoxNDQ5MTA1MTI2LCJhdXRoX2RhdGEiOiJmZWRlcmF0aW9uX3VzZXIxIn0---06b4f870d809d82a91433e92eae8320875c3e8b0;" -XPUT 'http://localhost:3000/api/1.2/federations' -d '
- {"federations": [
- { "deliveryService": "images-c1",
- "mappings":
+ {"federations": [
+ { "deliveryService": "images-c1",
+ "mappings":
{ "resolve4": [ "8.8.8.8/32", "8.8.4.4/32" ],
"resolve6": ["2001:4860:4860::8888/128", "2001:4860:4860::8844"]
- }
- }
- ]
+ }
+ }
+ ]
}'
HTTP/1.1 200 OK
@@ -105,7 +105,7 @@ Configure Federations
7) The resolvers added by the federation user will now visible in Traffic Ops.
-.. image:: federation04.png
+.. image:: federations/04.png
:scale: 100%
:align: center
@@ -132,4 +132,4 @@ Configure Federations
;; Query time: 9 msec
;; SERVER: 10.10.10.10#53(10.10.10.10)
;; WHEN: Wed Dec 2 22:05:26 2015
- ;; MSG SIZE rcvd: 84
\ No newline at end of file
+ ;; MSG SIZE rcvd: 84
diff --git a/docs/source/admin/quick_howto/federation01.png b/docs/source/admin/quick_howto/federations/01.png
similarity index 100%
rename from docs/source/admin/quick_howto/federation01.png
rename to docs/source/admin/quick_howto/federations/01.png
diff --git a/docs/source/admin/quick_howto/federation02.png b/docs/source/admin/quick_howto/federations/02.png
similarity index 100%
rename from docs/source/admin/quick_howto/federation02.png
rename to docs/source/admin/quick_howto/federations/02.png
diff --git a/docs/source/admin/quick_howto/federation03.png b/docs/source/admin/quick_howto/federations/03.png
similarity index 100%
rename from docs/source/admin/quick_howto/federation03.png
rename to docs/source/admin/quick_howto/federations/03.png
diff --git a/docs/source/admin/quick_howto/federation04.png b/docs/source/admin/quick_howto/federations/04.png
similarity index 100%
rename from docs/source/admin/quick_howto/federation04.png
rename to docs/source/admin/quick_howto/federations/04.png
diff --git a/docs/source/admin/quick_howto/index.rst b/docs/source/admin/quick_howto/index.rst
index 4c6b6dcc9..5d27bf636 100644
--- a/docs/source/admin/quick_howto/index.rst
+++ b/docs/source/admin/quick_howto/index.rst
@@ -23,21 +23,16 @@ Traffic Ops
.. toctree::
- multi_site.rst
- dnssec.rst
- federations.rst
- regionalgeo.rst
- anonymous_blocking.rst
- steering.rst
+ multi_site.rst
+ federations.rst
+ regionalgeo.rst
+ anonymous_blocking.rst
Traffic Portal
==============
.. toctree::
- ds_requests.rst
-
-
-
-
-
+ dnssec.rst
+ ds_requests.rst
+ steering.rst
diff --git a/docs/source/admin/quick_howto/multi_site.rst b/docs/source/admin/quick_howto/multi_site.rst
index 6e0f0dd2f..54d0bc98f 100644
--- a/docs/source/admin/quick_howto/multi_site.rst
+++ b/docs/source/admin/quick_howto/multi_site.rst
@@ -1,105 +1,101 @@
-..
-..
+..
+..
.. 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.
-..
+..
-.. _rl-multi-site-origin-qht:
+.. _multi-site-origin-qht:
***************************
-Configure Multi Site Origin
+Configure Multi-Site Origin
***************************
+The following steps will take you through the procedure of setting up a Multi-Site Origin (MSO).
-1) Create cachegroups for the origin locations, and assign the appropriate parent-child relationship between the mid and org cachegroups (click the image to see full size). Each mid cachegroup can be assigned a primary and secondary origin parent cachegroup. When the mid cache parent configuration is generated, origins in the primary cachegroups will be listed first, followed by origins in the secondary cachegroup. Origin servers assigned to the delivery service that are assigned to neither the primary nor secondary cachegroups will be listed last.
+#. Create Cache Groups for the origin locations, and assign the appropriate parent-child relationship between the mid and origin Cache Groups. Each mid Cache Group can be assigned a primary and secondary origin parent Cache Group. When the mid cache parent configuration is generated, origins in the primary Cache Groups will be listed first, followed by origins in the secondary Cache Group. Origin servers assigned to the Delivery Service that are assigned to neither the primary nor secondary Cache Groups will be listed last.
-.. image:: C5C4CD22-949A-48FD-8976-C673083E2177.png
- :scale: 100%
- :align: center
+ .. figure:: multi_site/00.png
+ :scale: 100%
+ :align: center
-2) Create a profile to assign to each of the origins:
+#. Create a profile to assign to each of the origins:
-.. image:: 19BB6EC1-B6E8-4D22-BFA0-B7D6A9708B42.png
- :scale: 100%
- :align: center
+ .. figure:: multi_site/01.png
+ :scale: 100%
+ :align: center
-3) Create server entries for the origination vips:
+#. Create server entries for the origination vips:
-.. image:: D28614AA-9758-45ED-9EFD-3A284FC4218E.png
- :scale: 100%
- :align: center
+ .. figure:: multi_site/02.png
+ :scale: 100%
+ :align: center
-4) Check the multi-site check box in the delivery service screen:
+#. Check the multi-site check box in the delivery service screen:
-.. image:: mso-enable.png
- :scale: 100%
- :align: center
+ .. figure:: multi_site/mso-enable.png
+ :scale: 100%
+ :align: center
-5) 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 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.
-.. image:: 066CEF4F-C1A3-4A89-8B52-4F72B0531367.png
- :scale: 100%
- :align: center
+ .. 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 failover, it requires that “Origin Server Base URL” (OFQDN) for each MSO enabled delivery service is unique unless the exceptions listed afterwards. This means that the OFQDN of a MSO enabled delivery service should be different with the OFQDNs of any other delivery service, regardless of whether they are MSO enabled or not. The exceptions are:
+ .. 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:
- 1. If there are multiple CDNs created on the same Traffic Ops, delivery services across different CDNs may have the same OFQDN configured.
- 2. If several delivery services in the same CDN have the same MSO algorithm configured, they may share the same OFQDN.
- 3. If delivery services are assigned with different MID cache groups respectively, they can share the same OFQDN.
- 4. This OFQDN must be valid - ATS will perform a DNS lookup on this FQDN even if IPs, not DNS, are used in the parent.config.
- 5. The OFQDN 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, 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 cache groups 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.
+#. 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.
-6) For ATS 5.x, configure the mid hdr_rewrite on the delivery service, example: ::
+ a) Create a profile of the type DS_PROFILE for the delivery service in question.
- cond %{REMAP_PSEUDO_HOOK} __RETURN__ set-config proxy.config.http.parent_origin.dead_server_retry_enabled 1 __RETURN__ set-config proxy.config.http.parent_origin.simple_retry_enabled 1 __RETURN__ set-config proxy.config.http.parent_origin.simple_retry_response_codes "400,404,412" __RETURN__ set-config proxy.config.http.parent_origin.dead_server_retry_response_codes "502,503" __RETURN__ set-config proxy.config.http.connect_attempts_timeout 2 __RETURN__ set-config proxy.config.http.connect_attempts_max_retries 2 __RETURN__ set-config proxy.config.http.connect_attempts_max_retries_dead_server 1 __RETURN__ set-config proxy.config.http.transaction_active_timeout_in 5 [L] __RETURN__
+ .. figure:: multi_site/ds_profile.png
+ :scale: 50%
+ :align: center
-7) 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.
+ #) Click "Show profile parameters" to bring up the parameters screen for the profile. Create parameters for the following:
- a) Create a profile of the type DS_PROFILE for the delivery service in question.
+ +----------------------------------------+------------------+--------------------------+-------------------------+
+ | Parameter Name | Config File Name | Value | ATS parent.config value |
+ +========================================+==================+==========================+=========================+
+ | mso.algorithm | parent.config | true, false, strict, | round_robin |
+ | | | consistent_hash | |
+ +----------------------------------------+------------------+--------------------------+-------------------------+
+ | mso.parent_retry | parent.config | simple_retry, both, | parent_retry |
+ | | | unavailable_server_retry | |
+ +----------------------------------------+------------------+--------------------------+-------------------------+
+ | mso.unavailable_server_retry_responses | parent.config | list of server response | defaults to the value |
+ | | | codes, eg "500,502,503" | in records.config |
+ | | | | when unused. |
+ +----------------------------------------+------------------+--------------------------+-------------------------+
+ | mso.max_simple_retries | parent.config | Nubmer of retries made | defaults to the value |
+ | | | after a 4xx error | in records.config |
+ | | | | when unused. |
+ +----------------------------------------+------------------+--------------------------+-------------------------+
+ | mso.max_unavailable_server_retries | parent.config | Nubmer of retries made | defaults to the value |
+ | | | after a 5xx error | in records.config |
+ | | | | when unused. |
+ +----------------------------------------+------------------+--------------------------+-------------------------+
- .. image:: ds-profile.png
- :scale: 50%
- :align: center
- b) Click "Show profile parameters" to bring up the parameters screen for the profile. Create parameters for the following:
+ .. figure:: multi_site/ds_profile_parameters.png
+ :scale: 100%
+ :align: center
- +----------------------------------------+------------------+--------------------------+-------------------------+
- | Parameter Name | Config File Name | Value | ATS parent.config value |
- +========================================+==================+==========================+=========================+
- | mso.algorithm | parent.config | true, false, strict, | round_robin |
- | | | consistent_hash | |
- +----------------------------------------+------------------+--------------------------+-------------------------+
- | mso.parent_retry | parent.config | simple_retry, both, | parent_retry |
- | | | unavailable_server_retry | |
- +----------------------------------------+------------------+--------------------------+-------------------------+
- | mso.unavailable_server_retry_responses | parent.config | list of server response | defaults to the value |
- | | | codes, eg "500,502,503" | in records.config |
- | | | | when unused. |
- +----------------------------------------+------------------+--------------------------+-------------------------+
- | mso.max_simple_retries | parent.config | Nubmer of retries made | defaults to the value |
- | | | after a 4xx error | in records.config |
- | | | | when unused. |
- +----------------------------------------+------------------+--------------------------+-------------------------+
- | mso.max_unavailable_server_retries | parent.config | Nubmer of retries made | defaults to the value |
- | | | after a 5xx error | in records.config |
- | | | | when unused. |
- +----------------------------------------+------------------+--------------------------+-------------------------+
+ #) In the delivery service page, select the newly created DS_PROFILE and save the delivery service.
-
- .. image:: ds_profile_parameters.png
- :scale: 100%
- :align: center
-
- c) In the delivery service page, select the newly created DS_PROFILE and save the delivery service.
-
-8) Turn on parent_proxy_routing in the MID profile.
+#. Turn on parent_proxy_routing in the MID profile.
diff --git a/docs/source/admin/quick_howto/C5C4CD22-949A-48FD-8976-C673083E2177.png b/docs/source/admin/quick_howto/multi_site/00.png
similarity index 100%
rename from docs/source/admin/quick_howto/C5C4CD22-949A-48FD-8976-C673083E2177.png
rename to docs/source/admin/quick_howto/multi_site/00.png
diff --git a/docs/source/admin/quick_howto/19BB6EC1-B6E8-4D22-BFA0-B7D6A9708B42.png b/docs/source/admin/quick_howto/multi_site/01.png
similarity index 100%
rename from docs/source/admin/quick_howto/19BB6EC1-B6E8-4D22-BFA0-B7D6A9708B42.png
rename to docs/source/admin/quick_howto/multi_site/01.png
diff --git a/docs/source/admin/quick_howto/D28614AA-9758-45ED-9EFD-3A284FC4218E.png b/docs/source/admin/quick_howto/multi_site/02.png
similarity index 100%
rename from docs/source/admin/quick_howto/D28614AA-9758-45ED-9EFD-3A284FC4218E.png
rename to docs/source/admin/quick_howto/multi_site/02.png
diff --git a/docs/source/admin/quick_howto/066CEF4F-C1A3-4A89-8B52-4F72B0531367.png b/docs/source/admin/quick_howto/multi_site/03.png
similarity index 100%
rename from docs/source/admin/quick_howto/066CEF4F-C1A3-4A89-8B52-4F72B0531367.png
rename to docs/source/admin/quick_howto/multi_site/03.png
diff --git a/docs/source/admin/quick_howto/ds-profile.png b/docs/source/admin/quick_howto/multi_site/ds_profile.png
similarity index 100%
rename from docs/source/admin/quick_howto/ds-profile.png
rename to docs/source/admin/quick_howto/multi_site/ds_profile.png
diff --git a/docs/source/admin/quick_howto/ds_profile_parameters.png b/docs/source/admin/quick_howto/multi_site/ds_profile_parameters.png
similarity index 100%
rename from docs/source/admin/quick_howto/ds_profile_parameters.png
rename to docs/source/admin/quick_howto/multi_site/ds_profile_parameters.png
diff --git a/docs/source/admin/quick_howto/mso-enable.png b/docs/source/admin/quick_howto/multi_site/mso-enable.png
similarity index 100%
rename from docs/source/admin/quick_howto/mso-enable.png
rename to docs/source/admin/quick_howto/multi_site/mso-enable.png
diff --git a/docs/source/admin/quick_howto/regionalgeo.rst b/docs/source/admin/quick_howto/regionalgeo.rst
index 36fd5081a..6a77ddde4 100644
--- a/docs/source/admin/quick_howto/regionalgeo.rst
+++ b/docs/source/admin/quick_howto/regionalgeo.rst
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _rl-regionalgeo-qht:
+.. _regionalgeo-qht:
**************************************
Configure Regional Geo-blocking (RGB)
@@ -62,13 +62,13 @@ The two new parameters in following table are required to be added into CRConfig
* "regional_geoblocking.polling.url": the HTTP URL of RGB configuration file. Traffic Router will fetch the file from this URL.
* "regional_geoblocking.polling.interval": the interval that Traffic Router polls the RGB configuration file.
-.. image:: regionalgeo01.png
+.. image:: regionalgeo/01.png
:scale: 100%
:align: center
3) Enable RGB for a delivery service
-.. image:: regionalgeo02.png
+.. image:: regionalgeo/02.png
:scale: 100%
:align: center
@@ -76,7 +76,7 @@ The two new parameters in following table are required to be added into CRConfig
Go to Tools->Snapshot CRConfig, perform “Diff CRConfig” and click "Write CRConfig".
-.. image:: regionalgeo03.png
+.. image:: regionalgeo/03.png
:scale: 70%
:align: center
diff --git a/docs/source/admin/quick_howto/regionalgeo01.png b/docs/source/admin/quick_howto/regionalgeo/01.png
similarity index 100%
rename from docs/source/admin/quick_howto/regionalgeo01.png
rename to docs/source/admin/quick_howto/regionalgeo/01.png
diff --git a/docs/source/admin/quick_howto/regionalgeo02.png b/docs/source/admin/quick_howto/regionalgeo/02.png
similarity index 100%
rename from docs/source/admin/quick_howto/regionalgeo02.png
rename to docs/source/admin/quick_howto/regionalgeo/02.png
diff --git a/docs/source/admin/quick_howto/regionalgeo03.png b/docs/source/admin/quick_howto/regionalgeo/03.png
similarity index 100%
rename from docs/source/admin/quick_howto/regionalgeo03.png
rename to docs/source/admin/quick_howto/regionalgeo/03.png
diff --git a/docs/source/admin/quick_howto/steering.rst b/docs/source/admin/quick_howto/steering.rst
index 96ae5bd49..f1d3325b3 100644
--- a/docs/source/admin/quick_howto/steering.rst
+++ b/docs/source/admin/quick_howto/steering.rst
@@ -13,99 +13,78 @@
.. limitations under the License.
..
-.. _rl-steering-qht:
+.. _steering-qht:
***********************************
Configure Delivery Service Steering
***********************************
-1) Create two target delivery services in Traffic Ops. They must both be HTTP delivery services that are part of the same CDN.
-
-.. image:: steering01.png
- :scale: 100%
- :align: center
-
-2) Create a delivery service with type STEERING in Traffic Ops.
-
-.. image:: steering02.png
- :scale: 100%
- :align: center
-
-3) Click the 'Manage Steering Assignments' button on the delivery service screen to assign targets.
-
-.. image:: steering03.png
- :scale: 100%
- :align: center
-
-4) Create a user with the role of Steering.
-
-.. image:: steering04.png
- :scale: 100%
- :align: center
-
-5) As the steering user, assign weights or orders to target delivery services. Assignments must either have a value for weight or order, but not both. The value of weight must be a positive integer, while the value of order can be any integer. This will require logging in to Traffic Ops first via ``http://to.kabletown.net/api/1.2/user/login`` and storing the mojolicious cookie.
-
- Sample cURL: ``curl -H "Cookie: mojolicious=xxxyyy" -XPUT "https://to.kabletown.net/internal/api/1.2/steering/steering-ds" -d @/tmp/steering.json``
-
- Sample JSON body:
-
-::
-
- {
- "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"
- }
- ]
- }
-
-6) If desired, the steering user can create filters for the target delivery services.
-
- Sample cURL: ``curl -H "Cookie: mojolicious=xxxyyy" -XPUT "https://to.kabletown.net/internal/api/1.2/steering/steering-ds" -d @/tmp/steering.json``
-
- Sample JSON body:
-
-::
-
- {
- "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"
- }
- ]
- }
-
-7) Any requests to Traffic Router for the steering delivery service should now be routed to target delivery services based on configured weight or order. Example: ``curl -Lvs http://foo.steering-ds.cdn.kabletown.net/bar``
+#. Create two target Delivery Services in Traffic Ops. They must both be HTTP Delivery Services that are part of the same CDN.
+ .. figure:: steering/01.png
+ :width: 80%
+ :align: center
+ :alt: Table of Target Delivery Services
+
+ Target Delivery Services
+
+#. Create a 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
+
+#. In the 'More' drop-down menu, click 'View Targets' and then use the blue '+' to assign targets.
+
+ .. figure:: steering/03.png
+ :width: 50%
+ :align: center
+ :alt: Table of STEERING Targets
+
+ 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!
diff --git a/docs/source/admin/quick_howto/steering/01.png b/docs/source/admin/quick_howto/steering/01.png
new file mode 100644
index 000000000..0b23abd46
Binary files /dev/null and b/docs/source/admin/quick_howto/steering/01.png differ
diff --git a/docs/source/admin/quick_howto/steering/02.png b/docs/source/admin/quick_howto/steering/02.png
new file mode 100644
index 000000000..6a481b5dc
Binary files /dev/null and b/docs/source/admin/quick_howto/steering/02.png differ
diff --git a/docs/source/admin/quick_howto/steering/03.png b/docs/source/admin/quick_howto/steering/03.png
new file mode 100644
index 000000000..fc2119c32
Binary files /dev/null and b/docs/source/admin/quick_howto/steering/03.png differ
diff --git a/docs/source/admin/quick_howto/steering01.png b/docs/source/admin/quick_howto/steering01.png
deleted file mode 100644
index 1515011a2..000000000
Binary files a/docs/source/admin/quick_howto/steering01.png and /dev/null differ
diff --git a/docs/source/admin/quick_howto/steering02.png b/docs/source/admin/quick_howto/steering02.png
deleted file mode 100644
index c2fc22c5e..000000000
Binary files a/docs/source/admin/quick_howto/steering02.png and /dev/null differ
diff --git a/docs/source/admin/quick_howto/steering03.png b/docs/source/admin/quick_howto/steering03.png
deleted file mode 100644
index f4b110d5b..000000000
Binary files a/docs/source/admin/quick_howto/steering03.png and /dev/null differ
diff --git a/docs/source/admin/quick_howto/steering04.png b/docs/source/admin/quick_howto/steering04.png
deleted file mode 100644
index 0ab962b1d..000000000
Binary files a/docs/source/admin/quick_howto/steering04.png and /dev/null differ
diff --git a/docs/source/admin/traffic_monitor.rst b/docs/source/admin/traffic_monitor.rst
index 859000a03..98b0080d1 100755
--- a/docs/source/admin/traffic_monitor.rst
+++ b/docs/source/admin/traffic_monitor.rst
@@ -1,177 +1,61 @@
-..
-..
+..
+..
.. 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 Monitor Administration (Legacy)
-***************************************
+******************************
+Traffic Monitor Administration
+******************************
-.. _rl-tm-java:
-
-* These instructions are for the legacy Java Traffic Monitor, for the new Golang version, see :ref:`here <rl-tm-golang>`.
+.. _tm-golang:
Installing Traffic Monitor
==========================
-The following are requirements to ensure an accurate set up:
-
-* CentOS 6
-* 4 vCPUs
-* 8GB RAM
-* Successful install of Traffic Ops
-* Tomcat
-* Administrative access to the Traffic Ops
-* Physical address of the site
-* perl-JSON
-* perl-WWW-Curl
-
-#. Add the Traffic Monitor server into Traffic Ops using 'Servers' -> 'Add Server'. Set the 'Type' field to 'RASCAL'.
-
-#. Make sure the FQDN of the Traffic Monitor is resolvable in DNS.
-
-#. Get the Traffic Monitor RPM.
-
- Sample command: ::
-
- wget http://traffic-control-cdn.net/downloads/1.7.0/RELEASE-1.7.0/traffic_monitor-1.7.0-3908.5b77f60f.el6.x86_64.rpm
-
-#. Install Traffic Monitor and Perl modules: ::
-
- sudo yum -y install traffic_monitor-*.rpm perl-JSON perl-WWW-Curl
-
-#. Take the config from Traffic Ops: ::
-
- sudo /opt/traffic_monitor/bin/traffic_monitor_config.pl https://<traffic-ops-URL> <traffic-ops-user>:<traffic-ops-password> prompt
-
- Sample session: ::
-
- traffic_mon # /opt/traffic_monitor/bin/traffic_monitor_config.pl https://traffic-ops.cdn.kabletown.net admin:kl0tevax prompt
- DEBUG: traffic_ops selected: https://traffic-ops.cdn.kabletown.net
- DEBUG: traffic_ops login: admin:kl0tevax
- DEBUG: Config write mode: prompt
- DEBUG: Found profile from traffic_ops: RASCAL_CDN
- DEBUG: Found CDN name from traffic_ops: kabletown_cdn
- DEBUG: Found location for rascal-config.txt from traffic_ops: /opt/traffic_monitor/conf
- WARN: Param not in traffic_ops: allow.config.edit description: Allow the running configuration to be edited through the UI Using default value of: false
- WARN: Param not in traffic_ops: default.accessControlAllowOrigin description: The value for the header: Access-Control-Allow-Origin for published jsons... should be narrowed down to TMs Using default value of: *
- WARN: Param not in traffic_ops: default.connection.timeout description: Default connection time for all queries (cache, peers, TM) Using default value of: 2000
- WARN: Param not in traffic_ops: hack.forceSystemExit description: Call System.exit on shutdown Using default value of: false
- WARN: Param not in traffic_ops: hack.peerOptimistic description: The assumption of a caches availability when unknown by peers Using default value of: true
- WARN: Param not in traffic_ops: hack.publishDsStates description: If true, the delivery service states will be included in the CrStates.json Using default value of: true
- WARN: Param not in traffic_ops: health.ds.interval description: The polling frequency for calculating the deliveryService states Using default value of: 1000
- WARN: Param not in traffic_ops: health.ds.leniency description: The amount of time before the deliveryService disregards the last update from a non-responsive cache Using default value of: 30000
- WARN: Param not in traffic_ops: health.event-count description: The number of historical events that will be kept Using default value of: 200
- WARN: Param not in traffic_ops: health.polling.interval description: The polling frequency for getting the states from caches Using default value of: 5000
- WARN: Param not in traffic_ops: health.startupMinCycles description: The number of query cycles that must be completed before this Traffic Monitor will start reporting Using default value of: 2
- WARN: Param not in traffic_ops: health.timepad description: A delay between each separate cache query Using default value of: 10
- WARN: Param not in traffic_ops: peers.polling.interval description: Polling frequency for getting states from peer monitors Using default value of: 5000
- WARN: Param not in traffic_ops: peers.polling.url description: The url for current, unfiltered states from peer monitors Using default value of: http://${hostname}/publish/CrStates?raw
- WARN: Param not in traffic_ops: peers.threadPool description: The number of threads given to the pool for querying peers Using default value of: 1
- WARN: Param not in traffic_ops: tm.auth.url description: The url for the authentication form Using default value of: https://${tmHostname}/login
- WARN: Param not in traffic_ops: tm.crConfig.json.polling.url description: Url for the cr-config (json) Using default value of: https://${tmHostname}/CRConfig-Snapshots/${cdnName}/CRConfig.json
- WARN: Param not in traffic_ops: tm.healthParams.polling.url description: The url for the heath params (json) Using default value of: https://${tmHostname}/health/${cdnName}
- WARN: Param not in traffic_ops: tm.polling.interval description: The polling frequency for getting updates from TM Using default value of: 10000
- DEBUG: allow.config.edit needed in config, but does not exist in config on disk.
- DEBUG: cdnName value on disk () does not match value needed in config (kabletown_cdn).
- DEBUG: default.accessControlAllowOrigin needed in config, but does not exist in config on disk.
- DEBUG: default.connection.timeout needed in config, but does not exist in config on disk.
- DEBUG: hack.forceSystemExit needed in config, but does not exist in config on disk.
- DEBUG: hack.peerOptimistic needed in config, but does not exist in config on disk.
- DEBUG: hack.publishDsStates needed in config, but does not exist in config on disk.
- DEBUG: health.ds.interval needed in config, but does not exist in config on disk.
- DEBUG: health.ds.leniency needed in config, but does not exist in config on disk.
- DEBUG: health.startupMinCycles needed in config, but does not exist in config on disk.
- DEBUG: health.timepad value on disk (20) does not match value needed in config (10).
- DEBUG: peers.polling.interval needed in config, but does not exist in config on disk.
- DEBUG: peers.threadPool needed in config, but does not exist in config on disk.
- DEBUG: tm.auth.password value on disk () does not match value needed in config (kl0tevax).
- DEBUG: tm.auth.username value on disk () does not match value needed in config (admin).
- DEBUG: tm.hostname value on disk () does not match value needed in config (traffic-ops.cdn.kabletown.net).
- DEBUG: Proposed traffic_monitor_config:
- {
- "traffic_monitor_config":{
- "default.accessControlAllowOrigin":"*",
- "health.startupMinCycles":"2",
- "tm.auth.password":"kl0tevax",
- "tm.auth.url":"https://${tmHostname}/login",
- "tm.healthParams.polling.url":"https://${tmHostname}/health/${cdnName}",
- "allow.config.edit":"false",
- "tm.crConfig.json.polling.url":"https://${tmHostname}/CRConfig-Snapshots/${cdnName}/CRConfig.json",
- "tm.auth.username":"admin",
- "peers.polling.url":"http://${hostname}/publish/CrStates?raw",
- "health.timepad":"10",
- "hack.publishDsStates":"true",
- "default.connection.timeout":"2000",
- "health.ds.interval":"1000",
- "peers.polling.interval":"5000",
- "hack.forceSystemExit":"false",
- "health.ds.leniency":"30000",
- "cdnName":"kabletown_cdn",
- "peers.threadPool":"1",
- "tm.polling.interval":"10000",
- "health.polling.interval":"5000",
- "health.event-count":"200",
- "hack.peerOptimistic":"true",
- "tm.hostname":"traffic-ops.cdn.kabletown.net"
- }
- }
- ----------------------------------------------
- ----OK to write this config to disk? (Y/n) [n]y
- ----------------------------------------------
- ----------------------------------------------
- ----OK to write this config to disk? (Y/n) [n]Y
- ----------------------------------------------
- DEBUG: Writing /opt/traffic_monitor/conf/traffic_monitor_config.js
- traffic_mon #
-
-#. Update the 'allow_ip' and 'allow_ip6' parameters in the profiles of all caches defined in traffic ops, both edge and mid,
- with the address of the traffic monitor being installed, so that the traffic servers will allow this Traffic Monitor
- to access the astats plugin.
- For details see :ref:`rl-param-prof` in the *Configuring Traffic Ops* section.
-
-#. Start Tomcat: ``sudo service tomcat start`` ::
-
- Using CATALINA_BASE: /opt/tomcat
- Using CATALINA_HOME: /opt/tomcat
- Using CATALINA_TMPDIR: /opt/tomcat/temp
- Using JRE_HOME: /usr
- Using CLASSPATH:/opt/tomcat/bin/bootstrap.jar
- Using CATALINA_PID:/var/run/tomcat/tomcat.pid
- Starting tomcat [ OK ]
-
-#. Configure tomcat to start automatically: ``sudo chkconfig tomcat on``
-
-#. Verify Traffic Monitor is running by pointing your browser to port 80 on the Traffic Monitor host:
-
- * The 'Cache States' tab should display all Mid and Edge caches configured in Traffic Ops.
- * The 'DeliveryService States' tab should display all delivery services configured in Traffic Ops.
-
-#. In Traffic Ops servers table, click 'Edit' for this server, then click 'Online'.
+The following are hard requirements requirements for Traffic Monitor to operate:
+
+* CentOS 6+
+* 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
+
+#. 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``
+#. Verify Traffic Monitor is running by e.g. opening your preferred web browser to port 80 on the Traffic Monitor host.
Configuring Traffic Monitor
===========================
Configuration Overview
----------------------
-Traffic Monitor is configured using its JSON configuration file, ``/opt/traffic_monitor/conf/traffic_monitor_config.js``.
-This file is created by ``traffic_monitor_config.pl`` script, and among other things, it contains the Traffic Ops URL and the user:password
-specified during the invocation of that script.
-When started, Traffic Monitor uses this basic configuration to downloads its configuration from Traffic Ops, and begins polling caches.
-Once a configurable number of polling cycles completes, health protocol state is available via RESTful JSON endpoints.
+.. _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 flush times and initial poll intervals. Once started with the correct configuration, Traffic Monitor downloads its configuration from Traffic Ops and begins polling caches. Once every cache has been polled, :ref:`health-proto` state is available via RESTful JSON endpoints.
-Troubleshooting and log files
+Troubleshooting and Log Files
=============================
-Traffic Monitor log files are in ``/opt/traffic_monitor/var/log/``, and tomcat log files are in ``/opt/tomcat/logs/``.
+Traffic Monitor log files are in ``/opt/traffic_monitor/var/log/``.
diff --git a/docs/source/admin/traffic_monitor_golang.rst b/docs/source/admin/traffic_monitor_golang.rst
deleted file mode 100755
index 649cf782f..000000000
--- a/docs/source/admin/traffic_monitor_golang.rst
+++ /dev/null
@@ -1,65 +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 Monitor Administration
-******************************
-
-.. _rl-tm-golang:
-
-* These instructions are for the Golang Traffic Monitor, for the legacy Java version, see :ref:`here <rl-tm-java>`.
-
-Installing Traffic Monitor
-==========================
-
-The following are requirements to ensure an accurate set up:
-
-* CentOS 6+
-* 8 vCPUs
-* 16GB RAM
-* Successful install of Traffic Ops
-* Administrative access to the Traffic Ops
-* Physical address of the site
-
-1. Enter the Traffic Monitor server into Traffic Ops
-2. Make sure the FQDN of the Traffic Monitor is resolvable in DNS.
-3. Install Traffic Monitor: ``sudo yum -y install traffic_monitor``
-4. Configure Traffic Monitor. See :ref:`here <rl-tm-configure>`
-5. Start the service: ``sudo service traffic_monitor start`` ::
-
- Starting traffic_monitor:
-
-6. Verify Traffic Monitor is running by pointing your browser to port 80 on the Traffic Monitor host.
-
-Configuring Traffic Monitor
-===========================
-
-Configuration Overview
-----------------------
-
-.. _rl-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.
-
-The ``traffic_ops.cfg`` config contains Traffic Ops connection information. Specify the URL, username, and password for the instance of Traffic Ops for which this Traffic Monitor is a member.
-
-The ``traffic_monitor.cfg`` config contains log file locations, as well as detailed application configuration variables, such as processing flush times and initial poll intervals.
-
-Once started with the correct configuration, Traffic Monitor downloads its configuration from Traffic Ops and begins polling caches. Once every cache has been polled, health protocol state is available via RESTful JSON endpoints.
-
-
-Troubleshooting and log files
-=============================
-Traffic Monitor log files are in ``/opt/traffic_monitor/var/log/``.
diff --git a/docs/source/admin/traffic_ops/configuration.rst b/docs/source/admin/traffic_ops/configuration.rst
index c63a5ecaf..bccde6032 100644
--- a/docs/source/admin/traffic_ops/configuration.rst
+++ b/docs/source/admin/traffic_ops/configuration.rst
@@ -1,151 +1,160 @@
-..
-..
+..
+..
.. 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 - Configuring
-%%%%%%%%%%%%%%%%%%%%%%%%%
+*************************
Follow the steps below to configure the newly installed Traffic Ops Instance.
-Installing the SSL Cert
-=======================
-By default, Traffic Ops runs as an SSL web server, and a certificate needs to be installed.
+Installing the SSL Certificate
+==============================
+By default, Traffic Ops runs as an SSL web server (that is, over HTTPS), and a certificate needs to be installed.
Self-signed Certificate (Development)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- Example Procedure::
-
- $ openssl genrsa -des3 -passout pass:x -out localhost.pass.key 2048
- Generating RSA private key, 2048 bit long modulus
- ...
- $ openssl rsa -passin pass:x -in localhost.pass.key -out localhost.key
- writing RSA key
- $ rm localhost.pass.key
-
- $ openssl req -new -key localhost.key -out localhost.csr
- You are about to be asked to enter information that will be incorporated
- into your certificate request.
- What you are about to enter is what is called a Distinguished Name or a DN.
- There are quite a few fields but you can leave some blank
- For some fields there will be a default value,
- If you enter '.', the field will be left blank.
- -----
- Country Name (2 letter code) [XX]:US<enter>
- State or Province Name (full name) []:CO<enter>
- Locality Name (eg, city) [Default City]:Denver<enter>
- Organization Name (eg, company) [Default Company Ltd]: <enter>
- Organizational Unit Name (eg, section) []: <enter>
- Common Name (eg, your name or your server's hostname) []: <enter>
- Email Address []: <enter>
-
- Please enter the following 'extra' attributes
- to be sent with your certificate request
- A challenge password []: pass<enter>
- An optional company name []: <enter>
- $ openssl x509 -req -sha256 -days 365 -in localhost.csr -signkey localhost.key -out localhost.crt
- Signature ok
- subject=/C=US/ST=CO/L=Denver/O=Default Company Ltd
- Getting Private key
- $ sudo cp localhost.crt /etc/pki/tls/certs
- $ sudo cp localhost.key /etc/pki/tls/private
- $ sudo chown trafops:trafops /etc/pki/tls/certs/localhost.crt
- $ sudo chown trafops:trafops /etc/pki/tls/private/localhost.key
+-------------------------------------
+
+Example Procedure
+
+.. code-block:: shell
+
+ $ openssl genrsa -des3 -passout pass:x -out localhost.pass.key 2048
+ Generating RSA private key, 2048 bit long modulus
+ ...
+ $ openssl rsa -passin pass:x -in localhost.pass.key -out localhost.key
+ writing RSA key
+ $ rm localhost.pass.key
+
+ $ openssl req -new -key localhost.key -out localhost.csr
+ You are about to be asked to enter information that will be incorporated
+ into your certificate request.
+ What you are about to enter is what is called a Distinguished Name or a DN.
+ There are quite a few fields but you can leave some blank
+ For some fields there will be a default value,
+ If you enter '.', the field will be left blank.
+ -----
+ Country Name (2 letter code) [XX]:US<enter>
+ State or Province Name (full name) []:CO<enter>
+ Locality Name (eg, city) [Default City]:Denver<enter>
+ Organization Name (eg, company) [Default Company Ltd]: <enter>
+ Organizational Unit Name (eg, section) []: <enter>
+ Common Name (eg, your name or your server's hostname) []: <enter>
+ Email Address []: <enter>
+
+ Please enter the following 'extra' attributes
+ to be sent with your certificate request
+ A challenge password []: pass<enter>
+ An optional company name []: <enter>
+ $ openssl x509 -req -sha256 -days 365 -in localhost.csr -signkey localhost.key -out localhost.crt
+ Signature ok
+ subject=/C=US/ST=CO/L=Denver/O=Default Company Ltd
+ Getting Private key
+ $ sudo cp localhost.crt /etc/pki/tls/certs
+ $ sudo cp localhost.key /etc/pki/tls/private
+ $ sudo chown trafops:trafops /etc/pki/tls/certs/localhost.crt
+ $ sudo chown trafops:trafops /etc/pki/tls/private/localhost.key
Certificate from Certificate Authority (Production)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. Note:: You will need to know the appropriate answers when generating the certificate request file `trafficopss.csr` below.
-
-Example Procedure::
-
- $ openssl genrsa -des3 -passout pass:x -out trafficops.pass.key 2048
- Generating RSA private key, 2048 bit long modulus
- ...
- $ openssl rsa -passin pass:x -in trafficops.pass.key -out trafficops.key
- writing RSA key
- $ rm localhost.pass.key
-
- Generate the Certificate Signing Request (CSR) file needed for Certificate Authority (CA) request.
-
- $ openssl req -new -key trafficops.key -out trafficops.csr
- You are about to be asked to enter information that will be incorporated
- into your certificate request.
- What you are about to enter is what is called a Distinguished Name or a DN.
- There are quite a few fields but you can leave some blank
- For some fields there will be a default value,
- If you enter '.', the field will be left blank.
- -----
- Country Name (2 letter code) [XX]: <enter country code>
- State or Province Name (full name) []: <enter state or province>
- Locality Name (eg, city) [Default City]: <enter locality name>
- Organization Name (eg, company) [Default Company Ltd]: <enter organization name>
- Organizational Unit Name (eg, section) []: <enter organizational unit name>
- Common Name (eg, your name or your server's hostname) []: <enter server's hostname name>
- Email Address []: <enter e-mail address>
-
- Please enter the following 'extra' attributes
- to be sent with your certificate request
- A challenge password []: <enter challenge password>
- An optional company name []: <enter>
- $ 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:
-
- $ sudo cp trafficops.crt /etc/pki/tls/certs
- $ sudo chown trafops:trafops /etc/pki/tls/certs/trafficops.crt
-
- If necessary, install the CA certificates .pem and .crt in /etc/pki/tls/certs.
-
- You will need to update the file /opt/traffic_ops/app/conf/cdn.conf with the following changes:
- ...
- e.g. given trafficops.crt and trafficops.key
- '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'
- ...
+---------------------------------------------------
+
+.. Note:: You will need to know the appropriate answers when generating the certificate request file ``trafficopss.csr`` below.
+
+Example Procedure
+
+.. code-block:: shell
+
+ $ openssl genrsa -des3 -passout pass:x -out trafficops.pass.key 2048
+ Generating RSA private key, 2048 bit long modulus
+ ...
+ $ openssl rsa -passin pass:x -in trafficops.pass.key -out trafficops.key
+ writing RSA key
+ $ rm localhost.pass.key
+
+Generate the Certificate Signing Request (CSR) file needed for Certificate Authority (CA) request
+
+.. code-block:: shell
+
+ $ openssl req -new -key trafficops.key -out trafficops.csr
+ You are about to be asked to enter information that will be incorporated
+ into your certificate request.
+ What you are about to enter is what is called a Distinguished Name or a DN.
+ There are quite a few fields but you can leave some blank
+ For some fields there will be a default value,
+ If you enter '.', the field will be left blank.
+ -----
+ Country Name (2 letter code) [XX]: <enter country code>
+ State or Province Name (full name) []: <enter state or province>
+ Locality Name (eg, city) [Default City]: <enter locality name>
+ Organization Name (eg, company) [Default Company Ltd]: <enter organization name>
+ Organizational Unit Name (eg, section) []: <enter organizational unit name>
+ Common Name (eg, your name or your server's hostname) []: <enter server's hostname name>
+ Email Address []: <enter e-mail address>
+
+ Please enter the following 'extra' attributes
+ to be sent with your certificate request
+ A challenge password []: <enter challenge password>
+ An optional company name []: <enter>
+ $ 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
+
+.. code-block:: shell
+
+ $ 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``.
+
+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
+
+.. code-block:: perl
+
+ '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'
+ ...
Content Delivery Networks
=========================
-.. _rl-param-prof:
+.. _param-prof:
Profile Parameters
-======================
-Many of the settings for the different servers in a Traffic Control CDN are controlled by parameters in the parameter view of Traffic Ops. Parameters are grouped in profiles and profiles are assigned to a server or a deliveryservice. For a typical cache there are hundreds of configuration settings to apply. The Traffic Ops parameter view contains the defined settings. To make life easier, Traffic Ops allows for duplication, comparison, import and export of Profiles. Traffic Ops also has a "Global profile" - the parameters in this profile are going to be applied to all servers in the Traffic Ops instance, or apply to Traffic Ops themselves. These parameters are:
+------------------
+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 profiles. Traffic Ops also has a "Global profile" - the parameters in this profile are going to be applied to all servers in the Traffic Ops instance, or apply to Traffic Ops themselves. These parameters are:
.. index::
Global Profile
+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Config file | Value |
+| 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 Config 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 scaleability of a CDN |
-| | | maintained by Traffic Ops by caching configuration files of profile and cdn scope. |
+| 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.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. |
+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -154,19 +163,20 @@ Many of the settings for the different servers in a Traffic Control CDN are cont
| | | 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 to get the GeoLiteCity database from. |
+| geolocation.polling.url | CRConfig.json | The location of a GeoIP2 database for Traffic Router to use. |
+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
-| geolocation6.polling.url | CRConfig.json | The location to get the IPv6 GeoLiteCity database from. |
+| 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 geo coordinates to use for client location when maxmind 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. |
-| | | Format: <CountryCode>;<Lat>,<Long> Ex: US;37.751,-97.822 |
+| 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`` |
+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
These parameters should be set to reflect the local environment.
-After running the postinstall script, Traffic Ops has the following profiles pre-loaded:
+After running the ``postinstall`` script, Traffic Ops has the following profiles pre-loaded:
+----------+-------------------------------------------------------------------------------------------------+
| Name | Description |
@@ -186,95 +196,103 @@ After running the postinstall script, Traffic Ops has the following profiles pre
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 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:`rl-purge`) |
-+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
-| coalesce_masklen_v4 | ip_allow.config | The masklen to use when coalescing v4 networks into one line using http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm |
-+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
-| coalesce_number_v4 | ip_allow.config | The number to use when coalescing v4 networks into one line using http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm |
-+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
-| coalesce_masklen_v6 | ip_allow.config | The masklen to use when coalescing v6 networks into one line using http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm |
-+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
-| coalesce_masklen_v6 | ip_allow.config | The masklen to use when coalescing v6 networks into one line using http://search.cpan.org/~miker/NetAddr-IP-4.078/IP.pm |
-+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
-| health.threshold.loadavg | rascal.properties | The Unix load average at which Traffic Router will stop sending traffic to this cache |
-+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
-| health.threshold.\\ | rascal.properties | The amount of bandwidth that Traffic Router will try to keep available on the cache. |
-| availableBandwidthInKbps | | For example: "">1500000" means stop sending new traffic to this cache when traffic is at 8.5Gbps on a 10Gbps interface. |
-+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
-
-Below is a list of Traffic Server plugins 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 config to be used for regex_revalidate. | `regex_revalidate <https://docs.trafficserver.apache.org/en/5.3.x/reference/plugins/regex_remap.en.html>`_ |
-| | | For example: --config regex_revalidate.config | |
-+------------------+---------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
-| remap_stats | plugin.config | The config to be used for remap_stats. | `remap_stats <https://github.com/apache/trafficserver/tree/master/plugins/experimental/remap_stats>`_ |
-| | | Value is left blank. | |
-+------------------+---------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
++--------------------------+-------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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 |
+| 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 cachegroup as a parent of their cachegroup. This is primarily useful for when edge caches |
-| | | are configured to have a cachegroup of other edge caches as parents (a highly unusual configuration), and it is |
-| | | necessary to exclude some, but not all, edges in the parent cachegroup from the parent.config (for example, because they|
-| | | lack necessary capabilities), but still have all edges in the same cachegroup in order to take traffic from ordinary |
-| | | delivery services at that cachegroup's geo location. Once again, this is a highly unusual scenario, and under ordinary |
-| | | circumstances this parameter should not exist. |
+| 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 Cache Group as a parent of their CacheGroup. This is primarily useful for when edge caches |
+| | | are configured to have a 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 Cache Group from the ``parent.config`` (for example, |
+| | | because they lack necessary capabilities), but still have all edges in the same Cache Group in order to take traffic |
+| | | from ordinary Delivery Services at that 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. Enter your divisions first in `Misc->Divisions`, then enter the regions in `Misc->Regions`, referencing the divisions entered, and finally, enter the physical locations in `Misc->Locations`, referencing the regions entered.
+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 also have to be part of a `cache group`. A cache group is a logical grouping of caches, that don't have to be in the same physical location (in fact, usually a cache group is spread across minimally 2 physical Locations for redundancy purposes), but share geo coordinates for content routing purposes. JvD to add more.
+.. figure:: images/topography.svg
+ :align: center
+ :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 Cache Group. A Cache Group is a logical grouping of caches, that don't have to be in the same physical location (in fact, usually a cache group is spread across minimally 2 physical Locations 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 this request matches a list of regular expressions, and if it does, we force a revalidation to the origin, making the original content inaccessible. The regex_revalidate plugin will monitor it's config file, and will pick up changes to it without a `traffic_line -x` signal to ATS. Changes to this file need to be distributed to the highest tier (MID) caches in the CDN before they are distributed to the lower tiers, to prevent filling the lower tiers with the content that should be purged from the higher tiers without hitting the origin. This is why the ort script (see :ref:`reference-traffic-ops-ort`) will by default push out config changes to MID first, confirm that they have all been updated, and then push out the changes to the lower tiers. In large CDNs, this can make the distribution and time to activation of the purge too long, and because of that there is the option to not distribute the `regex_revalidate.config` file using the ort script, but to do this using other means. By default, Traffic Ops will use ort to distribute the `regex_revalidate.config` file.
+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 this request matches a list of regular expressions, and if it does, we force a revalidation to the origin, making the original content inaccessible. The regex_revalidate plugin will monitor it's config file, and will pick up changes to it without a `traffic_line -x` signal to ATS. Changes to this file need to be distributed to the highest tier (MID) caches in the CDN before they are distributed to the lower tiers, to prevent filling the lower tiers with the content that should be purged from the higher tiers without hitting the origin. This is why the ort script (see :ref:`traffic-ops-ort`) will by default push out config changes to MID first, confirm that they have all been updated, and then push out the changes to the lower tiers. In large CDNs, this can make the distribution and time to activation of the purge too long, and because of that there is the option to not distribute the `regex_revalidate.config` file using the ort script, but to do this using other means. By default, Traffic Ops will use ort to distribute the `regex_revalidate.config` file.
Content Purge is controlled by the following parameters in the profile of the cache:
-+----------------------+-------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Config file | Description | Details |
-+======================+=========================+==================================================+=========================================================================================================================================================+
-| location | regex_revalidate.config | What location the file should be in on the cache | 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 time a purge can be active | To prevent a build up of many checks before each request, this is longest time the system will allow |
-+----------------------+-------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
-| regex_revalidate | plugin.config | The config to be used for regex_revalidate. | `regex_revalidate <https://docs.trafficserver.apache.org/en/5.3.x/reference/plugins/regex_remap.en.html>`_ |
-| | | For example: --config regex_revalidate.config | |
-+----------------------+-------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
-| use_reval_pending | global | Configures Traffic Ops to use separate | When this flag is in use ORT will check for a new regex_revalidate.config every 60 seconds in syncds mode during the dispersal timer. This will |
-| | | reval_pending flag for each cache. | 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. Use of this feature requires Traffic Ops 2.1 and above. Parameter should be assigned to the GLOBAL profile. |
-+----------------------+-------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
++----------------------+-------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
+| 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. |
++----------------------+-------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+
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 cache before it is considered stale, and set that to the same value as `maxRevalDurationDays` (Note that the former is in seconds and the latter is in days, so convert appropriately).
@@ -284,33 +302,32 @@ Note that the TTL the adminstrator enters in the purge request should be longer
.. _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.
To generate ISO, the CentOS Kickstart is necessary:
-1. Create a kickstart file.
-2. Create a boot media with the kickstart file or make the kickstart file available on the network.
-3. Make the installation tree available.
-4. Start the kickstart installation.
-
-Create a ks.src file in the root of the selection location. See the example below:
+#. 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:
+.. code-block:: shell
- mkdir newdir
- cd newdir/
- cp -r ../centos65/* .
- vim ks.src
- vim isolinux/isolinux.cfg
- cd vim osversions.cfg
- vim osversions.cfg
+ mkdir newdir
+ cd newdir/
+ cp -r ../centos65/* .
+ vim ks.src
+ vim isolinux/isolinux.cfg
+ cd vim osversions.cfg
+ vim osversions.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:: Streamline your install folder for under 1GB, which assists in creating a CD.
.. 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>`_
diff --git a/docs/source/admin/traffic_ops/default_profiles.rst b/docs/source/admin/traffic_ops/default_profiles.rst
deleted file mode 100644
index abf05cdf2..000000000
--- a/docs/source/admin/traffic_ops/default_profiles.rst
+++ /dev/null
@@ -1,54 +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 - Default Profiles
-
-.. _rl-to-default-profiles:
-
-Traffic Ops - Default Profiles
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-Traffic Ops has the concept of :ref:`rl-working-with-profiles`, which are an integral function within Traffic Ops. To get started, a set of default Traffic Ops profiles need to be imported into Traffic Ops
-to get started to support Traffic Control components Traffic Router, Traffic Monitor, and Apache Traffic Server.
-
-`Download Default Profiles from here <http://trafficcontrol.apache.org/downloads/profiles/>`_
-
-.. _rl-to-profiles-min-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
-
-
-
-Steps to Import a Profile
--------------------------
-1. Sign into Traffic Ops
-
-2. Navigate to 'Parameters->Select Profile'
-
-3. Click the "Import Profile" button at the bottom
-
-4. Choose the specific profile you want to import from your download directory
-
-5. Click 'Submit'
-
-6. Continue these steps for each :ref:`rl-to-profiles-min-needed` above
diff --git a/docs/source/admin/traffic_ops/extensions.rst b/docs/source/admin/traffic_ops/extensions.rst
index 4aceebbf5..559ac85c6 100644
--- a/docs/source/admin/traffic_ops/extensions.rst
+++ b/docs/source/admin/traffic_ops/extensions.rst
@@ -1,88 +1,93 @@
-..
-..
+..
+..
.. 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.
-..
+..
.. _admin-to-ext-script:
+*******************************
Managing Traffic Ops Extensions
*******************************
-Each script is a separate bash script located in ``$TO_HOME/bin/checks/``.
+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.
+
+.. _to-check-ext:
-The extensions must be registered with Traffic Ops in order to display a column on the Server Check page. The list of currently registered extensions can be listed by running ``/opt/traffic_ops/app/bin/extensions -a``.
+Check Extensions
+================
+Each extension is a separate bash script located in ``$TO_HOME/bin/checks/`` on the Traffic Ops server (though practically, they can be any executable). The extensions must be registered with Traffic Ops in order to display a column on the Cache Checks page. The currently registered extensions can be listed by running ``/opt/traffic_ops/app/bin/extensions -a``. Some extensions automatically registered with the Traffic Ops database (``to_extension`` table) at install time (see ``traffic_ops/app/db/seeds.sql``). However, cron must still be configured to run these checks periodically. The extensions are called like so:
-The below extensions are automatically registered with the Traffic Ops database (``to_extension`` table) at install time (see ``traffic_ops/app/db/seeds.sql``). However, cron must still be configured to run these checks periodically.
+.. code-block:: shell
-The scripts are called as follows: ::
+ $TO_HOME/bin/checks/<name> -c "{\"base_url\": \",https://\"<traffic_ops_ip>\", \"check_name\": \"<check_name>\"}" -l <log level>
-
- $TO_HOME/bin/checks/To<name>Check.pl -c "{\"base_url\": \",https://\"<traffic_ops_ip>\", \"check_name\": \"<check_name>\"}" -l <log level>
- where:
+:name: The basename of the extension executable
+:traffic_ops_ip: The IP address or Fully Qualified Domain Name (FQDN) 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. This field is optional
- <name> is the type of check script
- <traffic_ops_ip> is the IP address of the Traffic Ops Server
- <check_name> is the name of the check. For example: CDU, CHR, DSCP, MTU, etc...
- <log_level> is between 1 and 4, with 4 being the most verbose. This field is optional
+.. _to-datasource-ext:
+Data Source Extensions
+======================
+Data Source Extensions work in much the same way as `Check Extensions`_, but are implemented differently. Rather than being a totally external executable, a Data Source Extension *must* be written in Perl 5, as they are injected via manipulation of the ``$PERL5LIB`` environment variable. These extensions are not very well-documented (as you may be able to tell), and support for extending them may be phased out in future releases.
Example Cron File
=================
-Edit with ``crontab -e``. You may need to adjust the path to your $TO_HOME to match your system.
-
-::
-
-
- PERL5LIB=/opt/traffic_ops/app/local/lib/perl5:/opt/traffic_ops/app/lib
-
- # IPv4 ping examples - The 'select: ["hostName","domainName"]' works but, if you want to check DNS resolution use FQDN.
- */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G\", \"select\": [\"hostName\",\"domainName\"]}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
- */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G\", \"select\": \"ipAddress\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
- */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G\", \"name\": \"IPv4 Ping\", \"select\": \"ipAddress\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
-
- # IPv6 ping examples
- */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G6\", \"name\": \"IPv6 Ping\", \"select\": \"ip6Address\", \"syslog_facility\": \"local0\"}" >/dev/null 2>&1
- */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G6\", \"select\": \"ip6Address\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
-
- # iLO ping
- 18 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"ILO\", \"select\": \"iloIpAddress\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
- 18 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"ILO\", \"name\": \"ILO ping\", \"select\": \"iloIpAddress\", \"syslog_facility\": \"local0\"}" >/dev/null 2>&1
-
- # MTU ping
- 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"select\": \"ipAddress\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
- 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"select\": \"ip6Address\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
- 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"name\": \"Max Trans Unit\", \"select\": \"ipAddress\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
- 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"name\": \"Max Trans Unit\", \"select\": \"ip6Address\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
-
- # FQDN
- 27 * * * * root /opt/traffic_ops/app/bin/checks/ToFQDNCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"FQDN\"" >> /var/log/traffic_ops/extensionCheck.log 2>&1
- 27 * * * * root /opt/traffic_ops/app/bin/checks/ToFQDNCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"FQDN\", \"name\": \"DNS Lookup\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
-
- # 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
-
- # 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
- 10 * * * * root /opt/traffic_ops/app/bin/checks/ToRTRCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"RTR\", \"name\": \"Content Router Check\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
-
- # CHR
- */15 * * * * root /opt/traffic_ops/app/bin/checks/ToCHRCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"CHR\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
-
- # CDU
- 20 * * * * root /opt/traffic_ops/app/bin/checks/ToCDUCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"CDU\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
-
- # 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
-
+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.
+
+.. code-block:: shell
+
+ PERL5LIB=/opt/traffic_ops/app/local/lib/perl5:/opt/traffic_ops/app/lib
+
+ # IPv4 ping examples - The 'select: ["hostName","domainName"]' works but, if you want to check DNS resolution use FQDN.
+ */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G\", \"select\": [\"hostName\",\"domainName\"]}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+ */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G\", \"select\": \"ipAddress\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+ */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G\", \"name\": \"IPv4 Ping\", \"select\": \"ipAddress\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
+
+ # IPv6 ping examples
+ */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G6\", \"name\": \"IPv6 Ping\", \"select\": \"ip6Address\", \"syslog_facility\": \"local0\"}" >/dev/null 2>&1
+ */15 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"10G6\", \"select\": \"ip6Address\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+
+ # iLO ping
+ 18 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"ILO\", \"select\": \"iloIpAddress\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+ 18 * * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"ILO\", \"name\": \"ILO ping\", \"select\": \"iloIpAddress\", \"syslog_facility\": \"local0\"}" >/dev/null 2>&1
+
+ # MTU ping
+ 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"select\": \"ipAddress\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+ 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"select\": \"ip6Address\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+ 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"name\": \"Max Trans Unit\", \"select\": \"ipAddress\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
+ 45 0 * * * root /opt/traffic_ops/app/bin/checks/ToPingCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"MTU\", \"name\": \"Max Trans Unit\", \"select\": \"ip6Address\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
+
+ # FQDN
+ 27 * * * * root /opt/traffic_ops/app/bin/checks/ToFQDNCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"FQDN\"" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+ 27 * * * * root /opt/traffic_ops/app/bin/checks/ToFQDNCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"FQDN\", \"name\": \"DNS Lookup\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
+
+ # 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
+
+ # 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
+ 10 * * * * root /opt/traffic_ops/app/bin/checks/ToRTRCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"RTR\", \"name\": \"Content Router Check\", \"syslog_facility\": \"local0\"}" > /dev/null 2>&1
+
+ # CHR
+ */15 * * * * root /opt/traffic_ops/app/bin/checks/ToCHRCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"CHR\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+
+ # CDU
+ 20 * * * * root /opt/traffic_ops/app/bin/checks/ToCDUCheck.pl -c "{\"base_url\": \"https://localhost\", \"check_name\": \"CDU\"}" >> /var/log/traffic_ops/extensionCheck.log 2>&1
+
+ # 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/12m.png b/docs/source/admin/traffic_ops/images/12m.png
similarity index 100%
rename from docs/source/admin/12m.png
rename to docs/source/admin/traffic_ops/images/12m.png
diff --git a/docs/source/admin/traffic_ops/images/topography.svg b/docs/source/admin/traffic_ops/images/topography.svg
new file mode 100644
index 000000000..3d53d288f
--- /dev/null
+++ b/docs/source/admin/traffic_ops/images/topography.svg
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you 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. -->
+<svg xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" height="174.47356mm" width="174.47356mm" version="1.1" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" viewBox="0 0 618.21339 618.21339">
+ <g transform="translate(-105.05585,-181.61069)">
+ <path fill="#a7fffc" d="m723.25132 494.0449a309.10669 309.10669 0 0 1 -312.10398 305.76446 309.10669 309.10669 0 0 1 -306.07968 -311.79485 309.10669 309.10669 0 0 1 311.48541 -306.39458 309.10669 309.10669 0 0 1 306.70917 311.17564"/>
+ <text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="40px" y="276.99146" x="334.69965" font-family="sans-serif" line-height="125%" fill="#000000"><tspan x="334.69965" y="276.99146">Division</tspan></text>
+ <g transform="translate(81.26128 -.28444541)">
+ <path d="m273.74536 407.9839a103.03556 103.03556 0 0 1 -104.03465 101.92148 103.03556 103.03556 0 0 1 -102.026557 -103.93161 103.03556 103.03556 0 0 1 103.828467 -102.13152 103.03556 103.03556 0 0 1 102.23639 103.72521" fill="#ff7679"/>
+ <text style="word-spacing:0px;letter-spacing:0px" line-height="125%" font-size="25px" y="343.49908" x="127.76534" font-family="sans-serif" xml:space="preserve" fill="#000000"><tspan y="343.49908" x="127.76534">Region</tspan></text>
+ <path d="m215.38211 463.39205a44.95179 44.95179 0 0 1 -45.38767 44.46574 44.95179 44.95179 0 0 1 -44.51159 -45.34271 44.95179 44.95179 0 0 1 45.29772 -44.55738 44.95179 44.95179 0 0 1 44.60313 45.25266" fill="#caff8a"/>
+ <text style="word-spacing:0px;letter-spacing:0px" line-height="125%" font-size="17.5px" y="468.03418" x="133.30951" font-family="sans-serif" xml:space="preserve" fill="#000000"><tspan y="468.03418" x="133.30951">Location</tspan></text>
+ <path fill="#caff8a" d="m163.76043 389.12456a44.95179 44.95179 0 0 1 -45.38767 44.46575 44.95179 44.95179 0 0 1 -44.511583 -45.34272 44.95179 44.95179 0 0 1 45.297713 -44.55738 44.95179 44.95179 0 0 1 44.60313 45.25267"/>
+ <text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="17.5px" y="393.76669" x="81.687836" font-family="sans-serif" line-height="125%" fill="#000000"><tspan x="81.687836" y="393.76669">Location</tspan></text>
+ <path d="m264.5206 388.13173a44.95179 44.95179 0 0 1 -45.38767 44.46575 44.95179 44.95179 0 0 1 -44.51159 -45.34272 44.95179 44.95179 0 0 1 45.29771 -44.55738 44.95179 44.95179 0 0 1 44.60314 45.25267" fill="#caff8a"/>
+ <text style="word-spacing:0px;letter-spacing:0px" line-height="125%" font-size="17.5px" y="392.77386" x="182.448" font-family="sans-serif" xml:space="preserve" fill="#000000"><tspan y="392.77386" x="182.448">Location</tspan></text>
+ </g>
+ <g transform="translate(397.38317 -.51219714)">
+ <path fill="#ff7679" d="m273.74536 407.9839a103.03556 103.03556 0 0 1 -104.03465 101.92148 103.03556 103.03556 0 0 1 -102.026557 -103.93161 103.03556 103.03556 0 0 1 103.828467 -102.13152 103.03556 103.03556 0 0 1 102.23639 103.72521"/>
+ <text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="25px" y="343.49908" x="127.76534" font-family="sans-serif" line-height="125%" fill="#000000"><tspan x="127.76534" y="343.49908">Region</tspan></text>
+ <path fill="#caff8a" d="m215.38211 463.39205a44.95179 44.95179 0 0 1 -45.38767 44.46574 44.95179 44.95179 0 0 1 -44.51159 -45.34271 44.95179 44.95179 0 0 1 45.29772 -44.55738 44.95179 44.95179 0 0 1 44.60313 45.25266"/>
+ <text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="17.5px" y="468.03418" x="133.30951" font-family="sans-serif" line-height="125%" fill="#000000"><tspan x="133.30951" y="468.03418">Location</tspan></text>
+ <path d="m163.76043 389.12456a44.95179 44.95179 0 0 1 -45.38767 44.46575 44.95179 44.95179 0 0 1 -44.511583 -45.34272 44.95179 44.95179 0 0 1 45.297713 -44.55738 44.95179 44.95179 0 0 1 44.60313 45.25267" fill="#caff8a"/>
+ <text style="word-spacing:0px;letter-spacing:0px" line-height="125%" font-size="17.5px" y="393.76669" x="81.687836" font-family="sans-serif" xml:space="preserve" fill="#000000"><tspan y="393.76669" x="81.687836">Location</tspan></text>
+ <path fill="#caff8a" d="m264.5206 388.13173a44.95179 44.95179 0 0 1 -45.38767 44.46575 44.95179 44.95179 0 0 1 -44.51159 -45.34272 44.95179 44.95179 0 0 1 45.29771 -44.55738 44.95179 44.95179 0 0 1 44.60314 45.25267"/>
+ <text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="17.5px" y="392.77386" x="182.448" font-family="sans-serif" line-height="125%" fill="#000000"><tspan x="182.448" y="392.77386">Location</tspan></text>
+ </g>
+ <g transform="translate(242.65532,247.40291)">
+ <path d="m273.74536 407.9839a103.03556 103.03556 0 0 1 -104.03465 101.92148 103.03556 103.03556 0 0 1 -102.026557 -103.93161 103.03556 103.03556 0 0 1 103.828467 -102.13152 103.03556 103.03556 0 0 1 102.23639 103.72521" fill="#ff7679"/>
+ <text style="word-spacing:0px;letter-spacing:0px" line-height="125%" font-size="25px" y="343.49908" x="127.76534" font-family="sans-serif" xml:space="preserve" fill="#000000"><tspan y="343.49908" x="127.76534">Region</tspan></text>
+ <path d="m215.38211 463.39205a44.95179 44.95179 0 0 1 -45.38767 44.46574 44.95179 44.95179 0 0 1 -44.51159 -45.34271 44.95179 44.95179 0 0 1 45.29772 -44.55738 44.95179 44.95179 0 0 1 44.60313 45.25266" fill="#caff8a"/>
+ <text style="word-spacing:0px;letter-spacing:0px" line-height="125%" font-size="17.5px" y="468.03418" x="133.30951" font-family="sans-serif" xml:space="preserve" fill="#000000"><tspan y="468.03418" x="133.30951">Location</tspan></text>
+ <path fill="#caff8a" d="m163.76043 389.12456a44.95179 44.95179 0 0 1 -45.38767 44.46575 44.95179 44.95179 0 0 1 -44.511583 -45.34272 44.95179 44.95179 0 0 1 45.297713 -44.55738 44.95179 44.95179 0 0 1 44.60313 45.25267"/>
+ <text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="17.5px" y="393.76669" x="81.687836" font-family="sans-serif" line-height="125%" fill="#000000"><tspan x="81.687836" y="393.76669">Location</tspan></text>
+ <path d="m264.5206 388.13173a44.95179 44.95179 0 0 1 -45.38767 44.46575 44.95179 44.95179 0 0 1 -44.51159 -45.34272 44.95179 44.95179 0 0 1 45.29771 -44.55738 44.95179 44.95179 0 0 1 44.60314 45.25267" fill="#caff8a"/>
+ <text style="word-spacing:0px;letter-spacing:0px" line-height="125%" font-size="17.5px" y="392.77386" x="182.448" font-family="sans-serif" xml:space="preserve" fill="#000000"><tspan y="392.77386" x="182.448">Location</tspan></text>
+ </g>
+ </g>
+</svg>
diff --git a/docs/source/admin/traffic_ops/installation.rst b/docs/source/admin/traffic_ops/installation.rst
index d2eaec1ef..a288ac2f2 100644
--- a/docs/source/admin/traffic_ops/installation.rst
+++ b/docs/source/admin/traffic_ops/installation.rst
@@ -14,230 +14,232 @@
..
.. index::
- Traffic Ops - Installing
+ Traffic Ops - Installing
-.. _rl-to-install:
+.. _to-install:
+************************
Traffic Ops - Installing
-%%%%%%%%%%%%%%%%%%%%%%%%
+************************
System Requirements
-------------------
The user must have the following for a successful minimal install:
-* CentOS 7
-* 2 VMs with at least 2 vCPUs, 4GB RAM, 20 GB disk space each
-* Access to Centos Base and epel repositories
-* Access to `The Comprehensive Perl Archive Network (CPAN) <http://www.cpan.org/>`_
+- CentOS 7+
+- 2 machines or Virtual Machines (VMs), each with at least 2 (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 Postgres is supported as the database. This documentation assumes CentOS 7.2 and Postgresql 9.6.3 for a production install.
+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
-Navigating the Install
------------------------
-To begin the install:
+Installation
+------------
-1. Install Postgres
+#. Install PostgreSQL Database
- For a production install it is best to install postgres on it's own server/VM. To install postgres, on the postgres host (pg) ::
+ .. note:: For more information on installing PostgreSQL, see `their documentation <https://www.postgresql.org/docs/>`_.
- pg-$ sudo su -
- pg-# yum -y update
- pg-# yum -y install https://download.postgresql.org/pub/repos/yum/9.6/redhat/rhel-7-x86_64/pgdg-centos96-9.6-3.noarch.rpm
- pg-# yum -y install postgresql96-server
- pg-$ su - postgres
- pg-$ /usr/pgsql-9.6/bin/initdb -A md5 -W #-W forces the user to provide a superuser (postgres) password
+ 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``):
+ .. code-block:: shell
- Edit ``/var/lib/pgsql/9.6/data/pg_hba.conf`` to allow your traffic ops app server access. For example if you are going to install traffic ops on ``99.33.99.1`` add::
+ 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
+ yum install -y postgresql96-server
+ su - postgres -c /usr/pgsql-9.6/bin/initdb -A md5 -W #-W forces the user to provide a superuser (postgres) password
- host all all 99.33.99.1/32 md5
- to the appropriate section of this file. Edit the ``/var/lib/pgsql/9.6/data/postgresql.conf`` file to add the approriate listen_addresses or ``listen_addresses = '*'``, set ``timezone = 'UTC'``, and start the database: ::
+ 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::
- pg-$ exit
- pg-# systemctl enable postgresql-9.6
- pg-# systemctl start postgresql-9.6
- pg-# systemctl status postgresql-9.6
+ host all all 99.33.99.1/32 md5
+ 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:
-2. Build Traffic Ops
+ .. code-block:: shell
- Build a Traffic Ops rpm using the instructions under the :ref:`dev-building` page.
+ systemctl enable postgresql-9.6
+ systemctl start postgresql-9.6
+ systemctl status postgresql-9.6
-3. Install Postgresql
+#. Build a Traffic Ops ``.rpm`` file using the instructions under the :ref:`dev-building` page.
- Install the postgresql 9.6 yum repository access. ::
+#. Install PostgreSQL. To install the PostgreSQL 9.6 yum repository, run this command as the root user (or with ``sudo``):
- to-$ sudo su -
- to-# yum -y install https://download.postgresql.org/pub/repos/yum/9.6/redhat/rhel-7-x86_64/pgdg-centos96-9.6-3.noarch.rpm
+ .. code-block:: shell
-4. Install the rpm built in step 2. ::
+ yum install -y https://download.postgresql.org/pub/repos/yum/9.6/redhat/rhel-7-x86_64/pgdg-centos96-9.6-3.noarch.rpm
- to-# yum -y install ./dist/traffic_ops-2.0.0-xxxx.yyyyyyy.el7.x86_64.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``):
+ .. code-block:: shell
- Install some additional packages that it depends on that were not installed as dependecies in the previous step (these are for the 2.0.0 install, this may change, but the pre-installs won't hurt): ::
+ yum install -y ./dist/traffic_ops-2.0.0-xxxx.yyyyyyy.el7.x86_64.rpm
- to-# yum -y install git
- to-# wget -q https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz
- to-# tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz
- to-# PATH=$PATH:/usr/local/go/bin # go bins are needed in the path for postinstall
- to-# go get bitbucket.org/liamstask/goose/cmd/goose
+ .. note:: This will install the PostgreSQL client, ``psql`` as a dependency.
- At this point you should be able to login to the database from the ``to`` host to the ``pg`` host like: ::
+#. 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``):
- to-# psql -h 99.33.99.1 -U postgres
- Password for user postgres:
- psql (9.6.3)
- Type "help" for help.
+ .. code-block:: shell
- postgres=#
+ 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
- Use this connectivity to create the user and database. In this example, we use user: ``traffic_ops``, password: ``tcr0cks``, database: ``traffic_ops``: ::
+ .. note:: These are for the Traffic Control version 2.0.0 install, this may change, but the explicit installs won't hurt.
- to-# psql -U postgres -h 99.33.99.1 -c "CREATE USER traffic_ops WITH ENCRYPTED PASSWORD 'tcr0cks';"
- Password for user postgres:
- CREATE ROLE
- to-# createdb traffic_ops --owner traffic_ops -U postgres -h 99.33.99.1
- Password:
- to-#
-
-
- Now, run the following command as root: ``/opt/traffic_ops/install/bin/postinstall``
-
- The postinstall 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 installed into /opt/traffic_ops/app/local
-
- Some additional files will be installed, and then it will proceed with the next phase of the install, where it will ask you about the local environment for your CDN. Please make sure you remember all your answers and the database answers match the database information previously used to create the database.
-
-
- Example output::
-
- ===========/opt/traffic_ops/app/conf/production/database.conf===========
- Database type [Pg]:
- Database type: Pg
- Database name [traffic_ops]:
- Database name: traffic_ops
- Database server hostname IP or FQDN [localhost]: 99.33.99.1
- Database server hostname IP or FQDN: 99.33.99.1
- Database port number [5432]:
- Database port number: 5432
- Traffic Ops database user [traffic_ops]:
- Traffic Ops database user: traffic_ops
- Password for Traffic Ops database user:
- Re-Enter Password for Traffic Ops database user:
- Writing json to /opt/traffic_ops/app/conf/production/database.conf
- Database configuration has been saved
- ===========/opt/traffic_ops/app/db/dbconf.yml===========
- Database server root (admin) user [postgres]:
- Database server root (admin) user: postgres
- Password for database server admin:
- Re-Enter Password for database server admin:
- Download Maxmind Database? [yes]:
- Download Maxmind Database?: yes
- ===========/opt/traffic_ops/app/conf/cdn.conf===========
- Generate a new secret? [yes]:
- Generate a new secret?: yes
- Number of secrets to keep? [10]:
- Number of secrets to keep?: 10
- Not setting up ldap
- ===========/opt/traffic_ops/install/data/json/users.json===========
- Administration username for Traffic Ops [admin]:
- Administration username for Traffic Ops: admin
- Password for the admin user:
- Re-Enter Password for the admin user:
- Writing json to /opt/traffic_ops/install/data/json/users.json
- ===========/opt/traffic_ops/install/data/json/openssl_configuration.json===========
- Do you want to generate a certificate? [yes]:
- Country Name (2 letter code): US
- State or Province Name (full name): CO
- Locality Name (eg, city): Denver
- Organization Name (eg, company): Super CDN, Inc
- Organizational Unit Name (eg, section):
- Common Name (eg, your name or your server's hostname):
- RSA Passphrase:
- Re-Enter RSA Passphrase:
- ===========/opt/traffic_ops/install/data/json/profiles.json===========
- Traffic Ops url [https://localhost]:
- Traffic Ops url: https://localhost
- Human-readable CDN Name. (No whitespace, please) [kabletown_cdn]: blue_cdn
- Human-readable CDN Name. (No whitespace, please): blue_cdn
- DNS sub-domain for which your CDN is authoritative [cdn1.kabletown.net]: blue-cdn.supercdn.net
- DNS sub-domain for which your CDN is authoritative: blue-cdn.supercdn.net
- Writing json to /opt/traffic_ops/install/data/json/profiles.json
- Downloading Maxmind data
- --2017-06-11 15:32:41-- http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz
- Resolving geolite.maxmind.com (geolite.maxmind.com)... 2400:cb00:2048:1::6810:262f, 2400:cb00:2048:1::6810:252f, 104.16.38.47, ...
- Connecting to geolite.maxmind.com (geolite.maxmind.com)|2400:cb00:2048:1::6810:262f|:80... connected.
-
- ... much SQL output skipped
-
- Starting Traffic Ops
- Restarting traffic_ops (via systemctl): [ OK ]
- Waiting for Traffic Ops to restart
- Success! Postinstall complete.
-
- to-# ifconfig
-
-
- Explanation of the information that needs to be provided:
-
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Field | Description |
- +====================================================+==============================================================================================+
- | Database type | Pg |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Database name | The name of the database Traffic Ops uses to store the configuration information |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Database server hostname IP or FQDN | The hostname of the database server |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Database port number | The database port number |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Traffic Ops database user | The username Traffic Ops will use to read/write from the database |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Password for traffic ops | The password for the above database user |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Database server root (admin) user name | Privileged database user that has permission to create the database and user for Traffic Ops |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Database server root (admin) user password | The password for the above privileged database user |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Traffic Ops url | The URL to connect to this instance of Traffic Ops, usually https://<traffic ops host FQDN>/ |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Human-readable CDN Name | The name of the first CDN traffic Ops will be managing |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | DNS sub-domain for which your CDN is authoritative | The DNS domain that will be delegated to this Traffic Control CDN |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Administration username for Traffic Ops | The Administration (highest privilege) Traffic Ops user to create; |
- | | use this user to login for the first time and create other users |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
- | Password for the admin user | The password for the above user |
- +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+#. 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:
+
+ .. code-block:: psql
+
+ to-# psql -h 99.33.99.1 -U postgres
+ Password for user postgres:
+ psql (9.6.3)
+ Type "help" for help.
+
+ postgres=#
+
+
+#. Create the User and Database. In this example, we use user: ``traffic_ops``, password: ``tcr0cks``, database: ``traffic_ops``:
+
+ .. code-block:: psql
+
+ to-# psql -U postgres -h 99.33.99.1 -c "CREATE USER traffic_ops WITH ENCRYPTED PASSWORD 'tcr0cks';"
+ Password for user postgres:
+ CREATE ROLE
+ to-# createdb traffic_ops --owner traffic_ops -U postgres -h 99.33.99.1
+ 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 installed into /opt/traffic_ops/app/local``. Some additional files will be installed, and then it will proceed with the next phase of the install, where it will ask you about the local environment for your CDN. Please make sure you remember all your answers and verify that the database answers match the information previously used to create the database. Example output:
+
+ .. code-block:: none
+
+ ===========/opt/traffic_ops/app/conf/production/database.conf===========
+ Database type [Pg]:
+ Database type: Pg
+ Database name [traffic_ops]:
+ Database name: traffic_ops
+ Database server hostname IP or FQDN [localhost]: 99.33.99.1
+ Database server hostname IP or FQDN: 99.33.99.1
+ Database port number [5432]:
+ Database port number: 5432
+ Traffic Ops database user [traffic_ops]:
+ Traffic Ops database user: traffic_ops
+ Password for Traffic Ops database user:
+ Re-Enter Password for Traffic Ops database user:
+ Writing json to /opt/traffic_ops/app/conf/production/database.conf
+ Database configuration has been saved
+ ===========/opt/traffic_ops/app/db/dbconf.yml===========
+ Database server root (admin) user [postgres]:
+ Database server root (admin) user: postgres
+ Password for database server admin:
+ Re-Enter Password for database server admin:
+ Download Maxmind Database? [yes]:
+ Download Maxmind Database?: yes
+ ===========/opt/traffic_ops/app/conf/cdn.conf===========
+ Generate a new secret? [yes]:
+ Generate a new secret?: yes
+ Number of secrets to keep? [10]:
+ Number of secrets to keep?: 10
+ Not setting up ldap
+ ===========/opt/traffic_ops/install/data/json/users.json===========
+ Administration username for Traffic Ops [admin]:
+ Administration username for Traffic Ops: admin
+ Password for the admin user:
+ Re-Enter Password for the admin user:
+ Writing json to /opt/traffic_ops/install/data/json/users.json
+ ===========/opt/traffic_ops/install/data/json/openssl_configuration.json===========
+ Do you want to generate a certificate? [yes]:
+ Country Name (2 letter code): US
+ State or Province Name (full name): CO
+ Locality Name (eg, city): Denver
+ Organization Name (eg, company): Super CDN, Inc
+ Organizational Unit Name (eg, section):
+ Common Name (eg, your name or your server's hostname):
+ RSA Passphrase:
+ Re-Enter RSA Passphrase:
+ ===========/opt/traffic_ops/install/data/json/profiles.json===========
+ Traffic Ops url [https://localhost]:
+ Traffic Ops url: https://localhost
+ Human-readable CDN Name. (No whitespace, please) [kabletown_cdn]: blue_cdn
+ Human-readable CDN Name. (No whitespace, please): blue_cdn
+ DNS sub-domain for which your CDN is authoritative [cdn1.kabletown.net]: blue-cdn.supercdn.net
+ DNS sub-domain for which your CDN is authoritative: blue-cdn.supercdn.net
+ Writing json to /opt/traffic_ops/install/data/json/profiles.json
+ Downloading Maxmind data
+ --2017-06-11 15:32:41-- http://geolite.maxmind.com/download/geoip/database/GeoLite2-City.mmdb.gz
+ Resolving geolite.maxmind.com (geolite.maxmind.com)... 2400:cb00:2048:1::6810:262f, 2400:cb00:2048:1::6810:252f, 104.16.38.47, ...
+ Connecting to geolite.maxmind.com (geolite.maxmind.com)|2400:cb00:2048:1::6810:262f|:80... connected.
+
+ ... much SQL output skipped
+
+ Starting Traffic Ops
+ Restarting traffic_ops (via systemctl): [ OK ]
+ Waiting for Traffic Ops to restart
+ Success! Postinstall complete.
+
+
+
+ .. table:: Explanation of the information that needs to be provided:
+
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Field | Description |
+ +====================================================+==============================================================================================+
+ | Database type | This requests the type of database to be used. Answer with the default - 'Pg' to indicate a |
+ | | PostgreSQL database. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Database name | The name of the database Traffic Ops uses to store the configuration information. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Database server hostname IP or FQDN | The hostname of the database server (``pg`` in the example). |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Database port number | The database port number. The default value, 5432, should be correct unless you changed it |
+ | | during the setup. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Traffic Ops database user | The username Traffic Ops will use to read/write from the database. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Password for Traffic Ops | The password for the database user that Traffic Ops uses. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Database server root (admin) user name | Privileged database user that has permission to create the database and user for Traffic Ops.|
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | 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>/ |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Human-readable CDN Name | The name of the first CDN which Traffic Ops will be manage. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | DNS sub-domain for which your CDN is authoritative | The DNS domain that will be delegated to this Traffic Control CDN. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Administration username for Traffic Ops | The Administration (highest privilege) Traffic Ops user to create. Use this user to login |
+ | | for the first time and create other users. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
+ | Password for the admin user | The password for the administrative Traffic Ops user. |
+ +----------------------------------------------------+----------------------------------------------------------------------------------------------+
Traffic Ops is now installed!
-**To complete the Traffic Ops Setup See:** :ref:`rl-to-default-profiles`
+**To complete the Traffic Ops Setup See:** :ref:`default-profiles`
Upgrading Traffic Ops
=====================
-To upgrade:
-
-#. Enter the following command:``service traffic_ops stop``
-#. Enter the following command:``yum upgrade traffic_ops``
-#. Enter the following command from the /opt/traffic_ops/app directory:
- ``PERL5LIB=/opt/traffic_ops/app/lib:/opt/traffic_ops/app/local/lib/perl5 ./db/admin.pl --env production upgrade``
-#. See :ref:`rl-to-install` to run postinstall.
-#. Enter the following command:``service traffic_ops start``
-
+To upgrade from older Traffic Ops versions, run the following commands as the root user (or with ``sudo``):
+ .. code-block:: shell
+ systemctl stop traffic_ops
+ yum upgrade traffic_ops
+ pushd /opt/traffic_ops/app/
+ PERL5LIB=/opt/traffic_ops/app/lib:/opt/traffic_ops/app/local/lib/perl5 ./db/admin.pl --env production upgrade
+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``
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
index 4133fee2d..7f91fe6b3 100644
--- a/docs/source/admin/traffic_ops/migration_from_10_to_20.rst
+++ b/docs/source/admin/traffic_ops/migration_from_10_to_20.rst
@@ -1,88 +1,74 @@
-..
-..
+..
+..
.. 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
-
-.. _rl-ps:
+ Traffic Ops - Migrating from Traffic Ops 1.x to Traffic Ops 2.x
-Traffic Ops - Migrating from 1.x to 2.x
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+.. _ps:
-In Traffic Ops 2.x MySQL was removed and Postgres was replaced as the database of choice for the unforeseen future. A Docker-based migration tool was developed to
-help with that conversion using an open source Postgres tool called `pgloader <http://pgloader.io/>`_. The following instructions will help configuring the Migration tool
+***************************************
+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 (this migration was tested against version **docker-engine-selinux-17.05.0.ce-1.el7.centos.noarch.rpm**)
-* Postgres has been installed according to :ref:`rl-to-install`
-
-Setup the traffic_ops_db directory
-----------------------------------
+* Docker installed [1]_
+* PostgreSQL installed according to :ref:`to-install`
- Modify /opt dir permission to make it writable and owned by postgres:postgres
+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
- $ sudo chmod 755 /opt
-
- Download the Traffic Control tarball for 2.0.0
+ .. code-block:: shell
- ::
+ cd /opt
+ wget https://dist.apache.org/repos/dist/release/incubator/trafficcontrol/<tarball_version>
- $ 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``
- Extract the **traffic_ops_db** dir to **/opt/traffic_ops_db**
+ .. code-block:: shell
- ::
-
- $ tar -zxvf trafficcontrol-incubating-<version>.tar.gz --strip=1 trafficcontrol-incubating-<version>/traffic_ops_db
- $ sudo chown -R postgres:postgres /opt/traffic_ops_db
-
-.. highlight:: none
+ 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 Postgres server's IP address/port.
+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 permissions stay intact.
- ::
-
- $ su - postgres
- $ cd /opt/traffic_ops_db/
-
-1. Configure the **/opt/traffic_ops_db/pg-migration/mysql-to-postgres.env** migration for your source MySQL and target Postgres settings
-
-
-2. Run the migration, watch the console output for any errors (it may take some time)
- ::
-
- $ ./migrate.sh
-
+Begin the database migration after settings up the ``/opt/traffic_ops_db`` directory
+Switch to the postgres user, so that permissions remain intact.
- Your MySQL data should now be ported into your new instance of Postgres!
+.. 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
index db642a840..eaeb3575c 100644
--- a/docs/source/admin/traffic_ops/migration_from_20_to_22.rst
+++ b/docs/source/admin/traffic_ops/migration_from_20_to_22.rst
@@ -1,137 +1,148 @@
-..
-..
+..
+..
.. 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 hardcoded to use the name "edge", i.e. "edge.myds.mycdn.com", and HTTP Delivery Services use the name "tr" (or previously "ccr"), i.e. "tr.myds.mycdn.com". As of 2.2, Routing Names will default to "cdn" if left unspecified and can be set to any arbitrary non-dotted hostname.
+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.
-Pre-2.2 the HTTP Routing Name is configurable via the http.routing.name option in in the Traffic Router http.properties config 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:
+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:
-1. In Traffic Ops, create the following profile parameter (double-check for typos, trailing spaces, etc):
+#. 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
+ :name: upgrade_http_routing_name
+ :config_file: temp
+ :value: Whatever value is used for the affected CDN's ``http.routing.name``
-2. Add this parameter to a single profile in the affected CDN
+#. 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-DeliveryService Routing Names).
+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 7.x. With 7.x comes support for the new cachekey plugin which replaces the cacheurl plugin which is now deprecated.
-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.
+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.
+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 regex for your delivery service you will have to remove that existing value. Then you will need to make a new DS profile and assign parameters in
-it to the cachekey.config file.
+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
-.. highlight:: none
+static-prefix
+ This is used for a simple domain replacement.
-::
+separator
+ Used by Cachekey and in general is always a single space.
- 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 parameters from the URL
- capture-prefix-uri - This is usually used in combination with remove-path and remove-all-params.
- Capture-prefix-uri will let you use your own full regex value for non simple cases
+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: ::
-**Original regex value:**
+ http://test.net/(.*) http://test-cdn.net/$1
-``http://test.net/(.*) http://test-cdn.net/$1``
+.. table:: Cachekey Parameters
-**Cachekey parameters:**
+ +---------------+-----------------+---------------------------------+
+ |Parameter |File |Value |
+ +===============+=================+=================================+
+ | static-prefix | cachekey.config | ``http://test-cdn.net/`` |
+ +---------------+-----------------+---------------------------------+
+ | separator | cachekey.config | (empty space) |
+ +---------------+-----------------+---------------------------------+
-+---------------+-----------------+---------------------------------+
-| Parameter | File | Value |
-+===============+=================+=================================+
-| static-prefix | cachekey.config | ``http://test-cdn.net/`` |
-+---------------+-----------------+---------------------------------+
-| separator | cachekey.config | (empty space) |
-+---------------+-----------------+---------------------------------+
-**Original regex value:**
+Removing Query Parameters and Path Information
+""""""""""""""""""""""""""""""""""""""""""""""
+Original regex value: ::
-``http://([^?]+)(?:?|$) http://test-cdn.net/$1``
+ http://([^?]+)(?:?|$) http://test-cdn.net/$1
-**Cachekey parameters:**
+.. 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/`` |
-+-----------------------+-----------------+-----------------------------------------------------+
+ +-----------------------+-----------------+-----------------------------------------------------+
+ |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
+Also note the ``s?`` used here so that both HTTP and HTTPS requests will end up with the same key value
-**Original regex value:**
-``http://test.net/([^?]+)(?:\?|$) http://test-cdn.net/$1``
+Removing Query Parameters with a Static Prefix
+""""""""""""""""""""""""""""""""""""""""""""""
+Original regex value: ::
-**Cachekey parameters:**
+ http://test.net/([^?]+)(?:\?|$) http://test-cdn.net/$1
-+-------------------+-----------------+---------------------------------+
-| Parameter | File | Value |
-+===================+=================+=================================+
-| static-prefix | cachekey.config | ``http://test-cdn.net/`` |
-+-------------------+-----------------+---------------------------------+
-| separator | cachekey.config | (empty space) |
-+-------------------+-----------------+---------------------------------+
-| remove-all-params | cachekey.config | true |
-+-------------------+-----------------+---------------------------------+
+.. table:: Cachekey Parameters
-.. _ApacheTrafficServerDocs: https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cachekey.en.html
+ +-------------------+-----------------+---------------------------------+
+ |Parameter |File |Value |
+ +===================+=================+=================================+
+ | static-prefix | cachekey.config | ``http://test-cdn.net/`` |
+ +-------------------+-----------------+---------------------------------+
+ | separator | cachekey.config | (empty space) |
+ +-------------------+-----------------+---------------------------------+
+ | remove-all-params | cachekey.config | true |
+ +-------------------+-----------------+---------------------------------+
-Further documentation on the cachekey plugin can be found at `ApacheTrafficServerDocs`_
+.. 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)
--------------------------------------------
-Trafficserver v7 has changed the logging format. Previously this was an xml file and now it is a lua file. Traffic Control compensates for this
-automatically depending upon the filename used for the logging parameters. Previously the file used was ``logs_xml.config``, for ATS 7 it is now
-``logging.config``. The same parameters will work this new file, ``LogFormat.Format``, ``LogFormat.Name``, ``LogObject.Format`` etc.
+-----------------------------------
+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. Trafficserver recommends changes to the following parameters: https://cwiki.apache.org/confluence/display/TS/Upgrading+to+v7.0
+---------------------------------
+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 where making these modifications manually is a tedious and time consuming process. A new utility `traffic_ops/install/bin/convert_profile/convert_profile` is provided to automatically convert an ATS6 profile to an ATS7 profile. This utility can be reused in the future for ATS7->8 as well.
+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:
- 1. Use Traffic Portal GUI to export profile to JSON
- 2. Modify the trafficserver version numbers to match your current Traffic Server v6 RPM version and planned Traffic Server v7 RPM version
- 3. Run ``convert_profile -input_profile <exported_file> -rules convert622to713.json -out <new_profile_name>``
- 4. Review output messages and make manual updates if needed. If you have modified a default value 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.
- 5. Use Traffic Portal GUI to import the newly created profile
+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 97e20cbf6..f75d146b8 100644
--- a/docs/source/admin/traffic_ops/using.rst
+++ b/docs/source/admin/traffic_ops/using.rst
@@ -19,192 +19,199 @@
.. |X| image:: ../../_static/bad.png
.. |clock| image:: ../../_static/clock-black.png
+*******************
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.
The Traffic Ops Menu
====================
+.. figure:: images/12m.png
+ :align: center
+ :alt: The Traffic Ops Landing Page
-.. image:: ../12m.png
+ The Traffic Ops Landing Page
The following tabs are available in the menu at the top of the Traffic Ops user interface.
.. index::
- Health Tab
-
-* **Health**
-
- Information on the health of the system. Hover over this tab to get to the following options:
-
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +===============+====================================================================================================================================+
- | Table View | A real time view into the main performance indicators of the CDNs managed by Traffic Control. |
- | | This view is sourced directly by the Traffic Monitor data and is updated every 10 seconds. |
- | | This is the default screen of Traffic Ops. |
- | | See :ref:`rl-health-table` for details. |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Graph View | A real graphical time view into the main performance indicators of the CDNs managed by Traffic Control. |
- | | This view is sourced by the Traffic Monitor data and is updated every 10 seconds. |
- | | On loading, this screen will show a history of 24 hours of data from Traffic Stats |
- | | See :ref:`rl-health-graph` for details. |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Server Checks | A table showing the results of the periodic check extension scripts that are run. See :ref:`rl-server-checks` |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Daily Summary | A graph displaying the daily peaks of bandwidth, overall bytes served per day, and overall bytes served since initial installation |
- | | per CDN. |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
-
-* **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:
-
- +-------------+--------------------------------------+
- | Option | Description |
- +=============+======================================+
- | Federations | Add/Edit/Delete Federation Mappings. |
- +-------------+--------------------------------------+
-
-* **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:`rl-bulkserver` |
- +-------------------+------------------------------------------------------------------------------------------+
-
-* **Parameters**
-
- Parameters and Profiles can be edited here. Hover over the tab to get the following options:
-
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +=====================+=====================================================================================================================================================================+
- | Global Profile | The table of global parameters. See :ref:`rl-param-prof`. This is where you Create/Read/Update/Delete parameters in the Global profile |
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | All Cache Groups | The table of all parameters *that are assigned to a cachegroup* - this may be slow to pull up, as there can be thousands of parameters. |
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | All Profiles | The table of all parameters *that are assigned to a profile* - this may be slow to pull up, as there can be thousands of parameters. |
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | Select Profile | Select the parameter list by profile first, then get a table of just the parameters for that profile. |
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | Export Profile | Profiles can be exported from one Traffic Ops instance to another using 'Select Profile' and under the "Profile Details" dialog for the desired profile |
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | Import Profile | Profiles can be imported from one Traffic Ops instance to another using the button "Import Profile" after using the "Export Profile" feature |
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | Orphaned Parameters | A table of parameters that are not associated to any profile of cache group. These parameters either should be deleted or associated with a profile of cache group. |
- +---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
-* **Tools**
-
- Tools for working with Traffic Ops and it's servers. Hover over this tab to get the following options:
-
- +--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +====================+===================================================================================================================================+
- | Generate ISO | Generate a bootable image for any of the servers in the Servers table (or any server for that matter). See :ref:`rl-generate-iso` |
- +--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Queue Updates | Send Updates to the caches. See :ref:`rl-queue-updates` |
- +--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | DB Dump | Backup the Database to a .sql file. |
- +--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Snapshot CRConfig | Send updates to the Traffic Monitor / Traffic Router servers. See :ref:`rl-queue-updates` |
- +--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Invalidate Content | Invalidate or purge content from all caches in the CDN. See :ref:`rl-purge` |
- +--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Manage DNSSEC keys | Manage DNSSEC Keys for a chosen CDN. |
- +--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
-
-
-* **Misc**
-
- Miscellaneous editing options. Hover over this tab to get the following options:
-
- +--------------------+-------------------------------------------------------------------------------------------+
- | Option | Description |
- +====================+===========================================================================================+
- | CDNs | Create/Read/Update/Delete CDNs |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Cache Groups | Create/Read/Update/Delete cache groups |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Users | Create/Read/Update/Delete users |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Profiles | Create/Read/Update/Delete profiles. See :ref:`rl-working-with-profiles` |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Networks(ASNs) | Create/Read/Update/Delete Autonomous System Numbers See :ref:`rl-asn-czf` |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Hardware | Get detailed hardware information (note: this should be moved to a Traffic Ops Extension) |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Data Types | Create/Read/Update/Delete data types |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Divisions | Create/Read/Update/Delete divisions |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Regions | Create/Read/Update/Delete regions |
- +--------------------+-------------------------------------------------------------------------------------------+
- | Physical Locations | Create/Read/Update/Delete locations |
- +--------------------+-------------------------------------------------------------------------------------------+
+ Health Tab
-.. index::
- Change Log
+Health
+------
+Information on the health of the system. Hover over this tab to get to the following options:
+
++---------------+------------------------------------------------------------------------------------------------------------------------------------+
+| Option | Description |
++===============+====================================================================================================================================+
+| Table View | A real time view into the main performance indicators of the CDNs managed by Traffic Control. |
+| | This view is sourced directly by the Traffic Monitor data and is updated every 10 seconds. |
+| | This is the default screen of Traffic Ops. |
+| | See :ref:`health-table` for details. |
++---------------+------------------------------------------------------------------------------------------------------------------------------------+
+| Graph View | A real graphical time view into the main performance indicators of the CDNs managed by Traffic Control. |
+| | This view is sourced by the Traffic Monitor data and is updated every 10 seconds. |
+| | On loading, this screen will show a history of 24 hours of data from Traffic Stats |
+| | See :ref:`health-graph` for details. |
++---------------+------------------------------------------------------------------------------------------------------------------------------------+
+| Server Checks | A table showing the results of the periodic check extension scripts that are run. See :ref:`server-checks` |
++---------------+------------------------------------------------------------------------------------------------------------------------------------+
+| Daily Summary | A graph displaying the daily peaks of bandwidth, overall bytes served per day, and overall bytes served since initial installation |
+| | per CDN. |
++---------------+------------------------------------------------------------------------------------------------------------------------------------+
+
+
+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:
+
++-------------+--------------------------------------+
+| Option | Description |
++=============+======================================+
+| Federations | Add/Edit/Delete Federation Mappings. |
++-------------+--------------------------------------+
+
+
+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` |
++-------------------+------------------------------------------------------------------------------------------+
+
+Parameters
+----------
+Parameters and Profiles can be edited here. Hover over the tab to get the following options:
+
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Option | Description |
++=====================+=====================================================================================================================================================================+
+| Global Profile | The table of global parameters. See :ref:`param-prof`. This is where you Create/Read/Update/Delete parameters in the Global profile |
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| All Cache Groups | The table of all parameters *that are assigned to a cachegroup* - this may be slow to pull up, as there can be thousands of parameters. |
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| All Profiles | The table of all parameters *that are assigned to a profile* - this may be slow to pull up, as there can be thousands of parameters. |
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Select Profile | Select the parameter list by profile first, then get a table of just the parameters for that profile. |
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Export Profile | Profiles can be exported from one Traffic Ops instance to another using 'Select Profile' and under the "Profile Details" dialog for the desired profile |
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Import Profile | Profiles can be imported from one Traffic Ops instance to another using the button "Import Profile" after using the "Export Profile" feature |
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Orphaned Parameters | A table of parameters that are not associated to any profile of cache group. These parameters either should be deleted or associated with a profile of cache group. |
++---------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-* **ChangeLog**
+Tools
+-----
+Tools for working with Traffic Ops and it's servers. Hover over this tab to get the following options:
+
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| Option | Description |
++====================+===================================================================================================================================+
+| Generate ISO | Generate a bootable image for any of the servers in the Servers table (or any server for that matter). See :ref:`generate-iso` |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| Queue Updates | Send Updates to the caches. See :ref:`queue-updates` |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| DB Dump | Backup the Database to a .sql file. |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| Snapshot CRConfig | Send updates to the Traffic Monitor / Traffic Router servers. See :ref:`queue-updates` |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| Invalidate Content | Invalidate or purge content from all caches in the CDN. See :ref:`purge` |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| Manage DNSSEC keys | Manage DNSSEC Keys for a chosen CDN. |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+
+
+Misc
+----
+Miscellaneous editing options. Hover over this tab to get the following options:
+
++--------------------+-------------------------------------------------------------------------------------------+
+| Option | Description |
++====================+===========================================================================================+
+| CDNs | Create/Read/Update/Delete CDNs |
++--------------------+-------------------------------------------------------------------------------------------+
+| Cache Groups | Create/Read/Update/Delete cache groups |
++--------------------+-------------------------------------------------------------------------------------------+
+| Users | Create/Read/Update/Delete users |
++--------------------+-------------------------------------------------------------------------------------------+
+| Profiles | Create/Read/Update/Delete profiles. See :ref:`working-with-profiles` |
++--------------------+-------------------------------------------------------------------------------------------+
+| Networks(ASNs) | Create/Read/Update/Delete Autonomous System Numbers See :ref:`asn-czf` |
++--------------------+-------------------------------------------------------------------------------------------+
+| Hardware | Get detailed hardware information (note: this should be moved to a Traffic Ops Extension) |
++--------------------+-------------------------------------------------------------------------------------------+
+| Data Types | Create/Read/Update/Delete data types |
++--------------------+-------------------------------------------------------------------------------------------+
+| Divisions | Create/Read/Update/Delete divisions |
++--------------------+-------------------------------------------------------------------------------------------+
+| Regions | Create/Read/Update/Delete regions |
++--------------------+-------------------------------------------------------------------------------------------+
+| Physical Locations | Create/Read/Update/Delete locations |
++--------------------+-------------------------------------------------------------------------------------------+
- The Changelog table displays the changes that are being made to the Traffic Ops database through the Traffic Ops user interface. This tab will show the number of changes since you last visited this tab in (brackets) since the last time you visited this tab. There are currently no sub menus for this tab.
+.. index::
+ Change Log
+ChangeLog
+---------
+The Changelog table displays the changes that are being made to the Traffic Ops database through the Traffic Ops user interface. This tab will show the number of changes since you last visited this tab in (brackets) since the last time you visited this tab. There are currently no sub menus for this tab.
-* **Help**
- Help for Traffic Ops and Traffic Control. Hover over this tab to get the following options:
+Help
+----
+Help for Traffic Ops and Traffic Control. Hover over this tab to get the following options:
- +---------------+---------------------------------------------------------------------+
- | Option | Description |
- +===============+=====================================================================+
- | About | Traffic Ops information, such as version, database information, etc |
- +---------------+---------------------------------------------------------------------+
- | Release Notes | Release notes for the most recent releases of Traffic Ops |
- +---------------+---------------------------------------------------------------------+
- | Logout | Logout from Traffic Ops |
- +---------------+---------------------------------------------------------------------+
++---------------+---------------------------------------------------------------------+
+| Option | Description |
++===============+=====================================================================+
+| About | Traffic Ops information, such as version, database information, etc |
++---------------+---------------------------------------------------------------------+
+| Release Notes | Release notes for the most recent releases of Traffic Ops |
++---------------+---------------------------------------------------------------------+
+| Logout | Logout from Traffic Ops |
++---------------+---------------------------------------------------------------------+
.. index::
- Edge Health
- Health
+ Edge Health
+ Health
Health
======
-.. _rl-health-table:
+.. _health-table:
The Health Table
-++++++++++++++++
+----------------
The Health table is the default landing screen for Traffic Ops, it displays the status of the EDGE caches in a table form directly from Traffic Monitor (bypassing Traffic Stats), sorted by Mbps Out. The columns in this table are:
-* **Profile**: the Profile of this server or ALL, meaning this row shows data for multiple servers, and the row shows the sum of all values.
-* **Host Name**: the host name of the server or ALL, meaning this row shows data for multiple servers, and the row shows the sum of all values.
-* **Edge Cache Group**: the edge cache group short name or ALL, meaning this row shows data for multiple servers, and the row shows the sum of all values.
-* **Healthy**: indicates if this cache is healthy according to the Health Protocol. A row with ALL in any of the columns will always show a |checkmark|, this column is valid only for individual EDGE caches.
-* **Admin**: shows the administrative status of the server.
-* **Connections**: the number of connections this cache (or group of caches) has open (``ats.proxy.process.http.current_client_connections`` from ATS).
-* **Mbps Out**: the bandwidth being served out if this cache (or group of caches)
+:Profile: the Profile of this server or ALL, meaning this row shows data for multiple servers, and the row shows the sum of all values.
+:Edge Cache Group: the edge cache group short name or ALL, meaning this row shows data for multiple servers, and the row shows the sum of all values.
+:Host Name: the host name of the server or ALL, meaning this row shows data for multiple servers, and the row shows the sum of all values.
+:Healthy: indicates if this cache is healthy according to the Health Protocol. A row with ALL in any of the columns will always show a |checkmark|, this column is valid only for individual EDGE caches.
+:Admin: shows the administrative status of the server.
+:Connections: the number of connections this cache (or group of caches) has open (``ats.proxy.process.http.current_client_connections`` from ATS).
+:Mbps Out: the bandwidth being served out if this cache (or group of caches)
Since the top line has ALL, ALL, ALL, it shows the total connections and bandwidth for all caches managed by this instance of Traffic Ops.
-.. _rl-health-graph:
+.. _health-graph:
Graph View
-++++++++++
+----------
The Graph View shows a live view of the last 24 hours of bits per seconds served and open connections at the edge in a graph. This data is sourced from Traffic Stats. If there are 2 CDNs configured, this view will show the statistis for both, and the graphs are stacked. On the left-hand side, the totals and immediate values as well as the percentage of total possible capacity are displayed. This view is update every 10 seconds.
-.. _rl-server-checks:
+.. _server-checks:
Server Checks
-+++++++++++++
+-------------
The server checks page is intended to give an overview of the Servers managed by Traffic Control as well as their status. This data comes from `Traffic Ops extensions <traffic_ops_extensions.html>`_.
+------+-----------------------------------------------------------------------+
@@ -238,10 +245,10 @@ The server checks page is intended to give an overview of the Servers managed by
+------+-----------------------------------------------------------------------+
Daily Summary
-+++++++++++++
+-------------
Displays daily max gbps and bytes served for all CDNs. In order for the graphs to appear, the 'daily_bw_url' and 'daily_served_url' parameters need to be be created, assigned to the global profile, and have a value of a grafana graph. For more information on configuring grafana, see the `Traffic Stats <../traffic_stats.html>`_ section.
-.. _rl-server:
+.. _server:
Server
======
@@ -249,7 +256,7 @@ This view shows a table of all the servers in Traffic Ops. The table columns sho
Server Types
-++++++++++++
+------------
These are the types of servers that can be managed in Traffic Ops:
+---------------+---------------------------------------------+
@@ -277,236 +284,247 @@ These are the types of servers that can be managed in Traffic Ops:
+---------------+---------------------------------------------+
-.. index::
- Bulk Upload Server
-
-.. _rl-bulkserver:
-
-Bulk Upload Server
-++++++++++++++++++
-TBD
-
-
Delivery Service
================
The fields in the Delivery Service view are:
-
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Active | Whether or not this delivery service is active on the CDN and is capable of traffic. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Content Routing Type | DNS is the standard routing type for most CDN services. HTTP Redirect is a specialty routing service that is primarily used for video and large file downloads where localization and latency are significant concerns. |
-| | A "Live" routing type should be used for all live services. See :ref:`rl-ds-types`. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Key (XML ID) | This id becomes a part of the CDN service domain in the form ``http://cdn.service-key.company.com/``. Must be all lowercase, no spaces or special characters. May contain dashes. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Display Name | Name of the service that appears in the Traffic portal. No character restrictions. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Tenant | Name of company or division of company who owns account. Allows you to group your services and control access. Tenants are setup as a simple hierarchy where you may create parent / child accounts. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| CDN | The CDN in which the delivery service belongs to. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Routing Name | The routing name to use for the delivery FQDN, i.e. ``<routing-name>.<deliveryservice>.<cdn-domain>``. It must be a valid hostname without periods. [2]_ |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Protocol | The protocol to serve this delivery service to the clients with: |
-| | |
-| | - HTTP: Delivery only HTTP traffic |
-| | - HTTPS: Delivery only HTTPS traffic |
-| | - HTTP AND HTTPS: Deliver both types of traffic. |
-| | - HTTP TO HTTPS: Delivery HTTP traffic as HTTPS traffic |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DSCP Tag | The Differentiated Services Code Point (DSCP) value to mark IP packets to the client with. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Signing Algorithm | Type of URL signing method to sign the URLs: |
-| | |
-| | - null: token based auth is not enabled for this delivery service. |
-| | - “url_sig”: URL Sign token based auth is enabled for this delivery service. |
-| | - “uri_signing”: URI Signing token based auth is enabled for this delivery service. |
-| | |
-| | See :ref:`rl-signed-urls`. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Deep Caching | Enables clients to be routed to the closest possible "deep" edge caches on a per 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: |
-| | |
-| | - 0 use in cache key and hand up to origin: Each unique query string is treated as a unique URL. |
-| | - 1 Do not use in cache key, but pass up to origin: 2 URLs that are the same except for the query string will match and cache HIT, while the origin still sees original query string in the request. |
-| | - 2 Drop at edge: 2 URLs that are the same except for the query string will match and cache HIT, while the origin will not see original query string in the request. |
-| | |
-| | **Note:** Choosing to drop query strings at the edge will preclude the use of a Regex Remap Expression. See :ref:`rl-regex-remap`. |
-| | |
-| | To set the qstring without the use of regex remap, or for further options, see :ref:`rl-qstring-handling`. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Geolocation Provider | Choose which Geolocation database provider, company that collects data on the location of IP addresses, to use. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Anonymous Blocking | Set to true to enable blocking of anonymous IPs for this delivery service. **Note:** Requires Geolocation provider's Anonymous IP database. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Geo Limit | Some services are intended to be limited by geography. The possible settings are: |
-| | |
-| | - None: Do not limit by geography. |
-| | - CZF only: If the requesting IP is not in the Coverage Zone File, do not serve the request. |
-| | - CZF + US: If the requesting IP is not in the Coverage Zone File or not in the United States, do not serve the request. |
-| | |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Geo Limit Countries | How (if at all) is this service to be limited by geography. Example Country Codes: CA, IN, PR. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Geo Limit Redirect URL | Traffic Router will redirect to this URL when Geo Limit check fails. See :ref:`rl-tr-ngb` |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Regional Geoblocking | Define regional geo-blocking rules for delivery services in a JSON format and set it to True/False. |
-| | See `regional geo-blocking <http://traffic-control-cdn.readthedocs.io/en/latest/admin/quick_howto/regionalgeo.html#configure-regional-geo-blocking-rgb>`_ |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| IPv6 Routing Enabled | Default is "True", entering "False" allows you to turn off CDN response to IPv6 requests |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Range Request Handling | How to treat range requests: |
-| | |
-| | - 0: Do not cache (ranges requested from files that are already cached due to a non range request will be a HIT) |
-| | - 1: Use the `background_fetch <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ plugin. |
-| | - 2: Use the cache_range_requests plugin. |
-| | |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNS Bypass IP | IPv4 address to overflow requests when the Max Bps or Max Tps for this delivery service exceeds. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNS Bypass IPv6 | IPv6 address to overflow requests when the Max Bps or Max Tps for this delivery service exceeds. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNS Bypass CNAME | Domain name to overflow requests when the Max Bps or Max Tps for this delivery service exceeds. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNS Bypass TTL | TTL for the DNS bypass domain or IP when threshold exceeds |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 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. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 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. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Global Max Mbps | The maximum bits per second this delivery service can serve across all EDGE caches before traffic will be diverted to the bypass destination. For a DNS delivery service, the Bypass Ipv4 or Ipv6 will be used (depending on whether this was a A or AAAA request), and for HTTP delivery services the Bypass FQDN will be used. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Global Max TPS | The maximum transactions per se this delivery service can serve across all EDGE caches before traffic will be diverted to the bypass destination. For a DNS delivery service, the Bypass Ipv4 or Ipv6 will be used (depending on whether this was a A or AAAA request), and for HTTP delivery services the Bypass FQDN will be used. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Max DNS Answers | It is used to restrict the number of cache IP addresses that the CCR will hand back. A numeric value from 1 to 15 which determines how many caches your content will be spread across in a particular site. When a customer requests your content they will get 1 to 15 IP addresses back they can use. These are rotated in each response. Ideally the number will reflect the amount of traffic. 1 = trial account with very little traffic, 2 = small production service. Add 1 more server for every 20 Gbps of traffic you expect at peak. So 20 Gbps = 3, 40 Gbps = 4, 60 Gbps = 5 |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Initial Dispersion | Determines number of machines content will be placed on within a cache group. Setting too high will result in poor caching performance. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Origin Server Base URL | The Origin Server’s base URL which includes the protocol (http or https). Example: ``http://movies.origin.com`` |
-| | Must be a domain only, no directories or IP addresses |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Use Multi Site Origin Feature | Set True/False to enable/disable the Multi Site Origin feature for this delivery service. See :ref:`rl-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 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 lat. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Geo Miss Default Longitude | Default Longitude for this delivery service. When client localization fails for bot Coverage Zone and Geo Lookup, this the client will be routed as if it was at this long. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Edge Header Rewrite Rules | Headers can be added or altered at each layer of the CDN. You must tell us four things: the action, the header name, the header value, and the direction to apply. The action will tell us whether we are adding, removing, or replacing headers. The header name and header value will determine the full header text. The direction will determine whether we add it before we respond to a request or before we make a request further up the chain in the server hierarchy. Examples include: |
-| | |
-| | - Action: Set |
-| | - Header Name: X-CDN |
-| | - Header Value: Foo |
-| | - Direction: Edge Response to Client |
-| | |
-| | See :ref:`rl-header-rewrite`. [1]_ |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Mid Header Rewrite Rules | Headers can be added or altered at each layer of the CDN. You must tell us four things: the action, the header name, the header value, and the direction to apply. The action will tell us whether we are adding, removing, or replacing headers. The header name and header value will determine the full header text. The direction will determine whether we add it before we respond to a request or before we make a request further up the chain in the server hierarchy. Examples include: |
-| | |
-| | - Action: Set |
-| | - Header Name: Host |
-| | - Header Value: code_abc123 |
-| | - Direction: Mid Request to Origin |
-| | |
-| | See :ref:`rl-header-rewrite`. [1]_ |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Traffic Router Additional Response Headers | List of header name:value pairs separated by __RETURN__. Listed pairs will be included in all TR HTTP responses. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Traffic Router Log Request Headers | List of header keys separated by __RETURN__. Listed headers will be included in TR access log entries under the “rh=” token. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Regex remap expression | Allows remapping of incoming requests URL using regex pattern matching to search/replace text. |
-| | See `ATS documentation on regex_remap <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_. [1]_ |
-| | |
-| | **Note:** you will not be able to save a Regex Remap Expression if you have Query String Handling set to drop query strings at the edge. See :ref:`rl-regex-remap`. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Cache URL expression | Allows you to manipulate the cache key of the incoming requests. Normally, the cache key is the origin domain. This can be changed so that multiple services can share a cache key, can also be used to preserve cached content if service origin is changed. |
-| | |
-| | **Note:** Only valid in ATS 6.X and earlier. Must be empty if using ATS 7.X and/or the `cachekey plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cachekey.en.html>`_. [1]_ |
-| | |
-| | See `ATS documentation on cacheurl <https://docs.trafficserver.apache.org/en/6.2.x/admin-guide/plugins/cacheurl.en.html>`_. [1]_ |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Raw remap text | For HTTP and DNS delivery services, this will get added to the end of the remap line on the cache verbatim. For ANY_MAP delivery services this is the remap line. [1]_ |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Long Description | Free text field that describes the purpose of the delivery service and will be displayed in the portal as a description field. For example, you can use this field to describe your service. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Long Description 2 | Free text field not currently used in configuration. For example, you can use this field to describe your customer type. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Long Description 3 | Free text field not currently used in configuration. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Info URL | Free text field allowing you to enter a URL which provides information about the service. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Check Path | A path (ex: /crossdomain.xml) to verify the connection to the origin server with. This can be used by Check Extension scripts to do periodic health checks against the delivery service. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Origin Shield (Pipe Delimited String) | Add another forward proxy upstream of the mid caches. Example: go_direct=true will allow the Mid to hit the origin directly instead of failing if the origin shield is down. Experimental Feature. |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Logs Enabled | Allows you to turn on/off logging for the service |
-+--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Name | Description |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Active | Whether or not this delivery service is active on the CDN and is capable of traffic. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Content Routing Type | DNS is the standard routing type for most CDN services. HTTP Redirect is a specialty routing service that is primarily used for video and large file downloads where |
+| | localization and latency are significant concerns. A "Live" routing type should be used for all live services. See :ref:`ds-types`. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Key (XML ID) | This id becomes a part of the CDN service domain in the form ``http://cdn.service-key.company.com/``. Must be all lowercase, no spaces or special characters. May |
+| | contain dashes. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Display Name | Name of the service that appears in the Traffic portal. No character restrictions. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Tenant | Name of company or division of company who owns account. Allows you to group your services and control access. Tenants are setup as a simple hierarchy where you may |
+| | create parent / child accounts. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| CDN | The CDN in which the delivery service belongs to. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Routing Name | The routing name to use for the delivery FQDN, i.e. ``<routing-name>.<deliveryservice>.<cdn-domain>``. It must be a valid hostname without periods. [2]_ |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Protocol | The protocol to serve this delivery service to the clients with: |
+| | |
+| | - HTTP: Delivery only HTTP traffic |
+| | - HTTPS: Delivery only HTTPS traffic |
+| | - HTTP AND HTTPS: Deliver both types of traffic. |
+| | - HTTP TO HTTPS: Delivery HTTP traffic as HTTPS traffic |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DSCP Tag | The Differentiated Services Code Point (DSCP) value to mark IP packets to the client with. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Signing Algorithm | Type of URL signing method to sign the URLs: |
+| | |
+| | - null: token based auth is not enabled for this delivery service. |
+| | - “url_sig”: URL Sign token based auth is enabled for this delivery service. |
+| | - “uri_signing”: URI Signing token based auth is enabled for this delivery service. |
+| | |
+| | See :ref:`signed-urls`. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Deep Caching | Enables clients to be routed to the closest possible "deep" edge caches on a per 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: |
+| | |
+| | 0. use in cache key and hand up to origin: Each unique query string is treated as a unique URL. |
+| | 1. Do not use in cache key, but pass up to origin: 2 URLs that are the same except for the query string will match and cache HIT, while the origin still sees |
+| | original query string in the request. |
+| | 2. Drop at edge: 2 URLs that are the same except for the query string will match and cache HIT, while the origin will not see original query string in the request. |
+| | |
+| | **Note:** Choosing to drop query strings at the edge will preclude the use of a Regex Remap Expression. See :ref:`regex-remap`. |
+| | |
+| | To set the qstring without the use of regex remap, or for further options, see :ref:`qstring-handling`. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Geolocation Provider | Choose which Geolocation database provider, company that collects data on the location of IP addresses, to use. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Anonymous Blocking | Set to true to enable blocking of anonymous IPs for this delivery service. **Note:** Requires Geolocation provider's Anonymous IP database. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Geo Limit | Some services are intended to be limited by geography. The possible settings are: |
+| | |
+| | - None: Do not limit by geography. |
+| | - CZF only: If the requesting IP is not in the Coverage Zone File, do not serve the request. |
+| | - CZF + US: If the requesting IP is not in the Coverage Zone File or not in the United States, do not serve the request. |
+| | |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Geo Limit Countries | How (if at all) is this service to be limited by geography. Example Country Codes: CA, IN, PR. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Geo Limit Redirect URL | Traffic Router will redirect to this URL when Geo Limit check fails. See :ref:`tr-ngb` |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Regional Geoblocking | Define regional geo-blocking rules for delivery services in a JSON format and set it to True/False. |
+| | See `regional geo-blocking <http://traffic-control-cdn.readthedocs.io/en/latest/admin/quick_howto/regionalgeo.html#configure-regional-geo-blocking-rgb>`_ |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| IPv6 Routing Enabled | Default is "True", entering "False" allows you to turn off CDN response to IPv6 requests |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Range Request Handling | How to treat range requests: |
+| | |
+| | 0. Do not cache (ranges requested from files that are already cached due to a non range request will be a HIT) |
+| | 1. Use the `background_fetch <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/background_fetch.en.html>`_ plugin. |
+| | 2. Use the cache_range_requests plugin. |
+| | |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNS Bypass IP | IPv4 address to overflow requests when the Max Bps or Max Tps for this delivery service exceeds. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNS Bypass IPv6 | IPv6 address to overflow requests when the Max Bps or Max Tps for this delivery service exceeds. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNS Bypass CNAME | Domain name to overflow requests when the Max Bps or Max Tps for this delivery service exceeds. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNS Bypass TTL | TTL for the DNS bypass domain or IP when threshold exceeds |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Global Max Mbps | The maximum bits per second this delivery service can serve across all EDGE caches before traffic will be diverted to the bypass destination. For a DNS delivery |
+| | service, the Bypass Ipv4 or Ipv6 will be used (depending on whether this was a A or AAAA request), and for HTTP delivery services the Bypass FQDN will be used. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Global Max TPS | The maximum transactions per se this delivery service can serve across all EDGE caches before traffic will be diverted to the bypass destination. For a DNS delivery |
+| | service, the Bypass Ipv4 or Ipv6 will be used (depending on whether this was a A or AAAA request), and for HTTP delivery services the Bypass FQDN will be used. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Max DNS Answers | It is used to restrict the number of cache IP addresses that the CCR will hand back. A numeric value from 1 to 15 which determines how many caches your content will |
+| | be spread across in a particular site. When a customer requests your content they will get 1 to 15 IP addresses back they can use. These are rotated in each response. |
+| | Ideally the number will reflect the amount of traffic. 1 = trial account with very little traffic, 2 = small production service. Add 1 more server for every 20 Gbps |
+| | of traffic you expect at peak. So 20 Gbps = 3, 40 Gbps = 4, 60 Gbps = 5 |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Initial Dispersion | Determines number of machines content will be placed on within a cache group. Setting too high will result in poor caching performance. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Origin Server Base URL | The Origin Server’s base URL which includes the protocol (http or https). Example: ``http://movies.origin.com`` |
+| | Must be a domain only, no directories or IP addresses |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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 |
+| | 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 |
+| | lat. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Geo Miss Default Longitude | Default Longitude for this delivery service. When client localization fails for bot Coverage Zone and Geo Lookup, this the client will be routed as if it was at this |
+| | long. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Edge Header Rewrite Rules | Headers can be added or altered at each layer of the CDN. You must tell us four things: the action, the header name, the header value, and the direction to apply. The |
+| | action will tell us whether we are adding, removing, or replacing headers. The header name and header value will determine the full header text. The direction will |
+| | determine whether we add it before we respond to a request or before we make a request further up the chain in the server hierarchy. Examples include: |
+| | |
+| | - Action: Set |
+| | - Header Name: X-CDN |
+| | - Header Value: Foo |
+| | - Direction: Edge Response to Client |
+| | |
+| | See :ref:`header-rewrite`. [1]_ |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Mid Header Rewrite Rules | Headers can be added or altered at each layer of the CDN. You must tell us four things: the action, the header name, the header value, and the direction to apply. The |
+| | action will tell us whether we are adding, removing, or replacing headers. The header name and header value will determine the full header text. The direction will |
+| | determine whether we add it before we respond to a request or before we make a request further up the chain in the server hierarchy. Examples include: |
+| | |
+| | - Action: Set |
+| | - Header Name: Host |
+| | - Header Value: code_abc123 |
+| | - Direction: Mid Request to Origin |
+| | |
+| | See :ref:`header-rewrite`. [1]_ |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Traffic Router Additional Response Headers | List of header name:value pairs separated by __RETURN__. Listed pairs will be included in all TR HTTP responses. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Traffic Router Log Request Headers | List of header keys separated by __RETURN__. Listed headers will be included in TR access log entries under the “rh=” token. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Regex remap expression | Allows remapping of incoming requests URL using regex pattern matching to search/replace text. |
+| | See `ATS documentation on regex_remap <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_remap.en.html>`_. [1]_ |
+| | |
+| | **Note:** you will not be able to save a Regex Remap Expression if you have Query String Handling set to drop query strings at the edge. See :ref:`regex-remap`. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Cache URL expression | Allows you to manipulate the cache key of the incoming requests. Normally, the cache key is the origin domain. This can be changed so that multiple services can share |
+| | a cache key, can also be used to preserve cached content if service origin is changed. |
+| | |
+| | **Note:** Only valid in ATS 6.X and earlier. Must be empty if using ATS 7.X and/or the |
+| | `cachekey plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/cachekey.en.html>`_. [1]_ |
+| | |
+| | See `ATS documentation on cacheurl <https://docs.trafficserver.apache.org/en/6.2.x/admin-guide/plugins/cacheurl.en.html>`_. [1]_ |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Raw remap text | For HTTP and DNS delivery services, this will get added to the end of the remap line on the cache verbatim. For ANY_MAP delivery services this is the remap line. [1]_ |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Long Description | Free text field that describes the purpose of the delivery service and will be displayed in the portal as a description field. For example, you can use this field to |
+| | describe your service. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Long Description 2 | Free text field not currently used in configuration. For example, you can use this field to describe your customer type. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Long Description 3 | Free text field not currently used in configuration. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Info URL | Free text field allowing you to enter a URL which provides information about the service. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Check Path | A path (ex: /crossdomain.xml) to verify the connection to the origin server with. This can be used by Check Extension scripts to do periodic health checks against the |
+| | delivery service. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Origin Shield (Pipe Delimited String) | Add another forward proxy upstream of the mid caches. Example: go_direct=true will allow the Mid to hit the origin directly instead of failing if the origin shield is |
+| | down. Experimental Feature. |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Logs Enabled | Allows you to turn on/off logging for the service |
++--------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. [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.
.. index::
- Delivery Service Type
+ Delivery Service Type
-.. _rl-ds-types:
+.. _ds-types:
Delivery Service Types
-++++++++++++++++++++++
+----------------------
One of the most important settings when creating the delivery service is the selection of the delivery service *type*. This type determines the routing method and the primary storage for the delivery service.
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+=================+========================================================================================================================================================================================================================================================================================================================================+
-| HTTP | HTTP Content Routing - The Traffic Router DNS auth server returns its own IP address on DNS queries, and the client gets redirected to a specific cache |
-| | in the nearest cache group using HTTP 302. Use this for long sessions like HLS/HDS/Smooth live streaming, where a longer setup time is not a. |
-| | problem. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNS | DNS Content Routing - The Traffic Router DNS auth server returns an edge cache IP address to the client right away. The client will find the cache quickly |
-| | but the Traffic Router can not route to a cache that already has this content in the cache group. Use this for smaller objects like web page images / objects. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| HTTP_NO_CACHE | HTTP Content Routing, but the caches will not actually cache the content, they act as just proxies. The MID tier is bypassed. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| HTTP_LIVE | HTTP Content routing, but where for "standard" HTTP content routing the objects are stored on disk, for this delivery service type the objects are stored |
-| | on the RAM disks. Use this for linear TV. The MID tier is bypassed for this type. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| HTTP_LIVE_NATNL | HTTP Content routing, same as HTTP_LIVE, but the MID tier is NOT bypassed. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNS_LIVE_NATNL | DNS Content routing, but where for "standard" DNS content routing the objects are stored on disk, for this delivery service type the objects are stored |
-| | on the RAM disks. Use this for linear TV. The MID tier is NOT bypassed for this type. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNS_LIVE | DNS Content routing, same as DNS_LIVE_NATNL, but the MID tier is bypassed. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ANY_MAP | ANY_MAP is not known to Traffic Router. For this deliveryservice, the "Raw remap text" field in the input form will be used as the remap line on the cache. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 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 |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 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. |
-+-----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
-.. _rl-federations:
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Name | Description |
++=================+===================================================================================================================================================================================================+
+| HTTP | HTTP Content Routing - The Traffic Router DNS auth server returns its own IP address on DNS queries, and the client gets redirected to a specific cache |
+| | in the nearest cache group using HTTP 302. Use this for long sessions like HLS/HDS/Smooth live streaming, where a longer setup time is not a problem. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNS | DNS Content Routing - The Traffic Router DNS auth server returns an edge cache IP address to the client right away. The client will find the cache quickly |
+| | but the Traffic Router can not route to a cache that already has this content in the cache group. Use this for smaller objects like web page images / objects. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| HTTP_NO_CACHE | HTTP Content Routing, but the caches will not actually cache the content, they act as just proxies. The MID tier is bypassed. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| HTTP_LIVE | HTTP Content routing, but where for "standard" HTTP content routing the objects are stored on disk, for this delivery service type the objects are stored |
+| | on the RAM disks. Use this for linear TV. The MID tier is bypassed for this type. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| HTTP_LIVE_NATNL | HTTP Content routing, same as HTTP_LIVE, but the MID tier is NOT bypassed. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNS_LIVE_NATNL | DNS Content routing, but where for "standard" DNS content routing the objects are stored on disk, for this delivery service type the objects are stored |
+| | on the RAM disks. Use this for linear TV. The MID tier is NOT bypassed for this type. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNS_LIVE | DNS Content routing, same as DNS_LIVE_NATNL, but the MID tier is bypassed. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ANY_MAP | ANY_MAP is not known to Traffic Router. For this deliveryservice, the "Raw remap text" field in the input form will be used as the remap line on the cache. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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 |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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. |
++-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _federations:
Federations
-+++++++++++
- Federations allow for other (federated) CDNs (at a different ISP, MSO, etc) to add a list of resolvers and a CNAME to a delivery service Traffic Ops. When a request is made from one of federated CDN's clients, Traffic Router will return the CNAME configured in the federation mapping. This allows the federated CDN to serve the content without the content provider changing the URL, or having to manage multiple URLs.
+-----------
+ Federations allow for other (federated) CDNs (at a different ISP, MSO, etc) to add a list of resolvers and a CNAME to a delivery service Traffic Ops. When a request is made from one of federated CDN's clients, Traffic Router will return the CNAME configured in the federation mapping. This allows the federated CDN to serve the content without the content provider changing the URL, or having to manage multiple URLs.
- Before adding a federation in the Traffic Ops UI, a user with the federations role needs to be created. This user will be assigned to the federation and will be able to add resolvers to the federation via the Traffic Ops `Federation API <../../development/traffic_ops_api/v12/federation.html>`_.
+ Before adding a federation in the Traffic Ops UI, a user with the federations role needs to be created. This user will be assigned to the federation and will be able to add resolvers to the federation via the Traffic Ops `Federation API <../../development/traffic_ops_api/v12/federation.html>`_.
.. index::
- Header Rewrite
+ Header Rewrite
-.. _rl-header-rewrite:
+.. _header-rewrite:
Header Rewrite Options and DSCP
-+++++++++++++++++++++++++++++++
+-------------------------------
Most header manipulation and per-delivery service configuration overrides are done using the `ATS Header Rewrite Plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/header_rewrite.en.html>`_. Traffic Control allows you to enter header rewrite rules to be applied at the edge and at the mid level. The syntax used in Traffic Ops is the same as the one described in the ATS documentation, except for some special strings that will get replaced:
+-------------------+--------------------------+
@@ -523,68 +541,44 @@ The deliveryservice screen also allows you to set the DSCP value of traffic sent
.. index::
- Token Based Authentication
- Signed URLs
+ Token Based Authentication
+ Signed URLs
-.. _rl-signed-urls:
+.. _signed-urls:
Token Based Authentication
-++++++++++++++++++++++++++
+--------------------------
Token based authentication or *signed URLs* is implemented using the Traffic Server ``url_sig`` plugin. To sign a URL at the signing portal take the full URL, without any query string, and add on a query string with the following parameters:
Client IP address
- The client IP address that this signature is valid for.
-
- ``C=<client IP address>``
-
+ The client IP address that this signature is valid for. e.g. ``C=<client IP address>``
Expiration
- The Expiration time (seconds since epoch) of this signature.
-
- ``E=<expiration time in secs since unix epoch>``
-
+ The Expiration time (seconds since epoch) of this signature. e.g. ``E=<expiration time in secs since unix epoch>``
Algorithm
- The Algorithm used to create the signature. Only 1 (HMAC_SHA1)
- and 2 (HMAC_MD5) are supported at this time
-
- ``A=<algorithm number>``
-
+ The Algorithm used to create the signature. Only 1 (HMAC_SHA1) and 2 (HMAC_MD5) are supported at this time e.g. ``A=<algorithm number>``
Key index
- Index of the key used. This is the index of the key in the
- configuration file on the cache. The set of keys is a shared
- secret between the signing portal and the edge caches. There
- is one set of keys per reverse proxy domain (fqdn).
-
- ``K=<key index used>``
+ Index of the key used. This is the index of the key in the configuration file on the cache. The set of keys is a shared secret between the signing portal and the edge caches. There is one set of keys per reverse proxy domain (fqdn). e.g. ``K=<key index used>``
Parts
- Parts to use for the signature, always excluding the scheme
- (http://). parts0 = fqdn, parts1..x is the directory parts
- of the path, if there are more parts to the path than letters
- in the parts param, the last one is repeated for those.
- Examples:
+ Parts to use for the signature, always excluding the scheme (http://). parts0 = fqdn, parts1..x is the directory parts of the path, if there are more parts to the path than letters in the parts param, the last one is repeated for those. Format: ``P=<parts string (0's and 1's)>`` Examples:
- 1: use fqdn and all of URl path
- 0110: use part1 and part 2 of path only
- 01: use everything except the fqdn
-
- ``P=<parts string (0's and 1's)>``
+ :1: use fqdn and all of URl path
+ :0110: use part1 and part 2 of path only
+ :01: use everything except the fqdn
Signature
- The signature over the parts + the query string up to and
- including "S=".
-
- ``S=<signature>``
+ The signature over the parts + the query string up to and including "S=". e.g. ``S=<signature>``
.. seealso:: The url_sig `README <https://github.com/apache/trafficserver/blob/master/plugins/experimental/url_sig/README>`_.
Generate URL Sig Keys
-^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""
To generate a set of random signed url keys for this delivery service and store them in Traffic Vault, click the **Generate URL Sig Keys** button at the bottom of the delivery service details screen.
-.. rl-parent-selection:
+.. parent-selection:
Parent Selection
-++++++++++++++++
+----------------
Parameters in the Edge (child) profile that influence this feature:
@@ -639,38 +633,39 @@ Parameters in the Edge (child) profile that influence this feature:
Parameters in the Mid (parent) profile that influence this feature:
-+----------------+---------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Filename | Default | Description |
-+================+===============+=========+===================================================================================================================================================================================+
-| domain_name | CRConfig.json | - | Only parents with the same value as the edge are going to be used as parents (to keep separation between CDNs) |
-+----------------+---------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| weight | parent.config | 1.0 | The weight of this parent, translates to the number of replicas in the consistent hash ring. This parameter only has effect with algorithm at the client set to "consistent_hash" |
-+----------------+---------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| port | parent.config | 80 | The port this parent is listening on as a forward proxy. |
-+----------------+---------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| use_ip_address | parent.config | 0 | 1 means use IP(v4) address of this parent in the parent.config, 0 means use the host_name.domain_name concatenation. |
-+----------------+---------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
-.. _rl-qstring-handling:
++----------------+---------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Name | Filename | Default | Description |
++================+===============+=========+==========================================================================================================================================================================+
+| domain_name | CRConfig.json | - | Only parents with the same value as the edge are going to be used as parents (to keep separation between CDNs) |
++----------------+---------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| weight | parent.config | 1.0 | The weight of this parent, translates to the number of replicas in the consistent hash ring. This parameter only has effect with algorithm at the client set to |
+| | | | "consistent_hash" |
++----------------+---------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| port | parent.config | 80 | The port this parent is listening on as a forward proxy. |
++----------------+---------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| use_ip_address | parent.config | 0 | 1 means use IP(v4) address of this parent in the parent.config, 0 means use the host_name.domain_name concatenation. |
++----------------+---------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _qstring-handling:
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 delivery services assigned to servers with this profile parameter. If the parameter is not set for the server profile but is present for the Delivery Service profile, this will override the setting in the delivery service. A value of "ignore" will not result in the addition of regex remap configuration.
-+-----------------------+---------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 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". |
-+-----------------------+---------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
++-----------------------+---------------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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". |
++-----------------------+---------------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-.. _rl-multi-site-origin:
+.. _multi-site-origin:
Multi Site Origin
-+++++++++++++++++
+-----------------
-.. Note:: The configuration of this feature changed significantly between ATS version 5 and >= 6. Some configuration in Traffic Control is different as well. This documentation assumes ATS 6 or higher. See :ref:`rl-multi-site-origin-qht` for more details.
+.. Note:: The configuration of this feature changed significantly between ATS version 5 and >= 6. Some configuration in Traffic Control is different as well. This documentation assumes ATS 6 or higher. See :ref:`multi-site-origin-qht` for more details.
Normally, the mid servers are not aware of any redundancy at the origin layer. With Multi Site Origin enabled this changes - Traffic Server (and Traffic Ops) are now made aware of the fact there are multiple origins, and can be configured to do more advanced failover and loadbalancing actions. A prerequisite for MSO to work is that the multiple origin sites serve identical content with identical paths, and both are configured to serve the same origin hostname as is configured in the deliveryservice `Origin Server Base URL` field. See the `Apache Traffic Server docs <https://docs.trafficserver.apache.org/en/latest/admin-guide/files/parent.config.en.html>`_ for more information on that cache's implementation.
@@ -713,127 +708,133 @@ Parameters in the deliveryservice profile that influence this feature:
-see :ref:`rl-multi-site-origin-qht` for a *quick how to* on this feature.
+see :ref:`multi-site-origin-qht` for a *quick how to* on this feature.
-.. _rl-ccr-profile:
+.. _ccr-profile:
Traffic Router Profile
-++++++++++++++++++++++
-
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Config_file | Description |
-+=========================================+========================+===========================================================================================================================================================================================================+
-| location | dns.zone | Location to store the DNS zone files in the local file system of Traffic Router. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| location | http-log4j.properties | Location to find the log4j.properties file for Traffic Router. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| location | dns-log4j.properties | Location to find the dns-log4j.properties file for Traffic Router. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| location | geolocation.properties | Location to find the log4j.properties file for Traffic Router. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| CDN_name | rascal-config.txt | The human readable name of the CDN for this profile. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| CoverageZoneJsonURL | CRConfig.xml | The location (URL) to retrieve the coverage zone map file in JSON format from. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| geolocation.polling.url | CRConfig.json | The location (URL) to retrieve the geo database file from. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| geolocation.polling.interval | CRConfig.json | How often to refresh the coverage geo location database in ms |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| coveragezone.polling.interval | CRConfig.json | How often to refresh the coverage zone map in ms |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| coveragezone.polling.url | CRConfig.json | The location (URL) to retrieve the coverage zone map file in JSON format from. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| deepcoveragezone.polling.interval | CRConfig.json | How often to refresh the deep coverage zone map in ms |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| deepcoveragezone.polling.url | CRConfig.json | The location (URL) to retrieve the deep coverage zone map file in JSON format from. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.soa.expire | CRConfig.json | The value for the expire field the Traffic Router DNS Server will respond with on Start of Authority (SOA) records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.soa.minimum | CRConfig.json | The value for the minimum field the Traffic Router DNS Server will respond with on SOA records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.soa.admin | CRConfig.json | The DNS Start of Authority admin. Should be a valid support email address for support if DNS is not working correctly. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.soa.retry | CRConfig.json | The value for the retry field the Traffic Router DNS Server will respond with on SOA records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.soa.refresh | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on A records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.ttls.NS | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on NS records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.ttls.SOA | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on SOA records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.ttls.AAAA | CRConfig.json | The Time To Live (TTL) the Traffic Router DNS Server will respond with on AAAA records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.ttls.A | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on A records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.ttls.DNSKEY | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on DNSKEY records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| tld.ttls.DS | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on DS records. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| api.port | server.xml | The TCP port Traffic Router listens on for API (REST) access. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| api.cache-control.max-age | CRConfig.json | The value of the ``Cache-Control: max-age=`` header in the API responses of Traffic Router. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 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 |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| dnssec.enabled | CRConfig.json | Whether DNSSEC is enabled; this parameter is updated via the DNSSEC administration user interface. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| dnssec.allow.expired.keys | CRConfig.json | Allow Traffic Router to use expired DNSSEC keys to sign zones; default is true. This helps prevent DNSSEC related outages due to failed Traffic Control components or connectivity issues. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| dynamic.cache.primer.enabled | CRConfig.json | Allow Traffic Router to attempt to prime the dynamic zone cache; defaults to true |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| dynamic.cache.primer.limit | CRConfig.json | Limit the number of permutations to prime when dynamic zone cache priming is enabled; defaults to 500 |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| keystore.maintenance.interval | CRConfig.json | The interval in seconds which Traffic Router will check the keystore API for new DNSSEC keys |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| keystore.api.url | CRConfig.json | The keystore API URL (https://${tmHostname}/api/1.1/cdns/name/${cdnName}/dnsseckeys.json; ${tmHostname} and ${cdnName} are search and replace tokens used by Traffic Router to construct the correct URL) |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| keystore.fetch.timeout | CRConfig.json | The timeout in milliseconds for requests to the keystore API |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| keystore.fetch.retries | CRConfig.json | The number of times Traffic Router will attempt to load keys before giving up; defaults to 5 |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| keystore.fetch.wait | CRConfig.json | The number of milliseconds Traffic Router will wait before a retry |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| signaturemanager.expiration.multiplier | CRConfig.json | Multiplier used in conjunction with a zone's maximum TTL to calculate DNSSEC signature durations; defaults to 5 |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| zonemanager.threadpool.scale | CRConfig.json | Multiplier used to determine the number of cores to use for zone signing operations; defaults to 0.75 |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| zonemanager.cache.maintenance.interval | CRConfig.json | The interval in seconds which Traffic Router will check for zones that need to be resigned or if dynamic zones need to be expired from cache |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| zonemanager.dynamic.response.expiration | CRConfig.json | A string (e.g.: 300s) that defines how long a dynamic zone |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNSKEY.generation.multiplier | CRConfig.json | Used to deteremine when new keys need to be regenerated. Keys are regenerated if expiration is less than the generation multiplier * the TTL. If the parameter does not exist, the default is 10. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| DNSKEY.effective.multiplier | CRConfig.json | Used when creating an effective date for a new key set. New keys are generated with an effective date of old key expiration - (effective multiplier * TTL). Default is 2. |
-+-----------------------------------------+------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+----------------------
+
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| Name | Config_file | Description |
++=========================================+========================+==================================================================================================================================================+
+| location | dns.zone | Location to store the DNS zone files in the local file system of Traffic Router. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| location | http-log4j.properties | Location to find the log4j.properties file for Traffic Router. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| location | dns-log4j.properties | Location to find the dns-log4j.properties file for Traffic Router. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| location | geolocation.properties | Location to find the log4j.properties file for Traffic Router. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| CDN_name | rascal-config.txt | The human readable name of the CDN for this profile. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| CoverageZoneJsonURL | CRConfig.xml | The location (URL) to retrieve the coverage zone map file in JSON format from. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| geolocation.polling.url | CRConfig.json | The location (URL) to retrieve the geo database file from. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| geolocation.polling.interval | CRConfig.json | How often to refresh the coverage geo location database in ms |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| coveragezone.polling.interval | CRConfig.json | How often to refresh the coverage zone map in ms |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| coveragezone.polling.url | CRConfig.json | The location (URL) to retrieve the coverage zone map file in JSON format from. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| deepcoveragezone.polling.interval | CRConfig.json | How often to refresh the deep coverage zone map in ms |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| deepcoveragezone.polling.url | CRConfig.json | The location (URL) to retrieve the deep coverage zone map file in JSON format from. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.soa.expire | CRConfig.json | The value for the expire field the Traffic Router DNS Server will respond with on Start of Authority (SOA) records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.soa.minimum | CRConfig.json | The value for the minimum field the Traffic Router DNS Server will respond with on SOA records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.soa.admin | CRConfig.json | The DNS Start of Authority admin. Should be a valid support email address for support if DNS is not working correctly. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.soa.retry | CRConfig.json | The value for the retry field the Traffic Router DNS Server will respond with on SOA records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.soa.refresh | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on A records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.ttls.NS | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on NS records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.ttls.SOA | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on SOA records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.ttls.AAAA | CRConfig.json | The Time To Live (TTL) the Traffic Router DNS Server will respond with on AAAA records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.ttls.A | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on A records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.ttls.DNSKEY | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on DNSKEY records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| tld.ttls.DS | CRConfig.json | The TTL the Traffic Router DNS Server will respond with on DS records. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| api.port | server.xml | The TCP port Traffic Router listens on for API (REST) access. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| api.cache-control.max-age | CRConfig.json | The value of the ``Cache-Control: max-age=`` header in the API responses of Traffic Router. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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 |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| dnssec.enabled | CRConfig.json | Whether DNSSEC is enabled; this parameter is updated via the DNSSEC administration user interface. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| dnssec.allow.expired.keys | CRConfig.json | Allow Traffic Router to use expired DNSSEC keys to sign zones; default is true. This helps prevent DNSSEC related outages due to failed Traffic |
+| | | Control components or connectivity issues. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| dynamic.cache.primer.enabled | CRConfig.json | Allow Traffic Router to attempt to prime the dynamic zone cache; defaults to true |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| dynamic.cache.primer.limit | CRConfig.json | Limit the number of permutations to prime when dynamic zone cache priming is enabled; defaults to 500 |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| keystore.maintenance.interval | CRConfig.json | The interval in seconds which Traffic Router will check the keystore API for new DNSSEC keys |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| keystore.api.url | CRConfig.json | The keystore API URL (https://${tmHostname}/api/1.1/cdns/name/${cdnName}/dnsseckeys.json; ${tmHostname} and ${cdnName} are search and replace |
+| | | tokens used by Traffic Router to construct the correct URL) |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| keystore.fetch.timeout | CRConfig.json | The timeout in milliseconds for requests to the keystore API |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| keystore.fetch.retries | CRConfig.json | The number of times Traffic Router will attempt to load keys before giving up; defaults to 5 |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| keystore.fetch.wait | CRConfig.json | The number of milliseconds Traffic Router will wait before a retry |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| signaturemanager.expiration.multiplier | CRConfig.json | Multiplier used in conjunction with a zone's maximum TTL to calculate DNSSEC signature durations; defaults to 5 |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| zonemanager.threadpool.scale | CRConfig.json | Multiplier used to determine the number of cores to use for zone signing operations; defaults to 0.75 |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| zonemanager.cache.maintenance.interval | CRConfig.json | The interval in seconds which Traffic Router will check for zones that need to be resigned or if dynamic zones need to be expired from cache |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| zonemanager.dynamic.response.expiration | CRConfig.json | A string (e.g.: 300s) that defines how long a dynamic zone |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNSKEY.generation.multiplier | CRConfig.json | Used to deteremine when new keys need to be regenerated. Keys are regenerated if expiration is less than the generation multiplier * the TTL. If |
+| | | the parameter does not exist, the default is 10. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
+| DNSKEY.effective.multiplier | CRConfig.json | Used when creating an effective date for a new key set. New keys are generated with an effective date of old key expiration - (effective |
+| | | multiplier * TTL). Default is 2. |
++-----------------------------------------+------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+
.. index::
- Regex Remap Expression
+ Regex Remap Expression
-.. _rl-regex-remap:
+.. _regex-remap:
Regex Remap Expression
-++++++++++++++++++++++
+----------------------
The regex remap expression allows to to use a regex and resulting match group(s) in order to modify the request URIs that are sent to origin. For example: ::
- ^/original/(.*) http://origin.example.com/remapped/$1
+ ^/original/(.*) http://origin.example.com/remapped/$1
.. Note:: If **Query String Handling** is set to ``2 Drop at edge``, then you will not be allowed to save a regex remap expression, as dropping query strings actually relies on a regex remap of its own. However, if there is a need to both drop query strings **and** remap request URIs, this can be accomplished by setting **Query String Handling** to ``1 Do not use in cache key, but pass up to origin``, and then using a custom regex remap expression to do the necessary remapping, while simultaneously dropping query strings. The following example will capture the original request URI up to, but not including, the query string and then forward to a remapped URI: ::
- ^/([^?]*).* http://origin.example.com/remapped/$1
+ ^/([^?]*).* http://origin.example.com/remapped/$1
.. index::
- HOST_REGEXP
- PATH_REGEXP
- HEADER_REGEXP
- Delivery Service regexp
+ HOST_REGEXP
+ PATH_REGEXP
+ HEADER_REGEXP
+ Delivery Service regexp
-.. _rl-ds-regexp:
+.. _ds-regexp:
Delivery Service Regexp
-+++++++++++++++++++++++
+-----------------------
This table defines how requests are matched to the delivery service. There are 3 type of entries possible here:
+---------------+----------------------------------------------------------------------+--------------+-----------+
@@ -848,68 +849,67 @@ This table defines how requests are matched to the delivery service. There are 3
The **Order** entry defines the order in which the regular expressions get evaluated. To support ``CNAMES`` from domains outside of the Traffic Control top level DNS domain, enter multiple ``HOST_REGEXP`` lines.
-Example:
- Example foo.
-
.. Note:: In most cases is is sufficient to have just one entry in this table that has a ``HOST_REGEXP`` Type, and Order ``0``. For the *movies* delivery service in the Kabletown CDN, the entry is simply single ``HOST_REGEXP`` set to ``.*\.movies\..*``. This will match every url that has a hostname that ends with ``movies.cdn1.kabletown.net``, since ``cdn1.kabletown.net`` is the Kabletown CDN's DNS domain.
.. index::
- Static DNS Entries
+ Static DNS Entries
-.. _rl-static-dns:
+.. _static-dns:
Static DNS Entries
-++++++++++++++++++
+------------------
Static DNS entries allow you to create other names *under* the delivery service domain. You can enter any valid hostname, and create a CNAME, A or AAAA record for it by clicking the **Static DNS** button at the bottom of the delivery service details screen.
.. index::
- Server Assignments
+ Server Assignments
-.. _rl-assign-edges:
+.. _assign-edges:
Server Assignments
-++++++++++++++++++
+------------------
Click the **Server Assignments** button at the bottom of the screen to assign servers to this delivery service. Servers can be selected by drilling down in a tree, starting at the profile, then the cache group, and then the individual servers. Traffic Router will only route traffic for this delivery service to servers that are assigned to it.
-.. _rl-asn-czf:
+.. _asn-czf:
The Coverage Zone File and ASN Table
-++++++++++++++++++++++++++++++++++++
-The Coverage Zone File (CZF) should contain a cachegroup name to network prefix mapping in the form: ::
-
- {
- "coverageZones": {
- "cache-group-01": {
- "coordinates": {
- "latitude": 1.1,
- "longitude": 2.2
- },
- "network6": [
- "1234:5678::/64",
- "1234:5679::/64"
- ],
- "network": [
- "192.168.8.0/24",
- "192.168.9.0/24"
- ]
- },
- "cache-group-02": {
- "coordinates": {
- "latitude": 3.3,
- "longitude": 4.4
- },
- "network6": [
- "1234:567a::/64",
- "1234:567b::/64"
- ],
- "network": [
- "192.168.4.0/24",
- "192.168.5.0/24"
- ]
- }
- }
- }
+------------------------------------
+The Coverage Zone File (CZF) should contain a cachegroup name to network prefix mapping in the form:
+
+.. code-block:: json
+
+ {
+ "coverageZones": {
+ "cache-group-01": {
+ "coordinates": {
+ "latitude": 1.1,
+ "longitude": 2.2
+ },
+ "network6": [
+ "1234:5678::/64",
+ "1234:5679::/64"
+ ],
+ "network": [
+ "192.168.8.0/24",
+ "192.168.9.0/24"
+ ]
+ },
+ "cache-group-02": {
+ "coordinates": {
+ "latitude": 3.3,
+ "longitude": 4.4
+ },
+ "network6": [
+ "1234:567a::/64",
+ "1234:567b::/64"
+ ],
+ "network": [
+ "192.168.4.0/24",
+ "192.168.5.0/24"
+ ]
+ }
+ }
+ }
The CZF is an input to the Traffic Control CDN, and as such does not get generated by Traffic Ops, but rather, it gets consumed by Traffic Router. Some popular IP management systems output a very similar file to the CZF but in stead of a cachegroup an ASN will be listed. Traffic Ops has the "Networks (ASNs)" view to aid with the conversion of files like that to a Traffic Control CZF file; this table is not used anywhere in Traffic Ops, but can be used to script the conversion using the API.
@@ -917,52 +917,54 @@ The script that generates the CZF file is not part of Traffic Control, since it
.. note:: The ``"coordinates"`` section is optional and may be used by Traffic Router for localization in the case of a CZF "hit" where the zone name does not map to a Cache Group name in Traffic Ops (i.e. Traffic Router will route to the closest Cache Group(s) geographically).
-.. _rl-deep-czf:
+.. _deep-czf:
The Deep Coverage Zone File
-+++++++++++++++++++++++++++
-The Deep Coverage Zone File (DCZF) format is similar to the CZF format but adds a ``caches`` list under each ``deepCoverageZone``: ::
-
- {
- "deepCoverageZones": {
- "location-01": {
- "coordinates": {
- "latitude": 5.5,
- "longitude": 6.6
- },
- "network6": [
- "1234:5678::/64",
- "1234:5679::/64"
- ],
- "network": [
- "192.168.8.0/24",
- "192.168.9.0/24"
- ],
- "caches": [
- "edge-01",
- "edge-02"
- ]
- },
- "location-02": {
- "coordinates": {
- "latitude": 7.7,
- "longitude": 8.8
- },
- "network6": [
- "1234:567a::/64",
- "1234:567b::/64"
- ],
- "network": [
- "192.168.4.0/24",
- "192.168.5.0/24"
- ],
- "caches": [
- "edge-02",
- "edge-03"
- ]
- }
- }
- }
+---------------------------
+The Deep Coverage Zone File (DCZF) format is similar to the CZF format but adds a ``caches`` list under each ``deepCoverageZone``:
+
+.. code-block:: json
+
+ {
+ "deepCoverageZones": {
+ "location-01": {
+ "coordinates": {
+ "latitude": 5.5,
+ "longitude": 6.6
+ },
+ "network6": [
+ "1234:5678::/64",
+ "1234:5679::/64"
+ ],
+ "network": [
+ "192.168.8.0/24",
+ "192.168.9.0/24"
+ ],
+ "caches": [
+ "edge-01",
+ "edge-02"
+ ]
+ },
+ "location-02": {
+ "coordinates": {
+ "latitude": 7.7,
+ "longitude": 8.8
+ },
+ "network6": [
+ "1234:567a::/64",
+ "1234:567b::/64"
+ ],
+ "network": [
+ "192.168.4.0/24",
+ "192.168.5.0/24"
+ ],
+ "caches": [
+ "edge-02",
+ "edge-03"
+ ]
+ }
+ }
+ }
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 Cache Group in Traffic Ops, so currently the deep coverage zone name only needs to be unique.
@@ -971,13 +973,13 @@ If the Traffic Router gets a DCZF "hit" for a requested Delivery Service that ha
.. note:: The ``"coordinates"`` section is optional.
-.. _rl-working-with-profiles:
+.. _working-with-profiles:
Parameters and Profiles
=======================
Parameters are shared between profiles if the set of ``{ name, config_file, value }`` is the same. To change a value in one profile but not in others, the parameter has to be removed from the profile you want to change it in, and a new parameter entry has to be created (**Add Parameter** button at the bottom of the Parameters view), and assigned to that profile. It is easy to create new profiles from the **Misc > Profiles** view - just use the **Add/Copy Profile** button at the bottom of the profile view to copy an existing profile to a new one. Profiles can be exported from one system and imported to another using the profile view as well. It makes no sense for a parameter to not be assigned to a single profile - in that case it really has no function. To find parameters like that use the **Parameters > Orphaned Parameters** view. It is easy to create orphaned parameters by removing all profiles, or not assigning a profile directly after creating the parameter.
-.. seealso:: :ref:`rl-param-prof` in the *Configuring Traffic Ops* section.
+.. seealso:: :ref:`param-prof` in the *Configuring Traffic Ops* section.
@@ -985,17 +987,16 @@ Tools
=====
.. index::
- ISO
- Generate ISO
+ ISO
+ Generate ISO
-.. _rl-generate-iso:
+.. _generate-iso:
Generate ISO
-++++++++++++
-
+------------
Generate ISO is a tool for building custom ISOs for building caches on remote hosts. Currently it only supports Centos 6, but if you're brave and pure of heart you MIGHT be able to get it to work with other unix-like OS's.
-The interface is *mostly* self explainatory as it's got hints.
+The interface is *mostly* self-explanatory as it's got hints.
+-------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
| Field | Explaination |
@@ -1049,33 +1050,35 @@ We trigger those in a %pre section in ks.cfg and they will write config files to
For example this is a section of our ks.cfg file: ::
- %include /mnt/stage2/ks_scripts/packages.txt
+ %include /mnt/stage2/ks_scripts/packages.txt
- %pre
- python /mnt/stage2/ks_scripts/create_network_line.py
- bash /mnt/stage2/ks_scripts/drive_config.sh
- %end
+ %pre
+ python /mnt/stage2/ks_scripts/create_network_line.py
+ bash /mnt/stage2/ks_scripts/drive_config.sh
+ %end
These two scripts will then run _before_ anaconda sets up it's internal structures, then a bit further up in the ks.cfg file (outside of the %pre %end block) we do an ::
- %include /mnt/stage2/ks_scripts/password.cfg
- ...
- %include /tmp/network_line
+ %include /mnt/stage2/ks_scripts/password.cfg
+ ...
+ %include /tmp/network_line
- %include /tmp/drive_config
- ...
+ %include /tmp/drive_config
+ ...
This snarfs up the contents and inlines them.
If you only have one kind of hardware on your CDN it is probably best to just put the drive config right in the ks.cfg.
-If you have simple networking needs (we use bonded interfaces in most, but not all locations and we have several types of hardware meaning different ethernet interface names at the OS level etc.) then something like this: ::
+If you have simple networking needs (we use bonded interfaces in most, but not all locations and we have several types of hardware meaning different ethernet interface names at the OS level etc.) then something like this:
+
+.. code-block:: bash
- #!/bin/bash
- source /mnt/stage2/ks_scripts/network.cfg
- echo "network --bootproto=static --activate --ipv6=$IPV6ADDR --ip=$IPADDR --netmask=$NETMASK --gateway=$GATEWAY --ipv6gateway=$GATEWAY --nameserver=$NAMESERVER --mtu=$MTU --hostname=$HOSTNAME" >> /tmp/network.cfg
- # Note that this is an example and may not work at all.
+ #!/bin/bash
+ source /mnt/stage2/ks_scripts/network.cfg
+ echo "network --bootproto=static --activate --ipv6=$IPV6ADDR --ip=$IPADDR --netmask=$NETMASK --gateway=$GATEWAY --ipv6gateway=$GATEWAY --nameserver=$NAMESERVER --mtu=$MTU --hostname=$HOSTNAME" >> /tmp/network.cfg
+,, Note:: that this is an example and may not work at all.
You could also put this in the %pre section. Lots of ways to solve it.
@@ -1086,18 +1089,18 @@ We have included the two scripts we use in the "misc" directory of the git repo:
These scripts were written to support a very narrow set of expectations and environment and are almost certainly not suitable to just drop in, but they might provide a good starting point.
-.. _rl-queue-updates:
+.. _queue-updates:
Queue Updates and Snapshot CRConfig
-+++++++++++++++++++++++++++++++++++
+-----------------------------------
When changing delivery services special care has to be taken so that Traffic Router will not send traffic to caches for delivery services that the cache doesn't know about yet. In general, when adding delivery services, or adding servers to a delivery service, it is best to update the caches before updating Traffic Router and Traffic Monitor. When deleting delivery services, or deleting server assignments to delivery services, it is best to update Traffic Router and Traffic Monitor first and then the caches. Updating the cache configuration is done through the *Queue Updates* menu, and updating Traffic Monitor and Traffic Router config is done through the *Snapshot CRConfig* menu.
.. index::
- Cache Updates
- Queue Updates
+ Cache Updates
+ Queue Updates
Queue Updates
-^^^^^^^^^^^^^
+"""""""""""""
Every 15 minutes the caches should run a *syncds* to get all changes needed from Traffic Ops. The files that will be updated by the syncds job are:
- records.config
@@ -1112,48 +1115,46 @@ Every 15 minutes the caches should run a *syncds* to get all changes needed from
A cache will only get updated when the update flag is set for it. To set the update flag, use the *Queue Updates* menu - here you can schedule updates for a whole CDN or a cache group:
- #. Click **Tools > Queue Updates**.
- #. Select the CDN to queueu uodates for, or All.
- #. Select the cache group to queue updates for, or All
- #. Click the **Queue Updates** button.
- #. When the Queue Updates for this Server? (all) window opens, click **OK**.
+#. Click **Tools > Queue Updates**.
+#. Select the CDN to queueu uodates for, or All.
+#. Select the cache group to queue updates for, or All
+#. Click the **Queue Updates** button.
+#. When the Queue Updates for this Server? (all) window opens, click **OK**.
To schedule updates for just one cache, use the "Server Checks" page, and click the |checkmark| in the *UPD* column. The UPD column of Server Checks page will change show a |clock| when updates are pending for that cache.
-
.. index::
- Snapshot CRConfig
+ Snapshot CRConfig
-.. _rl-snapshot-crconfig:
+.. _snapshot-crconfig:
Snapshot CRConfig
-^^^^^^^^^^^^^^^^^
-
-Every 60 seconds Traffic Monitor will check with Traffic Ops to see if a new CRConfig snapshot exists; Traffic Monitor polls Traffic Ops for a new CRConfig, and Traffic Router polls Traffic Monitor for the same file. This is necessary to ensure that Traffic Monitor sees configuration changes first, which helps to ensure that the health and state of caches and delivery services propagates properly to Traffic Router. See :ref:`rl-ccr-profile` for more information on the CRConfig file.
+"""""""""""""""""
+Every 60 seconds Traffic Monitor will check with Traffic Ops to see if a new CRConfig snapshot exists; Traffic Monitor polls Traffic Ops for a new CRConfig, and Traffic Router polls Traffic Monitor for the same file. This is necessary to ensure that Traffic Monitor sees configuration changes first, which helps to ensure that the health and state of caches and delivery services propagates properly to Traffic Router. See :ref:`ccr-profile` for more information on the CRConfig file.
To create a new snapshot, use the *Tools > Snapshot CRConfig* menu:
- #. Click **Tools > Snapshot CRConfig**.
- #. Verify the selection of the correct CDN from the Choose CDN drop down and click **Diff CRConfig**.
- On initial selection of this, the CRConfig Diff window says the following:
+ #. Click **Tools > Snapshot CRConfig**.
+ #. Verify the selection of the correct CDN from the Choose CDN drop down and click **Diff CRConfig**.
+ On initial selection of this, the CRConfig Diff window says the following:
- There is no existing CRConfig for [cdn] to diff against... Is this the first snapshot???
- If you are not sure why you are getting this message, please do not proceed!
- To proceed writing the snapshot anyway click the 'Write CRConfig' button below.
+ There is no existing CRConfig for [cdn] to diff against... Is this the first snapshot???
+ If you are not sure why you are getting this message, please do not proceed!
+ To proceed writing the snapshot anyway click the 'Write CRConfig' button below.
- If there is an older version of the CRConfig, a window will pop up showing the differences
- between the active CRConfig and the CRConfig about to be written.
+ If there is an older version of the CRConfig, a window will pop up showing the differences
+ between the active CRConfig and the CRConfig about to be written.
- #. Click **Write CRConfig**.
- #. When the This will push out a new CRConfig.json. Are you sure? window opens, click **OK**.
- #. The Successfully wrote CRConfig.json! window opens, click **OK**.
+ #. Click **Write CRConfig**.
+ #. When the This will push out a new CRConfig.json. Are you sure? window opens, click **OK**.
+ #. The Successfully wrote CRConfig.json! window opens, click **OK**.
.. index::
- Invalidate Content
- Purge
+ Invalidate Content
+ Purge
-.. _rl-purge:
+.. _purge:
Invalidate Content
==================
@@ -1163,62 +1164,61 @@ Invalidating content on the CDN is sometimes necessary when the origin was mis-c
To invalidate content:
- 1. Click **Tools > Invalidate Content**
- 2. Fill out the form fields:
+#. Click **Tools > Invalidate Content**
+#. Fill out the form fields:
- - Select the **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.
+ - Select the **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.
- 3. Click the **Submit** button.
+#. Click the **Submit** button.
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 accessible to Traffic Ops. Other applications needing access to this data, such as Traffic Router, must use the Traffic Ops `DNSSEC APIs <../../development/traffic_ops_api/v12/cdn.html#dnssec-keys>`_ to retrieve this information.
To Manage DNSSEC Keys:
- 1. Click **Tools -> Manage DNSSEC Keys**
- 2. Choose a CDN and click **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 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.
The Manage DNSSEC Keys screen also allows a user to perform the following actions:
-**Activate/Deactivate DNSSEC for a CDN**
-
+Activate/Deactivate DNSSEC for a CDN
+------------------------------------
Fairly straight forward, this button set the **dnssec.enabled** param to either **true** or **false** on the Traffic Router profile for the CDN. The Activate/Deactivate option is only available if DNSSEC keys exist for CDN. In order to active DNSSEC for a CDN a user must first generate keys and then click the **Active DNSSEC** button.
-**Generate Keys**
-
+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:
- - **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.
- - **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.
+- **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.
+- **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
+--------------
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 are presented with a screen with the following options:
- - **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.
+: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.
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.
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.
-**Generation of keys for new Delivery Services**
-
+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.
-**Regeneration of expiring keys for a Delivery Service**
-
+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 when a KSK is regenerated for the CDN TLD then a new DS Record will also be created. The new DS Record needs to be added to the parent zone before Traffic Router attempts to sign with the new KSK in order for DNSSEC to work correctly. Therefore, management of the KSK needs to be a manual process.
diff --git a/docs/source/admin/traffic_portal/default_profiles.rst b/docs/source/admin/traffic_portal/default_profiles.rst
new file mode 100644
index 000000000..1a2c2c975
--- /dev/null
+++ b/docs/source/admin/traffic_portal/default_profiles.rst
@@ -0,0 +1,49 @@
+..
+..
+.. 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::
+ Default Profiles
+
+.. _default-profiles:
+
+****************
+Default Profiles
+****************
+Traffic Ops has the concept of :ref:`working-with-profiles`, which are an integral component of Traffic Ops. To get started, a set of default Traffic Ops profiles are provided. These can be imported into Traffic Ops, and are required by the Traffic Control components Traffic Router, Traffic Monitor, and Apache Traffic Server (Edge-tier and Mid-tier caches). Download Default Profiles from `here <http://trafficcontrol.apache.org/downloads/profiles/>`_
+
+.. _to-profiles-min-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
+
+.. 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'
+#. Drag and drop your desired profile into the upload pane
+#. Click 'Import'
+#. Continue these steps for each of the :ref:`to-profiles-min-needed`.
diff --git a/docs/source/admin/traffic_portal/installation.rst b/docs/source/admin/traffic_portal/installation.rst
index 8d0a3cef7..c55a4a58b 100644
--- a/docs/source/admin/traffic_portal/installation.rst
+++ b/docs/source/admin/traffic_portal/installation.rst
@@ -16,36 +16,49 @@
*****************************
Traffic Portal Administration
*****************************
-The following are requirements to ensure an accurate set up:
+Traffic Portal is only supported on CentOS Linux distributions - version 6.7 or higher (including 7.x). It runs on NodeJS and requires version 6.0 or higher.
-* CentOS 6.7 or 7
-* Node.js 6.0.x or above
-**Installing Traffic Portal**
+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 (./pkg -v traffic_portal_build).
- - Copy the Traffic Portal RPM to your server
- - curl --silent --location https://rpm.nodesource.com/setup_6.x | sudo bash -
- - sudo yum install -y nodejs
- - sudo yum install -y <traffic_portal rpm>
+#. 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).
+#. 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:
-**Configuring Traffic Portal**
+ .. code-block:: bash
- - 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)
+ curl --silent --location https://rpm.nodesource.com/setup_6.x | sudo bash -
-**Starting Traffic Portal**
+#. Install the Traffic Portal RPM e.g. by running ``yum install path/to/traffic_portal.rpm`` as the root user or with ``sudo``.
- - sudo service traffic_portal start
-**Stopping Traffic Portal**
+Configuring Traffic Portal
+==========================
- - sudo service traffic_portal stop
+- 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)
+Starting Traffic Portal
+=======================
+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
+as the root user or with ``sudo``.
+Stopping Traffic Portal
+=======================
+
+If Traffic Portal was started using ``systemctl``, simply run
+
+ .. code-block:: bash
+
+ systemctl stop traffic_portal
+
+as the root user, or with ``sudo``.
diff --git a/docs/source/admin/traffic_portal/usingtrafficportal.rst b/docs/source/admin/traffic_portal/usingtrafficportal.rst
index c7247e361..0cc3753b8 100644
--- a/docs/source/admin/traffic_portal/usingtrafficportal.rst
+++ b/docs/source/admin/traffic_portal/usingtrafficportal.rst
@@ -15,43 +15,57 @@
.. _usingtrafficportal:
+**********************
Traffic Portal - Using
-%%%%%%%%%%%%%%%%%%%%%%
+**********************
+Traffic Portal is the official Traffic Control UI. Traffic Portal typically runs on a different machine than Traffic Ops, and works by using the Traffic Ops API. The following high-level items are available in the Traffic Portal menu.
-Traffic Portal is the official replacement for the legacy Traffic Ops UI. Traffic Portal consumes the Traffic Ops API. The following high-level items are available in the Traffic Portal menu.
+.. figure:: ./images/tp_menu.png
+ :width: 55%
+ :align: center
+ :alt: The Traffic Portal Landing Page
-.. image:: ./images/tp_menu.png
+ Traffic Portal Start Page
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**: The current bandwidth of all of your CDNs.
-* **Current Connections**: The current number of connections to all of your CDNs.
-* **Healthy Caches**: Number of healthy caches across all CDNs. Click the link to view the healthy caches on the cache stats page.
-* **Unhealthy Caches**: Number of unhealthy caches across all CDNs. Click the link to view the unhealthy caches on the cache stats page.
-* **Online Caches**: Number of online caches. Traffic Monitor will not monitor the state of ONLINE servers. True health is unknown.
-* **Reported Caches**: Number of caches with REPORTED status.
-* **Offline Caches**: Number of caches with OFFLINE status.
-* **Admin Down Caches**: Number of caches with ADMIN_DOWN status.
+Current Bandwidth
+ The current bandwidth of all of your CDNs.
-Each component of this view is updated at the intervals defined in tp.domain.com/traffic_portal_properties.json.
+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.
+
+Unhealthy Caches
+ 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`.
+
+Reported Caches
+ Displays the number of cache servers with REPORTED status. For more information, see :ref:`health-proto`.
+
+Offline Caches
+ Displays the number of cache servers with OFFLINE status. For more information, see :ref:`health-proto`.
+
+Admin Down Caches
+ Displays the number of caches with ADMIN_DOWN status. For more information, see :ref:`health-proto`.
+
+Each component of this view is updated on the intervals defined in the ``tp.domain.com/traffic_portal_properties.json`` configuration file.
CDNs
====
A table of CDNs with the following columns:
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+======================================================================================================================+
-| Name | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Domain | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| DNSSEC Enabled | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
+:Name: The name of the CDN
+:Domain: The CDN's Top-Level Domain (TLD)
+:DNSSEC Enabled: 'true' if :ref:`tr-dnssec` is enabled on this CDN, 'false' otherwise.
CDN management includes the ability to (where applicable):
@@ -59,304 +73,157 @@ CDN management includes the ability to (where applicable):
- update an existing CDN
- delete an existing CDN
- queue/clear updates on all servers in a CDN
-- diff CDN snapshot
-- create CDN snapshot
-- manage CDN DNSSEC keys
-- manage CDN federations
-- view CDN delivery services
+- diff CDN snapshots
+- create a CDN snapshot
+- manage a CDN's DNSSEC keys
+- manage a CDN's federations
+- view Delivery Services of a CDN
- view CDN profiles
-- view CDN servers
+- view servers within a CDN
Monitor
=======
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +===============+====================================================================================================================================+
- | Cache Checks | A real time view into the status of each cache. |
- | | This view is sourced by the Traffic Monitor data thru the Traffic Ops API and is updated on demand. |
- | | See :ref:`tp-cache-checks` for details. |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Cache Stats | A table showing the results of the periodic check extension scripts that are run. See :ref:`tp-cache-stats` for details. |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
-
-Services
-========
-
- +----------------------------------+-----------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +==================================+=================================================================================================================+
- | Delivery Services | Settings for your delivery services. Only the delivery services defined by a user's tenancy are visible. |
- | | See :ref:`tp-delivery-services` for details. |
- +----------------------------------+-----------------------------------------------------------------------------------------------------------------+
- | Delivery Service Requests | If enabled in 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. |
- | | See :ref:`tp-delivery-service-requests` for details. |
- +----------------------------------+-----------------------------------------------------------------------------------------------------------------+
+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.
-Configure
-=========
-
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +===============+====================================================================================================================================+
- | Servers | Manage servers. See :ref:`tp-servers` |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Profiles | Manage profiles. See :ref:`tp-profiles` |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Parameters | Manage parameters. See :ref:`tp-parameters` |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Types | Manage types. See :ref:`tp-types` |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
- | Statuses | Manage server statuses. See :ref:`tp-statuses` |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------+
+.. figure:: ./images/tp_menu_monitor.png
+ :align: center
+ :alt: The Traffic Portal 'Monitor' Menu
-Topology
-========
+ The 'Monitor' Menu
- +----------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +================+===================================================================================================================================+
- | Cache Groups | Manage cache groups. See :ref:`tp-cache-groups` |
- +----------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Phys Locations | Manage profiles. See :ref:`tp-phys-locations` |
- +----------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Divisions | Manage divisions. See :ref:`tp-divisions` |
- +----------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | Regions | Manage regions. See :ref:`tp-regions` |
- +----------------+-----------------------------------------------------------------------------------------------------------------------------------+
- | ASNs | Manage autonomous system numbers (ASN). See :ref:`tp-asns` |
- +----------------+-----------------------------------------------------------------------------------------------------------------------------------+
-
-Tools
-=====
-
- +--------------------+-------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +====================+===============================================================================================================================+
- | Invalidate Content | Manage invalidate content jobs. See :ref:`tp-jobs` |
- +--------------------+-------------------------------------------------------------------------------------------------------------------------------+
- | Generate ISO | Generate a bootable image for any of the servers in the Servers table (or any server for that matter). See :ref:`tp-gen-iso` |
- +--------------------+-------------------------------------------------------------------------------------------------------------------------------+
-
-User Admin
-==========
-
- +--------------------+-------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +====================+===============================================================================================================================+
- | Users | Manage users. See :ref:`tp-users` |
- +--------------------+-------------------------------------------------------------------------------------------------------------------------------+
- | Tenants | Manage tenants. See :ref:`tp-tenants` |
- +--------------------+-------------------------------------------------------------------------------------------------------------------------------+
- | Roles | Manage roles. See :ref:`tp-roles` |
- +--------------------+-------------------------------------------------------------------------------------------------------------------------------+
-
-
-Other
-=====
-
- Custom menu items. By default, you get a link to Traffic Control docs. See :ref:`tp-menu-other`
-
- +--------------------+--------------------------------------------------------------------------------------------------------------------------------+
- | Option | Description |
- +====================+================================================================================================================================+
- | Docs | Link to trafficcontrol.apache.org |
- +--------------------+--------------------------------------------------------------------------------------------------------------------------------+
+Cache Checks
------------
+A real-time view into the status of each cache.
-Monitor
-=======
-
-.. image:: ./images/tp_menu_monitor.png
-
-.. _tp-cache-checks:
-
-Cache Checks
-++++++++++++
The cache checks page is intended to give an overview of the caches managed by Traffic Control as well as their status.
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+==========+============================================================================================================================================+
-| Hostname | Cache host name |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| Profile | The name of the profile applied to the cache |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| Status | The status of the cache (ONLINE, REPORTED, ADMIN_DOWN, OFFLINE) |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| UPD | Config updates pending for an edge or mid |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| RVL | Content invalidation requests are pending for and edge or mid |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| ILO | Ping the iLO interface for EDGE or MID servers |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| 10G | Ping the IPv4 address of the EDGE or MID servers |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| 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. |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| CHR | Cache Hit Ratio in percent. |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| CDU | Total Cache Disk Usage in 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. |
-+----------+--------------------------------------------------------------------------------------------------------------------------------------------+
-
-.. _tp-cache-stats:
+: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
+: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
+: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
+: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.
+
Cache Stats
-+++++++++++
-Displays health by cache group/profile.
-
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+==============+========================================================================================================================================+
-| Profile | Name of the profile applied to the edge or mid cache |
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
-| Host | ALL or grouped by profile |
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
-| Cache Group | Cache Group Name |
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
-| Healthy | True/False as determined by Traffic Monitor |
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
-| Status | Status of the cache or cache group |
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
-| Connections | Number of connections |
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
-| MbpsOut | MbpsOut |
-+--------------+----------------------------------------------------------------------------------------------------------------------------------------+
+-----------
+A table showing the results of the periodic check extension scripts that are run. These can be grouped by Cache Group and/or Profile.
+
+:Profile: Name of the profile applied to the Edge-tier or Mid-tier cache server
+:Host: 'ALL' for entries grouped by cache group, or the hostname of a particular cache server
+:Cache Group: Name of the Cache Group to which this server belongs, or the name of the Cache Group that is grouped for entries grouped by Cache Group
+:Healthy: True/False as determined by Traffic Monitor (See :ref:`health-proto`)
+:Status: Status of the cache or Cache Group
+:Connections: Number of connections to this cache server or Cache Group
+:MbpsOut: Data flow outward (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.
-.. image:: ./images/tp_menu_services.png
+.. figure:: images/tp_table_ds_requests.png
+ :align: center
+ :alt: An example table of Delivery Service Requests
-.. _tp-delivery-services:
+ Table of Delivery Service Requests
Delivery Services
-+++++++++++++++++
-
-A table of your delivery services with the following columns:
-
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+=======================================================================================================================+
-| Key (XML ID) | A unique string that identifies this delivery service. |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| Tenant | The tenant that the delivery service is assigned to. |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| 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. See :ref:`rl-ds-types`. |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| Protocol | The protocol to serve this delivery service to the clients with: |
-| | |
-| | - HTTP |
-| | - HTTPS |
-| | - HTTP and HTTPS |
-| | - HTTP to HTTPS |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| CDN | The CDN that the delivery service belongs to. |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| 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 DSCP value to mark IP packets to the client with. |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| Signing Algorithm | See :ref:`rl-signed-urls`. |
-| | - None |
-| | - URL Signature Keys |
-| | - URI Signing Keys |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------------+
-| Query String Handling | How to treat query strings: |
-| | |
-| | - use in cache key and hand up to origin (each unique query string is treated as a unique URL.) |
-| | - do not use in cache key, but pass up to origin (2 URLs that are the same except for the query string will match, |
-| | and cache HIT, while the origin still sees original query string in the request.) |
-| | - drop at edge (2 URLs that are the same except for the query string will match, and cache HIT, while the origin |
-| | will not see original query string in the request.) |
-| | |
-| | Dropping query strings at the edge will preclude the use of a Regex Remap Expression. See :ref:`rl-regex-remap`. |
-| | |
-| | To set the qstring without the use of regex remap, or for further options, see :ref:`rl-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 regexes
-- view and create delivery service invalidate content jobs
+-----------------
+This page contains a table displaying all Delivery Services 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
+
+ .. seealso:: :ref:`ds-types`
+
+:Protocol: The protocol which which this Delivery Service serves clients. Its value is one of:
+
+ HTTP
+ Only insecure requests will be serviced
+ HTTPS
+ Only secure requests will be serviced
+ HTTP and HTTPS
+ Both secure and insecure requests will be serviced
+ 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:
+
+ 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)
+ IGNORE
+ The query string will *not* be used in the ATS '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
+
+ .. 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
- manage steering targets
-
-.. _tp-delivery-service-requests:
-
Delivery Service Requests
-+++++++++++++++++++++++++
-
-A table of your delivery service requests with the following columns:
-
-.. image:: ./images/tp_table_ds_requests.png
-
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+======================================================================================================================+
-| Delivery Service | A unique string that identifies the delivery service that the request is associated with. |
-| | This unique string is also known as delivery service key or XML ID. |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Type | The type of delivery service request: |
-| | |
-| | - create (a request to create a new delivery service) |
-| | - update (a request to update an existing delivery service) |
-| | - delete (a request to delete an existing delivery service) |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Status | The status of the delivery service request: |
-| | |
-| | - draft (the delivery service request is NOT ready for review and fulfillment) |
-| | - submitted (the delivery service request is ready for review and fulfillment) |
-| | - rejected (the delivery service request has been rejected and cannot be modified) |
-| | - pending (the delivery service request has been fulfilled but the changes have yet to be deployed) |
-| | - 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. |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Last Edited By | The last user to edit the delivery service request. |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Created | Relative time indicating when the delivery service was created. |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Actions | Actions that can be performed on a delivery service request: |
-| | |
-| | - fulfill (Implement the changes captured in the delivery service request.) |
-| | - reject (Reject the changes captured in the delivery service request.) |
-| | - delete (Delete the delivery service request.) |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
+-------------------------
+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.
+
+: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:
+
+ draft
+ The Delivery Service Request is *not* ready for review and fulfillment
+ submitted
+ The Delivery Service Request is ready for review and fulfillment
+ rejected
+ The Delivery Service Request has been rejected and cannot be modified
+ pending
+ The Delivery Service Request has been fulfilled but the changes have yet to be deployed
+ 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
+: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:
+
+ fulfill
+ Implement the changes captured in the Delivery Service Request
+ reject
+ Reject the changes captured in the Delivery Service Request
+ delete
+ Delete the Delivery Service Request
Delivery service request management includes the ability to (where applicable):
@@ -369,45 +236,35 @@ Delivery service request management includes the ability to (where applicable):
- fulfill a delivery service request
- complete a delivery service request
-See :ref:`ds_requests` for details.
+.. seealso:: :ref:`ds_requests`
Configure
=========
+Interfaces for managing the various components of Traffic Control and how they interact are grouped under 'Configure'.
-.. image:: ./images/tp_menu_configure.png
+.. figure:: ./images/tp_menu_configure.png
+ :align: center
+ :alt: The 'Configure' Menu
-.. _tp-servers:
+ The 'Configure' Menu
Servers
-+++++++
-
-A table of servers with the following columns:
-
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+======================================================================================================================+
-| UPD | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Host | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Domain | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| IP | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| IPv6 | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Status | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Type | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Profile | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| CDN | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Cache Group | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| ISO | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
+-------
+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)
+:Cache Group: The name of the 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
+
+ .. seealso:: `Hewlett Packard ILO Wikipedia Page <https://en.wikipedia.org/wiki/HP_Integrated_Lights-Out>`_
Server management includes the ability to (where applicable):
@@ -417,30 +274,21 @@ Server management includes the ability to (where applicable):
- queue/clear updates on a server
- update server status
- view server delivery services
-- view server config files
+- view server configuration files
- clone delivery service assignments
- assign delivery services to server
-.. _tp-profiles:
Profiles
-++++++++
-
-A table of profiles with the following columns:
-
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+======================================================================================================================+
-| Name | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Type | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Routing Disabled | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Description | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| CDN | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
+--------
+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):
@@ -453,24 +301,19 @@ Profile management includes the ability to (where applicable):
- view profile delivery services
- view profile servers
-See :ref:`rl-working-with-profiles` for details.
+.. seealso:: :ref:`working-with-profiles`
-.. _tp-parameters:
Parameters
-++++++++++
-
-A table of parameters with the following columns:
+----------
+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 | Description |
-+===============================+======================================================================================================================+
-| Name | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Config File | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Value | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
+: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
Parameter management includes the ability to (where applicable):
@@ -479,22 +322,16 @@ Parameter management includes the ability to (where applicable):
- delete an existing parameter
- view parameter profiles
-.. _tp-types:
-Types
-+++++
+.. _tp-configure-types:
-A table of types with the following columns:
+Types
+-----
+'Types' groups Delivery Services, servers and Cache Groups for various purposes. Each entry in the table shown on this page has the following fields:
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+======================================================================================================================+
-| Name | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Use In Table | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
-| Description | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------------+
+: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
Type management includes the ability to (where applicable):
@@ -505,20 +342,13 @@ Type management includes the ability to (where applicable):
- view servers assigned to a type
- view cache groups assigned to a type
-.. _tp-statuses:
Statuses
-++++++++
-
-A table of statuses with the following columns:
+--------
+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 | Description |
-+===============================+=====================================================================================================================+
-| Name | |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
-| Description | |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
+:Name: The name of this status
+:Description: A short, usually user-defined, description of this status
Status management includes the ability to (where applicable):
@@ -527,31 +357,25 @@ Status management includes the ability to (where applicable):
- delete an existing status
- view status servers
+
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.
-.. image:: ./images/tp_menu_topology.png
+.. figure:: ./images/tp_menu_topology.png
+ :align: center
-.. _tp-cache-groups:
+ 'Topology' Menu
Cache Groups
-++++++++++++
-
-A table of cache groups with the following columns:
-
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+=====================================================================================================================+
-| Name | |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
-| Short Name | |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
-| Type | |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
-| Latitude | |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
-| Longitude | |
-+-------------------------------+---------------------------------------------------------------------------------------------------------------------+
+------------
+'Cache Groups' are sets of cache servers, typically grouped by geographic proximity. This menu allows user to add or remove caches from Cache Groups as well as creating, updating and deleting Cache Groups themselves. Each entry in the table of Cache Groups on this page has the following fields:
+
+:Name: The full name of this Cache Group
+:Short Name: A shorter, more human-friendly name for this Cache Group
+:Type: The Type of this Cache Group (see :ref:`tp-configure-types`)
+:Latitude: A geographic latitude assigned to this Cache Group
+:Longitude: A geographic longitude assigned to this Cache Group
Cache group management includes the ability to (where applicable):
@@ -563,28 +387,32 @@ Cache group management includes the ability to (where applicable):
- view and assign cache group parameters
- view cache group servers
-.. _tp-phys-locations:
+
+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:
+
+:Name: The name of this coordinate pair
+:Latitude: The geographic latitude part of the coordinate pair
+:Longitude: The geographic longitude part of the coordinate pair
+
+Coordination management includes the ability to (where applicable):
+
+- create a new coordinate pair
+- update an existing coordinate pair
+- delete an existing coordinate pair
+
Phys Locations
-++++++++++++++
-
-A table of physical locations with the following columns:
-
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+===================================================================================================================+
-| Name | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
-| Short Name | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
-| Address | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
-| City | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
-| State | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
-| Region | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
+--------------
+A table of physical locations which may be assigned to servers and Cache Groups, typically for the purpose of optimizing client routing. Here they can be created, updated deleted and assigned. 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
Physical location management includes the ability to (where applicable):
@@ -593,62 +421,37 @@ Physical location management includes the ability to (where applicable):
- delete an existing physical location
- view physical location servers
-.. _tp-divisions:
Divisions
-+++++++++
-
-A table of divisions with the following columns:
+---------
+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:
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+===================================================================================================================+
-| Name | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------------+
+:Name: The name of the Division
Division management includes the ability to (where applicable):
-- create a new division
-- update an existing division
-- delete an existing division
-- view division regions
-
-.. _tp-regions:
Regions
-+++++++
+-------
+Regions are groups of Cache Groups, and are themselves grouped into Divisions. Each entry in the table on this page has the following fields:
-A table of regions with the following columns:
-
-+-------------------------------+------------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+==================================================================================================================+
-| Name | |
-+-------------------------------+------------------------------------------------------------------------------------------------------------------+
-| Division | |
-+-------------------------------+------------------------------------------------------------------------------------------------------------------+
+:Name: The name of this Region
+:Division: The Division to which this Region is assigned
Region management includes the ability to (where applicable):
-- create a new region
-- update an existing region
-- delete an existing region
-- view region physical locations
+- create a new Region
+- update an existing Region
+- delete an existing Region
+- view Region physical locations
-.. _tp-asns:
ASNs
-++++
-
-A table of ASNs with the following columns:
+----
+Manage Autonomous System Numbers (ASNs). Each entry in the table on this page has the following fields:
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+=================================================================================================================+
-| ASN | |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------+
-| Cache Group | |
-+-------------------------------+-----------------------------------------------------------------------------------------------------------------+
+:ASN: The actual ASN
+:Cache Group: The Cache Group to which this ASN is assigned
ASN management includes the ability to (where applicable):
@@ -656,68 +459,96 @@ ASN management includes the ability to (where applicable):
- update an existing ASN
- delete an existing ASN
+.. seealso:: `Autonomous System (Internet) Wikipedia Page <https://en.wikipedia.org/wiki/Autonomous_system_(Internet)>`_
+
+
Tools
=====
-.. image:: ./images/tp_menu_tools.png
+.. figure:: ./images/tp_menu_tools.png
+ :align: center
+ :alt: The 'Tools' Menu
+
+ The 'Tools' Menu
-.. _tp-jobs:
+'Tools' contains various tools that don't directly relate to manipulating Traffic Control components or their groupings.
Invalidate Content
-++++++++++++++++++
-
-A table of invalidate content jobs with the following columns:
-
-+-------------------------------+----------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+================================================================================================================+
-| Delivery Service | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------+
-| Asset URL | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------+
-| Parameters | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------+
-| Start | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------+
-| Created By | |
-+-------------------------------+----------------------------------------------------------------------------------------------------------------+
+------------------
+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:
+
+:Delivery Service: The 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
+: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
Invalidate content includes the ability to (where applicable):
- create a new invalidate content job
-.. _tp-gen-iso:
-
Generate ISO
-++++++++++++
+------------
+Generates a boot-able system image for any of the servers in the Servers table (or any server for that matter). Currently it only supports CentOS 6 or 7, but if you're brave and pure of heart you MIGHT be able to get it to work with other Unix-like Operating Systems. The interface is *mostly* self-explanatory, but here is a short explanation of the fields in that form.
+
+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
+Hostname
+ The desired hostname of the resultant system
+Domain
+ The desired domain name of the resultant system
+DHCP
+ If this is 'no' the IP settings of the system must be specified, and the following extra fields will appear:
+
+ IP Address
+ The resultant system's IPv4 Address
+ Network Subnet
+ The system's network subnet mask
+ Network Gateway
+ 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
+
+ .. seealso:: `The Maximum transmission unit Wikipedia Page <https://en.wikipedia.org/wiki/Maximum_transmission_unit>`_
+
+Disk for OS Install
+ The disk on which to install the base system. A reasonable default is ``sda`` (the ``/dev/`` prefix is not necessary)
+Root Password
+ The password to be used for the root user. Input is MD5 hashed before being written to disk
+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
+
+ .. 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'.
-See :ref:`rl-generate-iso`
User Admin
==========
-.. image:: ./images/tp_menu_user_admin.png
+This section offers administrative functionality for users and their permissions.
-.. _tp-users:
+.. figure:: ./images/tp_menu_user_admin.png
+ :align: center
+ :alt: The 'User Admin' Menu
-Users
-+++++
+ The 'User Admin' Menu
-A table of users with the following columns:
+User
+----
+This page lists all the users that are visible to the user (so, for 'admin' users, all users will appear here). Each entry in the table on this page has the following fields:
-+-------------------------------+--------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+==============================================================================================================+
-| Full Name | |
-+-------------------------------+--------------------------------------------------------------------------------------------------------------+
-| Username | |
-+-------------------------------+--------------------------------------------------------------------------------------------------------------+
-| Email | |
-+-------------------------------+--------------------------------------------------------------------------------------------------------------+
-| Tenant | |
-+-------------------------------+--------------------------------------------------------------------------------------------------------------+
-| Role | |
-+-------------------------------+--------------------------------------------------------------------------------------------------------------+
+: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
User management includes the ability to (where applicable):
@@ -726,22 +557,14 @@ User management includes the ability to (where applicable):
- update an existing user
- view delivery services visible to a user
-.. _tp-tenants:
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:
-A table of tenants with the following columns:
-
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+=============================================================================================================+
-| Name | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
-| Active | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
-| Parent | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
+: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.
Tenant management includes the ability to (where applicable):
@@ -751,50 +574,35 @@ Tenant management includes the ability to (where applicable):
- view users assigned to a tenant
- view delivery services assigned to a tenant
-.. _tp-roles:
-
Roles
-+++++
-
-A table of roles with the following columns:
+-----
+'Roles' grant a user permissions to do certain things. Each entry in the table on this page has the following fields:
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
-| Name | Description |
-+===============================+=============================================================================================================+
-| Name | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
-| Privilege Level | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
-| Description | |
-+-------------------------------+-------------------------------------------------------------------------------------------------------------+
+: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
Role management includes the ability to (where applicable):
- view all roles
+- create new roles
+
+.. note:: Roles cannot be deleted through the Traffic Portal UI
Other
=====
+Custom menu items. By default, this contains only a link to the Traffic Control documentation.
-.. image:: ./images/tp_menu_other.png
-
-.. _tp-menu-other:
-
-Custom Menu Items
-+++++++++++++++++
-
-This section is configurable in tp.domain.com/traffic_portal_properties.json in the customMenu section.
-
-
-
-
-
-
-
-
-
-
-
-
+.. figure:: ./images/tp_menu_other.png
+ :align: center
+ :alt: The 'Other' Menu
+ The 'Other' Menu
+Docs
+----
+This is just a link to `the Traffic Control Documentation <https://trafficcontrol.apache.org>`_.
+Custom Menu Items
+-----------------
+This section is configurable in the ``tp.domain.com/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 7250c78c8..8f7d17322 100644
--- a/docs/source/admin/traffic_router.rst
+++ b/docs/source/admin/traffic_router.rst
@@ -17,118 +17,130 @@
Traffic Router Administration
*****************************
.. contents::
- :depth: 2
- :backlinks: top
+ :depth: 2
+ :backlinks: top
Installing Traffic Router
==========================
The following are requirements to ensure an accurate set up:
* CentOS 7
-* 4 vCPUs
-* 8GB RAM
-* Successful install of Traffic Ops
-* Successful install of Traffic Monitor
+* 4 CPUs
+* 8GB of RAM
+* Successful install of Traffic Ops (usually on another machine)
+* Successful install of Traffic Monitor (usually on another machine)
* Administrative access to Traffic Ops
-.. Note:: Hardware requirements are generally doubled if DNSSEC is enabled
+.. Note:: Hardware requirements are generally doubled if :ref:`tr-DNSSEC` is enabled
-1. If no suitable profile exists, create a new profile for Traffic Router.
+#. If no suitable profile exists, create a new profile for Traffic Router ('Configure' -> 'Profiles' -> '+').
-2. Enter the Traffic Router server into Traffic Ops, assign it to a Traffic Router profile, and ensure that its status is set to ``ONLINE``.
-3. Ensure the FQDN of the Traffic Router is resolvable in DNS. This FQDN must be resolvable by the clients expected to use this CDN.
-4. Install a traffic router: ``sudo yum install traffic_router``.
+ .. 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.
-.. 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 in your package repository.
+#. 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``).
-5. Edit ``/opt/traffic_router/conf/traffic_monitor.properties`` and specify the correct online Traffic Monitor(s) for your CDN. See :ref:`rl-tr-config-files`
- # traffic_monitor.properties: url that should normally point to this file
- traffic_monitor.properties=file:/opt/traffic_router/conf/traffic_monitor.properties
+ .. 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.
- # Frequency for reloading this file
- # traffic_monitor.properties.reload.period=60000
+#. Edit ``/opt/traffic_router/conf/traffic_monitor.properties`` and specify the correct online Traffic Monitor(s) for your CDN. See :ref:`tr-config-files`
+ :traffic_monitor.properties: URL that should normally point to this file. e.x. ``traffic_monitor.properties=file:/opt/traffic_router/conf/traffic_monitor.properties``
-6. Start Traffic Router: ``sudo systemctl start traffic_router``, and test lookups with dig and curl against that server.
- To restart, ``sudo systemctl stop traffic_router``, kill the traffic router process, and ``sudo systemctl restart traffic_router``
- Also, crconfig previously recieved will be cached, and needs to be removed manually to actually be reloaded /opt/traffic_router/db/cr-config.json
-7. Snapshot CRConfig; See :ref:`rl-snapshot-crconfig`
+ :traffic_monitor.properties.reload.period: Period to wait (in milliseconds) between reloading this file. e.x. ``traffic_monitor.properties.reload.period=60000``
-.. Note:: Once the CRConfig is snapshotted, live traffic will be sent to the new Traffic Routers provided that their status is set to ``ONLINE``.
-8. Ensure that the parent domain (e.g.: kabletown.net) for the CDN's top level domain (e.g.: cdn.kabletown.net) contains a delegation (NS records) for the new Traffic Router, and that the value specified matches the FQDN used in step 3.
+#. 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``.
+
+#. Snapshot CRConfig; See :ref:`snapshot-crconfig`
+
+ .. 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``.
+
+#. 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.
Configuring Traffic Router
==========================
-.. 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.
.. 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.
-.. Note:: Pre-existing installations having configuration files in ``/opt/traffic_router/conf`` will still be used and honored for Traffic Router 1.5 and onward.
+.. 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.
+
+.. 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.
-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 is mostly performed in Traffic Ops, and is distributed throughout Traffic Control via the CRConfig snapshot process. See :ref:`rl-snapshot-crconfig` for more information. Please see the parameter documentation for Traffic Router in the Using Traffic Ops guide documented under :ref:`rl-ccr-profile` for parameters that influence the behavior of Traffic Router via the CRConfig.
+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 Router in the Using Traffic Ops guide documented under :ref:`ccr-profile` for parameters that influence the behavior of Traffic Router via the CRConfig.
-.. _rl-tr-config-files:
+.. _tr-config-files:
Configuration files
-------------------
-+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| File name | Parameter | Description | Default Value |
-+============================+===========================================+=====================================================================================================+===================================================+
-| traffic_monitor.properties | traffic_monitor.bootstrap.hosts | Traffic Monitor FQDNs and port if necessary, separated by a semicolon (;) | N/A |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | traffic_monitor.bootstrap.local | Use only the Traffic Monitors specified in config file | false |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | traffic_monitor.properties | Path to the traffic_monitor.properties file; used internally to monitor the file for changes | /opt/traffic_router/traffic_monitor.properties |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | traffic_monitor.properties.reload.period | The interval in milliseconds which Traffic Router will reload this configuration file | 60000 |
-+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| 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 auto generated zone files for reference | /opt/traffic_router/var/auto-zones |
-+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| traffic_ops.properties | traffic_ops.username | Username 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 the MaxMind geolocation binary database file | /opt/traffic_router/db/GeoIP2-City.mmdb |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | cache.geolocation.database.refresh.period | The interval in milliseconds which Traffic Router will poll for a new geolocation database | 604800000 |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | 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 which Traffic Router will poll for a new coverage zone file | 10800000 |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | 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 which Traffic Router will poll for a new deep coverage zone file | 10800000 |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | 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 file | 1000 |
-| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| | 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 traffic_router | |
-| | | service is started. It primarily consists of command line settings for the Java process. | N/A |
-+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| log4j.properties | various parameters | Configuration of log4j is documented on their site; adjust as necessary based on needs | N/A |
-+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| server.xml | various parameters | Traffic Router specific configuration for Apache Tomcat. See Apache Tomcat documentation. | N/A |
-+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-| web.xml | various parameters | Default settings for all Web Applications running in the Traffic Router instance of Tomcat. | N/A |
-+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+
-
-.. _rl-tr-dnssec:
++----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
+| 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 | |
++----------------------------+-------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------+
+
+.. _tr-dnssec:
DNSSEC
======
@@ -139,64 +151,63 @@ Domain Name System Security Extensions (DNSSEC) is a set of extensions to DNS th
Several RFCs (4033, 4044, 4045) describe the low level details and define the extensions, RFC 7129 provides clarification around authenticated denial of existence of records, and finally RFC 6781 describes operational best practices for administering an authoritative DNSSEC enabled DNS server. The authenticated denial of existence RFC describes how an authoritative DNS server responds in NXDOMAIN and NODATA scenarios when DNSSEC is enabled.
-Traffic Router currently supports DNSSEC with NSEC, however, NSEC3 and more configurable options will be provided in the future.
+Traffic Router currently supports DNSSEC with NSEC, however, NSEC3 and more configurable options are planned for the future.
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 subdomain off 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 TTL to use for the DNSKEY record(s). All TTLs are configurable parameters; see the :ref:`rl-ccr-profile` documentation for more information.
+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 for the DNSKEY record(s). All TTLs are configurable parameters; see the :ref:`ccr-profile` documentation for more information.
-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.cdn.kabletown.net) 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.: cdn.kabletown.net); the DS record for the CDN TLD must be placed in its parent zone, which is not managed by Traffic Control.
+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 must be placed in its parent zone, which is not managed by Traffic Control.
-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.: kabletown.net), which is not managed by Traffic Control**. As such, the DS record (available in the Traffic Ops DNSSEC administration UI) 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, this might be a manual process or it might be automated; either way, extreme care and diligence must be taken and knowledge of the management of the upstream zone is imperative for a successful DNSSEC deployment.
+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, this might be a manual process or it might be automated. Either way, extreme care and diligence must be taken and knowledge of the management of the upstream zone is imperative for a successful DNSSEC deployment.
+
+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.
Rolling Zone Signing Keys
-------------------------
-Traffic Router currently follows the zone signing key pre-publishing operational best practice described in `section 4.1.1.1 of RFC 6781`_. Once DNSSEC is enabled for a CDN in Traffic Ops, key rolls are triggered via 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 in Traffic Ops.
+Traffic Router currently follows the zone signing key pre-publishing operational best practice described in `section 4.1.1.1 of RFC 6781`_. Once DNSSEC is enabled for a CDN in Traffic Portal, key rolls are triggered by Traffic Ops via the automated key generation process, and Traffic Router selects the active zone signing keys based on the expiration information returned from the 'keystore' API of Traffic Ops.
.. _section 4.1.1.1 of RFC 6781: https://tools.ietf.org/html/rfc6781#section-4.1.1.1
-Troubleshooting and log files
+Troubleshooting and Log Files
=============================
-Traffic Router log files are in ``/opt/traffic_router/var/log``. 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 ``/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``.
Event Log File Format
-=====================
+---------------------
Summary
--------
+"""""""
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)
+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>`_
---------------
+Message Format
+""""""""""""""
+- Except for the first item, each event that is logged is a series of space-separated key/value pairs.
+- The first item is always the Unix epoch in seconds with a decimal field precision of up to milliseconds.
+- Each key/value pair is in the form of ``unquoted_string="optionally quoted string"``
+- Values that are quoted strings may contain whitespace characters.
+- Values that are not quoted should not contains any whitespace characters.
+
+.. Note:: Any value that is a single dash character or a dash character enclosed in quotes represents an empty value
Sample Message
---------------
+""""""""""""""
-Items within brackets below 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
-**Message Format**
-- Each event that is logged is a series of space separated key value pairs except for the first item.
-- The first item is always the epoch in seconds with a decimal field precision of up to milliseconds
-- Each key value pair is in the form of unquoted string, equals character, optionally quoted string
-- Values that are quoted strings may contain space characters
-- Values that are not quoted should not contains any space characters
-
-.. Note:: Any value that is a single dash character or a dash character enclosed in quotes represents an empty value
-
---------
Fields Always Present
----------------------
+"""""""""""""""""""""
+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
|Name |Description |Data |
@@ -217,71 +228,63 @@ Fields Always Present
+------+---------------------------------------------------------------------------------+------------------------------------------------------------------------------------+
-**rtype meanings**
-
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|Name |Meaning |
-+=============+========================================================================================================================================================================+
-|ERROR |An internal error occurred within Traffic Router, more details may be found in the rerr field |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|CZ |The result was derived from Coverage Zone data based on the address in the chi field |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|DEEP_CZ |The result was derived from Deep Coverage Zone data based on the address in the chi field |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|GEO |The result was derived from geolocation service based on the address in the chi field |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|MISS |Traffic Router was unable to resolve a DNS request or find a cache for the requested resource |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|STATIC_ROUTE |_*DNS Only*_ No DNS Delivery Service supports the hostname portion of the requested url |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|DS_MISS |_*HTTP Only*_ No HTTP 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|
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|FED |_*DNS Only*_ The result was obtained through federated coverage zone data outside of any delivery service |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|GEO_REDIRECT |The request was redirected (302) based on the National Geo blocking (Geo Limit Redirect URL) configured on the Delivery Service. |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|RGALT |The request was redirected (302) to the Regional Geo blocking 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. |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|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. |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| "-" |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. |
-+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
-
-**rdtl meanings**
-
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|Name |Meaning |
-+=======================================+============================================================================================================================================+
-|DS_NOT_FOUND |Always goes with rtypes STATIC_ROUTE and DS_MISS |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|DS_BYPASS |Used Bypass Destination for Redirect of Delivery Service |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|DS_NO_BYPASS |No valid Bypass Destination is configured for the matched Delivery Service and the delivery service does not have the requested resource |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|DS_CZ_ONLY |The selected Delivery Service only supports resource lookup based on Coverage Zone data |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|DS_CLIENT_GEO_UNSUPPORTED |Traffic Router did not find a resource supported by coverage zone data and was unable to determine the geolocation of the requesting client |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|GEO_NO_CACHE_FOUND |Traffic Router could not find a resource via geolocation data based on the requesting client's geolocation |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|NO_DETAILS |This entry is for a standard request. |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|REGIONAL_GEO_ALTERNATE_WITHOUT_CACHE |This goes with the rtype RGDENY. The URL is being regionally Geo blocked. |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-|REGIONAL_GEO_NO_RULE |The request was blocked because there was no rule in the Delivery Service for the request. |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
-| "-" |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_CZ_BACKUP_CG |Traffic Router found a backup cache via fallback (cr-config's edgeLocation) / coordinates (CZF) configuration |
-+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
+``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
+
+:CZ: The result was derived from Coverage Zone data based on the address in the ``chi`` field
+
+: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
+
+: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
+
+: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
+
+:GEO: The result was derived from geolocation service based on the address in the ``chi`` field
+
+:GEO_REDIRECT: The request was redirected (302) based on the National Geo blocking (Geo Limit Redirect URL) configured on the 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 (302) to the Regional Geo blocking 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
+
+: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
+
+:STATIC_ROUTE: _*DNS Only*_ No DNS 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
+
+: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
+
+:DS_CZ_ONLY: The selected 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
+
+:DS_NOT_FOUND: Always goes with ``rtypes`` STATIC_ROUTE and DS_MISS
+
+:GEO_NO_CACHE_FOUND: Traffic Router could not find a resource via geographic location data based on the requesting client's location
+
+:NO_DETAILS: This entry is for a standard request
+
+: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
----------------
HTTP Specifics
--------------
@@ -291,27 +294,27 @@ 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"
-**Request Fields**
+.. table:: Request Fields
-+-----+-----------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------+
-|Name |Description |Data |
-+=====+=========================================================================================================================================+===========================================+
-|url |Requested URL with query string |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 Delivery Service |Key/value pair of the format ``name: value`` |
+ +-----+-----------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------+
-**Response Fields**
+.. table:: Response Fields
-+-----+----------------------------------------------------------+------------+
-|Name |Description |Data |
-+=====+==========================================================+============+
-|rurl |The resulting url of the resource requested by the client |A URL String|
-+-----+----------------------------------------------------------+------------+
+ +-----+----------------------------------------------------------+------------+
+ |Name |Description |Data |
+ +=====+==========================================================+============+
+ |rurl |The resulting URL of the resource requested by the client |A URL String|
+ +-----+----------------------------------------------------------+------------+
------------
@@ -323,72 +326,77 @@ 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"
-**Request Fields**
-
.. _qname: http://www.zytrax.com/books/dns/ch15/#qname
.. _qtype: http://www.zytrax.com/books/dns/ch15/#qtype
-+------+------------------------------------------------------------------+--------------------------------------------------------+
-|Name |Description |Data |
-+======+==================================================================+========================================================+
-|xn |The ID from the client DNS request header |a number from 0 to 65535 |
-+------+------------------------------------------------------------------+--------------------------------------------------------+
-|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) |
-+------+------------------------------------------------------------------+--------------------------------------------------------+
-
-**Response Fields**
-
-+------+---------------------------------------------------------------------+-----------------------------------------------------+
-|Name | Description | Data |
-+======+=====================================================================+=====================================================+
-|ttl | The 'time to live' in seconds for the answer provided by Traffic |A number from 0 to 4294967295 |
-| | Router (clients can reliably use this answer for this long without | |
-| | re-querying traffic router) | |
-+------+---------------------------------------------------------------------+-----------------------------------------------------+
-|rcode | The result code for the DNS answer provided by Traffic Router | One of NOERROR (success), NOTIMP (request is not |
-| | | NOTIMP (request is not supported), |
-| | | REFUSED (request is refused to be answered), or |
-| | | NXDOMAIN (the domain/name requested does not exist) |
-+------+---------------------------------------------------------------------+-----------------------------------------------------+
-
-.. _rl-tr-ngb:
-
-GeoLimit Failure Redirect feature
+.. 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) |
+ +------+------------------------------------------------------------------+--------------------------------------------------------+
+
+.. table:: Response Fields
+
+ +------+---------------------------------------------------------------------+-----------------------------------------------------+
+ |Name | Description | Data |
+ +======+=====================================================================+=====================================================+
+ |ttl | The 'time to live' in seconds for the answer provided by Traffic |A whole number between 0 and 4294967295 (inclusive) |
+ | | Router (clients can reliably use this answer for this long without | |
+ | | re-querying traffic router) | |
+ +------+---------------------------------------------------------------------+-----------------------------------------------------+
+ |rcode | The result code for the DNS answer provided by Traffic Router | One of NOERROR (success), NOTIMP (request is not |
+ | | | NOTIMP (request is not supported), |
+ | | | REFUSED (request is refused to be answered), or |
+ | | | NXDOMAIN (the domain/name requested does not exist) |
+ +------+---------------------------------------------------------------------+-----------------------------------------------------+
+
+.. _tr-ngb:
+
+GeoLimit Failure Redirect Feature
=================================
Overview
--------
-This feature is also called 'National GeoBlock' feature which is short for 'NGB' feature. In this section, the acronym 'NGB' will be used for this feature.
-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 return 503 response; but with this feature, when the check fails, it will return 302 if the redirect url is set in the delivery service.
+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.
-The Geolimit check failure has such scenarios:
-1) When the GeoLimit is set to 'CZF + only', if the client ip is not in the the CZ file, the check fails
-2) When the GeoLimit is set to any region, like 'CZF + US', if the client ip is not in such region, and the client ip is not in the CZ file, the check fails
+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. And the setting lays at 'Delivery Services'->Edit->'GeoLimit Redirect URL'. If no url is put in this field, the feature is disabled.
+
+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.
The URL has 3 kinds of formats, which have different meanings:
-1. URL with no domain. If no domain is in the URL (like 'vod/dance.mp4'), the router will try to find a proper cache server within the delivery service and return the redirect url with the format like 'http://[cache server name].[delivery service's FQDN]/[configured relative path]'
+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]``
-2. URL with domain that matches with the delivery service. For this URL, the router will also try to find a proper cache server within the delivery service and return the same format url as point 1.
+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]``
-3. URL with domain that doesn't match with the delivery service. For this URL, the router will return the configured url directly to the client.
+URL with domain that doesn't match with the Delivery Service
+ Traffic Router will return the configured URL directly to the client.
-.. _rl-deep-cache:
+.. _deep-cache:
Deep Caching - Deep Coverage Zone Topology
==========================================
@@ -396,145 +404,120 @@ Deep Caching - Deep Coverage Zone Topology
Overview
--------
-Deep Caching is a feature that enables clients to be routed to the closest
-possible "deep" edge caches on a per Delivery Service basis. The term "deep" is
-used in the networking sense, meaning that the edge caches are located deep in
-the network where the number of network hops to a client is as minimal as
-possible. 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 outweighs the cost of adding storage. While it
-may not be feasible to cache an entire copy of the CDN's contents in every deep
-location (for the best possible bandwidth savings), storing just a relatively
-small amount of the CDN's most requested content can lead to very high bandwidth
-savings.
-
-Getting started
+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 outweighs the cost of adding storage. While it may not be feasible to cache an entire copy of the CDN's contents in every deep location (for the best possible bandwidth savings), storing just a relatively small amount of the CDN's most requested content can lead to very high bandwidth savings.
+
+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:`rl-deep-czf` for details)
-#. Deep caching parameters in the Traffic Router Profile (see :ref:`rl-ccr-profile` for details):
+#. A Deep Coverage Zone File (DCZF) 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. ``deepCachingType`` = ALWAYS)
+#. 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)
-How it works
+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 DC (Deep Caching) 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 will "fall back" to the regular CZF and
-continue regular CZF routing from there.
+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 will fall back to the regular CZF and continue regular CZF routing from there.
-.. _rl-tr-steering:
+.. _tr-steering:
-Steering feature
+Steering Feature
================
Overview
--------
-A Steering delivery service is a delivery service that is used to "steer" traffic to other delivery services. 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 is separate from the consistent hash ring used in cache selection.
-
-Special regular expressions called 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 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 is separate from the consistent hash ring used in cache selection.
-A client can bypass the steering functionality by providing a header called X-TC-Steering-Option with the xml_id of the target delivery service to route to. When Traffic Router receives this header it will route to the requested target delivery service regardless of weight configuration.
+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.
Some other points of interest:
-- 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. This API is used by a Steering user to add filters and modify assignments. (Filters can only be added via the API).
+- 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.
- 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:
+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 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.
+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 weight configuration. This header is ignored by STEERING Delivery Services.
+
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 is created in Traffic Ops.
-#. Target delivery services are assigned to the steering delivery service using Traffic Ops.
+#. 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.
#. A user with the role of Steering is created.
-#. Using the API, 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 Delivery Services.
+#. If desired, the Steering user can create filters for the target Delivery Services.
-For more information see the `steering how-to guide <quick_howto/steering.html>`_.
+For more information see the `Steering how-to guide <quick_howto/steering.html>`_.
-HTTPS for Http Type Delivery Services
-=====================================
+HTTPS for HTTP Delivery Services
+================================
-Starting with version 1.7 Traffic Router added the ability to allow https traffic between itself and clients on a per http type 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 some decrease in performance if you wish to support a lot of HTTPS traffic.
- As noted for DNSSEC, you may need to plan to scale Traffic Router vertically and/or horizontally to handle the new load
+.. 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 some decrease in performance if you wish to support a lot of HTTPS traffic. As noted for DNSSEC, you may need to plan to scale Traffic Router vertically and/or horizontally to handle the new load.
-The summary for setting up https is to:
+The HTTPS set up process is:
-#. Select one of 'https', 'http and https', or '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 Delivery Service
+#. Generate private keys for the Delivery Service using a wildcard domain such as ``*.my-delivery-service.my-cdn.example.com``
#. Obtain and import signed certificate chain
-#. Snapshot CR Config
+#. Snapshot CRConfig
-Clients may make HTTPS requests delivery services only after Traffic Router receives the certificate chain from Traffic Ops and the new CR Config.
+Clients may make HTTPS requests to Delivery Services only after Traffic Router receives the certificate chain from Traffic Ops and the new CRConfig.
Protocol Options
----------------
-*https only*
- Traffic Router will only redirect (send a 302) to clients communicating with a secure connection, all other clients will receive a 503
-*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 and a location that is secure (i.e. starting with 'https' instead of 'http'), secure clients will remain on https
-*http*
- Any secure client will get an SSL handshake error. Non-secure clients will experience the same behavior as prior to 1.7
+HTTP
+ Any secure client will get an SSL handshake error. Non-secure clients will experience the same behavior as prior to 1.7
+HTTPS
+ Traffic Router will only redirect (send a ``302 Found`` response) to clients communicating with a secure connection, all other clients will receive a ``503 Service Unavailable`` response
+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.
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 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.
Traffic Router fetches certificates into memory:
* At startup time
-* When it receives a new CR Config
-* Once an hour from whenever the most recent of the last of the above occurred
+* When it receives a new CRConfig
+* Once an hour starting whenever the most recent of the last of the above occurred
-.. Note::
- To adjust the frequency when Traffic Router fetches certificates add the parameter 'certificates.polling.interval' to CR Config and
- setting it to the desired time in milliseconds.
+.. 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::
- Taking a snapshot of CR Config may be used at times to avoid waiting the entire polling cycle for a new set of certificates.
+.. Note:: Taking a snapshot of CRConfig may be used at times to avoid waiting the entire polling cycle for a new set of certificates.
-.. Warning::
- If a snapshot of CR Config is made that involves a delivery service missing its certificates, Traffic Router will ignore **ALL** changes in that CR-Config
- until one of the following occurs:
- * It receives certificates for that delivery service
- * Another snapshot of CR Config is created and the delivery service without certificates is changed so it's HTTP protocol is set to 'http'
+.. 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:
+
+ * 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'
Certificate Chain Ordering
--------------------------
@@ -543,53 +526,69 @@ 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 CA (optional)
+#. Root Certificate from a Certificate Authority (CA) (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.
+.. 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 ``openssl`` on each individual certificate
Suggested Way of Setting up an HTTPS Delivery Service
-----------------------------------------------------
-Do the following in Traffic Ops:
-
-#. Select one of 'https', 'http and https', or 'http to https' for the protocol field of a delivery service and click 'Save'.
-#. Click 'Manage SSL Keys'.
-#. Click 'Generate New Keys'.
-#. Copy the contents of the Certificate Signing Request field and save it locally.
-#. Click 'Load Keys'.
-#. Select 'http' for the protocol field of the delivery service and click 'Save' (to avoid preventing other CR Config updates from being blocked by Traffic Router)
-#. Follow your standard procedure for obtaining your signed certificate chain from a CA.
-#. 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'.
-#. Click 'Paste Existing Keys'.
-#. Paste the certificate chain into the CRT field.
-#. Click 'Load Keys'.
-#. Take a new snapshot of CR Config.
-
-Once this is done you should be able to test you are getting correctly redirected by Traffic Router using curl commands to https destinations on your delivery service.
-
-A new testing tool was created for load testing traffic router, it allows you to generate requests from your local box to multiple delivery services of a single cdn.
-You can control which cdn, delivery services, how many transactions per delivery service, and how many concurrent requests.
-During the test it will provide feedback about request latency and transactions per second.
-
-While it is running it is suggested that you monitor your Traffic Router nodes for memory and CPU utilization.
+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
+#. 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
+#. 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'
+#. Paste your key information into the appropriate fields
+#. Click the green 'Update Keys' button
+#. Take a new snapshot of CRConfig
+
+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.
+
+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.
+
+There are 2 parts to the load test:
+
+* A web server that makes the actual requests and takes commands to fetch data from the CDN, start the test, and return current results.
+* A web page that's used to run the test and see the results.
+
+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
+#. 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``
+#. Using your web browser of choice, open the file ``test/router/index.html``
+#. 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
+#. 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
+#. 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 throughput for Traffic Router and reduced 'Stop the World' garbage collection. Note that any environment variable settings in this file will override those
-set in /lib/systemd/system/traffic_router.service.
+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 throughput for Traffic Router and reduced 'Stop the World' garbage collection. Note that any environment variable settings in this file will override those
+set in ``/lib/systemd/system/traffic_router.service``.
- /opt/traffic_router/conf/startup.properties::
+.. code-block:: bash
CATALINA_OPTS="\
-server -Xms2g -Xmx8g \
diff --git a/docs/source/admin/traffic_router/migrationto2-3.rst b/docs/source/admin/traffic_router/migrationto2-3.rst
index b3642a9e5..a4d5f7a98 100644
--- a/docs/source/admin/traffic_router/migrationto2-3.rst
+++ b/docs/source/admin/traffic_router/migrationto2-3.rst
@@ -51,14 +51,14 @@ The 'tomcat' package gets created when you build Traffic Router. You must either
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.
Update the traffic_router Package
-------------------------------
+---------------------------------
If openssl, apr, tomcat-native, jdk 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, jdk 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.
+This will first cause the apr, tomcat-native, jdk 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.
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 /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.
Development Environment Upgrade
===============================
diff --git a/docs/source/admin/traffic_server.rst b/docs/source/admin/traffic_server.rst
index 13ce92b72..373a559cb 100644
--- a/docs/source/admin/traffic_server.rst
+++ b/docs/source/admin/traffic_server.rst
@@ -19,131 +19,115 @@ Traffic Server Administration
Installing Traffic Server
=========================
-#. Build the Traffic Server RPM. The best way to do this is to follow the Traffic Server documents: ::
+#. 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>`_.
- https://docs.trafficserver.apache.org/en/latest/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: ::
+.. note:: The ``astats`` plugin is bundled as a part of Apache Traffic Server as of version 7.2.
- https://github.com/apache/trafficcontrol/tree/<version>/traffic_server
+#. Install Traffic Server and astats
- Sample link: ::
+ The easiest way to accomplish this is by running this command as the root user (or with ``sudo``):
- https://github.com/apache/trafficcontrol/tree/master/traffic_server
+ .. code-block:: bash
-#. Install Traffic Server and astats: ::
+ yum -y install trafficserver-*.rpm astats_over_http*.rpm
- sudo yum -y install trafficserver-*.rpm astats_over_http*.rpm
+#. Add the server using the Traffic Portal UI:
-#. Add the server using the Traffic Ops web interface:
+ #. Under 'Configure', select 'Servers'.
+ #. Click on the '+' 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.
+ #. Verify that the server status is now listed as **Reported**
- #. Select **Servers**.
- #. Scroll to the bottom of the page and click **Add Server**.
- #. Complete the "Required Info:" section:
- * Set 'Interface Name' to the name of the interface from which traffic server delivers content.
- * Set 'Type' to 'MID' or 'EDGE'.
- #. Click **Submit**.
- #. Click **Save**.
- #. Click **Online Server**.
- #. 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 ORT script and run it in 'badass' mode to create the initial configuration, see :ref:`reference-traffic-ops-ort`
+#. Start the service by running ``systemctl start trafficserver`` as the root user (or with ``sudo``)
-#. Start the service: ``sudo service trafficserver start``
+#. Configure traffic server to start automatically: ``sudo systemctl enable trafficserver``
-#. Configure traffic server to start automatically: ``sudo systemctl enable trafficserver``
+#. Verify that the installation is good:
-#. Verify that the installation is good:
+ #. Make sure that the service is running: ``sudo systemctl status trafficserver``
- #. Make sure that the service is running: ``sudo systemctl status 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.
- #. 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.
-
-.. _reference-traffic-ops-ort:
+.. _traffic-ops-ort:
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 should be installed on all caches (by puppet or other non Traffic Ops means), usually in /opt/ort. It is used to do the initial install of the config files when the cache is being deployed, and to keep the config files up to date when the cache is already in service. The usage message of the script is shown below: ::
+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: ::
+
+ $ 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.
- $ 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.
+ <Log_Level> => ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, NONE
- <Log_Level> => ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, NONE
+ <Traffic_Ops_URL> = URL to Traffic Ops host. Example: https://trafficops.company.net
- <Traffic_Ops_URL> = URL to Traffic Ops host. Example: https://trafficops.company.net
+ <Traffic_Ops_Login> => Example: 'username:password'
- <Traffic_Ops_Login> => Example: 'username:password'
+ [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.
+ ====-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-====
+ $
- [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.
- ====-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-====
- $
+.. _installing-ort:
Installing the ORT script
--------------------------
-#. Build the ORT script RPM from the Apache Build Server and install it: ::
-
- https://builds.apache.org/view/S-Z/view/TrafficControl/
+#. 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``):
- Sample command (NOTE that the example name used here most likely no longer exists): ::
+ .. code-block:: bash
- sudo wget https://builds.apache.org/job/trafficcontrol-2.1.x-build/lastSuccessfulBuild/artifact/dist/traffic_ops_ort-2.1.0-6807.1dcd512f.el7.x86_64.rpm
- sudo yum install traffic_ops_ort*.rpm
+ yum install -y traffic_ops_ort.rpm
-#. Install modules required by ORT if needed: ``sudo yum -y install perl-JSON perl-Crypt-SSLeay``
+#. 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 config files will be fetched and installed, and (if needed) the Traffic Server application will be restarted.
+#. 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 run below: ::
+ Example usage: ::
- $ sudo /opt/ort/traffic_ops_ort.pl --dispersion=0 badass warn https://ops.$tcDomain admin:admin123
+ $ sudo /opt/ort/traffic_ops_ort.pl --dispersion=0 BADASS WARN https://ops.$tcDomain admin:admin123
- .. 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:: 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.
-#. 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 Ops, and it so, get the updated configuration.
- Run ``sudo crontab -e`` and add the following line ::
+#. 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.
- */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
+ This can be done by running ``crontab -e`` as the root user (or with ``sudo``) and adding the following line ::
- Changing ``https://traffops.kabletown.net``, ``admin``, and ``password`` to your CDN URL and credentials.
+ */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
- .. Note:: By default, running ort on an edge traffic server waits for it's parent (mid) servers to download their configuration before
- it downloads it's 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 traffic servers. To customize this dispersion time, use
- the command line option --dispersion=x where x is the number of seconds for the dispersion period. Servers will select a random number from
- within this dispersion period to being pulling down configuration files from Traffic Ops. Another option, --login_dispersion=x can be used.
- This option creates a dispersion period after the job begins during which ORT will wait before logging in and checking Traffic Ops for updates
- to the server. This defaults to 0. If use_reval_pending, a.k.a. Rapid Revalidate is enabled, edges will NOT wait for their parents to download
- their configuration before downloading their own.
+ Changing ``https://traffops.kabletown.net``, ``admin``, and ``password`` to your CDN URL and credentials.
- .. Note:: In 'syncds' mode, the ort script updates only configurations that might be changed as part of normal operations, such as:
+ .. 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 ``--dispersion=x`` where ``x`` is the number of seconds for the dispersion period. Servers will select a random number from within this dispersion period to being downloading configuration files from Traffic Ops. Another option, ``--login_dispersion=x`` can be used to create a dispersion period after the job begins during which ORT will wait before logging in and checking Traffic Ops for updates to the server. This defaults to 0. If ``use_reval_pending``, a.k.a. Rapid Revalidate is enabled, Edge-tier cache servers will NOT wait for their parents to download their configuration before downloading their own.
- * Delivery Services
- * 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.)
+ .. Note:: In SYNCDS mode, the ORT script updates only configurations that might be changed as part of normal operations, such as:
+ * Delivery Services
+ * 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.)
-#. 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.
- Run ``sudo crontab -e`` and add the following line ::
+#. 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
+ */1 * * * * /opt/ort/traffic_ops_ort.pl REVALIDATE WARN https://traffops.kabletown.net admin:password --login_dispersion=30 > /tmp/ort/syncds.log 2>&1
diff --git a/docs/source/admin/traffic_stats.rst b/docs/source/admin/traffic_stats.rst
index d484f59d2..1e3108425 100644
--- a/docs/source/admin/traffic_stats.rst
+++ b/docs/source/admin/traffic_stats.rst
@@ -17,172 +17,195 @@
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 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.
Installation
========================
-**Installing Traffic Stats:**
+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.
+- Copy the RPM to your server
+- Perform the following command: ``sudo rpm -ivh <traffic_stats rpm>``
- - 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.
- - Copy the RPM to your server
- - perform the following command: ``sudo rpm -ivh <traffic_stats rpm>``
+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
-**Installing InfluxDB:**
+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/>`_.
- **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/>`_.
-
-
-**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/>`__.
+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:
-
- - *toUser:* The user used to connect to Traffic Ops
- - *toPasswd:* The password to use when connecting to Traffic Ops
- - *toUrl:* The URL of the Traffic Ops server used by Traffic Stats
- - *influxUser:* The user to use when connecting to InfluxDB (if configured on InfluxDB, else leave default)
- - *influxPassword:* That password to use when connecting to InfluxDB (if configured, else leave blank)
- - *pollingInterval:* The interval at which Traffic Monitor is polled and stats are stored in InfluxDB
- - *statusToMon:* The status of Traffic Monitor to poll (poll ONLINE or OFFLINE traffic monitors)
- - *seelogConfig:* The absolute path of the seelong config 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 deliveryservice stats
- - *dailySummaryRetentionPolicy:* The retention policy to be used for the daily stats
- - *influxUrls:* An array of influxdb hosts for Traffic Stats to write stats to.
-
-**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 availabilty 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.
-
- 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.
-
-**Configuring Grafana:**
-
- In Traffic Ops the Health -> Graph View tab can be configured to display grafana graphs using influxDb data. In order for this to work correctly, you will need two things 1) a parameter added to traffic ops with the graph URL (more information below) and 2) 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.
-
- - Login to grafana as an admin user http://grafana_url:3000/login
- - Choose Data Sources and then Add New
- - Enter the necessary information to configure your data source
- - Click on the 'Home' dropdown 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
- - 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:
-
- ``SELECT sum(value)*1000 FROM "monthly"."bandwidth.cdn.1min" WHERE $timeFilter GROUP BY time(60s), cdn``
- - Once you have the graph the way you want it, click the 'Save Dashboard' button at the top
- - You should now have a new saved graph
-
- In order for Traffic Ops 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 Ops uses custom dashboards to display information about individual delivery services or cache groups. 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 the files in place. If your grafana server is different from your Traffic Stats server, you will need to manually copy the files to the correct directory.
-
- More information on custom scripted graphs can be found in the `scripted dashboards <http://docs.grafana.org/reference/scripting/>`_ section of the Grafana documentation.
-
-**Configuring Traffic Ops for Traffic Stats:**
-
- - The influxDb servers need to be added to Traffic Ops 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.
-
-**Configuring Traffic Ops to use Grafana Dashboards**
-
- To configure Traffic Ops 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 |
- +---------------------------+------------------------------------------------------------------------------------------------+
-
-InfluxDb Tools
+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:
+
+toUser
+ The user used to connect to Traffic Ops
+toPasswd
+ The password to use when connecting to Traffic Ops
+toUrl
+ The URL of the Traffic Ops server used by Traffic Stats
+influxUser
+ The user to use when connecting to InfluxDB (if configured on InfluxDB, else leave default)
+influxPassword
+ That password to use when connecting to InfluxDB (if configured, else leave blank)
+pollingInterval
+ The interval at which Traffic Monitor is polled and stats are stored in InfluxDB
+statusToMon
+ The status of Traffic Monitor to poll (poll ONLINE or OFFLINE traffic monitors)
+seelogConfig
+ The absolute path of the seelong 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
+dailySummaryRetentionPolicy
+ The retention policy to be used for the daily stats
+influxUrls
+ An array of InfluxDB hosts for Traffic Stats to write stats to.
+
+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.
+
+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.
+
+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:
+
+#. A 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
+#. 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
+#. 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:
+
+ .. code-block:: postgresql
+
+ 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
+#. 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 Cache Groups. 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 the files in place. If your Grafana server is different from your Traffic Stats server, you will need to manually copy the files to the correct directory.
+
+More information on custom scripted graphs can be found in the `scripted dashboards <http://docs.grafana.org/reference/scripting/>`_ section of the Grafana documentation.
+
+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.
+
+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 |
++---------------------------+------------------------------------------------------------------------------------------------+
+
+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.
-
-**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.
-
- **How to use create_ts_databases:**
-
- Pre-Requisites:
+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.
- 1. Go 1.7 or later
- 2. configured $GOPATH (e.g. export GOPATH=~/go)
+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.
- Using create_ts_databases.go
+How to Use ``create_ts_databases``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Pre-Requisites:
- 1. go to the traffic_stats/influxdb_tools/create directory
+ 1. Go 1.7 or later
+ 2. Configured $GOPATH (e.g. export GOPATH=~/go)
- 2. build it by running ``go build create_ts_databases.go`` or simply ``go build``
+Using ``create_ts_databases.go``
- 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``
+ 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``
-**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.
+``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.
- **How to use sync_ts_databases:**
+How to Use ``sync_ts_databases``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Pre-Requisites:
- Pre-Requisites:
+ 1. Go 1.7 or later
+ 2. Configured ``$GOPATH`` (e.g. ``export GOPATH=~/go``)
- 1. Go 1.7 or later
- 2. configured $GOPATH (e.g. export GOPATH=~/go)
+Using sync_ts_databases.go:
- Using sync_ts_databases.go:
+ 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
- 1. go to the traffic_stats/influxdb_tools/create directory
+ - ``./sync_ts_databases -help`` or ``./sync -help``
+ - required flags:
- 2. build it by running ``go build sync_ts_databases.go`` or simply ``go build``
+ - ``source-url`` - The URL of the source database
+ - ``target-url`` - The URL of the target database
- 3. Run it
- - ``./sync_ts_databases -help`` or ``./sync -help``
- - required flags:
- - source-url - The URL of the source database
- - target-url - The URL of the target database
+ - optional flags:
- -optional flags:
- - 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
+ - ``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
- - 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`
+ - 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``
diff --git a/docs/source/admin/traffic_vault.rst b/docs/source/admin/traffic_vault.rst
index 55fdc95a1..5c0b05d36 100644
--- a/docs/source/admin/traffic_vault.rst
+++ b/docs/source/admin/traffic_vault.rst
@@ -22,55 +22,54 @@ 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/>`__.
-Production is currently running version 2.0.5 of Riak, but the latest version should suffice.
-
+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 our environments.
+The following steps were taken to configure Riak in Comcast production environments.
Riak configuration file configuration
-------------------------------------
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
-* cd to /etc/riak/
+* ``cd /etc/riak/``
-* Update the following in riak.conf to reflect your IP:
- - nodename = riak@a-host.sys.kabletown.net
- - listener.http.internal = a-host.sys.kabletown.net:8098 (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 (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)
* 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
+ - ``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 config for tlsv1
- - tls_protocols.tlsv1 = on
+* Add a line at the bottom of the configuration file for TLSv1
+ - ``tls_protocols.tlsv1 = on``
-* Once the config file has been updated restart riak
+* 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
+ - ``https://<serverHostname>:8088/ping``
-Riak-admin configuration
--------------------------
+``riak-admin`` configuration
+----------------------------
-Riak-admin is a command line utility 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
+ * 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
+Add ``admin`` user and ``riakuser`` to Riak
+ * ``admin`` user will be a super user
+ * ``riakuser`` will be the application user
Login to one of the riak servers in the cluster as root (any will do)
@@ -85,24 +84,23 @@ Login to one of the riak servers in the cluster as root (any will do)
``riak-admin security add-group keysusers``
3. Add users
- .. Note:: username and password should be stored in /opt/traffic_ops/app/conf/<environment>/riak.conf
- ..
+ .. 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``
``riak-admin security add-user riakuser password=<RiakUserPassword> groups=keysusers``
- 4. Grant access for admin and riakuser
+ 4. Grant access for ``admin`` and ``riakuser``
``riak-admin security add-source riakuser 0.0.0.0/0 password``
``riak-admin security add-source admin 0.0.0.0/0 password``
- 5. Grant privs to admins for everything
+ 5. 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``
- 6. Grant privs to keysuser for ssl, dnssec, and url_sig_keys buckets only
+ 6. 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``
@@ -110,7 +108,7 @@ Login to one of the riak servers in the cluster as root (any will do)
``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 grant riak_kv.get,riak_kv.put,riak_kv.delete on default cdn_uri_sig_keys to 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/>`_.
@@ -125,61 +123,61 @@ There are a couple configurations that are necessary in Traffic Ops.
* The servers in the Riak cluster need to be added to the server table (TCP Port = 8088, type = RIAK, profile = RIAK_ALL)
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.
+ * ``/opt/traffic_ops/app/conf/<environment>/riak.conf`` needs to be updated to reflect the correct username and password for accessing riak.
Configuring Riak Search
=======================
-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.
+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 Configuration
------------------
On Each Riak Server:
-1. If java is not already installed on your Riak server, install Java
+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 jdk``
+ * To install Java: ``yum install -y jdk`` (CentOS/RedHat/Fedora), ``apt-get install -y java`` (Ubuntu/Debian/Linux Mint), ``pacman -Sy java`` (Arch/Manjaro)
-2. enable search in riak.conf
- * ``vim /etc/riak/riak.conf``
+2. Enable search in riak.conf
+ * ``$EDITOR /etc/riak/riak.conf``
* look for search and change ``search = off`` to ``search = on``
3. Restart Riak so search is on
- * ``service riak restart``
+ * ``systemctl restart riak`` (systemD-based systems)
One time configuration:
-1. **On one of the Riak servers in the cluster run the following riak-admin commands**
+1. On one of the Riak servers in the cluster run the following riak-admin commands:
-``riak-admin security grant search.admin on schema to admin``
+ - ``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.admin on index to admin``
-``riak-admin security grant search.query 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 sslkeys to admin``
-``riak-admin security grant search.query on index to riakuser``
+ - ``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 search.query on index sslkeys to riakuser``
-``riak-admin security grant riak_core.set_bucket on any to admin``
+ - ``riak-admin security grant riak_core.set_bucket on any to admin``
-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 deliveryservice.
- * 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``
+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``
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"}'``
+ * run the following cURL command: ``curl -kvs -XPUT "https://admin:pass@riakserver:8088/search/index/sslkeys" -H 'Content-Type: application/json' -d '{"schema":"sslkeys"}'``
-4. Associate the sslkeys index to the ssl bucket in Riak
+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"}}'``
-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 and when a search is performed riak will return the indexed fields along with the crt 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 explains how to run the script.
+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 explains how to run the script.
-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``
+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{.})
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"``
diff --git a/docs/source/api/routes.rst b/docs/source/api/routes.rst
index 1c849b3cb..98caabf20 100644
--- a/docs/source/api/routes.rst
+++ b/docs/source/api/routes.rst
@@ -1,43 +1,17 @@
-.. raw:: html
-
- <style>
- table {
- table-layout: fixed;
- width: 100%;
- }
-
- td {
- word-wrap:break-word;
- }
- table.docutils col:nth-child(1) {
- width: 30%;
- }
- table.docutils col:nth-child(2) {
- width: 30%;
- }
- table.docutils col:nth-child(3) {
- width: 30%;
- }
- .wy-nav-content {
- max-width: 1200px;
- width: 90%;
- }
- </style>
-
-..
-..
+..
+..
.. 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-routes:
@@ -45,74 +19,78 @@
API Routes
==========
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| 1.0 | 1.1 | 1.2 |
-+====================================+====================================================+====================================================+
-| /asns | :ref:`to-api-v11-asns-route` | :ref:`to-api-v12-asns-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /availableds | :ref:`to-api-v11-ds-route` | :ref:`to-api-v12-ds-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| *Not Implemented* | *Not Implemented* | :ref:`to-api-v12-cache-stats-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datacrans | /api/1.1/crans.json | /api/1.2/crans.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datacrans/orderby/:field | /api/1.1/crans.json | /api/1.2/crans.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datadeliveryservice | :ref:`to-api-v11-ds-route` | :ref:`to-api-v12-ds-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datadeliveryserviceserver | /api/1.1/deliveryserviceserver.json | /api/1.2/deliveryserviceserver.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datadomains | /api/1.1/cdns/domains.json | /api/1.2/cdns/domains.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| *Not Implemented* | *Not Implemented* | :ref:`to-api-v12-ds-stats-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datahwinfo | :ref:`to-api-v11-hwinfo-route` | :ref:`to-api-v12-hwinfo-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datalinks | /api/1.1/deliveryserviceserver.json | /api/1.2/deliveryserviceserver.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datalinks/orderby/:field | /api/1.1/deliveryserviceserver.json | /api/1.2/deliveryserviceserver.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datalogs | :ref:`to-api-v11-change-logs-route` | :ref:`to-api-v12-change-logs-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datalocation/orderby/id | :ref:`to-api-v11-cachegroups-route` | :ref:`to-api-v12-cachegroups-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datalocationparameters | :ref:`to-api-v11-cachegroups-route` | :ref:`to-api-v12-cachegroups-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataparameter | :ref:`to-api-v11-parameters-route` | :ref:`to-api-v12-parameters-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataparameter/:parameter | /api/1.1/parameters/profile/:parameter.json | /api/1.2/parameters/profile/:parameter.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataphys_location | :ref:`to-api-v11-phys-loc-route` | :ref:`to-api-v12-phys-loc-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataprofile | :ref:`to-api-v11-profiles-route` | :ref:`to-api-v12-profiles-route` |
-| | | |
-| /dataprofile/orderby/name | | |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataregion | :ref:`to-api-v11-regions-route` | :ref:`to-api-v12-regions-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datarole | :ref:`to-api-v11-roles-route` | :ref:`to-api-v12-roles-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datarole/orderby/:field | :ref:`to-api-v11-roles-route` | :ref:`to-api-v12-roles-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataserver | :ref:`to-api-v11-servers-route` | :ref:`to-api-v12-servers-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataserver/orderby/:field | :ref:`to-api-v11-servers-route` | :ref:`to-api-v12-servers-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /dataserverdetail/select/:hostname | /api/1.1/servers/hostname/:hostname/details.json | /api/1.2/servers/hostname/:hostname/details.json |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datastaticdnsentry | :ref:`to-api-v11-static-dns-route` | :ref:`to-api-v12-static-dns-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datastatus | :ref:`to-api-v11-statuses-route` | :ref:`to-api-v12-statuses-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datastatus/orderby/name | :ref:`to-api-v11-statuses-route` | :ref:`to-api-v12-statuses-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datatype | :ref:`to-api-v11-types-route` | :ref:`to-api-v12-types-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datatype/orderby/:field | :ref:`to-api-v11-types-route` | :ref:`to-api-v12-types-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datauser | :ref:`to-api-v11-users-route` | :ref:`to-api-v12-users-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| /datauser/orderby/:field | :ref:`to-api-v11-users-route` | :ref:`to-api-v12-users-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
-| *Not Implemented* | *Not Implemented* | :ref:`to-api-v12-configfiles_ats-route` |
-+------------------------------------+----------------------------------------------------+----------------------------------------------------+
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| 1.0 | 1.1 | 1.2 | 1.3 |
++====================================+====================================================+====================================================+====================================================+
+| /asns | :ref:`to-api-v11-asns-route` | :ref:`to-api-v12-asns-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /availableds | :ref:`to-api-v11-ds-route` | :ref:`to-api-v12-ds-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| *Not Implemented* | *Not Implemented* | :ref:`to-api-v12-cache-stats-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| *Not Implemented* | *Not Implemented* | *Not Implemented* | :ref:`to-api-v13-coordinates-route` |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datacrans | /api/1.1/crans.json | /api/1.2/crans.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datacrans/orderby/:field | /api/1.1/crans.json | /api/1.2/crans.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datadeliveryservice | :ref:`to-api-v11-ds-route` | :ref:`to-api-v12-ds-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datadeliveryserviceserver | /api/1.1/deliveryserviceserver.json | /api/1.2/deliveryserviceserver.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datadomains | /api/1.1/cdns/domains.json | /api/1.2/cdns/domains.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| *Not Implemented* | *Not Implemented* | :ref:`to-api-v12-ds-stats-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datahwinfo | :ref:`to-api-v11-hwinfo-route` | :ref:`to-api-v12-hwinfo-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datalinks | /api/1.1/deliveryserviceserver.json | /api/1.2/deliveryserviceserver.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datalinks/orderby/:field | /api/1.1/deliveryserviceserver.json | /api/1.2/deliveryserviceserver.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datalogs | :ref:`to-api-v11-change-logs-route` | :ref:`to-api-v12-change-logs-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datalocation/orderby/id | :ref:`to-api-v11-cachegroups-route` | :ref:`to-api-v12-cachegroups-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datalocationparameters | :ref:`to-api-v11-cachegroups-route` | :ref:`to-api-v12-cachegroups-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataparameter | :ref:`to-api-v11-parameters-route` | :ref:`to-api-v12-parameters-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataparameter/:parameter | /api/1.1/parameters/profile/:parameter.json | /api/1.2/parameters/profile/:parameter.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataphys_location | :ref:`to-api-v11-phys-loc-route` | :ref:`to-api-v12-phys-loc-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataprofile | :ref:`to-api-v11-profiles-route` | :ref:`to-api-v12-profiles-route` | *Not Implemented* |
+| | | | |
+| /dataprofile/orderby/name | | | |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataregion | :ref:`to-api-v11-regions-route` | :ref:`to-api-v12-regions-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datarole | :ref:`to-api-v11-roles-route` | :ref:`to-api-v12-roles-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datarole/orderby/:field | :ref:`to-api-v11-roles-route` | :ref:`to-api-v12-roles-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataserver | :ref:`to-api-v11-servers-route` | :ref:`to-api-v12-servers-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataserver/orderby/:field | :ref:`to-api-v11-servers-route` | :ref:`to-api-v12-servers-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /dataserverdetail/select/:hostname | /api/1.1/servers/hostname/:hostname/details.json | /api/1.2/servers/hostname/:hostname/details.json | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datastaticdnsentry | :ref:`to-api-v11-static-dns-route` | :ref:`to-api-v12-static-dns-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datastatus | :ref:`to-api-v11-statuses-route` | :ref:`to-api-v12-statuses-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datastatus/orderby/name | :ref:`to-api-v11-statuses-route` | :ref:`to-api-v12-statuses-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datatype | :ref:`to-api-v11-types-route` | :ref:`to-api-v12-types-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datatype/orderby/:field | :ref:`to-api-v11-types-route` | :ref:`to-api-v12-types-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datauser | :ref:`to-api-v11-users-route` | :ref:`to-api-v12-users-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| /datauser/orderby/:field | :ref:`to-api-v11-users-route` | :ref:`to-api-v12-users-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| *Not Implemented* | *Not Implemented* | :ref:`to-api-v12-configfiles_ats-route` | *Not Implemented* |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
+| *Not Implemented* | *Not Implemented* | *Not Implemented* | :ref:`to-api-v13-origin-route` |
++------------------------------------+----------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
diff --git a/docs/source/api/v11/deliveryservice.rst b/docs/source/api/v11/deliveryservice.rst
index 1d01d6174..f3acd0cb5 100644
--- a/docs/source/api/v11/deliveryservice.rst
+++ b/docs/source/api/v11/deliveryservice.rst
@@ -1,17 +1,17 @@
-..
-..
+..
+..
.. 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-v11-ds:
@@ -119,9 +119,9 @@ Delivery Service
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``missLong`` | string | The longitude to use when the client cannot be found in the CZF or the Geo lookup. |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
@@ -351,9 +351,9 @@ Delivery Service
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``missLong`` | string | The longitude to use when the client cannot be found in the CZF or the Geo lookup. |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
@@ -897,7 +897,7 @@ SSL Keys
**Response Example** ::
- {
+ {
"response": {
"certificate": {
"crt": "crt",
@@ -966,7 +966,7 @@ SSL Keys
**Response Example** ::
- {
+ {
"response": {
"certificate": {
"crt": "crt",
@@ -1017,12 +1017,12 @@ SSL Keys
**Response Example** ::
- {
+ {
"response": "Successfully deleted ssl keys for <xml_id>"
}
|
-
+
**POST /api/1.1/deliveryservices/sslkeys/generate**
Generates SSL crt, csr, and private key for a delivery service
@@ -1085,12 +1085,12 @@ SSL Keys
**Response Example** ::
- {
+ {
"response": "Successfully created ssl keys for ds-01"
}
|
-
+
**POST /api/1.1/deliveryservices/sslkeys/add**
Allows user to add SSL crt, csr, and private key for a delivery service.
@@ -1141,7 +1141,7 @@ SSL Keys
**Response Example** ::
- {
+ {
"response": "Successfully added ssl keys for ds-01"
}
diff --git a/docs/source/api/v12/deliveryservice.rst b/docs/source/api/v12/deliveryservice.rst
index f977fc92c..6d5c04220 100644
--- a/docs/source/api/v12/deliveryservice.rst
+++ b/docs/source/api/v12/deliveryservice.rst
@@ -147,7 +147,7 @@ Delivery Service
| ``missLong`` | float | The longitude as decimal degrees to use when the client cannot be found in the CZF or the Geo lookup. |
| | | - e.g. -104.9847000 or null |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
@@ -401,7 +401,7 @@ Delivery Service
| ``missLong`` | float | The longitude as decimal degrees to use when the client cannot be found in the CZF or the Geo lookup. |
| | | - e.g. -104.9847000 or null |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
@@ -2360,7 +2360,7 @@ URL Sig Keys
| ``missLong`` | float | The longitude as decimal degrees to use when the client cannot be found in the CZF or the Geo lookup. |
| | | - e.g. -104.9847000 or null |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
@@ -2792,7 +2792,7 @@ URL Sig Keys
| ``missLong`` | float | The longitude as decimal degrees to use when the client cannot be found in the CZF or the Geo lookup. |
| | | - e.g. -104.9847000 or null |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
@@ -3072,7 +3072,7 @@ URL Sig Keys
| ``missLong`` | float | The longitude as decimal degrees to use when the client cannot be found in the CZF or the Geo lookup. |
| | | - e.g. -104.9847000 or null |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+------------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
diff --git a/docs/source/api/v12/server.rst b/docs/source/api/v12/server.rst
index accc23415..c1410975a 100644
--- a/docs/source/api/v12/server.rst
+++ b/docs/source/api/v12/server.rst
@@ -453,9 +453,9 @@ Server
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``missLong`` | string | The longitude to use when the client cannot be found in the CZF or the Geo lookup. |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
diff --git a/docs/source/api/v12/user.rst b/docs/source/api/v12/user.rst
index 8d22fc72a..33cf1e3dd 100644
--- a/docs/source/api/v12/user.rst
+++ b/docs/source/api/v12/user.rst
@@ -1,17 +1,17 @@
-..
-..
+..
+..
.. 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-v12-users:
@@ -279,8 +279,8 @@ Users
**Request Example** ::
-
- {
+
+ {
"username": "tsimpson"
"tenantId": 1,
"fullName": "Tom Simpson"
@@ -341,7 +341,7 @@ Users
+----------------------+--------+------------------------------------------------+
**Response Example** ::
-
+
{"alerts": [
{
"level":"success",
@@ -529,9 +529,9 @@ Users
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``missLong`` | string | The longitude to use when the client cannot be found in the CZF or the Geo lookup. |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOrigin`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
- | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`rl-multi-site-origin` |
+ | ``multiSiteOriginAlgor`` | bool | Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See :ref:`multi-site-origin` |
+--------------------------+--------+--------------------------------------------------------------------------------------------------------------------------------------+
| ``orgServerFqdn`` | string | The origin server base URL (FQDN when used in this instance, includes the |
| | | protocol (http:// or https://) for use in retrieving content from the origin server. |
@@ -747,7 +747,7 @@ Users
}
|
-
+
**PUT /api/1.2/user/current**
Updates the date for the authenticated user.
@@ -1003,7 +1003,7 @@ Role(s) Required: None
{
"alerts":
[
- {
+ {
"level": "success",
"text": "Successfully created purge job for: ."
}
@@ -1255,4 +1255,4 @@ Role(s) Required: None
}
|
-
+
diff --git a/docs/source/basics/cache_revalidation.rst b/docs/source/basics/cache_revalidation.rst
index 980ca53a2..879bef242 100644
--- a/docs/source/basics/cache_revalidation.rst
+++ b/docs/source/basics/cache_revalidation.rst
@@ -1,40 +1,40 @@
-..
-..
+..
+..
.. 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::
Cache Control Header
Revalidation
HTTP 304
-
+
Cache Control Headers and Revalidation
======================================
The `HTTP/1.1 spec <https://www.ietf.org/rfc/rfc2616.txt>`_ allows for origin servers and clients to influence how caches treat their requests and responses. By default, the Traffic Control CDN will honor cache control headers. Most commonly, origin servers will tell the downstream caches how long a response can be cached::
- 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"
- Cache-Control: max-age=86400
- Content-Length: 45
- Connection: close
- Content-Type: text/html; charset=UTF-8
+ 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"
+ Cache-Control: max-age=86400
+ Content-Length: 45
+ Connection: close
+ Content-Type: text/html; charset=UTF-8
- <html><body>This is a fun file</body></html>
+ <!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 again from the origin server, the cache will send a request to the origin indicating what version of the response it has, and asking if it has changed. If it changed, the server will send a ``200 OK`` response, with the new data. If it has not changed, the origin server will send back a ``304 Not Modified`` response indicating the response is still valid, and that the cache can reset the timer on the response expiration. To indicate what version the client (cache) has it will add an ``If-Not-Modified-Since:`` header, or an ``If-None-Match:`` header. For example, in the ``If-None-Match:`` case, the origin will send an ``ETag`` header that uniquely identifies the response. The client can use that in an revalidation request like::
+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 again from the origin server, the cache will send a request to the origin indicating what version of the response it has, and asking if it has changed. If it changed, the server will send a ``200 OK`` response, with the new data. If it has not changed, the origin server will send back a ``304 Not Modified`` response indicating the response is still valid, and that the cache can reset the timer on the response expiration. To indicate what version the client (cache) has it will add an ``If-Not-Modified-Since:`` header, or an ``If-None-Match:`` header. For example, in the ``If-None-Match:`` case, the origin will send an ``ETag`` header that uniquely identifies the response. The client can use that in an revalidation request like::
GET /foo/bar/fun.html HTTP/1.1
If-None-Match: "1aa008f-2d-50a3559482cc0"
@@ -42,30 +42,30 @@ In the above response, the origin server tells downstream caching systems that t
If the content has changed (meaning, the new response would not have had the same ETag) it will respond with ``200 OK``, like::
- HTTP/1.1 200 OK
- 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-50aa00feadd"
- Cache-Control: max-age=604800
- Content-Length: 49
- Connection: close
- Content-Type: text/html; charset=UTF-8
+ HTTP/1.1 200 OK
+ 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-50aa00feadd"
+ Cache-Control: max-age=604800
+ Content-Length: 49
+ Connection: close
+ Content-Type: text/html; charset=UTF-8
- <html><body>This is NOT a fun file</body></html>
+ <!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::
- 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
+ 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
index af9373074..b6570ea10 100644
--- a/docs/source/basics/caching_proxies.rst
+++ b/docs/source/basics/caching_proxies.rst
@@ -1,159 +1,155 @@
-..
-..
+..
+..
.. 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.
-..
+..
.. |arrow| image:: fwda.png
-.. _rl-caching_proxy:
+.. _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 which are described below.
+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>`_.
.. index::
- Reverse Proxy
+ Reverse Proxy
-.. _rl-rev-proxy:
+.. _rev-proxy:
|arrow| 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 HTTP 1.1 specification, the client sends a ``Host:`` header to the reverse
- proxy that matches the hostname in the URL.
- The proxy looks up this hostname in a
- list of mappings to find the origin hostname; if the hostname of the Host header is not found in the list,
- the proxy will send an error (``404 Not Found``) to the client.
- If the supplied hostname is found in this list of mappings, the proxy checks the cache, and when the content is not already present, connects to the
- origin the requested ``Host:`` maps to and requests the path of the original URL, providing the origin hostname in the ``Host`` header. The proxy then stores the URL in cache and serves the contents to the client. When there are subsequent requests for
- the same URL, a caching proxy serves the content out of cache thereby reducing
- latency and network traffic.
+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 HTTP 1.1 specification, the client sends a ``Host:`` header to the reverse proxy that matches the hostname in the URL. The proxy looks up this hostname in a list of mappings to find the origin hostname; if the hostname of the ``Host:`` header is not found in the list, the proxy will send an error (``404 Not Found``) to the client. If the supplied hostname is found in this list of mappings, the proxy checks the cache, and when the content is not already present, connects to the origin the requested ``Host:`` maps to and requests the path of the original URL, providing the origin hostname in the ``Host`` header. The proxy then stores the URL in cache and serves the contents to the client. When there are subsequent requests for the same URL, a caching proxy serves the content out of cache thereby reducing latency and network traffic.
.. 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
+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.
+.. 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
+ 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
- <html><body>This is a fun file</body></html>
+ <!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:
-1. The client sends a request to the LDNS server to resolve the name ``www-origin-cache.cdn.com`` to an IPv4 address.
+1. 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.
2. 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.
3. 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: ::
- GET /foo/bar/fun.html HTTP/1.1
- Host: www-origin-cache.cdn.com
+ GET /foo/bar/fun.html HTTP/1.1
+ Host: www-origin-cache.cdn.com
4. The reverse proxy looks up ``www-origin-cache.cdn.com`` in its remap rules, and finds the origin is ``www.origin.com``.
-5. The proxy checks its cache to see if the response for ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` is already in the cache.
+5. The proxy checks its cache to see if the response for ``http://www.origin.com/foo/bar/fun.html`` is already in the cache.
6a. If the response is not in the cache:
- 1. The proxy uses DNS to get the IPv4 address for ``www.origin.com``, connect to it on port 80, and sends: ::
+ 1. The proxy uses DNS to get the IPv4 address for ``www.origin.com``, connect to it on port 80, and sends:
- GET /foo/bar/fun.html HTTP/1.1
- Host: www.origin.com
+ .. code-block:: http
- 2. The origin server responds with the headers and content as shown: ::
+ GET /foo/bar/fun.html HTTP/1.1
+ Host: www.origin.com
- 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
+ 2. The origin server responds with the headers and content as shown:
- <html><body>This is a fun file</body></html>
+ .. code-block:: http
- 3. The proxy sends the origin response on to the client adding a ``Via:`` header (and maybe others): ::
+ 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
- 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>
- <html><body>This is a fun file</body></html>
+ 3. 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>
6b. If it *is* in the cache:
-
- The proxy responds to the client with the previously retrieved result: ::
- 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
+ The proxy responds to the client with the previously retrieved result:
- <html><body>This is a fun file</body></html>
+ .. 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>
.. index::
- Forward Proxy
+ Forward Proxy
-.. _rl-fwd-proxy:
+.. _fwd-proxy:
|arrow| 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 explicitely 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
- client obtains, and is unaware of the proxy in the middle.
+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 client obtains, and is unaware of the proxy in the middle.
.. seealso:: `ATS documentation on forward proxy <https://docs.trafficserver.apache.org/en/latest/admin/forward-proxy.en.html>`_.
@@ -161,78 +157,77 @@ Below is an example of the client retrieving the URL ``http://www.origin.com/foo
1. 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.
-2. To retrieve ``http://www.origin.com/foo/bar/fun.html`` URL, the client connects to 99.88.77.66 on port 8080 and sends:
-
- ::
+2. 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
+ 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.
+.. 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``.
3. The proxy verifies whether the response for ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` is already in the cache.
4a. If it is not in the cache:
- 1. The proxy uses DNS to obtain the IPv4 address for ``www.origin.com``, connects to it on port 80, and sends: ::
+ 1. 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
+ GET /foo/bar/fun.html HTTP/1.1
+ Host: www.origin.com
- 2. The origin server responds with the headers and content as shown below: ::
+ 2. 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
+ 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
- <html><body>This is a fun file</body></html>
+ <!DOCTYPE html><html><body>This is a fun file</body></html>
- 3. The proxy sends this on to the client adding a ``Via:`` header (and maybe others): ::
+ 3. The proxy sends this on to the client adding a ``Via:`` header (and maybe others):
- 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
-
- <html><body>This is a fun file</body></html>
+ .. 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>
4b. If it *is* in the cache:
-
- The proxy responds to the client with the previously retrieved result: ::
-
- 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
-
- <html><body>This is a fun file</body></html>
-.. index::
- Transparent Proxy
-
-|arrow| Transparent Proxy
--------------------------
- Neither the origin nor the client are aware of the actions performed by the transparent proxies. A Traffic Control based CDN does not use transparent proxies. If you are interested you can learn more about transparent proxies on `wikipedia <http://en.wikipedia.org/wiki/Proxy_server#Transparent_proxy>`_.
+ 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 872018e57..8893610c9 100644
--- a/docs/source/basics/content_delivery_networks.rst
+++ b/docs/source/basics/content_delivery_networks.rst
@@ -1,40 +1,38 @@
-..
-..
+..
+..
.. 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::
Log File Analysis
CDN
- Content Delivery Network
+ 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 the goal of optimizing the delivery of content to the end users, while minimizing the traffic on the network. A CDN typically consists of the following:
+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 the goal of optimizing the delivery of content to the end users, while minimizing the traffic on the network. A CDN typically consists of the following:
-* **Caching Proxies**
- The proxy (cache or caching proxy) is a server that both proxies the requests and caches the results for reusing.
+Caching Proxies
+ The proxy (cache or caching proxy) is a server that both proxies the requests and caches the results for reusing.
-* **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.
+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.
-* **Health Protocol**
- The Health Protocol monitors the usage of the caches and tenants in the CDN.
-
-* **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.
-
-* **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.
+Health Protocol
+ The :ref:`health-proto` monitors the usage of the caches and tenants in the CDN.
+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.
+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.
diff --git a/docs/source/basics/http_11.rst b/docs/source/basics/http_11.rst
index 65d6d710c..928324855 100644
--- a/docs/source/basics/http_11.rst
+++ b/docs/source/basics/http_11.rst
@@ -1,27 +1,27 @@
-..
-..
+..
+..
.. 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::
http/1.1
HTTP
-HTTP 1.1
+HTTP/1.1
========
-For a comprehensive look at Traffic Control, it is important to understand basic HTTP 1.1 protocol operations and how caches function. The example below illustrates the fulfillment of an HTTP 1.1 request in a situation without CDN or proxy, followed by viewing the changes after inserting different types of (caching) proxies. Several of the examples below are simplified for clarification of the essentials.
+For a comprehensive look at Traffic Control, it is important to understand basic HTTP/1.1 protocol operations and how caches function. The example below illustrates the fulfillment of an HTTP/1.1 request in a situation without CDN or proxy, followed by viewing the changes after inserting different types of (caching) proxies. Several of the examples below are simplified for clarification of the essentials.
-For complete details on HTTP 1.1 see `RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1 <https://www.ietf.org/rfc/rfc2616.txt>`_.
+For complete details on HTTP/1.1 see `RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1 <https://www.ietf.org/rfc/rfc2616.txt>`_.
Below are the steps of a client retrieving the URL ``http://www.origin.com/foo/bar/fun.html`` using HTTP/1.1 without proxies:
@@ -29,20 +29,24 @@ Below are the steps of a client retrieving the URL ``http://www.origin.com/foo/b
2. If the LDNS does not have this name (IPv4 mapping cached), it sends DNS requests to the ., .com, and .origin.com authoritative servers until it receives a response with the address for ``www.origin.com``. Per the DNS SPEC, this response has a Time To Live (TTL), which indicates how long this mapping can be cached at the LDNS server. In the example, the IP address found by the LDNS server for www.origin.com is 44.33.22.11.
- .. Note:: While longer DNS TTLs of a day (86400 seconds) or more are quite common in other use cases, in CDN use cases DNS TTLs are often below a minute.
+ .. Note:: While longer DNS TTLs of a day (86400 seconds) or more are quite common in other use cases, in CDN use cases DNS TTLs are often below a minute.
-3. The client opens a TCP connection from a random port locally to port 80 (the HTTP default) on 44.33.22.11, and sends this (showing the minimum HTTP 1.1 request, typically there are additional headers): ::
+3. The client opens a TCP connection from a random port locally to port 80 (the HTTP default) on 44.33.22.11, and sends this (showing the minimum HTTP 1.1 request, typically there are additional headers):
- GET /foo/bar/fun.html HTTP/1.1
- Host: www.origin.com
+ .. code-block:: http
-4. The server at ``www.origin.com`` looks up the Host: header to match that to a configuration section, usually referred to as a virtual host section. If the Host: header and configuration section match, the search continues for the content of the path ``/foo/bar/fun.html``, in the example, this is a file that contains ``<html><body>This is a fun file</body></html>``, so the server responds with the following: ::
+ GET /foo/bar/fun.html HTTP/1.1
+ Host: www.origin.com
+4. The server at ``www.origin.com`` looks up the Host: header to match that to a configuration section, usually referred to as a virtual host section. If the Host: header and configuration section match, the search continues for the content of the path ``/foo/bar/fun.html``, in the example, this is a file that contains ``<!DOCTYPE html><html><body>This is a fun file</body></html>``, so the server responds with the following:
- HTTP/1.1 200 OK
- Content-Type: text/html; charset=UTF-8
- Content-Length: 45
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: text/html; charset=UTF-8
+ Content-Length: 45
+
+ <!DOCTYPE html><html><body>This is a fun file</body></html>
- <html><body>This is a fun file</body></html>
At this point, HTTP transaction is complete.
diff --git a/docs/source/basics/index.rst b/docs/source/basics/index.rst
index 23ee1da11..7515156e9 100644
--- a/docs/source/basics/index.rst
+++ b/docs/source/basics/index.rst
@@ -1,17 +1,17 @@
-..
-..
+..
+..
.. 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.
-..
+..
CDN Basics
**********
@@ -19,11 +19,11 @@ CDN Basics
Traffic Control is a CDN control plane, see the topics below to familiarize yourself with the basic concepts of a CDN.
.. toctree::
- :maxdepth: 2
+ :maxdepth: 2
- content_delivery_networks
- http_11
- caching_proxies
- cache_revalidation
+ content_delivery_networks
+ http_11
+ caching_proxies
+ cache_revalidation
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9c22d152d..fd1d8a53a 100755
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -122,11 +122,11 @@
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
- # 'papersize': 'letterpaper',
+ 'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
#
- # 'pointsize': '10pt',
+ 'pointsize': '12pt',
# Additional stuff for the LaTeX preamble.
#
@@ -134,7 +134,7 @@
# Latex figure (float) alignment
#
- # 'figure_align': 'htbp',
+ 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
diff --git a/docs/source/development/traffic_monitor.rst b/docs/source/development/traffic_monitor.rst
index 74ac42159..24ba78335 100644
--- a/docs/source/development/traffic_monitor.rst
+++ b/docs/source/development/traffic_monitor.rst
@@ -1,17 +1,17 @@
-..
-..
+..
+..
.. 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 Monitor Golang
**********************
@@ -292,9 +292,9 @@ Tests can be executed by running ``go test ./...`` at the root of the ``traffic_
API
===
-:ref:`reference-tm-api`
+:ref:`tm-api`
-.. toctree::
+.. toctree::
:hidden:
:maxdepth: 1
diff --git a/docs/source/development/traffic_monitor/traffic_monitor_api.rst b/docs/source/development/traffic_monitor/traffic_monitor_api.rst
index 0240fd430..72870813f 100644
--- a/docs/source/development/traffic_monitor/traffic_monitor_api.rst
+++ b/docs/source/development/traffic_monitor/traffic_monitor_api.rst
@@ -1,19 +1,19 @@
-..
-..
+..
+..
.. 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.
-..
+..
-.. _reference-tm-api:
+.. _tm-api:
Traffic Monitor APIs
====================
diff --git a/docs/source/development/traffic_ops.rst b/docs/source/development/traffic_ops.rst
index 9bab72de7..91f18f18d 100644
--- a/docs/source/development/traffic_ops.rst
+++ b/docs/source/development/traffic_ops.rst
@@ -1,24 +1,24 @@
-..
-..
+..
+..
.. 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
***********
Introduction
============
-Traffic Ops uses a Postgres database to store the configuration information, and the `Mojolicious framework <http://mojolicio.us/>`_ to generate the user interface and REST APIs.
+Traffic Ops uses a Postgres database to store the configuration information, and the `Mojolicious framework <http://mojolicio.us/>`_ to generate the user interface and REST APIs.
Software Requirements
=====================
@@ -37,7 +37,7 @@ To work on Traffic Ops you need a \*nix (MacOS and Linux are most commonly used)
Addionally, the installation of the following RPMs (or equivalent) is required:
-* All RPMs listed in :ref:`rl-ps`
+* All RPMs listed in :ref:`ps`
Traffic Ops Project Tree Overview
=======================================
@@ -61,27 +61,27 @@ Traffic Ops Project Tree Overview
* /API - Mojo Controllers for the /API area of the application.
* /Common - Common Code between both the API and UI areas.
- * /Extensions
+ * /Extensions
* Fixtures/ - Test Case fixture data for the 'to_test' database.
* /Integration - Integration Tests.
* /MojoPlugins - Mojolicious Plugins for Common Controller Code.
* Schema/ - Database Schema area.
* /Result - DBIx ORM related files.
- * /Test - Common Test.
+ * /Test - Common Test.
* /UI - Mojo Controllers for the Traffic Ops UI itself.
- * Utils/
+ * Utils/
* /Helper - Common utilities for the Traffic Ops application.
* log/ - Log directory where the development and test files are written by the app.
* public/
-
+
* css/ - Stylesheets.
* images/ - Images.
* js/ - Javascripts
* script/ - Mojo Bootstrap scripts.
-
+
* t/ - Unit Tests for the UI.
* api/ - Unit Tests for the API.
@@ -92,7 +92,7 @@ Traffic Ops Project Tree Overview
-Perl Formatting Conventions
+Perl Formatting Conventions
===========================
Perl tidy is for use in code formatting. See the following config file for formatting conventions.
@@ -126,7 +126,7 @@ Database Management
===================
.. Add db naming conventions
-The admin.pl script is for use in managing the Traffic Ops database tables. Below is an example of its usage.
+The admin.pl script is for use in managing the Traffic Ops database tables. Below is an example of its usage.
``$ db/admin.pl``
@@ -177,10 +177,10 @@ To install the Traffic Ops Developer environment:
3. Set up a role (user) in Postgres
- See Postgres instructions on initdb https://wiki.postgresql.org/wiki/First_steps
+ See Postgres instructions on initdb https://wiki.postgresql.org/wiki/First_steps
-4. Enter ``db/admin.pl --env=<enviroment name> setup`` to set up the traffic_ops database(s).
+4. Enter ``db/admin.pl --env=<enviroment name> setup`` to set up the traffic_ops database(s).
* Unit test database: ``$ db/admin.pl --env=test setup``
* Development database: ``$ db/admin.pl --env=development setup``
@@ -222,16 +222,16 @@ To install the Traffic Ops Developer environment:
Start up success includes the following:
::
-
+
[2015-02-24 10:44:34,991] [INFO] Listening at "http://*:3000".
-
+
Server available at http://127.0.0.1:3000.
8. Using a browser, navigate to the given address: ``http://127.0.0.1:3000``
9. For the initial log in:
-
+
* User name: admin
* Password: password
@@ -248,11 +248,11 @@ The KableTown CDN example
-------------------------
The integration tests will load an example CDN with most of the features of Traffic Control being used. This is mostly for testing purposes, but can also be used as an example of how to configure certain features. To load the KableTown CDN example and access it:
-1. Run the integration tests
+1. Run the integration tests
2. Start morbo against the integration database: ``export MOJO_MODE=integration; ./bin/start.pl``
3. Using a browser, navigate to the given address: ``http://127.0.0.1:3000``
4. For the initial log in:
-
+
* User name: admin
* Password: password
@@ -280,7 +280,7 @@ Check Extensions
In other words, check extensions are scripts that, after registering with Traffic Ops, have a column reserved in the "Health->Server Checks" view and that usually run periodically out of cron.
-.. |checkmark| image:: ../_static/good.png
+.. |checkmark| image:: ../_static/good.png
.. |X| image:: ../_static/bad.png
@@ -289,7 +289,7 @@ It is the responsibility of the check extension script to iterate over the serve
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 hardcoded with an auth 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 a list of all caches to be polled by accessing Traffic Ops' ``/api/1.1/servers.json`` REST target. This list is walked, running a command to gather the stats from that cache. For some extensions, an HTTP GET request might be made to the ATS astats plugin, while for others the cache might be pinged, or a command run over SSH. The results are then compiled into a numeric or boolean result and the script POSTs tha result back to the Traffic Ops ``/api/1.1/servercheck/`` target.
-A check extension can have a column of |checkmark|'s and |X|'s (CHECK_EXTENSION_BOOL) or a column that shows a number (CHECK_EXTENSION_NUM).A simple example of a check extension of type CHECK_EXTENSION_NUM that will show 99.33 for all servers of type EDGE is shown below: ::
+A check extension can have a column of |checkmark|'s and |X|'s (CHECK_EXTENSION_BOOL) or a column that shows a number (CHECK_EXTENSION_NUM).A simple example of a check extension of type CHECK_EXTENSION_NUM that will show 99.33 for all servers of type EDGE is shown below: ::
Script here.
@@ -302,7 +302,7 @@ Currently, the following Check Extensions are available and installed by default
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**
- The cache hit ratio for the cache in the last 15 minutes (the interval is determined by the cron entry).
+ The cache hit ratio for the cache in the last 15 minutes (the interval is determined by the cron entry).
**DiffServe 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)
@@ -311,23 +311,23 @@ Currently, the following Check Extensions are available and installed by default
Checks if the Traffic Ops host (if that is the one running the check) can send and receive 8192 size packets to the ``ip_address`` of the server in the server table.
**Operational Readiness Check - ORT**
- See :ref:`reference-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.
+ 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.
**Ping Check - 10G, ILO, 10G6, FQDN**
The bin/checks/ToPingCheck.pl is to check 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 pingable?
ILO
Is the ``ilo_ip_address`` (the lights-out-mangement IPv4 address) from the server table pingable?
10G6
Is the ``ip6_address`` (the main IPv6 address) from the server table pingable?
- FQDN
+ FQDN
Is the Fully Qualified Domain name (the concatenation of ``host_name`` and ``.`` and ``domain_name`` from the server table) pingable?
**Traffic Router Check - RTR**
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")
-
+
Configuration Extensions
------------------------
diff --git a/docs/source/development/traffic_router.rst b/docs/source/development/traffic_router.rst
index 5bdae89c0..09f722026 100644
--- a/docs/source/development/traffic_router.rst
+++ b/docs/source/development/traffic_router.rst
@@ -1,24 +1,24 @@
-..
-..
+..
+..
.. 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 Router
**************
Introduction
============
Traffic Router is a Java Tomcat application that routes clients to the closest available cache on the CDN using both HTTP and DNS. Cache availability is determined by Traffic Monitor; consequently Traffic Router polls Traffic Monitor for its configuration and cache health state information, and uses this data to make routing decisions. HTTP routing is performed by localizing the client based on the request's source IP address (IPv4 or IPv6), and issues an HTTP 302 redirect to the nearest cache. HTTP routing utilizes consistent hashing on request URLs to optimize cache performance and request distribution. DNS routing is performed by localizing clients, resolvers in most cases, requesting ``A`` and ``AAAA`` records for a configurable name such as ``foo.deliveryservice.somecdn.net``. Traffic Router is comprised of seven separate Maven modules:
-
+
* shared - A reusable utility JAR for defining Delivery Service Certificates
* configuration - A resuable JAR defining the ConfigurationListener interface
* connector - A JAR that overrides Tomcat's standard Http11Protocol Connector class and allows Traffic Router to delay opening listen sockets until it is in a state suitable for routing traffic
@@ -68,7 +68,7 @@ Traffic Router Project Tree Overview
* ``var/auto-zones`` - BIND formatted zone files generated by Traffic Router Core during unit testing
-Java Formatting Conventions
+Java Formatting Conventions
===========================
None at this time. The codebase will eventually be formatted per Java standards.
@@ -148,9 +148,9 @@ This will create the traffic_router.rpm and the tomcat.rpm and copy them to the
API
===
-:ref:`reference-tr-api`
+:ref:`tr-api`
-.. toctree::
+.. toctree::
:hidden:
:maxdepth: 1
diff --git a/docs/source/development/traffic_router/traffic_router_api.rst b/docs/source/development/traffic_router/traffic_router_api.rst
index f56ca2e10..e98774d87 100644
--- a/docs/source/development/traffic_router/traffic_router_api.rst
+++ b/docs/source/development/traffic_router/traffic_router_api.rst
@@ -13,7 +13,7 @@
.. limitations under the License.
..
-.. _reference-tr-api:
+.. _tr-api:
Traffic Router API
diff --git a/docs/source/faq/administration.rst b/docs/source/faq/administration.rst
index e9060f44b..277633f7e 100644
--- a/docs/source/faq/administration.rst
+++ b/docs/source/faq/administration.rst
@@ -1,48 +1,48 @@
-..
-..
+..
+..
.. 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.
-..
+..
Running a Traffic Control CDN
*****************************
-.. _rl-cachegroup:
+.. _cachegroup:
Cache Group
-------------------
- A cache group is a logical group of caches that Traffic Router tries to use as a combined cache. Traffic Router treats all servers in a cache group as though they are in the same physical location, though they are in fact only in the same region (network). A cache group has one single set of geographical coordinates even if the caches that make up the cache group are in different physical locations. The caches in a cache group are not aware of the other caches in the group - there is no clustering software or communications between caches in a cache group.
+ A cache group is a logical group of caches that Traffic Router tries to use as a combined cache. Traffic Router treats all servers in a cache group as though they are in the same physical location, though they are in fact only in the same region (network). A cache group has one single set of geographical coordinates even if the caches that make up the cache group are in different physical locations. The caches in a cache group are not aware of the other caches in the group - there is no clustering software or communications between caches in a cache group.
- There are two types of cache groups: EDGE and MID. Traffic Control is a two tier system, where the clients get directed to the EDGE cache group. On cache miss, the cache in the EDGE cache group obtains content from a MID cache group, rather than the origin, which is shared with multiple EDGEs. EDGE cache groups are configured to have one single parent cache group.
+ There are two types of cache groups: EDGE and MID. Traffic Control is a two tier system, where the clients get directed to the EDGE cache group. On cache miss, the cache in the EDGE cache group obtains content from a MID cache group, rather than the origin, which is shared with multiple EDGEs. EDGE cache groups are configured to have one single parent cache group.
- .. Note:: Often the EDGE to MID relationship is based on network distance, and does not necessarily match the geographic distance.
+ .. Note:: Often the EDGE to MID relationship is based on network distance, and does not necessarily match the geographic distance.
- A cache group serves a particular part of the network as defined in the coverage zone file. See :ref:`rl-asn-czf`.
+ A cache group serves a particular part of the network as defined in the coverage zone file. See :ref:`asn-czf`.
Consider the example CDN below:
.. image:: cache_groups_1.png
:align: center
- There are two MID tier cache groups, each assigned with three EDGEs. The lax, den and chi EDGE locations are configured with the West MID as their parent, and the nyc, phl, and hou EDGEs, are configured with the East MID as their parent. On a cache miss, the EDGEs use their assigned parent.
+ There are two MID tier cache groups, each assigned with three EDGEs. The lax, den and chi EDGE locations are configured with the West MID as their parent, and the nyc, phl, and hou EDGEs, are configured with the East MID as their parent. On a cache miss, the EDGEs use their assigned parent.
-All caches (and other servers) are assigned a Profile in Traffic Ops.
+All caches (and other servers) are assigned a Profile in Traffic Ops.
-.. _rl-profile:
+.. _profile:
Profile
---------------
- A Profile is a set of configuration settings and parameters, applied to a server or deliveryservice. For a typical cache there are hundreds of configuration settings to apply. The Traffic Ops parameter view contains the defined settings, and bundled into groups using Profiles. Traffic Ops allows for duplication, comparison, import and export of Profiles.
+ A Profile is a set of configuration settings and parameters, applied to a server or deliveryservice. For a typical cache there are hundreds of configuration settings to apply. The Traffic Ops parameter view contains the defined settings, and bundled into groups using Profiles. Traffic Ops allows for duplication, comparison, import and export of Profiles.
@@ -78,7 +78,7 @@ Why is my CRConfig.json rejected?
You will need to enter at least one Traffic Router - make sure to change the server status to *ONLINE*.
* Add Edges
- You will need at least one edge cache to make Traffic Router accept the CRConfig.
+ You will need at least one edge cache to make Traffic Router accept the CRConfig.
* Add Mid
Technically you don't need a mid tier, but if you have one, best to enter the info before continuing.
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index a9325796e..2871cf705 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -21,61 +21,61 @@ Glossary
.. glossary::
302 content routing
- :ref:`rl-http-cr`.
+ :ref:`http-cr`.
astats (stats_over_http)
- An ATS plugin that allows you to monitor vitals of the ATS server. See :ref:`rl-astats`.
+ An ATS plugin that allows you to monitor vitals of the ATS server. See :ref:`astats`.
cache
- A caching proxy server. See :ref:`rl-caching_proxy`.
+ A caching proxy server. See :ref:`caching_proxy`.
cachegroup
- A group of caches that together create a combined larger cache using consistent hashing. See :ref:`rl-cachegroup`.
+ A group of caches that together create a combined larger cache using consistent hashing. See :ref:`cachegroup`.
consistent hashing
- See `the Wikipedia article <http://en.wikipedia.org/wiki/Consistent_hashing>`_; Traffic Control uses consistent hashing when using :ref:`rl-http-cr` for the edge tier and when selecting parents in the mid tier.
+ See `the Wikipedia article <http://en.wikipedia.org/wiki/Consistent_hashing>`_; Traffic Control uses consistent hashing when using :ref:`http-cr` for the edge tier and when selecting parents in the mid tier.
content routing
- Directing clients (or client systems) to a particular location or device in a location for optimal delivery of content See also :ref:`rl-http-cr` and :ref:`rl-dns-cr`.
+ Directing clients (or client systems) to a particular location or device in a location for optimal delivery of content See also :ref:`http-cr` and :ref:`dns-cr`.
coverage zone map
- The coverage zone map (czm) or coverage zone file (zcf) is a file that maps network prefixes to cachegroups. See :ref:`rl-localization`.
+ The coverage zone map (czm) or coverage zone file (zcf) is a file that maps network prefixes to cachegroups. See :ref:`localization`.
delivery service
- A grouping of content in the CDN, usually a determined by the URL hostname. See :ref:`rl-ds`.
+ A grouping of content in the CDN, usually a determined by the URL hostname. See :ref:`ds`.
edge (tier or cache)
- Closest to the client or end-user. The edge tier is the tier that serves the client, edge caches are caches in the edge tier. In a Traffic Control CDN the basic function of the edge cache is that of a :ref:`rl-rev-proxy`. See also :ref:`rl-cachegroup`.
+ Closest to the client or end-user. The edge tier is the tier that serves the client, edge caches are caches in the edge tier. In a Traffic Control CDN the basic function of the edge cache is that of a :ref:`rev-proxy`. See also :ref:`cachegroup`.
- (traffic ops) extension
- Using *extensions*, Traffic Ops be extended to use proprietary checks or monitoring sources. See :ref:`rl-trops-ext`.
+ (traffic ops) extension
+ Using *extensions*, Traffic Ops be extended to use proprietary checks or monitoring sources. See :ref:`trops-ext`.
forward proxy
- A proxy that works that acts like it is the client to the origin. See :ref:`rl-fwd-proxy`.
+ A proxy that works that acts like it is the client to the origin. See :ref:`fwd-proxy`.
geo localization or geo routing
- Localizing clients to the nearest caches using a geo database like the one from Maxmind.
+ Localizing clients to the nearest caches using a geo database like the one from Maxmind.
health protocol
- The protocol to monitor the health of all the caches. See :ref:`rl-health-proto`.
+ The protocol to monitor the health of all the caches. See :ref:`health-proto`.
localization
- Finding location on the network, or on planet earth. See :ref:`rl-localization`.
+ Finding location on the network, or on planet earth. See :ref:`localization`.
mid (tier or cache)
- The tier above the edge tier. The mid tier does not directly serves the end-user and is used as an additional layer between the edge and the origin. In a Traffic Control CDN the basic function of the mid cache is that of a :ref:`rl-fwd-proxy`. See also :ref:`rl-cachegroup`.
+ The tier above the edge tier. The mid tier does not directly serves the end-user and is used as an additional layer between the edge and the origin. In a Traffic Control CDN the basic function of the mid cache is that of a :ref:`fwd-proxy`. See also :ref:`cachegroup`.
origin
The source of content for the CDN. Usually a redundant HTTP/1.1 webserver.
parent (cache or cachegroup)
- The (group of) cache(s) in the higher tier. See :ref:`rl-cachegroup`.
+ The (group of) cache(s) in the higher tier. See :ref:`cachegroup`.
profile
- A group of settings (parameters) that will be applied to a server. See :ref:`rl-profile`.
+ A group of settings (parameters) that will be applied to a server. See :ref:`profile`.
reverse proxy
- A proxy that acts like it is the origin to the client. See :ref:`rl-rev-proxy`.
+ A proxy that acts like it is the origin to the client. See :ref:`rev-proxy`.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 4f9782547..75b5cccda 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,31 +1,31 @@
-..
-..
+..
+..
.. 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 Control
%%%%%%%%%%%%%%%
-The vast majority of today's Internet traffic is media files being sent from a single source to many thousands or even millions of destinations. Content Delivery Networks make that one-to-many distribution possible in an economical way.
+The vast majority of today's Internet traffic is media files being sent from a single source to many thousands or even millions of destinations. Content Delivery Networks make that one-to-many distribution possible in an economical way.
-Traffic Control is an Open Source implementation of a Content Delivery Network.
+Traffic Control is an Open Source implementation of a Content Delivery Network.
The following documentation sections are available:
CDN Basics
==========
-A review of the basic functionality of a Content Delivery Network.
+A review of the basic functionality of a Content Delivery Network.
.. toctree::
:maxdepth: 2
diff --git a/docs/source/overview/index.rst b/docs/source/overview/index.rst
index 865d34431..60d0e970c 100644
--- a/docs/source/overview/index.rst
+++ b/docs/source/overview/index.rst
@@ -1,29 +1,29 @@
-..
-..
+..
+..
.. 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 Control Overview
************************
Introduces the Traffic Control architecture, components, and their integration.
.. toctree::
- :maxdepth: 2
+ :maxdepth: 2
- introduction.rst
- traffic_ops
- traffic_portal
- traffic_router
- traffic_monitor
- traffic_stats
- traffic_vault
+ introduction.rst
+ traffic_ops
+ traffic_portal
+ traffic_router
+ traffic_monitor
+ traffic_stats
+ traffic_vault
diff --git a/docs/source/overview/introduction.rst b/docs/source/overview/introduction.rst
index 2789b4655..bc6599412 100644
--- a/docs/source/overview/introduction.rst
+++ b/docs/source/overview/introduction.rst
@@ -1,49 +1,47 @@
-..
-..
+..
+..
.. 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
-..
+..
+.. 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.
-..
+..
Introduction
============
-Traffic Control is a caching server control plane application which is used to aggregate caching servers into a Content Delivery Network (CDN). The CDN caching software chosen for Traffic Control is `Apache Traffic Server <http://trafficserver.apache.org/>`_ (ATS). Although the current release only supports ATS as a cache, this may change with future releases.
+Traffic Control is a caching server control plane application which is used to aggregate caching servers into a Content Delivery Network (CDN). In principle, a CDN may be implemented with any HTTP caching proxy. The caching software chosen for Traffic Control is `Apache Traffic Server <http://trafficserver.apache.org/>`_ (ATS). Although the current release only supports ATS as a cache, this may change with future releases.
Traffic Control was first developed at Comcast for internal use and released to Open Source in April of 2015. Traffic Control moved into the Apache Incubator in August of 2016.
-Traffic Control implements the elements illustrated in green in the diagram below.
+Traffic Control implements the elements illustrated in green in the diagram below.
.. image:: traffic_control_overview_3.png
:align: center
-**Traffic Ops**
- * `Traffic Ops <http://trafficcontrol.apache.org/docs/latest/overview/traffic_ops.html/>`_ is used to configure caching servers and CDN delivery services. It also contains APIs used to access CDN data.
+Traffic Ops
+ `Traffic Ops <http://trafficcontrol.apache.org/docs/latest/overview/traffic_ops.html/>`_ is used to configure caching servers and CDN delivery services. It also contains APIs used to access CDN data. Traffic Ops provides a UI for interacting with the CDN(s) that it manages, which is considered legacy as of Traffic Control 2.2, deprecated in 3.0, and will be removed by 4.0.
-**Traffic Router**
- * `Traffic Router <http://trafficcontrol.apache.org/docs/latest/overview/traffic_router.html/>`_ is used to route clients requests to the closest healthy cache by analyzing the health, capacity, and state of the caching servers and relative distance from each cache group to the location of the client.
+Traffic Router
+ `Traffic Router <http://trafficcontrol.apache.org/docs/latest/overview/traffic_router.html/>`_ is used to route clients requests to the closest healthy cache by analyzing the health, capacity, and state of the caching servers and relative distance from each cache group to the location of the client.
-**Traffic Monitor**
- * `Traffic Monitor <http://trafficcontrol.apache.org/docs/latest/overview/traffic_monitor.html/>`_ does health polling of the caching servers on a very short interval to keep track of which servers should be kept in rotation.
+Traffic Monitor
+ `Traffic Monitor <http://trafficcontrol.apache.org/docs/latest/overview/traffic_monitor.html/>`_ does health polling of the caching servers on a very short interval to keep track of which servers should be kept in rotation.
-**Traffic Stats**
- * `Traffic Stats <http://trafficcontrol.apache.org/docs/latest/overview/traffic_stats.html/>`_ collects real time traffic statistics aggregated from each of the caching servers. This data is used by the Traffic Router to assess the available capacity of each caching server which it uses to balance traffic load and prevent overload.
+Traffic Stats
+ `Traffic Stats <http://trafficcontrol.apache.org/docs/latest/overview/traffic_stats.html/>`_ collects real time traffic statistics aggregated from each of the caching servers. This data is used by the Traffic Router to assess the available capacity of each caching server which it uses to balance traffic load and prevent overload.
-**Traffic Portal**
- * `Traffic Portal <http://trafficcontrol.apache.org/docs/latest/overview/traffic_portal.html/>`_ is a web application which leverages the Traffic Ops APIs to present CDN data through a web interface.
-
-**Traffic Logs**
- * Traffic Logs is currently under construction and is intended to aggregate Traffic Server request/response logs as well as other server logs. Logs will be parsed and indexed for search.
+Traffic Portal
+ `Traffic Portal <http://trafficcontrol.apache.org/docs/latest/overview/traffic_portal.html/>`_ is a web application which leverages the Traffic Ops APIs to present CDN data through a web interface. As of Traffic Control 2.2, this is the recommended, official UI for the Traffic Control platform. In Traffic Control 3.x, the Traffic Ops UI has been deprecated, and it will be removed with the release of Traffic Control 4.0.
+Traffic Logs
+ Traffic Logs is currently under construction and is intended to aggregate Traffic Server request/response logs as well as other server logs. Logs will be parsed and indexed for search.
In the next sections each of these components will be explained further.
-
diff --git a/docs/source/overview/traffic_monitor.rst b/docs/source/overview/traffic_monitor.rst
index d97bdddb5..eefb67c8f 100644
--- a/docs/source/overview/traffic_monitor.rst
+++ b/docs/source/overview/traffic_monitor.rst
@@ -1,19 +1,19 @@
-..
-..
+..
+..
.. 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.
-..
+..
-.. _reference-label-tc-tm:
+.. _tc-tm:
.. index::
Traffic Monitor - Overview
@@ -24,43 +24,43 @@ Traffic Monitor
===============
Traffic Monitor is an HTTP service that monitors the caches in a CDN for a variety of metrics. These metrics are for use in determining the overall health of a given cache and the related delivery services. A given CDN can operate a number of Traffic Monitors, from a number of geographically diverse locations, to prevent false positives caused by network problems at a given site.
-Traffic Monitors operate independently, but use the state of other Traffic Monitors in conjunction with their own state, to provide a consistent view of CDN cache health to upstream applications such as Traffic Router. Health Protocol governs the cache and Delivery Service availability.
+Traffic Monitors operate independently, but use the state of other Traffic Monitors in conjunction with their own state, to provide a consistent view of CDN cache health to upstream applications such as Traffic Router. Health Protocol governs the cache and Delivery Service availability.
Traffic Monitor provides a view into CDN health using several RESTful JSON endpoints, which are consumed by other Traffic Monitors and upstream components such as Traffic Router. Traffic Monitor is also responsible for serving the overall CDN configuration to Traffic Router, which ensures that the configuration of these two critical components remain synchronized as operational and health related changes propagate through the CDN.
-.. _rl-astats:
+.. _astats:
|arrow| Cache Monitoring
-------------------------
- Traffic Monitor polls all caches configured with a status of ``REPORTED`` or ``ADMIN_DOWN`` at an interval specified as a configuration parameter in Traffic Ops. If the cache is set to ``ADMIN_DOWN`` it is marked as unavailable but still polled for availability and statistics. If the cache is explicitly configured with a status of ``ONLINE`` or ``OFFLINE``, it is not polled by Traffic Monitor and presented to Traffic Router as configured, regardless of actual availability.
+Traffic Monitor polls all caches configured with a status of ``REPORTED`` or ``ADMIN_DOWN`` at an interval specified as a configuration parameter in Traffic Ops. If the cache is set to ``ADMIN_DOWN`` it is marked as unavailable but still polled for availability and statistics. If the cache is explicitly configured with a status of ``ONLINE`` or ``OFFLINE``, it is not polled by Traffic Monitor and presented to Traffic Router as configured, regardless of actual availability.
- Traffic Monitor makes HTTP requests at regular intervals to a special URL on each EDGE cache and consumes the JSON output. The special URL is a plugin running on the Apache Traffic Server (ATS) caches called astats, which is restricted to Traffic Monitor only. The astats plugin provides insight into application and system performance, such as:
+Traffic Monitor makes HTTP requests at regular intervals to a special URL on each EDGE cache and consumes the JSON output. The special URL is a plugin running on the Apache Traffic Server (ATS) caches called astats, which is restricted to Traffic Monitor only. The astats plugin provides insight into application and system performance, such as:
- - Throughput (e.g. bytes in, bytes out, etc).
- - Transactions (e.g. number of 2xx, 3xx, 4xx responses, etc).
- - Connections (e.g. from clients, to parents, origins, etc).
- - Cache performance (e.g.: hits, misses, refreshes, etc).
- - Storage performance (e.g.: writes, reads, frags, directories, etc).
- - System performance (e.g: load average, network interface throughput, etc).
+- Throughput (e.g. bytes in, bytes out, etc).
+- Transactions (e.g. number of 2xx, 3xx, 4xx responses, etc).
+- Connections (e.g. from clients, to parents, origins, etc).
+- Cache performance (e.g.: hits, misses, refreshes, etc).
+- Storage performance (e.g.: writes, reads, frags, directories, etc).
+- System performance (e.g: load average, network interface throughput, etc).
- Many of the application level statistics are available at the global or aggregate level, some at the Delivery Service (remap rule) level. Traffic Monitor uses the system level performance to determine the overall health of the cache by evaluating network throughput and load against values configured in Traffic Ops. Traffic Monitor also uses throughput and transaction statistics at the remap rule level to determine Delivery Service health.
+Many of the application-level statistics are available at the global or aggregate level, some at the Delivery Service (remap rule) level. Traffic Monitor uses the system level performance to determine the overall health of the cache by evaluating network throughput and load against values configured in Traffic Ops. Traffic Monitor also uses throughput and transaction statistics at the remap rule level to determine Delivery Service health.
-If astats is unavailable due to a network related issue or the system statistics have exceeded the configured thresholds, Traffic Monitor will mark the cache as unavailable. If the delivery service statistics exceed the configured thresholds, the delivery service is marked as unavailable, and Traffic Router will start sending clients to the overflow destinations for that delivery service, but the cache remains available to serve other content,
+If astats is unavailable due to a network related issue or the system statistics have exceeded the configured thresholds, Traffic Monitor will mark the cache as unavailable. If the delivery service statistics exceed the configured thresholds, the delivery service is marked as unavailable, and Traffic Router will start sending clients to the overflow destinations for that delivery service, but the cache remains available to serve other content,
.. seealso:: For more information on ATS Statistics, see the `ATS documentation <https://docs.trafficserver.apache.org/en/latest/index.html>`_
-.. _rl-health-proto:
+.. _health-proto:
-|arrow| Health Protocol
+|arrow| Health Protocol
-----------------------
- Redundant Traffic Monitor servers operate independently from each other but take the state of other Traffic Monitors into account when asked for health state information. In the above overview of cache monitoring, the behavior of Traffic Monitor pertains only to how an individual instance detects and handles failures. The Health Protocol adds another dimension to the health state of the CDN by merging the states of all Traffic Monitors into one, and then taking the *optimistic* approach when dealing with a cache or Delivery Service that might have been marked as unavailable by this particular instance or a peer instance of Traffic Monitor.
+Redundant Traffic Monitor servers operate independently from each other but take the state of other Traffic Monitors into account when asked for health state information. In the above overview of cache monitoring, the behavior of Traffic Monitor pertains only to how an individual instance detects and handles failures. The Health Protocol adds another dimension to the health state of the CDN by merging the states of all Traffic Monitors into one, and then taking the *optimistic* approach when dealing with a cache or Delivery Service that might have been marked as unavailable by this particular instance or a peer instance of Traffic Monitor.
- Upon startup or configuration change in Traffic Ops, in addition to caches, Traffic Monitor begins polling its peer Traffic Monitors whose state is set to ``ONLINE``. Each ``ONLINE`` Traffic Monitor polls all of its peers at a configurable interval and saves the peer's state for later use. When polling its peers, Traffic Monitor asks for the raw health state from each respective peer, which is strictly that instance's view of the CDN's health. When any ``ONLINE`` Traffic Monitor is asked for CDN health by an upstream component, such as Traffic Router, the component gets the health protocol influenced version of CDN health (non-raw view).
+Upon startup or configuration change in Traffic Ops, in addition to caches, Traffic Monitor begins polling its peer Traffic Monitors whose state is set to ``ONLINE``. Each ``ONLINE`` Traffic Monitor polls all of its peers at a configurable interval and saves the peer's state for later use. When polling its peers, Traffic Monitor asks for the raw health state from each respective peer, which is strictly that instance's view of the CDN's health. When any ``ONLINE`` Traffic Monitor is asked for CDN health by an upstream component, such as Traffic Router, the component gets the health protocol influenced version of CDN health (non-raw view).
- In operation of the health protocol, Traffic Monitor takes all health states from all peers, including the locally known health state, and serves an optimistic outlook to the requesting client. This means that, for example, if three of the four Traffic Monitors see a given cache or Delivery Service as exceeding its thresholds and unavailable, it is still considered available. Only if all Traffic Monitors agree that the given object is unavailable is that state propagated to upstream components. This optimistic approach to the Health Protocol is counter to the "fail fast" philosophy, but serves well for large networks with complicated geography and or routing. The optimistic Health Protocol allows network failures or latency to occur without affecting overall traffic routing, as Traffic Monitors can and do have a different view of the network when deployed in geographically diverse locations. Short polling intervals of both the caches and Traffic Monitor peers help to reduce customer impact of outages.
+In operation of the health protocol, Traffic Monitor takes all health states from all peers, including the locally known health state, and serves an optimistic outlook to the requesting client. This means that, for example, if three of the four Traffic Monitors see a given cache or Delivery Service as exceeding its thresholds and unavailable, it is still considered available. Only if all Traffic Monitors agree that the given object is unavailable is that state propagated to upstream components. This optimistic approach to the Health Protocol is counter to the "fail fast" philosophy, but serves well for large networks with complicated geography and or routing. The optimistic Health Protocol allows network failures or latency to occur without affecting overall traffic routing, as Traffic Monitors can and do have a different view of the network when deployed in geographically diverse locations. Short polling intervals of both the caches and Traffic Monitor peers help to reduce customer impact of outages.
-It is not uncommon for a cache to be marked unavailable by Traffic Monitor - in fact, it is business as usual for many CDNs. A hot video asset may cause a single cache (say cache-03) to get close to it's interface capacity, the health protocol "kicks in", and Traffic Monitor marks cache-03 as unavailable. New clients want to see the same asset, and now, Traffic Router will send these customers to another cache (say cache-01) in the same cachegroup. The load is now shared between cache-01 and cache-03. As clients finish watching the asset on cache-03, it will drop below the threshold and gets marked available again, and new clients will now go back to cache-03 again.
+It is not uncommon for a cache to be marked unavailable by Traffic Monitor - in fact, it is business as usual for many CDNs. Should a widely requested video asset cause a single cache to get close to its interface capacity, the Health Protocol will "kicks in", and Traffic Monitor marks cache-03 as unavailable. New clients want to see the same asset, and now, Traffic Router will send these customers to another cache (say cache-01) in the same Cache Group. The load is now shared between cache-01 and cache-03. As clients finish watching the asset on cache-03, it will drop below the threshold and gets marked available again, and new clients will now go back to cache-03 again.
It is less common for a delivery service to be marked unavailable by Traffic Monitor, the delivery service thresholds are usually used for overflow situations at extreme peaks to protect other delivery services in the CDN from getting impacted.
diff --git a/docs/source/overview/traffic_ops.rst b/docs/source/overview/traffic_ops.rst
index b6ede6e23..84936b5f2 100644
--- a/docs/source/overview/traffic_ops.rst
+++ b/docs/source/overview/traffic_ops.rst
@@ -1,41 +1,43 @@
-..
-..
+..
+..
.. 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.
-..
-
-.. |arrow| image:: fwda.png
+..
Traffic Ops
===========
-Traffic Ops is the tool for administration (configuration and monitoring) of all components in a Traffic Control CDN. The CDN administrator uses Traffic Ops to manage servers, cache groups, delivery services, etc. In many cases, a configuration change requires propagation to several, or even all, caches and only explicitly after or before the same change propagates to Traffic Router. Traffic Ops takes care of this required consistency between the different components and their configuration. Traffic Ops exposes its data through a series of HTTP APIs and has a user interface that is interactive and viewable using a standard web browser.
+Traffic Ops is the tool for administration (configuration and monitoring) of all components in a Traffic Control CDN. Traffic Portal uses Traffic Ops APIs to manage servers, cache groups, delivery services, etc. In many cases, a configuration change requires propagation to several, or even all, caches and only explicitly after or before the same change propagates to Traffic Router. Traffic Ops takes care of this required consistency between the different components and their configuration. Traffic Ops exposes its data through a series of HTTP APIs. Traffic Ops also provides a legacy user interface that has been superseded by the Traffic Portal UI.
-Traffic Ops uses a PostgreSQL database to store the configuration information, and the `Mojolicious framework <http://mojolicio.us/>`_ and `Go <https://golang.org/>`_ to generate APIs used by the Traffic Portal. Not all configuration data is in this database however; for sensitive data like SSL private keys or token based authentication shared secrets, a separate key-value store is used, allowing the operator to harden the server that runs this key-value store better from a security perspective (i.e only allow Traffic Ops access it with a cert). The Traffic Ops server, by design, needs to be accessible from all the other servers in the Traffic Control CDN.
+Traffic Ops uses a PostgreSQL database to store the configuration information, and the `Mojolicious framework <http://mojolicio.us/>`_ and `Go <https://golang.org/>`_ to generate APIs used by the Traffic Portal. Not all configuration data is in this database however; for sensitive data like SSL private keys or token based authentication shared secrets, a separate key/value store is used, allowing the operator to harden the server that runs this key/value store better from a security perspective (i.e only allow Traffic Ops access it with a cert). The Traffic Ops server, by design, needs to be accessible from all the other servers in the Traffic Control CDN.
-Traffic Ops generates all the application specific configuration files for the caches and other servers. The caches and other servers check in with Traffic Ops at a regular interval (default 15 minutes) to see if updated configuration files require application.
+Traffic Ops generates all the application specific configuration files for the caches and other servers. The caches and other servers check in with Traffic Ops at a regular interval (default 15 minutes) to see if updated configuration files require application. This is done by the Traffic Ops Operations Readiness Test (ORT) script.
-Traffic Ops also runs a collection of periodic checks to determine the operational readiness of the caches. These periodic checks are customizable by the Traffic Ops admin using extensions.
+Traffic Ops also runs a collection of periodic checks to determine the operational readiness of the caches. These periodic checks are customizable by the Traffic Ops administrative user using extensions.
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.
-|
+.. _trops-ext:
+
+Traffic Ops Extension
+---------------------
+Traffic Ops Extensions are a way to enhance the basic functionality of Traffic Ops in a custom manner. There are two types of extensions:
-.. _rl-trops-ext:
+:ref:`to-check-ext`
+ Allow you to add custom checks to the 'Monitor' -> 'Cache Checks' view.
-|arrow| Traffic Ops Extension
------------------------------
- Traffic Ops Extensions are a way to enhance the basic functionality of Traffic Ops in a custom manner. There are three types of extensions:
+:ref:`to-datasource-ext`
+ Allow you to add data sources for the graph views and usage APIs.
- * Check Extensions - Allows you to add custom checks to the "Health->Server Checks" view.
- * Configuration Extension - Allows you to add custom configuration file generators.
- * Data source Extensions - Allows you to add data sources for the graph views and usage APIs.
+.. These are listed as "in beta" as far back as TO 1.0, sooo
+.. Configuration Extension
+.. Allows you to add custom configuration file generators.
diff --git a/docs/source/overview/traffic_portal.rst b/docs/source/overview/traffic_portal.rst
index ae455b632..c985159b8 100644
--- a/docs/source/overview/traffic_portal.rst
+++ b/docs/source/overview/traffic_portal.rst
@@ -1,23 +1,24 @@
-..
-..
+..
+..
.. 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 Portal - Overview
-
+
Traffic Portal
==============
+
Traffic Portal is an `AngularJS 1.x <https://angularjs.org/>`_ client served from a `Node.js <https://nodejs.org/en/>`_ web server designed to consume the Traffic Ops API. It is the official replacement for the legacy Traffic Ops UI.
Features include:
@@ -28,6 +29,3 @@ Features include:
- Cache Maintenance
See :ref:`usingtrafficportal`
-
-
-
diff --git a/docs/source/overview/traffic_router.rst b/docs/source/overview/traffic_router.rst
index e85ad3220..d466e8a8a 100644
--- a/docs/source/overview/traffic_router.rst
+++ b/docs/source/overview/traffic_router.rst
@@ -1,28 +1,28 @@
-..
-..
+..
+..
.. 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.
-..
+..
-.. _reference-label-tc-tr:
+.. _tc-tr:
.. |arrow| image:: fwda.png
.. index::
- Traffic Router - Overview
+ Traffic Router - Overview
Traffic Router
==============
-Traffic Router's function is to send clients to the most optimal cache. Optimal in this case is based on a number of factors:
+Traffic Router's function is to send clients to the most optimal cache. 'Optimal' in this case is based on a number of factors:
* Distance between the cache and the client (not necessarily measured in meters, but quite often in layer 3 network hops). Less network distance between the client and cache yields better performance, and lower network load. Traffic Router helps clients connect to the best performing cache for their location at the lowest network cost.
@@ -30,80 +30,73 @@ Traffic Router's function is to send clients to the most optimal cache. Optimal
* Availability of content on a particular cache. Reusing of content through cache HITs is the most important performance gain a CDN can offer. Traffic Router sends clients to the cache that is most likely to already have the desired content.
-Traffic routing options are often configured at the Delivery Service level.
+Traffic routing options are often configured at the Delivery Service level.
-|
-
-
-.. _rl-ds:
+.. _ds:
|arrow| Delivery Service
------------------------
- As discussed in the basic concepts section, the EDGE caches are configured as reverse proxies, and the Traffic Control CDN looks from the outside as a very large reverse proxy. Delivery Services are often referred to a reverse proxy remap rule. In most cases, a Delivery Service is a one to one mapping to a FQDN that is used as a hostname to deliver the content. Many options and settings regarding how to optimize the content delivery, which is configurable on a Delivery Service basis. Some examples of these Delivery Service settings are:
+ As discussed in the basic concepts section, the EDGE caches are configured as reverse proxies, and the Traffic Control CDN looks from the outside as a very large reverse proxy. Delivery Services are often referred to a reverse proxy remap rule. In most cases, a Delivery Service is a one to one mapping to a FQDN that is used as a hostname to deliver the content. Many options and settings regarding how to optimize the content delivery, which is configurable on a Delivery Service basis. Some examples of these Delivery Service settings are:
- * Cache in RAM, cache on disk, or do not cache at all.
- * Use DNS or HTTP Content routing (see below).
- * Limits on transactions per second and bandwidth.
- * Protocol (http or https).
- * Token based authentication settings.
- * Header rewrite rules.
+ * Cache in RAM, cache on disk, or do not cache at all.
+ * Use DNS or HTTP Content routing (see below).
+ * Limits on transactions per second and bandwidth.
+ * Protocol (HTTP or HTTPS).
+ * Token based authentication settings.
+ * Header rewrite rules.
- Since Traffic Control version 2.1 deliveryservices can optionally be linked to a :ref:`rl-profile`, and have parameters associated with them. The first feature that uses deliveryservice parameters is the :ref:`rl-multi-site-origin` configuration.
- Delivery Services are also for use in allowing multi-tenants to coexist in the Traffic Control CDN without interfering with each other, and to keep information about their content separated.
+ Since Traffic Control version 2.1 Delivery Services can optionally be linked to a :ref:`profile`, and have parameters associated with them. The first feature that uses Delivery Service parameters is the :ref:`multi-site-origin` configuration.
+ Delivery Services are also for use in allowing multi-tenants to coexist in the Traffic Control CDN without interfering with each other, and to keep information about their content separated.
-|
-
-.. _rl-localization:
+.. _localization:
|arrow| Localization
--------------------
- Traffic Router uses a JSON input file called the *coverage zone map* to determine what *cachegroup* is closest to the client. If the client IP address is not in this coverage zone map, it falls back to *geo*, using the maxmind database to find the client's location, and the geo coordinates from Traffic Ops for the cachegroup.
-
-|
+ Traffic Router uses a JSON input file called the *coverage zone map* to determine what *Cache Group* is closest to the client. If the client IP address is not in this coverage zone map, it falls back to geographic mapping, using a GeoIP2 database to find the client's location, and the geographic coordinates from Traffic Ops for the Cache Group.
-Traffic Router is inserted into the HTTP retrieval process by making it DNS authoritative for the domain of the CDN delivery service. In the example of the reverse proxy, the client was given the ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` url. In a Traffic Control CDN, URLs start with a routing name, which is configurable per-Delivery Service, e.g. ``http://foo.mydeliveryservice.cdn.com/fun/example.html`` with the chosen routing name ``foo``.
-
-|
+Traffic Router is inserted into the HTTP retrieval process by making it DNS authoritative for the domain of the CDN delivery service. In the example of the reverse proxy, the client was given the ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` URL. In a Traffic Control CDN, URLs start with a routing name, which is configurable per-Delivery Service, e.g. ``http://foo.mydeliveryservice.cdn.com/fun/example.html`` with the chosen routing name ``foo``.
.. index::
- Content Routing
+ Content Routing
-.. _rl-dns-cr:
+.. _dns-cr:
|arrow| DNS Content Routing
---------------------------
- For a DNS delivery service the client might receive a URL such as ``http://foo.dsname.cdn.com/fun/example.html``. When the LDNS server is resolving this ``foo.dsname.cdn.com`` hostname to an IP address, it ends at Traffic Router because it is the authoritative DNS server for ``cdn.com`` and the domains below it, and subsequently responds with a list of IP addresses from the eligible caches based on the location of the LDNS server. When responding, Traffic Router does not know the actual client IP address or the path that the client is going to request. The decision on what cache IP address (or list of cache IP addresses) to return is solely based on the location of the LDNS server and the health of the caches. The client then connects to port 80 on the cache, and sends the ``Host: foo.dsname.cdn.com`` header. The configuration of the cache includes the remap rule ``http://foo.dsname.cdn.com http://origin.dsname.com`` to map the routed name to an origin hostname.
-
-|
+ For a DNS Delivery Service the client might receive a URL such as ``http://foo.dsname.cdn.com/fun/example.html``. When the Local Domain Name Server (LDNS) server is resolving this ``foo.dsname.cdn.com`` hostname to an IP address, it ends at Traffic Router because it is the authoritative DNS server for ``cdn.com`` and the domains below it, and subsequently responds with a list of IP addresses from the eligible caches based on the location of the LDNS server. When responding, Traffic Router does not know the actual client IP address or the path that the client is going to request. The decision on what cache IP address (or list of cache IP addresses) to return is solely based on the location of the LDNS server and the health of the caches. The client then connects to port 80 on the cache, and sends the ``Host: foo.dsname.cdn.com`` header. The configuration of the cache includes the remap rule ``http://foo.dsname.cdn.com http://origin.dsname.com`` to map the routed name to an origin hostname.
-.. _rl-http-cr:
+.. _http-cr:
|arrow| HTTP Content Routing
----------------------------
- For an HTTP delivery service the client might receive a URL such as ``http://bar.dsname.cdn.com/fun/example.html``. The LDNS server resolves this ``bar.dsname.cdn.com`` to an IP address, but in this case Traffic Router returns its own IP address. The client opens a connection to port 80 on the Traffic Router's IP address, and sends: ::
+ For an HTTP Delivery Service the client might receive a URL such as ``http://bar.dsname.cdn.com/fun/example.html``. The LDNS server resolves this ``bar.dsname.cdn.com`` to an IP address, but in this case Traffic Router returns its own IP address. The client opens a connection to port 80 on the Traffic Router's IP address, and sends:
+
+ .. code-block:: http
+
+ GET /fun/example.html HTTP/1.1
+ Host: bar.dsname.cdn.com
- GET /fun/example.html HTTP/1.1
- Host: bar.dsname.cdn.com
+ Traffic Router uses an HTTP 302 to redirect the client to the best cache. For example:
- Traffic Router uses an HTTP 302 to redirect the client to the best cache. For example: ::
+ .. code-block:: http
- HTTP/1.1 302 Moved Temporarily
- Server: Apache-Coyote/1.1
- Location: http://atsec-nyc-02.dsname.cdn.com/fun/example.html
- Content-Length: 0
- Date: Tue, 13 Jan 2015 20:01:41 GMT
+ HTTP/1.1 302 Moved Temporarily
+ Server: Apache-Coyote/1.1
+ Location: http://atsec-nyc-02.dsname.cdn.com/fun/example.html
+ Content-Length: 0
+ Date: Tue, 13 Jan 2015 20:01:41 GMT
- The information Traffic Router can consider when selecting a cache in this case is much better:
+ The information Traffic Router can consider when selecting a cache in this case is much better:
- * The client's IP address (the other side of the socket).
- * The URL path the client is requesting, excluding query string.
- * All HTTP 1.1 headers.
+ * The client's IP address (the other side of the socket).
+ * The URL path the client is requesting, excluding query string.
+ * All HTTP 1.1 headers.
- The client follows the redirect and performs a DNS request for the IP address for ``atsec-nyc-02.dsname.cdn.com``, and normal HTTP steps follow, except the sending of the Host: header when connected to the cache is ``Host: atsec-nyc-02.dsname.cdn``, and the configuration of the cache includes the remap rule (e.g.``http://atsec-nyc-02.dsname.cdn http://origin.dsname.com``).
+ The client follows the redirect and performs a DNS request for the IP address for ``atsec-nyc-02.dsname.cdn.com``, and normal HTTP steps follow, except the sending of the Host: header when connected to the cache is ``Host: atsec-nyc-02.dsname.cdn``, and the configuration of the cache includes the remap rule (e.g.``http://atsec-nyc-02.dsname.cdn http://origin.dsname.com``).
- Traffic Router sends all requests for the same path in a delivery service to the same cache in a cache group using consistent hashing, in this case all caches in a cache group are not carrying the same content, and there is a much larger combined cache in the cache group.
+ Traffic Router sends all requests for the same path in a delivery service to the same cache in a cache group using consistent hashing, in this case all caches in a cache group are not carrying the same content, and there is a much larger combined cache in the cache group.
-In many cases DNS content routing is the best possible option, especially in cases where the client is receiving small objects from the CDN like images and web pages.
+In many cases DNS content routing is the best possible option, especially in cases where the client is receiving small objects from the CDN like images and web pages.
Traffic Router is redundant and horizontally scalable by adding more instances into the DNS hierarchy using NS records.
diff --git a/docs/source/overview/traffic_stats.rst b/docs/source/overview/traffic_stats.rst
index 10981deb8..debf5a036 100644
--- a/docs/source/overview/traffic_stats.rst
+++ b/docs/source/overview/traffic_stats.rst
@@ -13,23 +13,36 @@
.. limitations under the License.
..
-.. _reference-label-tc-ts:
+.. _tc-ts:
.. |arrow| image:: fwda.png
Traffic Stats
=============
-Traffic Stats is a program written in `Golang <http://golang.org>`_ that is used to acquire and store statistics about CDNs controlled by Traffic Control. Traffic Stats mines metrics from Traffic Monitor's JSON APIs and stores the data in `InfluxDb <http://influxdb.com>`_. Data is typically stored in InfluxDb on a short-term basis (30 days or less). The data from InfluxDb is then used to drive graphs created by `Grafana <http://grafana.org>`_ - which are linked to from Traffic Ops - as well as provide data exposed through the Traffic Ops API. Traffic Stats performs two functions: first it gathers stat data for Edge Caches and Delivery Services at a configurable interval (10 second default) from the Traffic Monitor API's and stores the data in InfluxDb; second it summarizes all of the stats once a day (around midnight UTC) and creates a daily rollup containing the Max Gbps served and the Total Bytes served.
+Traffic Stats is a program written in `Go <http://golang.org>`_ that is used to acquire and store statistics about CDNs controlled by Traffic Control. Traffic Stats mines metrics from Traffic Monitor's JSON APIs and stores the data in `InfluxDB <http://influxdb.com>`_. Data is typically stored in InfluxDB on a short-term basis (30 days or less). The data from InfluxDB is then used to drive graphs created by `Grafana <http://grafana.org>`_ - which are linked to from Traffic Ops - as well as provide data exposed through the Traffic Ops API. Traffic Stats performs two functions:
+
+- Gathers stat data for Edge Caches and Delivery Services at a configurable interval (10 second default) from the Traffic Monitor API's and stores the data in InfluxDB
+- Summarizes all of the stats once a day (around midnight UTC) and creates a daily report containing the Max Gbps Served and the Total Bytes Served.
Stat data is stored in three different databases:
- - cache_stats: The cache_stats database is used to store data gathered from edge caches. The `measurements <https://influxdb.com/docs/v0.9/concepts/glossary.html#measurement>`_ stored by cache are: bandwidth, maxKbps, and client_connections (ats.proxy.process.http.current_client_connections). Cache Data is stored with `tags <https://influxdb.com/docs/v0.9/concepts/glossary.html#tag>`_ for hostname, cachegroup, and CDN. Data can be queried using tags.
+ - ``cache_stats``: Stores data gathered from edge caches. The `measurements <https://influxdb.com/docs/v0.9/concepts/glossary.html#measurement>`_ stored by cache are: bandwidth, maxKbps, and ``client_connections`` (``ats.proxy.process.http.current_client_connections``). Cache Data is stored with `tags <https://influxdb.com/docs/v0.9/concepts/glossary.html#tag>`_ for hostname, Cache Group, and CDN. Data can be queried using tags.
+
+ - ``deliveryservice_stats``: Stores data for Delivery Services. The measurements stored by delivery service are:
+ - ``kbps``
+ - ``status_4xx``
+ - ``status_5xx``
+ - ``tps_2xx``
+ - ``tps_3xx``
+ - ``tps_4xx``
+ - ``tps_5xx``
+ - ``tps_total``
- - deliveryservice_stats: The deliveryservice_stats database is used to store data for delivery services. The measurements stored by delivery service are: kbps, status_4xx, status_5xx, tps_2xx, tps_3xx, tps_4xx, tps_5xx, and tps_total. Delivery Service stats are stored with tags for cachegroup, CDN, and Deliveryservice xml_id.
+ Delivery Service statistics are stored with tags for Cache Group, CDN, and Delivery Service ``xml_id``.
- - daily_stats: The daily_stats database is used to store summary data for daily activities. The stats that are currently summarized are Max Bandwidth and Bytes Served and they are stored by CDN.
+ - ``daily_stats``: Stores summary data for daily activities. The statistics that are currently summarized are Max Bandwidth and Bytes Served and they are stored by CDN.
------------
-Traffic Stats does not influence overall CDN operation, but is required in order to display charts in Traffic Ops and Traffic Portal.
+Traffic Stats does not influence overall CDN operation, but is required in order to display charts in Traffic Portal and the legacy Traffic Ops UI.
diff --git a/docs/source/overview/traffic_vault.rst b/docs/source/overview/traffic_vault.rst
index 933b86bad..28ea3efce 100644
--- a/docs/source/overview/traffic_vault.rst
+++ b/docs/source/overview/traffic_vault.rst
@@ -1,17 +1,17 @@
-..
-..
+..
+..
.. 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 Vault
=============
@@ -31,6 +31,4 @@ Traffic Vault is a keystore used for storing the following types of information:
- public key
* URL Signing Keys
-As the name suggests, Traffic Vault is meant to be a "vault" of private keys that only certain users are allowed to access. In order to create, add, and retrieve keys a user must have admin privileges. Keys can be created via the Traffic Ops UI, but they can only be retrieved via the Traffic Ops API. The keystore used by Traffic Vault is `Riak <http://basho.com/riak/>`_. Traffic ops accesses Riak via https on port 8088. Traffic ops uses Riak's rest API with username/password authentication. Information on the API can be found `here <http://docs.basho.com/riak/latest/dev/references/http/>`_.
-
-
+As the name suggests, Traffic Vault is meant to be a "vault" of private keys that only certain users are allowed to access. In order to create, add, and retrieve keys a user must have administrative privileges. Keys can be created via the Traffic Portal UI, but they can only be retrieved via the Traffic Ops API. The keystore used by Traffic Vault is `Riak <http://basho.com/riak/>`_. Traffic Ops accesses Riak via HTTPS on port 8088. Traffic ops uses Riak's REST API with username/password authentication. Information on the API can be found `here <http://docs.basho.com/riak/latest/dev/references/http/>`_.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services