[trafficcontrol] 15/39: Formatting

[mi...@apache.org]

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 da4cc35eb18c1a7dbfa7a1c8f9e8029cde883dad
Author: ocket8888 <oc...@gmail.com>
AuthorDate: Wed Sep 19 09:07:09 2018 -0600

    Formatting
---
 docs/source/admin/quick_howto/regionalgeo.rst | 75 ++++++++++++++-------------
 1 file changed, 38 insertions(+), 37 deletions(-)

diff --git a/docs/source/admin/quick_howto/regionalgeo.rst b/docs/source/admin/quick_howto/regionalgeo.rst
index 30d9ba4..e2859f7 100644
--- a/docs/source/admin/quick_howto/regionalgeo.rst
+++ b/docs/source/admin/quick_howto/regionalgeo.rst
@@ -47,56 +47,57 @@ Configure Regional Geo-blocking (RGB)
 	``deliveryServiceId``
 		Should be equal to the ``ID`` or ``xml_id`` field of the intended Delivery Service as configured in Traffic Portal
 	``urlRegex``
-		A regular expression to be used to determine
+		A regular expression to be used to determine to what URLs the rule shall apply; a URL that matches it is subject to the rule
+	``geoLocation``
+		An object that currently supports only the keys ``includePostalCode`` and ``excludePostalCode`` (mutually exclusive). When the ``includePostalCode`` key is used, only the clients whose Forward Sortation Areas (FSA)s - the first three postal characters of Canadian postal codes - are in the ``includePostalCode`` list are able to view the content at URLs matched by the ``urlRegex``. When ``excludePostalCode`` is used, any client whose FSA is not in the ``excludePostalCode`` list will be a [...]
+	``redirectUrl``
+		The URL that will be returned to the blocked clients. Without a domain name in the URL, the URL will still be served in the same Delivery Service. Thus Traffic Router will redirect the client to a chosen cache server assigned to the Delivery Service. If the URL includes a domain name, Traffic Router simply redirects the client to the defined URL. In the later case, the redirect URL must not match the ``urlRegex`` value, or an infinite loop of  HTTP ``302 Found`` responses will occur at [...]
+	``ipWhiteList``
+		An optional element that is an array of CIDR (Classless Inter-Domain Routing) blocks indicating the IPv4 subnets that are allowed by the rule. If this list exists and the value is not empty, client IP will be matched against the CIDR list, bypassing the value of ``geoLocation``. If there is no match in the white list, Traffic Router defers to the value of ``geoLocation`` to determine if content ought to be blocked.
 
-* “geoLocation” currently supports “includePostalCode” and “excludePostalCode” attribute. When “includePostalCode” attribute is used, only the clients whose FSAs are in the “includePostalCode” list are able to view the content represented by “urlRegex”. When “excludePostalCode” is used, any client whose FSA are not in the “excludePostalCode” list are allowed to view the content. “includePostalCode” and “excludePostalCode” are mutually exclusive in one rule. (FSA: Forward Sortation Area,  [...]
 
-* “redirectUrl” is the URL that will be responded to the blocked clients. Without a domain name in the URL, the URL will still be served in the same delivery service. Thus Traffic Router will redirect the client to a chosen cache server assigned to the delivery service. If the URL includes a domain name, Traffic Router simply redirects the client to the defined URL. In the later case, the redirect URL must not match the “urlRegex” part to avoid HTTP 302 loop on Traffic Router.
+#. Add RGB parameters in Traffic Portal to the Delivery Service's Traffic Router(s)'s profile(s). The ``configFile`` field should be set to ``CRConfig.json``, and the following two parameter name/values need to be specified:
 
-* “ipWhiteList” is an optional element. It includes a list of CIDR (Classless Inter-Domain Routing) blocks indicating the IPv4 subnets that are allowed by the rule. If this list exists and the value is not empty, client IP will be matched against the CIDR list, and if there is any match, the request will be allowed and no postal code matching logic is needed. If there is no match in the white list, postal code matching logic will be processed further.
+	``regional_geoblocking.polling.url``
+		The URL of the RGB configuration file. Traffic Router will fetch the file from this URL using an HTTP ``GET`` request.
+	``regional_geoblocking.polling.interval``
+		The interval on which Traffic Router polls the RGB configuration file.
 
+	.. figure:: regionalgeo/01.png
+		:scale: 100%
+		:align: center
 
-2)	Add RGB parameters on Traffic Ops
+#. Enable RGB for a delivery service
 
