http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/9694fb23/docs/latest/_sources/admin/traffic_portal.rst.txt ---------------------------------------------------------------------- diff --git a/docs/latest/_sources/admin/traffic_portal.rst.txt b/docs/latest/_sources/admin/traffic_portal.rst.txt deleted file mode 100644 index 9e761b8..0000000 --- a/docs/latest/_sources/admin/traffic_portal.rst.txt +++ /dev/null @@ -1,53 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -***************************** -Traffic Portal Administration -***************************** -The following are requirements to ensure an accurate set up: - -* CentOS 6.7 or 7 -* Node.js 6.0.x or above - -**Installing Traffic Portal** - - - Download the Traffic Portal RPM from the traffic control `downloads <https://trafficcontrol.apache.org/downloads/index.html>`_ page or build from `source <https://github.com/apache/incubator-trafficcontrol/traffic_portal/build>`_. - - Copy the Traffic Portal RPM to your server - - curl --silent --location https://rpm.nodesource.com/setup_6.x | sudo bash - - - sudo yum install -y nodejs - - sudo yum install -y <traffic_portal rpm> - -**Configuring Traffic Portal** - - - cd /etc/traffic_portal/conf - - sudo cp config-template.js config.js - - sudo vi config.js (read the inline comments) - - [OPTIONAL] sudo vi /opt/traffic_portal/public/traffic_portal_properties.json (to customize traffic portal content) - - [OPTIONAL] sudo vi /opt/traffic_portal/public/resources/assets/css/custom.css (to customize traffic portal skin) - -**Starting Traffic Portal** - - - sudo service traffic_portal start - -**Stopping Traffic Portal** - - - sudo service traffic_portal stop - - - - - - -
http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/9694fb23/docs/latest/_sources/admin/traffic_router.rst.txt ---------------------------------------------------------------------- diff --git a/docs/latest/_sources/admin/traffic_router.rst.txt b/docs/latest/_sources/admin/traffic_router.rst.txt deleted file mode 100644 index 01ab6b3..0000000 --- a/docs/latest/_sources/admin/traffic_router.rst.txt +++ /dev/null @@ -1,494 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -***************************** -Traffic Router Administration -***************************** -.. contents:: - :depth: 2 - :backlinks: top - -Installing Traffic Router -========================== -The following are requirements to ensure an accurate set up: - -* CentOS 6 -* 4 vCPUs -* 8GB RAM -* Successful install of Traffic Ops -* Successful install of Traffic Monitor -* Administrative access to Traffic Ops - -.. Note:: Hardware requirements are generally doubled if DNSSEC is enabled - -1. If no suitable profile exists, create a new profile for Traffic Router. - -2. Enter the Traffic Router server into Traffic Ops, assign it to a Traffic Router profile, and ensure that its status is set to ``ONLINE``. -3. Ensure the FQDN of the Traffic Monitor is resolvable in DNS. This FQDN must be resolvable by the clients expected to use this CDN. -4. Install a traffic router: ``sudo yum install traffic_router``. -5. Edit ``/opt/traffic_router/conf/traffic_monitor.properties`` and specify the correct online Traffic Monitor(s) for your CDN. See :ref:`rl-tr-config-files` - # traffic_monitor.properties: url that should normally point to this file - traffic_monitor.properties=file:/opt/traffic_router/conf/traffic_monitor.properties - - # Frequency for reloading this file - # traffic_monitor.properties.reload.period=60000 - - -6. Start Tomcat: ``sudo service tomcat start``, and test lookups with dig and curl against that server. -7. Snapshot CRConfig; See :ref:`rl-snapshot-crconfig` - -.. Note:: Once the CRConfig is snapshotted, live traffic will be sent to the new Traffic Routers provided that their status is set to ``ONLINE``. - -8. Ensure that the parent domain (e.g.: kabletown.net) for the CDN's top level domain (e.g.: cdn.kabletown.net) contains a delegation (NS records) for the new Traffic Router, and that the value specified matches the FQDN used in step 3. - -Configuring Traffic Router -========================== - -.. Note:: Starting with Traffic Router 1.5, many of the configuration files under ``/opt/traffic_router/conf`` are only needed to override the default configuration values for Traffic Router. Most of the given default values will work well for any CDN. Critical values that must be changed are hostnames and credentials for communicating with other Traffic Control components such as Traffic Ops and Traffic Monitor. - -.. Note:: Pre-existing installations having configuration files in ``/opt/traffic_router/conf`` will still be used and honored for Traffic Router 1.5 and onward. - -For the most part, the configuration files and parameters that follow are used to get Traffic Router online and communicating with various Traffic Control components. Once Traffic Router is successfully communicating with Traffic Control, configuration is mostly performed in Traffic Ops, and is distributed throughout Traffic Control via the CRConfig snapshot process. See :ref:`rl-snapshot-crconfig` for more information. Please see the parameter documentation for Traffic Router in the Using Traffic Ops guide documented under :ref:`rl-ccr-profile` for parameters that influence the behavior of Traffic Router via the CRConfig. - -.. _rl-tr-config-files: - -Configuration files -------------------- - -+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| File name | Parameter | Description | Default Value | -+============================+===========================================+=====================================================================================================+===================================================+ -| traffic_monitor.properties | traffic_monitor.bootstrap.hosts | Traffic Monitor FQDNs and port if necessary, separated by a semicolon (;) | N/A | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | traffic_monitor.bootstrap.local | Use only the Traffic Monitors specified in config file | false | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | traffic_monitor.properties | Path to the traffic_monitor.properties file; used internally to monitor the file for changes | /opt/traffic_router/traffic_monitor.properties | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | traffic_monitor.properties.reload.period | The interval in milliseconds which Traffic Router will reload this configuration file | 60000 | -+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| dns.properties | dns.tcp.port | TCP port that Traffic Router will use for incoming DNS requests | 53 | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | dns.tcp.backlog | Maximum length of the queue for incoming TCP connection requests | 0 | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | dns.udp.port | UDP port that Traffic Router will use for incoming DNS requests | 53 | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | dns.max-threads | Maximum number of threads used to process incoming DNS requests | 1000 | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | dns.zones.dir | Path to auto generated zone files for reference | /opt/traffic_router/var/auto-zones | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | dns.routing.name | The label (A/AAAA) Traffic Router will use for the entry point for a DNS delivery service | edge (e.g.: edge.mydeliveryservice.kabletown.net) | -+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| traffic_ops.properties | traffic_ops.username | Username to access the APIs in Traffic Ops (must be in the admin role) | admin | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | traffic_ops.password | Password for the user specified in traffic_ops.username | N/A | -+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| http.properties | http.routing.name | The label (A/AAAA) Traffic Router will use for the entry point for an HTTP delivery service | tr (e.g.: tr.mydeliveryservice.kabletown.net) | -+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| cache.properties | cache.geolocation.database | Full path to the local copy of the MaxMind geolocation binary database file | /opt/traffic_router/db/GeoIP2-City.mmdb | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | cache.geolocation.database.refresh.period | The interval in milliseconds which Traffic Router will poll for a new geolocation database | 604800000 | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | cache.czmap.database | Full path to the local copy of the coverage zone file | /opt/traffic_router/db/czmap.json | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | cache.czmap.database.refresh.period | The interval in milliseconds which Traffic Router will poll for a new coverage zone file | 10800000 | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | cache.health.json | Full path to the local copy of the health state | /opt/traffic_router/db/health.json | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | cache.health.json.refresh.period | The interval in milliseconds which Traffic Router will poll for a new health state file | 1000 | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | cache.config.json | Full path to the local copy of the CRConfig | /opt/traffic_router/db/cr-config.json | -| +-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| | cache.config.json.refresh.period | The interval in milliseconds which Traffic Router will poll for a new CRConfig | 60000 | -+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ -| log4j.properties | various parameters | Configuration of log4j is documented on their site; adjust as necessary based on needs | N/A | -+----------------------------+-------------------------------------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------+ - -.. _rl-tr-dnssec: - -DNSSEC -====== - -Overview --------- -Domain Name System Security Extensions (DNSSEC) is a set of extensions to DNS that provides a cryptographic mechanism for resolvers to verify the authenticity of responses served by an authoritative DNS server. - -Several RFCs (4033, 4044, 4045) describe the low level details and define the extensions, RFC 7129 provides clarification around authenticated denial of existence of records, and finally RFC 6781 describes operational best practices for administering an authoritative DNSSEC enabled DNS server. The authenticated denial of existence RFC describes how an authoritative DNS server responds in NXDOMAIN and NODATA scenarios when DNSSEC is enabled. - -Traffic Router currently supports DNSSEC with NSEC, however, NSEC3 and more configurable options will be provided in the future. - -Operation ---------- -Upon startup or a configuration change, Traffic Router obtains keys from the keystore API in Traffic Ops which returns key signing keys (KSK) and zone signing keys (ZSK) for each delivery service that is a subdomain off the CDN's top level domain (TLD), in addition to the keys for the CDN TLD itself. Each key has timing information that allows Traffic Router to determine key validity (expiration, inception, and effective dates) in addition to the appropriate TTL to use for the DNSKEY record(s). All TTLs are configurable parameters; see the :ref:`rl-ccr-profile` documentation for more information. - -Once Traffic Router obtains the key data from the API, it converts each public key into the appropriate record types (DNSKEY, DS) to place in zones and uses the private key to sign zones. DNSKEY records are added to each delivery service's zone (e.g.: mydeliveryservice.cdn.kabletown.net) for every valid key that exists, in addition to the CDN TLD's zone. A DS record is generated from each zone's KSK and is placed in the CDN TLD's zone (e.g.: cdn.kabletown.net); the DS record for the CDN TLD must be placed in its parent zone, which is not managed by Traffic Control. - -The DNSKEY to DS record relationship allows resolvers to validate signatures across zone delegation points; with Traffic Control, we control all delegation points below the CDN's TLD, **however, the DS record for the CDN TLD must be placed in the parent zone (e.g.: kabletown.net), which is not managed by Traffic Control**. As such, the DS record (available in the Traffic Ops DNSSEC administration UI) must be placed in the parent zone prior to enabling DNSSEC, and prior to generating a new CDN KSK. Based on your deployment's DNS configuration, this might be a manual process or it might be automated; either way, extreme care and diligence must be taken and knowledge of the management of the upstream zone is imperative for a successful DNSSEC deployment. - -Rolling Zone Signing Keys -------------------------- -Traffic Router currently follows the zone signing key pre-publishing operational best practice described in `section 4.1.1.1 of RFC 6781`_. Once DNSSEC is enabled for a CDN in Traffic Ops, key rolls are triggered via Traffic Ops via the automated key generation process, and Traffic Router selects the active zone signing keys based on the expiration information returned from the keystore API in Traffic Ops. - -.. _section 4.1.1.1 of RFC 6781: https://tools.ietf.org/html/rfc6781#section-4.1.1.1 - -Troubleshooting and log files -============================= -Traffic Router log files are in ``/opt/traffic_router/var/log``, and Tomcat log files are in ``/opt/tomcat/logs``. Application related logging is in ``/opt/traffic_router/var/log/traffic_router.log``, while access logs are written to ``/opt/traffic_router/var/log/access.log``. - -Event Log File Format -===================== - -Summary -------- - -All access events to Traffic Router are logged to the file ``/opt/traffic_router/var/log/access.log`` -This file grows up to 200Mb and gets rolled into older log files, 10 log files total are kept (total of up to 2Gb of logged events per traffic router) - -Traffic Router logs access events in a format that largely following `ATS event logging format -<https://docs.trafficserver.apache.org/en/6.0.x/admin/event-logging-formats.en.html>`_ - --------------- - -Sample Message --------------- - -Items within brackets below are detailed under the HTTP and DNS sections -:: - - 144140678.000 qtype=DNS chi=192.168.10.11 ttms=789 [Fields Specific to the DNS request] rtype=CZ rloc="40.252611,58.439389" rdtl=- rerr="-" [Fields Specific to the DNS result] - 144140678.000 qtype=HTTP chi=192.168.10.11 ttms=789 [Fields Specific to the HTTP request] rtype=GEO rloc="40.252611,58.439389" rdtl=- rerr="-" [Fields Specific to the HTTP result] - -.. Note:: The above message samples contain fields that are always present for every single access event to Traffic Router - -**Message Format** -- Each event that is logged is a series of space separated key value pairs except for the first item. -- The first item is always the epoch in seconds with a decimal field precision of up to milliseconds -- Each key value pair is in the form of unquoted string, equals character, optionally quoted string -- Values that are quoted strings may contain space characters -- Values that are not quoted should not contains any space characters - -.. Note:: Any value that is a single dash character or a dash character enclosed in quotes represents an empty value - --------- - -Fields Always Present ---------------------- - -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ -|Name |Description |Data | -+======+=================================================================================+===========================================================================+ -|qtype |Whether the request was for DNS or HTTP |Always DNS or HTTP | -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ -|chi |The IP address of the requester |Depends on whether this was a DNS or HTTP request, see below sections | -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ -|ttms |The amount of time in milliseconds it took Traffic Router to process the request |A number greater than or equal to zero | -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ -|rtype |Routing Result Type |One of ERROR, CZ, GEO, MISS, STATIC_ROUTE, DS_REDIRECT, DS_MISS, INIT, FED | -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ -|rloc |GeoLocation of result |Latitude and Longitude in Decimal Degrees | -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ -|rdtl |Result Details Associated with unusual conditions |One of DS_NOT_FOUND, DS_NO_BYPASS, DS_BYPASS, DS_CZ_ONLY | -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ -|rerr |Message about internal Traffic Router Error |String | -+------+---------------------------------------------------------------------------------+---------------------------------------------------------------------------+ - -**rtype meanings** - -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|Name |Meaning | -+=============+========================================================================================================================================================================+ -|ERROR |An internal error occurred within Traffic Router, more details may be found in the rerr field | -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|CZ |The result was derived from Coverage Zone data based on the address in the chi field | -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|GEO |The result was derived from geolocation service based on the address in the chi field | -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|MISS |Traffic Router was unable to resolve a DNS request or find a cache for the requested resource | -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|STATIC_ROUTE |_*DNS Only*_ No DNS Delivery Service supports the hostname portion of the requested url | -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|DS_MISS |_*HTTP Only*_ No HTTP Delivery Service supports either this request's URL path or headers | -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|DS_REDIRECT |The result is using the Bypass Destination configured for the matched Delivery Service when that Delivery Service is unavailable or does not have the requested resource| -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|FED |_*DNS Only*_ The result was obtained through federated coverage zone data outside of any delivery service | -+-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -**rdtl meanings** - -+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -|Name |Meaning | -+==========================+============================================================================================================================================+ -|DS_NOT_FOUND |Always goes with rtypes STATIC_ROUTE and DS_MISS | -+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -|DS_BYPASS |Used Bypass Destination for Redirect of Delivery Service | -+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -|DS_NO_BYPASS |No valid Bypass Destination is configured for the matched Delivery Service and the delivery service does not have the requested resource | -+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -|DS_CZ_ONLY |The selected Delivery Service only supports resource lookup based on Coverage Zone data | -+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -|DS_CLIENT_GEO_UNSUPPORTED |Traffic Router did not find a resource supported by coverage zone data and was unable to determine the geolocation of the requesting client | -+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ -|GEO_NO_CACHE_FOUND |Traffic Router could not find a resource via geolocation data based on the requesting client's geolocation | -+--------------------------+--------------------------------------------------------------------------------------------------------------------------------------------+ - ---------------- - -HTTP Specifics --------------- - -Sample Message -:: - - 1452197640.936 qtype=HTTP chi=69.241.53.218 url="http://ccr.mm-test.jenkins.cdnlab.comcast.net/some/asset.m3u8"; cqhm=GET cqhv=HTTP/1.1 rtype=GEO rloc="40.252611,58.439389" rdtl=- rerr="-" pssc=302 ttms=0 rurl="http://odol-atsec-sim-114.mm-test.jenkins.cdnlab.comcast.net:8090/some/asset.m3u8"; rh="Accept: */*" rh="myheader: asdasdasdasfasg" - -**Request Fields** - -+-----+-----------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------+ -|Name |Description |Data | -+=====+=========================================================================================================================================+===========================================+ -|url |Requested URL with query string |String | -+-----+-----------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------+ -|cqhm |Http Method |e.g GET, POST | -+-----+-----------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------+ -|cqhv |Http Protocol Version |e.g. HTTP/1.1 | -+-----+-----------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------+ -|rh |One or more of these key value pairs may exist in a logged event and are controlled by the configuration of the matched Delivery Service |Key value pair of the format "name: value" | -+-----+-----------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------+ - -**Response Fields** - -+-----+----------------------------------------------------------+------------+ -|Name |Description |Data | -+=====+==========================================================+============+ -|rurl |The resulting url of the resource requested by the client |A URL String| -+-----+----------------------------------------------------------+------------+ - ------------- - -DNS Specifics -------------- - -Sample Message -:: - - 144140678.000 qtype=DNS chi=192.168.10.11 ttms=123 xn=65535 fqdn=www.example.com. type=A class=IN ttl=12345 rcode=NOERROR rtype=CZ rloc="40.252611,58.439389" rdtl=- rerr="-" ans="192.168.1.2 192.168.3.4 0:0:0:0:0:ffff:c0a8:102 0:0:0:0:0:ffff:c0a8:304" - -**Request Fields** - -.. _qname: http://www.zytrax.com/books/dns/ch15/#qname - -.. _qtype: http://www.zytrax.com/books/dns/ch15/#qtype - -+------+------------------------------------------------------------------+--------------------------------------------------------+ -|Name |Description |Data | -+======+==================================================================+========================================================+ -|xn |The ID from the client DNS request header |a number from 0 to 65535 | -+------+------------------------------------------------------------------+--------------------------------------------------------+ -|fqdn |The qname field from the client DNS request message (i.e. The |A series of DNS labels/domains separated by '.' | -| |fully qualified domain name the client is requesting be resolved) |characters and ending with a '.' character (see qname_) | -+------+------------------------------------------------------------------+--------------------------------------------------------+ -|type |The qtype field from the client DNS request message (i.e. |Examples are A (IpV4), AAAA (IpV6), NS (Name Service), | -| |the type of resolution that's requested such as IPv4, IPv6) | SOA (Start of Authority), and CNAME, (see qtype_) | -+------+------------------------------------------------------------------+--------------------------------------------------------+ -|class |The qclass field from the client DNS request message (i.e. The |Either IN (Internet resource) or ANY (Traffic router | -| |class of resource being requested) | rejects requests with any other value of class) | -+------+------------------------------------------------------------------+--------------------------------------------------------+ - -**Response Fields** - -+------+---------------------------------------------------------------------+-----------------------------------------------------+ -|Name | Description | Data | -+======+=====================================================================+=====================================================+ -|ttl | The 'time to live' in seconds for the answer provided by Traffic |A number from 0 to 4294967295 | -| | Router (clients can reliably use this answer for this long without | | -| | re-querying traffic router) | | -+------+---------------------------------------------------------------------+-----------------------------------------------------+ -|rcode | The result code for the DNS answer provided by Traffic Router | One of NOERROR (success), NOTIMP (request is not | -| | | NOTIMP (request is not supported), | -| | | REFUSED (request is refused to be answered), or | -| | | NXDOMAIN (the domain/name requested does not exist) | -+------+---------------------------------------------------------------------+-----------------------------------------------------+ - -.. _rl-tr-ngb: - -GeoLimit Failure Redirect feature -================================= - -Overview --------- -This feature is also called 'National GeoBlock' feature which is short for 'NGB' feature. In this section, the acronym 'NGB' will be used for this feature. - -In the past, if the Geolimit check fails (for example, the client ip is not in the 'US' region but the geolimit is set to 'CZF + US'), the router will return 503 response; but with this feature, when the check fails, it will return 302 if the redirect url is set in the delivery service. - -The Geolimit check failure has such scenarios: -1) When the GeoLimit is set to 'CZF + only', if the client ip is not in the the CZ file, the check fails -2) When the GeoLimit is set to any region, like 'CZF + US', if the client ip is not in such region, and the client ip is not in the CZ file, the check fails - - -Configuration -------------- -To enable the NGB feature, the DS must be configured with the proper redirect url. And the setting lays at 'Delivery Services'->Edit->'GeoLimit Redirect URL'. If no url is put in this field, the feature is disabled. - -The URL has 3 kinds of formats, which have different meanings: - -1. URL with no domain. If no domain is in the URL (like 'vod/dance.mp4'), the router will try to find a proper cache server within the delivery service and return the redirect url with the format like 'http://<cache server name>.<delivery service's FQDN>/<configured relative path>' - -2. URL with domain that matches with the delivery service. For this URL, the router will also try to find a proper cache server within the delivery service and return the same format url as point 1. - -3. URL with domain that doesn't match with the delivery service. For this URL, the router will return the configured url directly to the client. - -.. _rl-tr-steering: - -Steering feature -================ - -Overview --------- -A Steering delivery service is a delivery service that is used to "steer" traffic to other delivery services. A Steering delivery service will have target delivery services configured for it with weights assigned to them. Traffic Router uses the weights to make a consistent hash ring which it then uses to make sure that requests are routed to a target based on the configured weights. This consistent hash ring is separate from the consistent hash ring used in cache selection. - -Special regular expressions called Filters can also be configured for target delivery services to pin traffic to a specific delivery service. For example, if a filter called .*/news/.* for a target called target-ds-1 is created, any requests to traffic router with 'news' in them will be routed to target-ds-1. This will happen regardless of the configured weights. - -A client can bypass the steering functionality by providing a header called X-TC-Steering-Option with the xml_id of the target delivery service to route to. When Traffic Router receives this header it will route to the requested target delivery service regardless of weight configuration. - -Some other points of interest: -- Steering is currently only available for HTTP delivery services that are a part of the same CDN. -- A new role called STEERING has been added to the traffic ops database. Only users with Admin or Steering privileges can modify steering assignments for a Delivery Service. -- A new API has been created in Traffic Ops under /internal. This API is used by a Steering user to add filters and modify assignments. (Filters can only be added via the API). -- Traffic Router uses the steering API in Traffic Ops to poll for steering assignments, the assignments are then used when routing traffic. - -A couple simple use cases for steering are: - -#. Migrating traffic from one delivery service to another over time. -#. Trying out new functionality for a subset of traffic with an experimental delivery service. -#. Load balancing between delivery services. - - - -Configuration -------------- - -The following needs to be completed for Steering to work correctly: - -#. Two target delivery services are created in Traffic Ops. They must both be HTTP delivery services part of the same CDN. -#. A delivery service with type STEERING is created in Traffic Ops. -#. Target delivery services are assigned to the steering delivery service using Traffic Ops. -#. A user with the role of Steering is created. -#. Using the API, the steering user assigns weights to the target delivery services. -#. If desired, the steering user can create filters for the target delivery services. - -For more information see the `steering how-to guide <quick_howto/steering.html>`_. - -HTTPS for Http Type Delivery Services -===================================== - -Starting with version 1.7 Traffic Router added the ability to allow https traffic between itself and clients on a per http type delivery service basis. - -.. Warning:: - The establishing of an HTTPS connection is much more computationally demanding than an HTTP connection. - Since each client will in turn get redirected to ATS, Traffic Router is most always creating a new HTTPS connection for all HTTPS traffic. - It is likely to mean that an existing Traffic Router will have some decrease in performance depending on the amount of https traffic you want to support - As noted for DNSSEC, you may need to plan to scale Traffic Router vertically and/or horizontally to handle the new load - -The summary for setting up https is to: - -#. Select one of 'https', 'http and https', or 'http to https' for the delivery service -#. Generate private keys for the delivery service using a wildcard domain such as ``*.my-delivery-service.my-cdn.example.com`` -#. Obtain and import signed certificate chain -#. Snapshot CR Config - -Clients may make HTTPS requests delivery services only after Traffic Router receives the certificate chain from Traffic Ops and the new CR Config. - -Protocol Options ----------------- - -*https only* - Traffic Router will only redirect (send a 302) to clients communicating with a secure connection, all other clients will receive a 503 -*http and https* - Traffic Router will redirect both secure and non-secure clients -*http to https* - Traffic Router will redirect non-secure clients with a 302 and a location that is secure (i.e. starting with 'https' instead of 'http'), secure clients will remain on https -*http* - Any secure client will get an SSL handshake error. Non-secure clients will experience the same behavior as prior to 1.7 - -Certificate Retrieval ---------------------- - -.. Warning:: - If you have https delivery services in your CDN, Traffic Router will not accept **any** connections until it is able to - fetch certificates from Traffic Ops and load them into memory. Traffic Router does not persist certificates to the java keystore or anywhere else. - -Traffic Router fetches certificates into memory: - -* At startup time -* When it receives a new CR Config -* Once an hour from whenever the most recent of the last of the above occurred - -.. Note:: - To adjust the frequency when Traffic Router fetches certificates add the parameter 'certificates.polling.interval' to CR Config and - setting it to the desired time in milliseconds. - -.. Note:: - Taking a snapshot of CR Config may be used at times to avoid waiting the entire polling cycle for a new set of certificates. - -.. Warning:: - If a snapshot of CR Config is made that involves a delivery service missing its certificates, Traffic Router will ignore **ALL** changes in that CR-Config - until one of the following occurs: - * It receives certificates for that delivery service - * Another snapshot of CR Config is created and the delivery service without certificates is changed so it's HTTP protocol is set to 'http' - -Certificate Chain Ordering --------------------------- - -The ordering of certificates within the certificate bundle matters. It must be: - -#. Primary Certificate (e.g. the one created for ``*.my-delivery-service.my-cdn.example.com``) -#. Intermediate Certificate(s) -#. Root Certificate from CA (optional) - -.. Warning:: - If something is wrong with the certificate chain (e.g. the order of the certificates is backwards or for the wrong domain) the - client will get an SSL handshake. Inspection of /opt/tomcat/logs/catalina.out is likely to yield information to reveal this. - -To see the ordering of certificates you may have to manually split up your certificate chain and use openssl on each individual certificate - -Suggested Way of Setting up an HTTPS Delivery Service ------------------------------------------------------ - -Do the following in Traffic Ops: - -#. Select one of 'https', 'http and https', or 'http to https' for the protocol field of a delivery service and click 'Save'. -#. Click 'Manage SSL Keys'. -#. Click 'Generate New Keys'. -#. Copy the contents of the Certificate Signing Request field and save it locally. -#. Click 'Load Keys'. -#. Select 'http' for the protocol field of the delivery service and click 'Save' (to avoid preventing other CR Config updates from being blocked by Traffic Router) -#. Follow your standard procedure for obtaining your signed certificate chain from a CA. -#. After receiving your certificate chain import it into Traffic Ops. -#. Edit the delivery service. -#. Restore your original choice for the protocol field and click save. -#. Click 'Manage SSL Keys'. -#. Click 'Paste Existing Keys'. -#. Paste the certificate chain into the CRT field. -#. Click 'Load Keys'. -#. Take a new snapshot of CR Config. - -Once this is done you should be able to test you are getting correctly redirected by Traffic Router using curl commands to https destinations on your delivery service. - -A new testing tool was created for load testing traffic router, it allows you to generate requests from your local box to multiple delivery services of a single cdn. -You can control which cdn, delivery services, how many transactions per delivery service, and how many concurrent requests. -During the test it will provide feedback about request latency and transactions per second. - -While it is running it is suggested that you monitor your Traffic Router nodes for memory and CPU utilization. - http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/9694fb23/docs/latest/_sources/admin/traffic_server.rst.txt ---------------------------------------------------------------------- diff --git a/docs/latest/_sources/admin/traffic_server.rst.txt b/docs/latest/_sources/admin/traffic_server.rst.txt deleted file mode 100644 index 1b99ce0..0000000 --- a/docs/latest/_sources/admin/traffic_server.rst.txt +++ /dev/null @@ -1,71 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -***************************** -Traffic Server Administration -***************************** -Installing Traffic Server -========================= -1. Select **Servers** in the Traffic Ops web interface. -2. Scroll to the bottom of the page and click **Add Server**. -3. Complete the *Required Info*: section. -4. Click **Submit**. -5. Click **Save**. - -.. 6. Click **Online Server**. -.. 7. From the Set status of this machine to ONLINE? screen, click **OK**. - -.. _reference-traffic-ops-ort: - -Configuring Traffic Server -========================== -All of the Traffic Server application configuration files are generated by Traffic Ops and installed by way of the traffic_ops_ort.pl script. - - -**traffic_ops_ort.pl** - 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 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: :: - - $ sudo ./traffic_ops_ort.pl syncds warn https://to.cdn.kabletown.net - Thu May 26 15:52:11 UTC 2016 - ====-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==== - 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. - - <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_Login> => Example: 'username:password' - - [optional flags]: - dispersion=<time> => wait a random number between 0 and <time> before starting. Default = 300. - 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. - ====-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-==== - $ - - - 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. Example run below: :: - - run here - - For "every day changes" such as adding deliveryservices or changing records.config parameters caches should run the script in "syncds" mode out of cron. Example crontab entry: :: - - */15 * * * * /opt/ort/traffic_ops_ort.pl syncds warn https://traffops.kabletown.net admin:password > /tmp/ort/syncds.log 2>&1 - - .. Note:: <disclaimer on what is "hot changeable" here> http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/9694fb23/docs/latest/_sources/admin/traffic_stats.rst.txt ---------------------------------------------------------------------- diff --git a/docs/latest/_sources/admin/traffic_stats.rst.txt b/docs/latest/_sources/admin/traffic_stats.rst.txt deleted file mode 100644 index ae9d91b..0000000 --- a/docs/latest/_sources/admin/traffic_stats.rst.txt +++ /dev/null @@ -1,187 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -**************************** -Traffic 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. - -Installation -======================== - -**Installing Traffic Stats:** - - - Download the Traffic Stats RPM from the traffic control `downloads <https://trafficcontrol.apache.org/downloads/index.html>`_ page. - - Copy the Traffic Stats RPM to your server - - 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** - - In order to store traffic stats data you will need to install `InfluxDB <https://docs.influxdata.com/influxdb/latest/introduction/installation/>`_. While not required, it is recommended to use some sort of high availability option like `Influx enterprise <https://portal.influxdata.com/>`_, `Influxdb Relay <https://github.com/influxdata/influxdb-relay>`_, or another `high availability option <https://www.influxdata.com/high-availability/>`_. - - -**Installing Grafana:** - - Grafana is used to display Traffic Stats/InfluxDB data in Traffic Ops. Grafana is typically run on the same server as Traffic Stats but this is not a requirement. Grafana can be installed on any server that can access InfluxDB and can be accessed by Traffic Ops. Documentation on installing Grafana can be found on the `Grafana website <http://docs.grafana.org/installation/>`_. - -Configuration -========================= - -**Configuring Traffic Stats:** - - Traffic Stats' configuration file can be found in /opt/traffic_stats/conf/traffic_stats.cfg. - The following values need to be configured: - - - *toUser:* The user used to connect to Traffic Ops - - *toPasswd:* The password to use when connecting to Traffic Ops - - *toUrl:* The URL of the Traffic Ops server used by Traffic Stats - - *influxUser:* The user to use when connecting to InfluxDB (if configured on InfluxDB, else leave default) - - *influxPassword:* That password to use when connecting to InfluxDB (if configured, else leave blank) - - *pollingInterval:* The interval at which Traffic Monitor is polled and stats are stored in InfluxDB - - *statusToMon:* The status of Traffic Monitor to poll (poll ONLINE or OFFLINE traffic monitors) - - *seelogConfig:* The absolute path of the seelong config file - - *dailySummaryPollingInterval:* The interval, in seconds, at which Traffic Stats checks to see if daily stats need to be computed and stored. - - *cacheRetentionPolicy:* The default retention policy for cache stats - - *dsRetentionPolicy:* The default retention policy for deliveryservice stats - - *dailySummaryRetentionPolicy:* The retention policy to be used for the daily stats - - *influxUrls:* An array of influxdb hosts for Traffic Stats to write stats to. - -**Configuring InfluxDB:** - - As mentioned above, it is recommended that InfluxDb be running in some sort of high availability configuration. There are several ways to achieve high availabilty so it is best to consult the high availability options on the `InfuxDB website <https://www.influxdata.com/high-availability/>`_. - - Once InfluxDB is installed and configured, databases and retention policies need to be created. Traffic Stats writes to three different databases: cache_stats, deliveryservice_stats, and daily_stats. More information about the databases and what data is stored in each can be found on the `overview <../overview/traffic_stats.html>`_ page. - - To easily create databases, retention policies, and continuous queries, run create_ts_databases from the /opt/traffic_stats/influxdb_tools directory on your Traffic Stats server. See the `InfluxDb Tools <traffic_stats.html#influxdb-tools>`_ section below for more information. - -**Configuring Grafana:** - - In Traffic Ops the Health -> Graph View tab can be configured to display grafana graphs using influxDb data. In order for this to work correctly, you will need two things 1) a parameter added to traffic ops with the graph URL (more information below) and 2) the graphs created in grafana. See below for how to create some simple graphs in grafana. These instructions assume that InfluxDB has been configured and that data has been written to it. If this is not true, you will not see any graphs. - - - Login to grafana as an admin user http://grafana_url:3000/login - - Choose Data Sources and then Add New - - Enter the necessary information to configure your data source - - Click on the 'Home' dropdown at the top of the screen and choose New at the bottom - - Click on the green menu bar (with 3 lines) at the top and choose Add Panel -> Graph - - Where it says 'No Title (click here)' click and choose edit - - Choose your data source at the bottom - - You can have grafana help you create a query, or you can create your own. Here is a sample query: - - ``SELECT sum(value)*1000 FROM "monthly"."bandwidth.cdn.1min" WHERE $timeFilter GROUP BY time(60s), cdn`` - - Once you have the graph the way you want it, click the 'Save Dashboard' button at the top - - You should now have a new saved graph - - In order for Traffic Ops users to see Grafana graphs, Grafana will need to allow anonymous access. Information on how to configure anonymous access can be found on the configuration page of the `Grafana Website <http://docs.grafana.org/installation/configuration/#authanonymous>`_. - - Traffic Ops uses custom dashboards to display information about individual delivery services or cache groups. In order for the custom graphs to display correctly, the `traffic_ops_*.js <https://github.com/apache/incubator-trafficcontrol/blob/master/traffic_stats/grafana/>`_ files need to be in the ``/usr/share/grafana/public/dashboards/`` directory on the grafana server. If your Grafana server is the same as your Traffic Stats server the RPM install process will take care of putting the files in place. If your grafana server is different from your Traffic Stats server, you will need to manually copy the files to the correct directory. - - More information on custom scripted graphs can be found in the `scripted dashboards <http://docs.grafana.org/reference/scripting/>`_ section of the Grafana documentation. - -**Configuring Traffic Ops for Traffic Stats:** - - - The influxDb servers need to be added to Traffic Ops with profile = InfluxDB. Make sure to use port 8086 in the configuration. - - The traffic stats server should be added to Traffic Ops with profile = Traffic Stats. - - Parameters for which stats will be collected are added with the release, but any changes can be made via parameters that are assigned to the Traffic Stats profile. - -**Configuring Traffic Ops to use Grafana Dashboards** - - To configure Traffic Ops to use Grafana Dashboards, you need to enter the following parameters and assign them to the GLOBAL profile. This assumes you followed the above instructions to install and configure InfluxDB and Grafana. You will need to place 'cdn-stats','deliveryservice-stats', and 'daily-summary' with the name of your dashboards. - - +---------------------------+------------------------------------------------------------------------------------------------+ - | parameter name | parameter value | - +===========================+================================================================================================+ - | all_graph_url | https://<grafana_url>/dashboard/db/deliveryservice-stats | - +---------------------------+------------------------------------------------------------------------------------------------+ - | cachegroup_graph_url | https://<grafanaHost>/dashboard/script/traffic_ops_cachegroup.js?which= | - +---------------------------+------------------------------------------------------------------------------------------------+ - | deliveryservice_graph_url | https://<grafanaHost>/dashboard/script/traffic_ops_devliveryservice.js?which= | - +---------------------------+------------------------------------------------------------------------------------------------+ - | server_graph_url | https://<grafanaHost>/dashboard/script/traffic_ops_server.js?which= | - +---------------------------+------------------------------------------------------------------------------------------------+ - | visual_status_panel_1 | https://<grafanaHost>/dashboard-solo/db/cdn-stats?panelId=2&fullscreen&from=now-24h&to=now-60s | - +---------------------------+------------------------------------------------------------------------------------------------+ - | visual_status_panel_2 | https://<grafanaHost>/dashboard-solo/db/cdn-stats?panelId=1&fullscreen&from=now-24h&to=now-60s | - +---------------------------+------------------------------------------------------------------------------------------------+ - | daily_bw_url | https://<grafanaHost>/dashboard-solo/db/daily-summary?panelId=1&fullscreen&from=now-3y&to=now | - +---------------------------+------------------------------------------------------------------------------------------------+ - | daily_served_url | https://<grafanaHost>/dashboard-solo/db/daily-summary?panelId=2&fullscreen&from=now-3y&to=now | - +---------------------------+------------------------------------------------------------------------------------------------+ - -InfluxDb Tools -========================= - -Under the Traffic Stats source directory there is a directory called influxdb_tools. These tools are meant to be used as one-off scripts to help a user quickly get new databases and continuous queries setup in influxdb. -They are specific for traffic stats and are not meant to be generic to influxdb. Below is an brief description of each script along with how to use it. - -**create_ts_databases** - This script creates all `databases <https://docs.influxdata.com/influxdb/latest/concepts/key_concepts/#database>`_, `retention policies <https://docs.influxdata.com/influxdb/latest/concepts/key_concepts/#retention-policy>`_, and `continuous queries <https://docs.influxdata.com/influxdb/v0.11/query_language/continuous_queries/>`_ required by traffic stats. - - **How to use create_ts_databases:** - - Pre-Requisites: - - 1. Go 1.4 or later - 2. configured $GOPATH (e.g. export GOPATH=~/go) - - Using create_ts_databases.go - - 1. go get github.com/influxdata/influxdb - - 2. go build create_ts_databases.go - - 3. Run it: - - ./create_ts_databases -help - - optional flags: - - influxUrl - 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 -influxUrl=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. - - **How to use sync_ts_databases:** - - Pre-Requisites: - - 1. Go 1.4 or later - 2. configured $GOPATH (e.g. export GOPATH=~/go) - - Using sync_ts_databases.go: - - 1. go get github.com/influxdata/influxdb - - 2. go build sync_ts_databases.go - - 3. Run it - - ./sync_ts_databases -help - - required flags: - - sourceUrl - The URL of the source database - - targetUrl - 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) - - sourceUser - The user of the source database - - sourcePass - The password for the source database - - targetUser - The user of the target database - - targetPass - The password for the target database - - - example: ./sync_ts_databases -sourceUrl=http://influxdb-production-01.kabletown.net:8086 -targetUrl=http://influxdb-dev-01.kabletown.net:8086 -database=cache_stats -days=7 -sourceUser=joe sourcePass=mysecret - http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/9694fb23/docs/latest/_sources/admin/traffic_vault.rst.txt ---------------------------------------------------------------------- diff --git a/docs/latest/_sources/admin/traffic_vault.rst.txt b/docs/latest/_sources/admin/traffic_vault.rst.txt deleted file mode 100644 index 35be160..0000000 --- a/docs/latest/_sources/admin/traffic_vault.rst.txt +++ /dev/null @@ -1,195 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -**************************** -Traffic Vault Administration -**************************** -Installing Traffic Vault -======================== -In order to successfully store private keys you will need to install Riak. -The latest version of Riak can be downloaded on the Riak `website <http://docs.basho.com/riak/latest/downloads/>`_. -The installation instructions for Riak can be found `here <http://docs.basho.com/riak/latest/ops/building/installing/>`_. - -Production is currently running version 2.0.5 of Riak, but the latest version should suffice. - - -Configuring Traffic Vault -========================= -The following steps were taken to configure Riak in our 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 - -* cd to /etc/riak/ - -* Update the following in riak.conf to reflect your IP: - - nodename = [email protected] - - 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) - -* Updated the following conf file to point to your cert files - - ssl.certfile = /etc/riak/certs/server.crt - - ssl.keyfile = /etc/riak/certs/server.key - - ssl.cacertfile = /etc/pki/tls/certs/ca-bundle.crt - -* Add a line at the bottom of the config for tlsv1 - - tls_protocols.tlsv1 = on - -* Once the config file has been updated restart riak - - ``/etc/init.d/riak restart`` - -* Validate server is running by going to the following URL: - - https://<serverHostname>:8088/ping - -Riak-admin configuration -------------------------- - -Riak-admin is a command line utility that needs to be run as root on a server in the riak cluster. - -Assumptions: - * Riak 2.0.2 or greater is installed - * SSL Certificates have been generated (signed or self-signed) - * Root access to riak servers - -Add admin user and riakuser to riak - * Admin user will be a super user - * Riakuser will be the application user - -Login to one of the riak servers in the cluster as root (any will do) - - 1. Enable security - - ``riak-admin security enable`` - - 2. Add groups - - ``riak-admin security add-group admins`` - - ``riak-admin security add-group keysusers`` - 3. Add users - - .. Note:: username 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 - - ``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 - - ``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 - - ``riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default ssl to keysusers`` - - ``riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default dnssec to keysusers`` - - ``riak-admin security grant riak_kv.get,riak_kv.put,riak_kv.delete on default url_sig_keys to keysusers`` - -.. 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/>`_. - - -Traffic Ops Configuration -------------------------- - -There are a couple configurations that are necessary in Traffic Ops. - -1. Database Updates - * A new profile for Riak needs to be added to the profile table - * A new type of Riak needs to be added to the type table - * The servers in the Riak cluster need to be added to the server table - - .. Note:: profile and type data should be pre-loaded by seeds sql script. - .. - -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. - -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. - -Riak Configuration ------------------- - -On Each Riak Server: - -1. If java 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`` - -2. enable search in riak.conf - * ``vim /etc/riak/riak.conf`` - * look for search and change ``search = off`` to ``search = on`` - -3. Restart Riak so search is on - * ``service riak restart`` - -One time configuration: - -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 index to admin`` - -``riak-admin security grant search.query on index to admin`` - -``riak-admin security grant search.query on index sslkeys to admin`` - -``riak-admin security grant search.query on index to riakuser`` - -``riak-admin security grant search.query on index sslkeys to riakuser`` - -``riak-admin security grant riak_core.set_bucket on any to admin`` - -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/incubator-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"}'`` - -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. The following explains how to run the script. - -1. Get script from github either by cloning the project and going to `traffic_ops/app/script` or from `here <https://github.com/apache/incubator-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`` - -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"`` - -Validation can also be done by querying Traffic Ops: -``curl -Lvs -H "Cookie: $COOKIE" https://traffic-ops.kabletown.net/api/1.2/cdns/name/mycdn/sslkeys.json`` - - - - http://git-wip-us.apache.org/repos/asf/incubator-trafficcontrol-website/blob/9694fb23/docs/latest/_sources/basics/cache_revalidation.rst.txt ---------------------------------------------------------------------- diff --git a/docs/latest/_sources/basics/cache_revalidation.rst.txt b/docs/latest/_sources/basics/cache_revalidation.rst.txt deleted file mode 100644 index dc57346..0000000 --- a/docs/latest/_sources/basics/cache_revalidation.rst.txt +++ /dev/null @@ -1,71 +0,0 @@ -.. -.. -.. Licensed under the Apache License, Version 2.0 (the "License"); -.. you may not use this file except in compliance with the License. -.. You may obtain a copy of the License at -.. -.. http://www.apache.org/licenses/LICENSE-2.0 -.. -.. Unless required by applicable law or agreed to in writing, software -.. distributed under the License is distributed on an "AS IS" BASIS, -.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -.. See the License for the specific language governing permissions and -.. limitations under the License. -.. - -.. index:: - 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 - - <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. In stead of requesting the object again from the origin server, the cache will send a request to the origin indicating what version of the response it has, and asking if it has changed. If it changed, the server will send a ``200 OK`` response, with the new data. If it has not changed, the origin server will send back a ``304 Not Modified`` response indicating the response is still valid, and that the cache can reset the timer on the response expiration. To indicate what version the client (cache) has it will add an ``If-Not-Modifie d-Since:`` header, or an ``If-None-Match:`` header. For example, in the ``If-None-Match:`` case, the origin will send and ``ETag`` header that uniquely identifies the response. The client can use that in an revalidation request like:: - - GET /foo/bar/fun.html HTTP/1.1 - If-None-Match: "1aa008f-2d-50a3559482cc0" - Host: www.origin.com - -If the content has changed (meaning, the new response would not have had the same ETag) it will respond with ``200 OK``, like:: - - 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> - - -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 - -Note that the 304 response only has headers, not the data. - \ No newline at end of file
