You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by mi...@apache.org on 2018/09/26 13:51:21 UTC
[trafficcontrol] 04/46: Lots of minor changes
This is an automated email from the ASF dual-hosted git repository.
mitchell852 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
commit f3772dbac7bf5e9fb831370eb11c07ca56fce93d
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Mon Sep 10 14:50:12 2018 -0600
Lots of minor changes
---
docs/source/_static/theme_overrides.css | 32 +--
docs/source/admin/index.rst | 12 +-
docs/source/admin/traffic_ops/configuration.rst | 234 ++++++++++----------
.../source/admin/traffic_router/migrationto2-3.rst | 6 +-
docs/source/admin/traffic_server.rst | 144 ++++++------
docs/source/admin/traffic_stats.rst | 205 +++++++++--------
docs/source/admin/traffic_vault.rst | 104 +++++----
docs/source/basics/cache_revalidation.rst | 74 +++----
docs/source/basics/caching_proxies.rst | 243 ++++++++++-----------
docs/source/basics/content_delivery_networks.rst | 5 +-
docs/source/basics/http_11.rst | 24 +-
docs/source/basics/index.rst | 20 +-
docs/source/conf.py | 6 +-
docs/source/overview/index.rst | 26 +--
docs/source/overview/introduction.rst | 31 ++-
docs/source/overview/traffic_ops.rst | 10 +-
docs/source/overview/traffic_portal.rst | 3 -
docs/source/overview/traffic_router.rst | 81 +++----
18 files changed, 610 insertions(+), 650 deletions(-)
diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
index a00e0b8..b5202a5 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
@@ -36,20 +36,21 @@
.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: #edf0f2;*/
+ background-color: powderblue;
}
-.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 +65,7 @@
.wy-nav-content {
padding:1.618em 3.236em;
height:100%;
- max-width:1100px;
- margin:auto;
+ /*max-width:1100px;*/
+ max-width: 100%;
+ /*margin:auto;*/
}
diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst
index 827777f..c010ed8 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
*********************
@@ -29,7 +29,7 @@ When installing a complete CDN from scratch, a sample recommended order is:
#. 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
diff --git a/docs/source/admin/traffic_ops/configuration.rst b/docs/source/admin/traffic_ops/configuration.rst
index c63a5ec..d6acfb3 100644
--- a/docs/source/admin/traffic_ops/configuration.rst
+++ b/docs/source/admin/traffic_ops/configuration.rst
@@ -1,121 +1,119 @@
-..
-..
+..
+..
.. 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::
+
+ $ 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.
+.. 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'
- ...
+ $ 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 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::
+ '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
@@ -124,8 +122,8 @@ Content Delivery Networks
.. _rl-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 [...]
+------------------
+Many of the settings for the different servers in a Traffic Control CDN are controlled by parameters in the Configure -> Parameters view of Traffic Portal. Parameters are grouped in profiles and profiles are assigned to a server or a Delivery Service. For a typical cache there are hundreds of configuration settings to apply. The Traffic Portal 'Parameters' view contains the defined settings. To make life easier, Traffic Portal allows for duplication, comparison, import and export of prof [...]
.. index::
@@ -136,10 +134,10 @@ Many of the settings for the different servers in a Traffic Control CDN are cont
+==========================+===============+=======================================================================================================================================+
| 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 scaleability 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. |
+--------------------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -166,7 +164,7 @@ Many of the settings for the different servers in a Traffic Control CDN are cont
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 |
@@ -189,11 +187,11 @@ Below is a list of cache parameters that are likely to need changes from the def
+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
| 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_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. |
+| 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`` |
+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
@@ -211,7 +209,7 @@ Below is a list of cache parameters that are likely to need changes from the def
+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
| 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. |
+| 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. |
+--------------------------+-------------------+-------------------------------------------------------------------------------------------------------------------------+
@@ -222,13 +220,13 @@ Below is a list of Traffic Server plugins that need to be configured in the para
+==================+===============+======================================================+============================================================================================================+
| 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>`_ |
+| 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>`_ |
+| 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. | |
+| 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. | |
+------------------+---------------+------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
Below is a list of cache parameters for special configuration, which are unlikely to need changes, but may be useful in particular circumstances:
@@ -243,13 +241,13 @@ Below is a list of cache parameters for special configuration, which are unlikel
| | | 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. |
+| | | 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 regio [...]
+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 regio [...]
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.
@@ -257,7 +255,7 @@ All servers also have to be part of a `cache group`. A cache group is a logical
Configuring Content Purge
=========================
-Content purge using ATS is not simple; there is no file system to delete files/directories from, and in large caches it can be hard to delete a simple regular expression from the cache. This is why Traffic Control uses the `Regex Revalidate Plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_revalidate.en.html>`_ to purge content from the system. We don't actually remove the content, we have a check that gets run before each request on each cache to see if t [...]
+Content purge using ATS is not simple; there is no file system to delete files/directories from, and in large caches it can be hard to delete a simple regular expression from the cache. This is why Traffic Control uses the `Regex Revalidate Plugin <https://docs.trafficserver.apache.org/en/latest/admin-guide/plugins/regex_revalidate.en.html>`_ to purge content from the system. We don't actually remove the content, we have a check that gets run before each request on each cache to see if t [...]
Content Purge is controlled by the following parameters in the profile of the cache:
@@ -268,12 +266,12 @@ Content Purge is controlled by the following parameters in the profile of the ca
+----------------------+-------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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>`_ |
+| 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. |
+| | | 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. |
+----------------------+-------------------------+--------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -294,7 +292,7 @@ To generate ISO, the CentOS Kickstart is necessary:
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 ks.src file in the root of the selection location. See the example below:
::
@@ -310,7 +308,7 @@ Create a ks.src file in the root of the selection location. See the example belo
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_router/migrationto2-3.rst b/docs/source/admin/traffic_router/migrationto2-3.rst
index b3642a9..a4d5f7a 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 13ce92b..f4d419e 100644
--- a/docs/source/admin/traffic_server.rst
+++ b/docs/source/admin/traffic_server.rst
@@ -21,43 +21,42 @@ Installing Traffic Server
#. Build the Traffic Server RPM. The best way to do this is to follow the Traffic Server documents: ::
- 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: ::
- https://github.com/apache/trafficcontrol/tree/<version>/traffic_server
+ https://github.com/apache/trafficcontrol/tree/<version>/traffic_server
- Sample link: ::
+ Sample link: ::
- https://github.com/apache/trafficcontrol/tree/master/traffic_server
+ https://github.com/apache/trafficcontrol/tree/master/traffic_server
-#. Install Traffic Server and astats: ::
+#. Install Traffic Server and astats: ::
- sudo 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 Ops web interface:
+#. Add the server using the Traffic Portal UI:
- #. 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**
+ #. 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:`rl-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**
-#. Install the ORT script and run it in 'badass' mode to create the initial configuration, see :ref:`reference-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: ``sudo service trafficserver start``
+#. 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:
@@ -65,85 +64,76 @@ Installing Traffic Server
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 and install it: ::
- Sample command (NOTE that the example name used here most likely no longer exists): ::
+ https://builds.apache.org/view/S-Z/view/TrafficControl/
- 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
+ Sample command (NOTE that the example name used here most likely no longer exists): ::
-#. Install modules required by ORT if needed: ``sudo yum -y install perl-JSON perl-Crypt-SSLeay``
+ 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 -O traffic_ops_ort.rpm
+ sudo yum install -y traffic_ops_ort.rpm
-#. 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.
+#. Install modules required by ORT if needed: ``sudo yum install -y perl-JSON perl-Crypt-SSLeay``
- Example run below: ::
+#. 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.
- $ sudo /opt/ort/traffic_ops_ort.pl --dispersion=0 badass warn https://ops.$tcDomain admin:admin123
+ Example run below: ::
- .. 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.
+ $ sudo /opt/ort/traffic_ops_ort.pl --dispersion=0 badass warn https://ops.$tcDomain admin:admin123
-#. 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.
+ .. 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.
- 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 Ops, and it 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
+ Run ``sudo crontab -e`` and add 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 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 t [...]
- * 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.
+#. 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 ::
+ Run ``sudo crontab -e`` and add 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 d484f59..ee378ed 100644
--- a/docs/source/admin/traffic_stats.rst
+++ b/docs/source/admin/traffic_stats.rst
@@ -17,91 +17,109 @@
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>``
-
-**Installing InfluxDB:**
-
- **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**
+ - Perform the following command: ``sudo rpm -ivh <traffic_stats rpm>``
- 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 InfluxDB
+-------------------
+ .. Note::As of Traffic Stats 1.8.0, InfluxDB 1.0.0 or higher is required. For InfluxDB versions less than 1.0.0 use Traffic Stats 1.7.x
+ In order to store traffic stats data you will need to install `InfluxDB <https://docs.influxdata.com/influxdb/latest/introduction/installation/>`_. While not required, it is recommended to use some sort of high availability option like `Influx enterprise <https://portal.influxdata.com/>`_, `InfluxDB Relay <https://github.com/influxdata/influxdb-relay>`_, or another `high availability option <https://www.influxdata.com/high-availability/>`_.
-**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.
+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 an [...]
-
- - 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:
+ 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 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 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:
+ 1. A parameter with the graph URL (more information below)
+ 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.
+
+ To create a graph in Grafana, you can follow these basic steps:
+
+ 1. Login to Grafana as an administrative user at e.g. ``http://grafana_url:3000/login``
+ 2. 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:
``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
+ #. 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>`_.
+ 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 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 i [...]
+ 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 [...]
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.
+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.
-**Configuring Traffic Ops to use Grafana Dashboards**
+ .. Note::The legacy Traffic Ops UI also supports viewing Grafana graphs from its Health -> Graphs tab.
- 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.
+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 |
@@ -123,66 +141,65 @@ Configuration
| daily_served_url | https://<grafanaHost>/dashboard-solo/db/daily-summary?panelId=2&fullscreen&from=now-3y&to=now |
+---------------------------+------------------------------------------------------------------------------------------------+
-InfluxDb Tools
+InfluxDB Tools
=========================
-Under the Traffic Stats source directory there is a directory called influxdb_tools. These tools are meant to be used as one-off scripts to help a user quickly get new databases and continuous queries setup in influxdb.
-They are specific for traffic stats and are not meant to be generic to influxdb. Below is an brief description of each script along with how to use it.
+Under the Traffic Stats source directory there is a directory called ``influxdb_tools``. These tools are meant to be used as one-off scripts to help a user quickly get new databases and continuous queries setup in InfluxDB.
+They are specific for traffic stats and are not meant to be generic to InfluxDB. Below is an brief description of each script along with how to use it.
-**create/create_ts_databases.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.
- **How to use create_ts_databases:**
-
+How to Use ``create_ts_databases``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pre-Requisites:
1. Go 1.7 or later
- 2. configured $GOPATH (e.g. export GOPATH=~/go)
-
- Using create_ts_databases.go
+ 2. Configured $GOPATH (e.g. export GOPATH=~/go)
- 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``
+ Using ``create_ts_databases.go``
+ 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
+ - ``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:
1. Go 1.7 or later
- 2. configured $GOPATH (e.g. export GOPATH=~/go)
+ 2. Configured ``$GOPATH`` (e.g. ``export GOPATH=~/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``
-
+ 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
- ``./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:
- - 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`
+ - ``source-url`` - The URL of the source database
+ - ``target-url`` - The URL of the target database
+
+ - 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
+
+ - 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 55fdc95..5c0b05d 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 [...]
+Riak Search (using Apache Solr) will now index all **new** records that are added to the ``ssl`` bucket. The ``cdn``, ``deliveryservice``, and ``hostname`` fields are indexed. When a search is performed Riak will return the indexed fields along with the certificate and key values for a SSL record. In order to add the indexed fields to current records and to get the current records added, a standalone script needs to be run. This does not need to be done on new installs. The following exp [...]
-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/basics/cache_revalidation.rst b/docs/source/basics/cache_revalidation.rst
index 980ca53..879bef2 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 [...]
+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 [...]
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 7338ff4..d407e8e 100644
--- a/docs/source/basics/caching_proxies.rst
+++ b/docs/source/basics/caching_proxies.rst
@@ -25,29 +25,23 @@ 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.
+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:
|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 HT [...]
.. seealso:: `ATS documentation on reverse proxy <https://docs.trafficserver.apache.org/en/latest/admin/reverse-proxy-http-redirects.en.html#http-reverse-proxy>`_.
@@ -57,182 +51,165 @@ this origin. The content owner must inform the clients, by updating the URL, to
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.::
- 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
+ GET /foo/bar/fun.html HTTP/1.1
+ Host: www.origin.com
- 2. The origin server responds with the headers and content as shown: ::
+ 2. The origin server responds with the headers and content as shown: ::
- 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 the origin response on to the client adding a ``Via:`` header (and maybe others): ::
+ 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
- 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
+ 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>
+ <!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: ::
+ 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
+ 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
- <html><body>This is a fun file</body></html>
+ <!DOCTYPE html><html><body>This is a fun file</body></html>
.. index::
- Forward Proxy
+ Forward Proxy
.. _rl-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.
-
-.. seealso:: `ATS documentation on forward proxy <https://docs.trafficserver.apache.org/en/latest/admin/forward-proxy.en.html>`_.
-
-Below is an example of the client retrieving the URL ``http://www.origin.com/foo/bar/fun.html`` through a forward proxy:
+ 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 [...]
-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.
+ .. seealso:: `ATS documentation on forward proxy <https://docs.trafficserver.apache.org/en/latest/admin/forward-proxy.en.html>`_.
-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:
+ Below is an example of the client retrieving the URL ``http://www.origin.com/foo/bar/fun.html`` through a forward proxy:
- ::
+ 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.
- GET http://www.origin.com/foo/bar/fun.html HTTP/1.1
+ 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: ::
+ 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.
-3. The proxy verifies whether the response for ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` is already in the cache.
+ .. 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``.
-4a. If it is not in the cache:
+ 3. The proxy verifies whether the response for ``http://www-origin-cache.cdn.com/foo/bar/fun.html`` is already 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: ::
+ 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: ::
- 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: ::
- 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>
+ HTTP/1.1 200 OK
+ Date: Sun, 14 Dec 2014 23:22:44 GMT
+ Server: Apache/2.2.15 (Red Hat)
+ Last-Modified: Sun, 14 Dec 2014 23:18:51 GMT
+ ETag: "1aa008f-2d-50a3559482cc0"
+ Content-Length: 45
+ Connection: close
+ Content-Type: text/html; charset=UTF-8
+ <!DOCTYPE html><html><body>This is a fun file</body></html>
- 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
+ 3. The proxy sends this on to the client adding a ``Via:`` header (and maybe others): ::
- <html><body>This is a fun file</body></html>
+ 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: ::
+ 4b. If it *is* in the cache:
- 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
+ The proxy responds to the client with the previously retrieved result: ::
-|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>`_.
+ 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 72863af..6ae6e95 100644
--- a/docs/source/basics/content_delivery_networks.rst
+++ b/docs/source/basics/content_delivery_networks.rst
@@ -22,9 +22,6 @@ Content Delivery Networks
=========================
The vast majority of today's Internet traffic is media files (often video or audio) being sent from a single source (the *Content Provider*) to many thousands or even millions of destinations (the *Content Consumers*). Content Delivery Networks are the technology that make that one-to-many distribution possible in an economical way. A Content Delivery Network (CDN) is a distributed system of servers for delivering content over HTTP. These servers are deployed in multiple locations with t [...]
-<<<<<<< Updated upstream
-Caching Proxies
-=======
Caching Proxies
The proxy (cache or caching proxy) is a server that both proxies the requests and caches the results for reusing.
@@ -32,7 +29,7 @@ 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:ref:`rl-health-proto`.
+ The :ref:`rl-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.
diff --git a/docs/source/basics/http_11.rst b/docs/source/basics/http_11.rst
index 65d6d71..d550f7b 100644
--- a/docs/source/basics/http_11.rst
+++ b/docs/source/basics/http_11.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.
-..
+..
.. index::
http/1.1
@@ -29,20 +29,20 @@ 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): ::
- GET /foo/bar/fun.html HTTP/1.1
- Host: www.origin.com
+ 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 ``<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
- 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 23ee1da..7515156 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 9c22d15..fd1d8a5 100755
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -122,11 +122,11 @@ htmlhelp_basename = 'traffic-control-cdn-doc'
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_elements = {
# 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/overview/index.rst b/docs/source/overview/index.rst
index 865d344..60d0e97 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 b93a45a..bc65994 100644
--- a/docs/source/overview/introduction.rst
+++ b/docs/source/overview/introduction.rst
@@ -4,7 +4,7 @@
.. 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,
@@ -19,32 +19,29 @@ Traffic Control is a caching server control plane application which is used to a
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 provides a legacy UI for interacting with the CDN(s) that it manages.
+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. As of its stable release in Traffic Control 2.0,
- this is the recommended, official UI for the Traffic Control platform.
-
-**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_ops.rst b/docs/source/overview/traffic_ops.rst
index 00d9e29..ad6d291 100644
--- a/docs/source/overview/traffic_ops.rst
+++ b/docs/source/overview/traffic_ops.rst
@@ -27,15 +27,13 @@ Traffic Ops also runs a collection of periodic checks to determine the operation
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.
-|
-
.. _rl-trops-ext:
|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:
+ Traffic Ops Extensions are a way to enhance the basic functionality of Traffic Ops in a custom manner. There are three types of extensions:
- * 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.
+ * 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.
diff --git a/docs/source/overview/traffic_portal.rst b/docs/source/overview/traffic_portal.rst
index 4dafd1c..c985159 100644
--- a/docs/source/overview/traffic_portal.rst
+++ b/docs/source/overview/traffic_portal.rst
@@ -29,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 e85ad32..383abbf 100644
--- a/docs/source/overview/traffic_router.rst
+++ b/docs/source/overview/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.
-..
+..
.. _reference-label-tc-tr:
.. |arrow| image:: fwda.png
.. index::
- Traffic Router - Overview
+ Traffic Router - Overview
Traffic Router
==============
@@ -30,80 +30,69 @@ 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:
|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. S [...]
-
- * 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.
+ 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. So [...]
- 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.
+ * 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.
.. _rl-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 *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 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:
|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 actua [...]
-
-|
+ 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 [...]
.. _rl-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: ::
- 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: ::
- 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.