-The two new parameters in following table are required to be added into CRConfig.json:
+	.. figure:: regionalgeo/02.png
+		:scale: 100%
+		:align: center
 
-* "regional_geoblocking.polling.url": the HTTP URL of RGB configuration file. Traffic Router will fetch the file from this URL.
-* "regional_geoblocking.polling.interval": the interval that Traffic Router polls the RGB configuration file.
+#. Go to Tools->Snapshot CRConfig, perform “Diff CRConfig” and click "Write CRConfig".
 
-.. image:: regionalgeo/01.png
-	:scale: 100%
-	:align: center
+	.. figure:: regionalgeo/03.png
+		:scale: 70%
+		:align: center
 
-3)	Enable RGB for a delivery service
+Traffic Router Access Log
+=========================
+.. seealso:: :ref:`tr-logs`
 
-.. image:: regionalgeo/02.png
-	:scale: 100%
-	:align: center
+RGB extends the ``rtype`` field and adds a new field ``rgb`` in Traffic Router access.log to help to monitor this feature. A value of ``RGALT`` in the ``rtype`` field indicates that a request is redirected to an alternate URL by RGB; a value of ``RGDENY`` indicates that a request is denied by RGB because there is no matching rule in the RGB configuration file for this request. When RGB is enabled, the ``RGB`` field will be non-empty with following format::
 
-4)	Make configuration effective
+	{FSA}:{allowed/disallowed}:{include/exclude postal}:{fallback config}:{allowed by whitelist}
 
-Go to Tools->Snapshot CRConfig, perform “Diff CRConfig” and click "Write CRConfig".
 
-.. image:: regionalgeo/03.png
-	:scale: 70%
-	:align: center
-
-5)	Traffic Router access log with RGB
-
-RGB extends the field of "rtype" and adds a new field "rgb" in Traffic Router access.log to help to monitor the working of this feature.
-
-For "rtype", RGALT indicates that a request is redirected to an alternate URL by RGB; RGDENY indicates that a request is denied by RGB because there is no matching rule in JSON for this request.
-
-For "rgb", when RGB is enabled, it will be non-empty with following format::
-
-	{FSA}:{allowed/disallowed}:{include/exclude postal}:{fallback config/current config}:{allowed by whitelist/otherwise}
-
-
-* {FSA}: It is the client’s FSA part of its postal code, which is retrieved from geo-location database. If FSA is empty, dash (“-“) is filled in.
-* {allowed/disallowed}: This flag shows if a request is allowed or disallowed by RGB (1 for yes, and 0 for no).
-* {include/exclude postal}: It shows that when a rule in JSON is matched for a request, it is an include or exclude list of postal codes (i.e. FSAs). “I” for include, and “X” for exclude. If no rule matches, dash (“-“) is filled in.
-* {fallback config/current config}: when TR fails to parse an RGB JSON, TR will handle requests with latest valid JSON configuration, but will set {fallback config} flag to 1. If the new JSON is valid, then the flag is set to 0.
-* {allowed by whitelist/otherwise}: If a request is allowed by whitelist, this flag is set to 1; for all other cases, it is 0.
+FSA
+	FSA part of the client’s postal code, which is retrieved from a geographic location database. If this field is empty, a dash (“-“) is filled in.
+allowed/disallowed
+	This flag shows if a request was allowed or disallowed by RGB (1 for yes, and 0 for no).
+include/exclude postal
+	This shows that when a rule in JSON is matched for a request, it's value is "I" if the rule matched because of an ``includePostalCode`` rule, "X" if the rule matched because of an ``excludePostalCode`` rule, or "-" if no rule matched.
+fallback config
+	When Traffic Router fails to parse an RGB configuration file as JSON, Traffic Router will handle requests with latest valid configuration that it had, but will set the ``fallback config`` flag to 1. If no fall-back occurred, then the flag is set to 0.
+allowed by whitelist
+	If a request is allowed by a ``whitelist`` field in the configuration, this flag is set to 1; for all other cases, it is 0.
 
 
 Example::