trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [43/51] trafficserver git commit: Documentation reorganization
Date Tue, 03 Nov 2015 06:10:19 GMT
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/configuration/explicit-forward-proxying.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/explicit-forward-proxying.en.rst b/doc/admin-guide/configuration/explicit-forward-proxying.en.rst
new file mode 100644
index 0000000..3608536
--- /dev/null
+++ b/doc/admin-guide/configuration/explicit-forward-proxying.en.rst
@@ -0,0 +1,83 @@
+.. _explicit-proxy-caching:
+
+Explicit Proxy Caching
+**********************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. toctree::
+   :maxdepth: 2
+
+If you want to use Traffic Server as an explicit proxy cache, you must
+configure client software (i.e., browsers) to send requests directly to
+Traffic Server.
+
+If you do not configure Traffic Server to use the transparency option
+(with which client requests are intercepted en route to origin servers
+by a switch/router and rerouted to the Traffic Server machine), then
+clients must configure their web browsers to send HTTP requests to the
+Traffic Server proxy cache by configuring their browsers to download
+proxy configuration instructions from a :ref:`PAC file <using-a-pack-file>`
+(Proxy Auto-Configuration file).
+
+Configuring Browsers Manually
+=============================
+
+To manually configure a browser to send HTTP requests to Traffic Server,
+clients must provide the following information:
+
+-  The fully-qualified hostname or IP address of the Traffic Server node
+-  The Traffic Server proxy server port (by default, 8080)
+
+In addition, clients can specify not to use Traffic Server for certain
+sites - in such cases, requests to the listed sites go directly to the
+origin server. The procedures for manual configuration vary among
+browser versions; refer to specific browser documentation for complete
+proxy configuration instructions. You do not need to set any special
+configuration options on Traffic Server if you want to accept requests
+from manually-configured browsers.
+
+.. _using-a-pack-file:
+
+Using a PAC File
+================
+
+A *PAC file* is a specialized JavaScript function definition that a
+browser calls to determine how requests are handled. Clients must
+specify (in their browser settings) the URL from which the PAC file is
+loaded. You can store a PAC file on Traffic Server (or on any server in
+your network) and then provide the URL for this file to your clients.
+
+Sample PAC File
+---------------
+
+The following sample PAC file instructs browsers to connect directly to
+all hosts without a fully-qualified domain name and to all hosts in the
+local domain. All other requests go to the Traffic Server named
+``myproxy.company.com``.::
+
+    function FindProxyForURL(url, host)
+    {
+      if (isPlainHostName(host)) || (localHostOrDomainIs(host, ".company.com")) {
+        return "DIRECT";
+      }
+      else
+        return "PROXY myproxy.company.com:8080; DIRECT";
+    }
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/configuration/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/index.en.rst b/doc/admin-guide/configuration/index.en.rst
new file mode 100644
index 0000000..f84057e
--- /dev/null
+++ b/doc/admin-guide/configuration/index.en.rst
@@ -0,0 +1,34 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. include:: ../../common.defs
+
+.. _admin-configuration:
+
+Proxy Cache Configuration
+*************************
+
+.. toctree::
+   :maxdepth: 2
+
+   session-protocol.en
+   cache-basics.en
+   redirecting-http-requests.en
+   reverse-proxying.en
+   explicit-forward-proxying.en
+   transparent-forward-proxying.en
+   multi-server-caches.en

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/configuration/multi-server-caches.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/multi-server-caches.en.rst b/doc/admin-guide/configuration/multi-server-caches.en.rst
new file mode 100644
index 0000000..aa37530
--- /dev/null
+++ b/doc/admin-guide/configuration/multi-server-caches.en.rst
@@ -0,0 +1,180 @@
+.. _traffic-server-cluster:
+
+Traffic Server Cluster
+**********************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+Traffic Server scales from a single node to multiple nodes that form a
+cluster allowing you to improve system performance and reliability.
+
+.. toctree::
+   :maxdepth: 1
+
+Understanding Traffic Server Clusters
+=====================================
+
+A Traffic Server cluster consists of multiple Traffic Server nodes. The
+nodes in a cluster share configuration information and can form a single
+logical cache. Traffic Server detects the addition and deletion of nodes
+in the cluster automatically and can detect when a node is unavailable.
+Traffic Server uses its own protocol for clustering, which is multicast
+for node location and heartbeat, but unicast for all data exchange
+within the cluster. Traffic Server has two clustering modes:
+
+-  Management-only mode; refer to `Management-Only Clustering`_ below.
+-  Full-clustering mode; refer to `Full Clustering`_
+
+Management-Only Clustering
+==========================
+
+In management-only clustering mode, Traffic Server cluster nodes share
+configuration information. You can administer all the nodes at the same
+time. Traffic Server uses a multicast management protocol to provide a
+single system image of your Traffic Server cluster. Information about
+cluster membership, configuration, and exceptions is shared across all
+nodes, and the :program:`traffic_manager` process automatically propagates
+configuration changes to all the nodes.
+
+Full Clustering
+===============
+
+In full-clustering mode, as well as sharing configuration information, a
+Traffic Server cluster distributes its cache across its nodes into a
+single, virtual object store, rather than replicating the cache node by
+node. Traffic Server can provide an enormous aggregate cache size and
+can maximize cache hit rate by storing objects only once across the
+entire cluster.
+
+A fully clustered Traffic Server maps objects to specific nodes in the
+cluster. When a node receives a request, it checks to see if the request
+is a hit somewhere in the cluster. If the request is a hit on a
+different node, the node handling the request obtains the object from
+the hit node and serves it to the client. Traffic Server uses its own
+communication protocol to obtain an object from sibling cluster nodes.
+
+If a node fails or is shut down and removed, Traffic Server removes
+references to the missing node on all nodes in the cluster.
+
+Full clustering recommends a dedicated network interface for cluster
+communication to achieve better performance.
+
+Enabling Clustering Mode
+========================
+
+Before a node is added into a cluster, please ensure that the following
+conditions are being met:
+
+-  All nodes are running the same operating system:
+
+   -  The same distribution, e.g.: RHEL 6.6
+   -  The same kernel, e.g.: 2.6.32-504.23.4.el6
+   -  The same architecture, e.g.: x86_64
+
+-  All nodes have the same version of Traffic Server installed
+-  All nodes are composed of the same hardware
+-  All nodes are on the same switch or same VLAN.
+
+Traffic Server does not apply the clustering mode change to all the
+nodes in the cluster. You must change the clustering mode on each node
+individually. You may following these instructions:
+
+1. Setup the same cluster name, with :ts:cv:`proxy.config.proxy_name`, e.g. ``MyCluster``.
+
+2. Set :ts:cv:`proxy.local.cluster.type` to ``1`` to enable cluster mode. The
+   following values of this configuration are valid:
+
+================= ==================================================
+Value             Description
+================= ==================================================
+1                 Full-Clustering mode
+2                 Management-Only mode
+3                 No clustering (*default*)
+================= ==================================================
+
+3. Configure :ts:cv:`proxy.config.cluster.ethernet_interface`, e.g.: ``eth0``.
+   This should be replaced with the node's real interface. We recommends a
+   dedicated physical interface here. Refer to :ts:cv:`proxy.local.cluster.type`
+   for a full description.
+
+4. Enable configuration changes::
+
+       traffic_ctl config reload
+
+5. Restart traffic server::
+
+       traffic_ctl server restart
+
+   The :program:`traffic_server` and :program:`traffic_manager` processes will need to
+   restart after the change of :ts:cv:`proxy.local.cluster.type` and
+   :ts:cv:`proxy.config.cluster.ethernet_interface` have taken place.
+
+Traffic Server will join the cluster in about 10 seconds. To verify the hosts in the
+cluster, you can run::
+
+    traffic_ctl metric get proxy.process.cluster.nodes
+
+Cluster node status is also tracked in ``cluster.config`` in the configuration
+directory. This configuration is generated by the system and should not be
+edited. It contains a list of the machines that are currently members of the
+cluster, for example::
+
+    # 3
+    127.1.2.3:80
+    127.1.2.4:80
+    127.1.2.5:80
+
+After successfully joining a cluster, all changes of global configurations
+performed on any node in that cluster will take effect on all nodes, removing
+the need to manually duplicate configuration changes across each node individually.
+
+Deleting Nodes from a Cluster
+=============================
+
+To delete a node from the Traffic Server cluster, return the setting
+:ts:cv:`proxy.local.cluster.type` to the default value ``3`` and reload.
+
+Common issues for Cluster setup
+===============================
+
+1. The Cluster member auto discovery is built upon multi-casting UDP, and as such
+   is impossible to setup where multi-casting is not avaliable, such as AWS EC2.
+
+2. The Cluster will depend on ports 8088, 8089, and 8086. These ports must not be
+   blocked by any network configurations or firewalls on the network used for
+   internal cluster communication.
+
+Performance Tuning for Busy Clusters
+====================================
+
+Beginning with version 3.2.0, Apache Traffic Server can handle multiple internal
+cluster connections and the number of Cluster Threads is configurable. Each
+of the threads will keep one connection open to all peering cluster nodes.
+
+Increasing Cluster Threads
+--------------------------
+
+In the cluster environment, the current performance of the cluster threads
+will consume the same cpu usage as a normal network thread. It's reasonable
+to keep roughly the same number of cluster threads as network threads. For
+example, if you are running a system with 10 network processing threads,
+you can set the number of cluster threads by modifying
+:ts:cv:`proxy.config.cluster.threads` to ``10``::
+
+    traffic_ctl config set proxy.config.cluster.threads 10
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/configuration/redirecting-http-requests.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/redirecting-http-requests.en.rst b/doc/admin-guide/configuration/redirecting-http-requests.en.rst
new file mode 100644
index 0000000..8c69a9f
--- /dev/null
+++ b/doc/admin-guide/configuration/redirecting-http-requests.en.rst
@@ -0,0 +1,331 @@
+.. _reverse-proxy-and-http-redirects:
+
+Reverse Proxy and HTTP Redirects
+********************************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+Reverse Proxy and HTTP Redirects
+================================
+
+As a reverse proxy cache, Traffic Server serves requests on behalf of
+origin servers. Traffic Server is configured in such a way that it
+appears to clients like a normal origin server.
+
+.. toctree::
+   :maxdepth: 2
+
+Understanding Reverse Proxy Caching
+===================================
+
+With *forward proxy caching*, Traffic Server handles web requests to origin
+servers on behalf of the clients requesting the content. *Reverse proxy
+caching* (also known as *server acceleration*) is different because Traffic
+Server acts as a proxy cache on behalf of the origin servers that store the
+content. Traffic Server is configured to behave outwardly as origin server
+which the client is trying to connect to. In a typical scenario the advertised
+hostname of the origin server resolves to Traffic Server, which serves client
+requests directly, fetching content from the true origin server when necessary.
+
+Reverse Proxy Solutions
+-----------------------
+
+There are many ways to use Traffic Server as a reverse proxy. Below are
+a few example scenarios.
+
+-  Offload heavily-used origin servers.
+
+-  Deliver content efficiently in geographically distant areas.
+
+-  Provide security for origin servers that contain sensitive information.
+
+Offloading Heavily-Used Origin Servers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Traffic Server can accept requests on behalf of the origin server and improve
+the speed and quality of web serving by reducing load and hot spots on
+backup origin servers. For example, a web hoster can maintain a scalable
+Traffic Server system with a set of low-cost, low-performance,
+less-reliable PC origin servers as backup servers. In fact, a single
+Traffic Server can act as the virtual origin server for multiple backup
+origin servers, as shown in the figure below.
+
+.. figure:: /static/images/admin/revproxy.jpg
+   :align: center
+   :alt: Traffic Server as reverse proxy for a pair of origin servers
+
+   Traffic Server as reverse proxy for a pair of origin servers
+
+Delivering Content in Geographically-Dispersed Areas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Traffic Server can be used in reverse proxy mode to accelerate origin
+servers that provide content to areas not located within close
+geographical proximity. Caches are typically easier to manage and are
+more cost-effective than replicating data. For example, Traffic Server
+can be used as a mirror site on the far side of a trans-Atlantic link to
+serve users without having to fetch the request and content across
+expensive, or higher latency, international connections. Unlike replication,
+for which hardware must be configured to replicate all data and to handle peak
+capacity, Traffic Server dynamically adjusts to optimally use the
+serving and storing capacity of the hardware. Traffic Server is also
+designed to keep content fresh automatically, thereby eliminating the
+complexity of updating remote origin servers.
+
+Providing Security for an Origin Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Traffic Server can be used in reverse proxy mode to provide security for
+an origin server. If an origin server contains sensitive information
+that you want to keep secure inside your firewall, then you can use a
+Traffic Server outside the firewall as a reverse proxy for that origin
+server. When outside clients try to access the origin server, the
+requests instead go to Traffic Server. If the desired content is not
+sensitive, then it can be served from the cache. If the content is
+sensitive and not cacheable, then Traffic Server obtains the content
+from the origin server (the firewall allows only Traffic Server access
+to the origin server). The sensitive content resides on the origin
+server, safely inside the firewall.
+
+How Does Reverse Proxy Work?
+----------------------------
+
+When a browser makes a request, it normally sends that request directly
+to the origin server. When Traffic Server is in reverse proxy mode, it
+intercepts the request before it reaches the origin server. Typically,
+this is done by setting up the DNS entry for the origin server (i.e.,
+the origin server's advertised hostname) so it resolves to the Traffic
+Server IP address. When Traffic Server is configured as the origin
+server, the browser connects to Traffic Server rather than the origin
+server. For additional information, see `HTTP Reverse Proxy`_.
+
+.. note::
+
+    To avoid a DNS conflict, the origin server’s hostname and its advertised
+    hostname must not be the same.
+
+HTTP Reverse Proxy
+==================
+
+In reverse proxy mode, Traffic Server serves HTTP requests on behalf of
+a web server. The figure below illustrates how Traffic Server in reverse
+proxy mode serves an HTTP request from a client browser.
+
+.. figure:: /static/images/admin/httprvs.jpg
+   :align: center
+   :alt: HTTP reverse proxy
+
+   HTTP reverse proxy
+
+The figure above demonstrates the following steps:
+
+.. List below should remain manually numbered, as the entries correspond to numbers in the figure above.
+
+1. A client browser sends an HTTP request addressed to a host called
+   ``www.host.com`` on port 80. Traffic Server receives the request
+   because it is acting as the origin server (the origin server’s
+   advertised hostname resolves to Traffic Server).
+
+2. Traffic Server locates a map rule in the :file:`remap.config` file and
+   remaps the request to the specified origin server (``realhost.com``).
+
+3. If the request cannot be served from cache, Traffic Server opens a
+   connection to the origin server (or more likely, uses an existing
+   connection it has pre-established), retrieves the content, and optionally
+   caches it for future use.
+
+4. If the request was a cache hit and the content is still fresh in the cache,
+   or the content is now available through Traffic Server because of step 3,
+   Traffic Server sends the requested object to the client from the cache
+   directly.
+
+.. note::
+
+    Traffic Server, when updating its own cache from the origin server, will
+    simultaneously deliver that content to the client while updating its
+    cache database. The response to the client containing the requested object
+    will begin as soon as Traffic Server has received and processed the full
+    response headers from the origin server.
+
+To configure HTTP reverse proxy, you must perform the following tasks:
+
+-  Create mapping rules in the :file:`remap.config` file (refer to `Creating
+   Mapping Rules for HTTP Requests`_). ::
+
+      map http://www.host.com http://realhost.com
+
+-  Enable the reverse proxy option (refer to `Enabling HTTP Reverse Proxy`_).
+
+In addition to the tasks above, you can also `Setting Optional HTTP Reverse Proxy Options`_.
+
+Handling Origin Server Redirect Responses
+-----------------------------------------
+
+Origin servers often send redirect responses back to browsers
+redirecting them to different pages. For example, if an origin server is
+overloaded, then it might redirect browsers to a less loaded server.
+Origin servers also redirect when web pages have moved to different
+locations. When Traffic Server is configured as a reverse proxy, it must
+readdress redirects from origin servers so that browsers are redirected
+to Traffic Server and not to another origin server.
+
+To readdress redirects, Traffic Server uses reverse-map rules. Unless
+you have :ts:cv:`proxy.config.url_remap.pristine_host_hdr` enabled
+(the default) you should generally set up a reverse-map rule for
+each map rule. To create reverse-map rules, refer to `Using Mapping
+Rules for HTTP Requests`_.
+
+Using Mapping Rules for HTTP Requests
+-------------------------------------
+
+Traffic Server uses two types of mapping rules for HTTP reverse proxy.
+
+map rule
+~~~~~~~~
+
+A *map rule* translates the URL in client requests into the URL where
+the content is located. When Traffic Server is in reverse proxy mode and
+receives an HTTP client request, it first constructs a complete request
+URL from the relative URL and its headers. Traffic Server then looks for
+a match by comparing the complete request URL with its list of target
+URLs in :file:`remap.config`. For the request URL to match a target URL, the
+following conditions must be true:
+
+-  The scheme of both URLs must be the same.
+
+-  The host in both URLs must be the same. If the request URL contains
+   an unqualified hostname, then it will never match a target URL with a
+   fully-qualified hostname.
+
+-  The ports in both URLs must be the same. If no port is specified in a
+   URL, then the default port for the scheme of the URL is used.
+
+-  The path portion of the target URL must match a prefix of the request
+   URL path.
+
+If Traffic Server finds a match, then it translates the request URL into
+the replacement URL listed in the map rule: it sets the host and path of
+the request URL to match the replacement URL. If the URL contains path
+prefixes, then Traffic Server removes the prefix of the path that
+matches the target URL path and substitutes it with the path from the
+replacement URL. If two mappings match a request URL, then Traffic
+Server applies the first mapping listed in :file:`remap.config`.
+
+reverse-map rule
+~~~~~~~~~~~~~~~~
+
+A *reverse-map rule* translates the URL in origin server redirect
+responses to point to Traffic Server so that clients are redirected
+to Traffic Server instead of accessing an origin server directly. For
+example, if there is a directory ``/pub`` on an origin server at
+``www.molasses.com`` and a client sends a request to that origin server
+for ``/pub``, then the origin server might reply with a redirect by
+sending the Header ``Location: http://realhost.com/pub/`` to let the
+client know that it was a directory it had requested, not a document (a
+common use of redirects is to normalize URLs so that clients can
+bookmark documents properly).
+
+Traffic Server uses ``reverse_map`` rules to prevent clients (that
+receive redirects from origin servers) from bypassing Traffic Server and
+directly accessing the origin servers. In many cases the client would be
+hitting a wall because ``realhost.com`` actually does not resolve for
+the client. (E.g.: Because it's running on a port shielded by a
+firewall, or because it's running on a non-routable LAN IP)
+
+Both map and reverse-map rules consist of a *target* (origin) URL and
+a *replacement* (destination) URL. In a *map rule*, the target URL
+points to Traffic Server and the replacement URL specifies where the
+original content is located. In a *reverse-map rule*, the target URL
+specifies where the original content is located and the replacement URL
+points to Traffic Server. Traffic Server stores mapping rules in
+:file:`remap.config` located in the Traffic Server ``config`` directory.
+
+Creating Mapping Rules for HTTP Requests
+----------------------------------------
+
+To create mapping rules:
+
+#. Enter the map and reverse-map rules into :file:`remap.config`.
+
+#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
+
+Enabling HTTP Reverse Proxy
+---------------------------
+
+To enable HTTP reverse proxy:
+
+#. Edit :ts:cv:`proxy.config.reverse_proxy.enabled` in :file:`records.config`. ::
+
+    CONFIG proxy.config.reverse_proxy.enabled INT 1
+
+#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
+
+Setting Optional HTTP Reverse Proxy Options
+-------------------------------------------
+
+Traffic Server provides several reverse proxy configuration options in
+:file:`records.config` that enable you to:
+
+-  Configure Traffic Server to retain the client host header information
+   in a request during translation.
+   See :ts:cv:`proxy.config.url_remap.pristine_host_hdr`.
+
+-  Configure Traffic Server to serve requests only to the origin servers
+   listed in the mapping rules. As a result, requests to origin servers
+   not listed in the mapping rules are not served.
+   See :ts:cv:`proxy.config.url_remap.remap_required`.
+
+-  Specify an alternate URL to which incoming requests from older clients ,such
+   as ones that do not provide ``Host`` headers, are directed.
+   See :ts:cv:`proxy.config.header.parse.no_host_url_redirect`.
+
+Run the command :option:`traffic_ctl config reload` to apply any of these configuration
+changes.
+
+Redirecting HTTP Requests
+=========================
+
+You can configure Traffic Server to redirect HTTP requests without
+having to contact any origin servers. For example, if you redirect all
+requests for ``http://www.ultraseek.com`` to
+``http://www.server1.com/products/portal/search/``, then all HTTP
+requests for ``www.ultraseek.com`` go directly to
+``www.server1.com/products/portal/search``.
+
+You can configure Traffic Server to perform permanent or temporary
+redirects. *Permanent redirects* notify the browser of the URL change
+(by returning the HTTP status code ``301``) so that the browser can
+update bookmarks. *Temporary redirects* notify the browser of the URL
+change for the current request only (by returning the HTTP status code
+``307`` ).
+
+To set redirect rules:
+
+#. For each redirect you want to set enter a mapping rule in :file:`remap.config`.
+
+#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
+
+Example
+-------
+
+The following permanently redirects all HTTP requests for
+``www.server1.com`` to ``www.server2.com``: ::
+
+    redirect http://www.server1.com http://www.server2.com
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/configuration/session-protocol.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/session-protocol.en.rst b/doc/admin-guide/configuration/session-protocol.en.rst
new file mode 100644
index 0000000..20a3bf1
--- /dev/null
+++ b/doc/admin-guide/configuration/session-protocol.en.rst
@@ -0,0 +1,59 @@
+.. _session-protocol:
+
+Session Protocol
+****************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+Traffic Server supports some session level protocols in place of, or on top of
+HTTP. These can be provided by a plugin (see :ref:`new-protocol-plugins`) or
+be one that is supported directly by Traffic Server. The
+`SPDY <http://www.chromium.org/spdy>`_ protocol is the only one currently
+supported, but it is planned to support HTTP 2 when that is finalized.
+
+Session protocols are specified by explicit names, based on the
+`NPN <https://technotes.googlecode.com/git/nextprotoneg.html>`_ names. The
+core supported names are:
+
+*  ``http/0.9``
+*  ``http/1.0``
+*  ``http/1.1``
+*  ``http/2``
+*  ``spdy/1``
+*  ``spdy/2``
+*  ``spdy/3``
+*  ``spdy/3.1``
+
+The ``http/2`` value is not currently functional, but is included for future
+use. Both ``spdy/1`` and ``spdy/2`` are obsolete, but are include for
+completeness.
+
+The session protocols supported on a proxy port are a subset of these values.
+For convenience some pseudo-values are defined in terms of these fundamental
+protocols:
+
+*  ``http`` means ``http/0.9``, ``http/1.0``, and ``http/1.1``
+*  ``spdy`` means ``spdy/3`` and ``spdy/3.1``.
+*  ``http2`` means ``http/2``
+
+Each proxy port can be configured in :ts:cv:`proxy.config.http.server_ports`
+to support a subset of these session protocols. For TLS enabled connections this
+configuration controls which protocols are offered by NPN. Protocol sniffing is
+use for non-TLS proxy ports to determine which protocol is being used by the
+client. If the detected protocol is not supported for that proxy port the
+connection is dropped.

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/configuration/transparent-forward-proxying.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/transparent-forward-proxying.en.rst b/doc/admin-guide/configuration/transparent-forward-proxying.en.rst
new file mode 100644
index 0000000..cee8ba6
--- /dev/null
+++ b/doc/admin-guide/configuration/transparent-forward-proxying.en.rst
@@ -0,0 +1,118 @@
+.. _forward-proxy:
+
+Forward Proxy
+*************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+The Apache Traffic Server is a general purpose proxy, configurable as both a
+reverse and forward proxy.
+
+A forward proxy can be used as a central tool in your infrastructure
+to access the web and it may be combined with a cache to lower your overall
+bandwidth usage. Forward proxies act as a gatekeeper between client browsers
+on your local network and all (or some, at your configuration's discretion)
+web sites accessed by those clients. The forward proxy will receive the
+HTTP requests, perform any filtering or request alteration rules you
+establish, and when appropriate forward the request on to its destination
+website. The response will return through your proxy, where it may optionally
+be cached and/or modified, and then returned to the original client.
+
+There are two modes in which your forward proxy may operate:
+
+Forward Proxy
+    Each client must be configured explicitly to use the forward proxy. Client
+    browsers will be aware of the fact they are using a proxy and will form their
+    HTTP requests appropriately. This results in the initial HTTP command being
+    issued with fully qualified URIs that contain the destination hostname::
+
+        GET http://example.com/index.php?id=123 HTTP/1.1
+
+Transparent Proxy
+    The use of a transparent proxy is typically done in concert with network
+    routing rules which redirect all outbound HTTP traffic through your proxy.
+    Clients will behave, and form their HTTP requests, as if they are contacting
+    the remote site directly, and will not be aware of the existence of a proxy
+    server in between themselves and the remote servers. HTTP requests will be
+    generated per their usual form, with only paths in the command and a
+    separate Host request header::
+
+        GET /index?id=123 HTTP/1.1
+        Host: example.com
+
+Apache Traffic Server may be configured to operate as both a forward and
+a transparent proxy simultaneously.
+
+Proxy Configuration
+===================
+
+Configuring basic forward proxy operation in Traffic Server is quite simple
+and straightforward.
+
+1. Permit Traffic Server to process requests for hosts not explicitly configured
+   in the remap rules, by modifying :ts:cv:`proxy.config.url_remap.remap_required`
+   in :file:`records.config`::
+
+        CONFIG proxy.config.url_remap.remap_required INT 0
+
+2. *Optional*: If Traffic Server will be operating strictly as a forward proxy,
+   you will want to disable reverse proxy support by modifying
+   :ts:cv:`proxy.config.reverse_proxy.enabled` in :file:`records.config`::
+
+        CONFIG proxy.config.reverse_proxy.enabled INT 0
+
+You may also want to consider some of these configuration options:
+
+- Setting :ts:cv:`proxy.config.http.no_dns_just_forward_to_parent` determines which
+  host will be used for DNS resolution.
+
+- Proxy Authentication can be enabled or disabled with
+  :ts:cv:`proxy.config.http.forward.proxy_auth_to_parent` should you also be
+  employing a proxy cache.
+
+- The client request header X-Forwarded-For may be toggled with
+  :ts:cv:`proxy.config.http.insert_squid_x_forwarded_for`.
+
+Client Configuration
+====================
+
+If you are operating your proxy in transparent mode, your clients should require
+no special proxy-related configuration.
+
+If you are operating in explicit forward proxy mode, without automatic routing
+rules on your network to direct all outbound traffic through the proxy, your
+client browsers will need to be directed to the proxy. This may be accomplished
+in two different ways.
+
+Clients may be configured to use the default ``8080`` port on your Traffic Server
+host as a proxy. This will result in all requests from that client browser being
+issued through the single forward proxy as configured.
+
+Security Considerations
+=======================
+
+It's important to note that once your Apache Traffic Server is configured as a
+forward proxy it will indiscriminately accept proxy requests from anyone. If it
+is reachable from the Internet, then you have configured an *Open Proxy*.
+
+This is generally not desirable, as it will permit anyone to potentially use
+your network as the source of traffic to sites of their choosing. To avoid
+this, you'll have to make sure your proxy server is either only reachable from
+within your private network or is secured by firewall rules that permit only
+those you wish to have access to the proxy.
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/configuring-traffic-server.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuring-traffic-server.en.rst b/doc/admin-guide/configuring-traffic-server.en.rst
new file mode 100644
index 0000000..bb076b4
--- /dev/null
+++ b/doc/admin-guide/configuring-traffic-server.en.rst
@@ -0,0 +1,80 @@
+.. _configuring-traffic-server:
+
+Configuring Traffic Server
+**************************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+Traffic Server provides several options for configuring the system.
+
+.. toctree::
+   :maxdepth: 2
+
+.. _configure-using-traffic-line:
+
+Configure Traffic Server Using Traffic Line
+===========================================
+
+Traffic Line enables you to quickly and easily change your Traffic
+Server configuration via command-line interface.
+
+View Configuration Options in Traffic Line
+------------------------------------------
+
+To view a configuration setting, enter the following command::
+
+    traffic_ctl config get VARIABLE
+
+where *var* is the variable associated with the configuration
+option. For a list of variables, refer to :ref:`configuration-variables`.
+
+Change Configuration Options in Traffic Line
+--------------------------------------------
+
+To change the value of a configuration setting, enter the following
+command::
+
+    traffic_config set VARIABLE VALUE
+
+where *var* is the variable associated with the configuration option
+and *value* is the value you want to use. For a list of the
+variables, see :ref:`configuration-variables`.
+
+Configure Traffic Server Using Configuration Files
+==================================================
+
+As an alternative to using Traffic Line, you can change
+Traffic Server configuration options by manually editing specific
+variables in :file:`records.config`.
+
+Traffic Server must reread the configuration files for any changes to take effect.
+This is done with :option:`traffic_ctl config reload`. Some configuration changes require a
+full restart of Traffic Server.
+
+The following is a sample portion of :file:`records.config`:
+
+.. figure:: ../static/images/admin/records.jpg
+   :align: center
+   :alt: Sample records.config file
+
+   Sample records.config file
+
+In addition to :file:`records.config`,
+Traffic Server provides other configuration files that are used to
+configure specific features. You can manually edit all configuration
+files as described in :ref:`admin-configuration-files`.

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/cache.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/cache.config.en.rst b/doc/admin-guide/files/cache.config.en.rst
new file mode 100644
index 0000000..0472151
--- /dev/null
+++ b/doc/admin-guide/files/cache.config.en.rst
@@ -0,0 +1,203 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+.. configfile:: cache.config
+
+============
+cache.config
+============
+
+The :file:`cache.config` file (by default, located in 
+``/usr/local/etc/trafficserver/``) defines how Traffic Server caches 
+web objects. You can add caching rules to specify the following: 
+
+    - Not to cache objects from specific IP addresses 
+    - How long to pin particular objects in the cache
+    - How long to consider cached objects as fresh 
+    - Whether to ignore no-cache directives from the server
+    
+.. important::
+
+   After you modify the :file:`cache.config` file, navigate to
+   the Traffic Server bin directory; then run the :option:`traffic_ctl config reload`
+   command to apply changes. When you apply the changes to a node in a
+   cluster, Traffic Server automatically applies the changes to all other
+   nodes in the cluster.
+
+Format
+======
+
+Each line in the :file:`cache.config` file contains a caching rule. Traffic
+Server recognizes three space-delimited tags::
+
+   primary_destination=value secondary_specifier=value action=value
+
+You can use more than one secondary specifier in a rule. However, you
+cannot repeat a secondary specifier. The following list shows the
+possible primary destinations with allowed values.
+
+.. _cache-config-format-dest-domain:
+
+``dest_domain``
+   A requested domain name. Traffic Server matches the domain name of
+   the destination from the URL in the request.
+
+.. _cache-config-format-dest-host:
+
+``dest_host``
+   A requested hostname. Traffic Server matches the hostname of the
+   destination from the URL in the request.
+
+.. _cache-config-format-dest-ip:
+
+``dest_ip``
+   A requested IP address. Traffic Server matches the IP address of the
+   destination in the request.
+
+.. _cache-config-format-url-regex:
+
+``url_regex``
+   A regular expression (regex) to be found in a URL.
+
+The secondary specifiers are optional in the :file:`cache.config` file. The
+following list shows possible secondary specifiers with allowed values.
+
+.. _cache-config-format-port:
+
+``port``
+   A requested URL port.
+
+.. _cache-config-format-scheme:
+
+``scheme``
+   A request URL protocol: http or https.
+
+.. _cache-config-format-prefix:
+
+``prefix``
+   A prefix in the path part of a URL.
+
+.. _cache-config-format-suffix:
+
+``suffix``
+   A file suffix in the URL.
+
+.. _cache-config-format-method:
+
+``method``
+   A request URL method: get, put, post, trace.
+
+.. _cache-config-format-time:
+
+``time``
+   A time range, such as 08:00-14:00.
+
+.. _cache-config-format-src-ip:
+
+``src_ip``
+   A client IP address.
+
+.. _cache-config-format-internal:
+
+``internal``
+    A boolean value, ``true`` or ``false``, specifying if the rule should
+    match (or not match) a transaction originating from an internal API. This
+    is useful to differentiate transaction originating from an ATS plugin.
+
+The following list shows possible actions and their allowed values.
+
+
+.. _cache-config-format-action:
+
+``action``
+   One of the following values:
+
+   -  ``never-cache`` configures Traffic Server to never cache
+      specified objects.
+   -  ``ignore-no-cache`` configures Traffic Server to ignore all
+      ``Cache-Control: no-cache`` headers.
+   -  ``ignore-client-no-cache`` configures Traffic Server to ignore
+      ``Cache-Control: no-cache`` headers from client requests.
+   -  ``ignore-server-no-cache`` configures Traffic Server to ignore
+      ``Cache-Control: no-cache`` headers from origin server responses.
+   -  ``cluster-cache-local`` configures the cluster cache to allow for
+      this content to be stored locally on every cluster node.
+
+.. _cache-responses-to-cookies:
+
+``cache-responses-to-cookies``
+   Change the style of caching with regard to cookies. This effectively
+   overrides the configuration parameter
+   :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies`
+   and uses the same values with the same semantics. The override happens
+   only for requests that match.
+    
+
+.. _cache-config-format-pin-in-cache:
+
+``pin-in-cache``
+   Preserves objects in cache, preventing them from being overwritten.
+   Does not affect objects that are determined not to be cacheable. This
+   setting can have performance issues, and  severely affect the cache. 
+   For instance, if the primary destination matches all objects, once the 
+   cache is full, no new objects could get written as nothing would be 
+   evicted.  Similarly, for each cache-miss, each object would incur extra 
+   checks to determine if the object it would replace could be overwritten. 
+
+   The value is the amount of time you want to keep the object(s) in the cache. The
+   following time formats are allowed:
+
+   -  ``d`` for days; for example: 2d
+   -  ``h`` for hours; for example: 10h
+   -  ``m`` for minutes; for example: 5m
+   -  ``s`` for seconds; for example: 20s
+   -  mixed units; for example: 1h15m20s
+
+.. _cache-config-format-revalidate:
+
+``revalidate``
+   For objects that are in cache, overrides the the amount of time the object(s) 
+   are to be considered fresh. Use the same time formats as ``pin-in-cache``.
+
+.. _cache-config-format-ttl-in-cache:
+
+``ttl-in-cache``
+   Forces object(s) to become cached, as if they had a Cache-Control: max-age:<time>
+   header. Can be overruled by requests with cookies. The value is the amount of 
+   time object(s) are to be kept in the cache, regardless of Cache-Control response 
+   headers. Use the same time formats as pin-in-cache and revalidate.
+
+Examples
+========
+
+The following example configures Traffic Server to revalidate ``gif``
+and ``jpeg`` objects in the domain ``mydomain.com`` every 6 hours, and
+all other objects in ``mydomain.com`` every hour. The rules are applied
+in the order listed. ::
+
+   dest_domain=mydomain.com suffix=gif revalidate=6h
+   dest_domain=mydomain.com suffix=jpeg revalidate=6h
+   dest_domain=mydomain.com revalidate=1h
+
+Force a specific regex to be in cache between 7-11pm of the server's time for 26hours. ::
+
+   url_regex=example.com/articles/popular.* time=19:00-23:00 ttl-in-cache=1d2h
+
+Prevent objects from being evicted from cache: 
+
+   url_regex=example.com/game/.* pin-in-cache=1h
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/congestion.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/congestion.config.en.rst b/doc/admin-guide/files/congestion.config.en.rst
new file mode 100644
index 0000000..47af214
--- /dev/null
+++ b/doc/admin-guide/files/congestion.config.en.rst
@@ -0,0 +1,198 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+=================
+congestion.config
+=================
+
+.. configfile:: congestion.config
+
+The :file:`congestion.config` file (by default, located in 
+``/usr/local/etc/trafficserver/``) enables you to configure Traffic Server
+to stop forwarding HTTP requests to origin servers when they become
+congested, and then send the client a message to retry the congested
+origin server later. After you modify the :file:`congestion.config` file,
+navigate to the Traffic Server bin directory; then run the
+:option:`traffic_ctl config reload` command to apply changes. When you apply the changes
+to a node in a cluster, Traffic Server automatically applies the changes
+to all other nodes in the cluster. Traffic Server uses the
+:file:`congestion.config` file only if you enable the 
+:ts:cv:`proxy.config.http.congestion_control.enabled` option.
+
+You can create rules in the congestion.config file to specify:
+
+-  Which origin servers Traffic Server tracks for congestion.
+-  The timeouts Traffic Server uses, depending on whether a server is
+   congested.
+-  The page Traffic Server sends to the client when a server becomes
+   congested.
+-  If Traffic Server tracks the origin servers per IP address or per
+   hostname.
+
+Format
+======
+
+Each line in :file:`congestion.config` must follow the format below. Traffic
+Server applies the rules in the order listed, starting at the top of the
+file. Traffic Server recognizes three space-delimited tags::
+
+    primary_destination=value secondary_specifier=value action=value
+
+The following list shows possible primary destinations with allowed
+values.
+
+``dest_domain``
+    A requested domain name.
+
+``dest_host``
+    A requested hostname.
+
+``dest_ip``
+    A requested IP address.
+
+``url_regex``
+    A regular expression (regex) to be found in a URL.
+
+The secondary specifiers are optional in the congestion.config file. The
+following list shows possible secondary specifiers with allowed values.
+You can use more than one secondary specifier in a rule; however, you
+cannot repeat a secondary specifier.
+
+``port``
+    A requested URL port or range of ports.
+
+``prefix``
+    A prefix in the path part of a URL.
+
+The following list shows the possible tags and their allowed values.
+
+``max_connection_failures``
+    Default: ``5``
+    The maximum number of connection failures allowed within the fail
+    window described below before Traffic Server marks the origin server
+    as congested.
+
+``fail_window``
+    Default: ``120`` seconds.
+    The time period during which the maximum number of connection
+    failures can occur before Traffic Server marks the origin server as
+    congested.
+
+``proxy_retry_interval``
+    Default: ``10`` seconds.
+    The number of seconds that Traffic Server waits before contacting a
+    congested origin server again.
+
+``client_wait_interval``
+    Default: ``300`` seconds.
+    The number of seconds that the client is advised to wait before
+    retrying the congested origin server.
+
+``wait_interval_alpha``
+    Default: ``30`` seconds
+    The upper limit for a random number that is added to the wait
+    interval.
+
+``live_os_conn_timeout``
+    Default: ``60`` seconds.
+    The connection timeout to the live (uncongested) origin server. If a
+    client stops a request before the timeout occurs, then Traffic
+    Server does not record a connection failure.
+
+``live_os_conn_retries``
+    Default: ``2``
+    The maximum number of retries allowed to the live (uncongested)
+    origin server.
+
+``dead_os_conn_timeout``
+    Default: ``15`` seconds.
+    The connection timeout to the congested origin server.
+
+``dead_os_conn_retries``
+    Default: ``1``
+    The maximum number of retries allowed to the congested origin
+    server.
+
+``max_connection``
+    Default: ``-1``
+    The maximum number of connections allowed from Traffic Server to the
+    origin server.
+
+``error_page``
+    Default: ``"congestion#retryAfter"``
+    The error page sent to the client when a server is congested. You
+    must enclose the value in quotes;
+
+``congestion_scheme``
+    Default: ``"per_ip"``
+    Specifies if Traffic Server applies the rule on a per-host
+    (``"per_host"``) or per-IP basis (``"per_ip"``). You must enclose
+    the value in quotes.
+
+    For example: if the server ``www.host1.com`` has two IP addresses
+    and you use the tag value ``"per_ip"``, then each IP address has its
+    own number of connection failures and is marked as congested
+    independently. If you use the tag value ``"per_host"`` and the
+    server ``www.host1.com`` is marked as congested, then both IP
+    addresses are marked as congested.
+
+Examples
+========
+
+The following :file:`congestion.config` rule configures Traffic Server to
+stop forwarding requests to the server ``www.host.com`` on port 80 (HTTP
+traffic) if the server is congested, according to the timeouts
+specified. Traffic Server uses the default tag values because no tag has
+been specified.
+
+::
+
+    dest_host=www.host.com port=80
+
+You can use one or more tags in a rule, but each tag must have one value
+only. If you specify no tags in the rule, then Traffic Server uses the
+default values.
+
+You can override any of the default tag values by adding configuration
+variables at the end of :file:`records.config` as follows:
+
+::
+
+    CONFIG proxy.config.http.congestion_control.default.tag INT|STRING value
+
+where tag is one of the tags described in the list under
+:file:`congestion.config` and value is the value you
+want to use.
+
+For example::
+
+    CONFIG proxy.config.http.congestion_control.default.congestion_scheme STRING per_host
+
+.. important::
+
+    Rules in the :file:`congestion.config` file override the
+    following variables in the :file:`records.config` file:
+
+::
+
+    proxy.config.http.connect_attempts_max_retries
+    proxy.config.http.connect_attempts_max_retries_dead_server
+    proxy.config.http.connect_attempts_rr_retries
+    proxy.config.http.connect_attempts_timeout
+    proxy.config.http.down_server.cache_time
+    proxy.config.http.down_server.abort_threshold
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/hosting.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/hosting.config.en.rst b/doc/admin-guide/files/hosting.config.en.rst
new file mode 100644
index 0000000..3052264
--- /dev/null
+++ b/doc/admin-guide/files/hosting.config.en.rst
@@ -0,0 +1,98 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+==============
+hosting.config
+==============
+
+.. configfile:: hosting.config
+
+The :file:`hosting.config` file (by default, located in 
+``/usr/local/etc/trafficserver/``) you to assign cache volumes to
+specific origin servers and/or domains so that you can manage cache
+space efficiently and restrict disk usage. For step-by-step instructions
+on partitioning the cache according to origin servers and/or domains,
+refer to :ref:`partitioning-the-cache`.
+
+Before you can assign cache volumes to specific
+origin servers and/or domains, you must first partition your cache
+according to size and protocol in the :file:`volume.config`
+file.
+
+After you modify hosting.config, navigate to the Traffic Server bin
+directory and run :option:`traffic_ctl config reload` to apply your changes.
+
+When you apply the changes to a node in a cluster, Traffic Server
+automatically applies the changes to all other nodes in the cluster.
+
+.. important::
+
+    The :file:`volume.config` configuration must be the same on all nodes in a cluster.
+
+Format
+======
+
+Each line in the :file:`hosting.config` file must have one of the following
+formats::
+
+    hostname=HOST volume=NUMBERS
+    domain=DOMAIN volume=NUMBERS
+
+where ``HOST`` is the fully-qualified hostname of the origin server
+whose content you want to store on a particular volume (for example,
+``www.myhost.com``); ``DOMAIN`` is the domain whose content you
+want to store on a particular partition(for example, ``mydomain.com``);
+and ``NUMBERS`` is a comma-separated list of the partitions on
+which you want to store the content that belongs to the origin server or
+domain listed. The partition numbers must be valid numbers listed in the
+file:`volume.config`.
+
+**Note:** To allocate more than one partition to an origin server or
+domain, you must enter the partitions in a comma-separated list on one
+line, as shown in the example below. The
+:file:`hosting.config`  file cannot contain multiple entries
+for the same origin server or domain.
+
+Generic Partition
+=================
+
+When configuring the :file:`hosting.config` file, you must assign a generic
+volume to use for content that does not belong to any of the origin
+servers or domains listed. If all volumes for a particular origin
+server become corrupt, Traffic Server will also use the generic
+volume to store content for that origin server.
+
+The generic volume must have the following format::
+
+    hostname=* volume=NUMBERS
+
+where ``NUMBERS`` is a comma-separated list of generic
+volumes.
+
+Examples
+========
+
+The following example configures Traffic Server to store content from
+the domain ``mydomain.com`` in volume 1 and content from
+``www.myhost.com`` in volume 2. Traffic Server stores content from
+all other origin servers in volumes 3 and 4.
+
+::
+
+    domain=mydomain.com volume=1
+    hostname=www.myhost.com volume=2
+    hostname=* volume=3,4

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/icp.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/icp.config.en.rst b/doc/admin-guide/files/icp.config.en.rst
new file mode 100644
index 0000000..24a5704
--- /dev/null
+++ b/doc/admin-guide/files/icp.config.en.rst
@@ -0,0 +1,99 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+==========
+icp.config
+==========
+
+.. configfile:: icp.config
+
+The :file:`icp.config` file defines ICP peers (parent and sibling caches).
+
+.. important::
+
+    After you modify the icp.config file, navigate to the
+    Traffic Server bin directory and run the :option:`traffic_ctl config reload` command to
+    apply the changes. When you apply the changes to a node in a cluster,
+    Traffic Server automatically applies the changes to all other nodes in
+    the cluster.
+
+Format
+======
+
+Each line in the icp.config file contains the name and configuration
+information for a single ICP peer in the following format::
+
+    host : host_IP : ctype : proxy_port : icp_port : MC_on : MC_IP : MC_TTL :
+
+Each field is described in the following list.
+
+``host``
+    The hostname of the ICP peer.
+
+    This field is optional; if you do not specify the hostname of the
+    ICP peer, you must specify the IP address.
+
+``host_IP``
+    The IP address of the ICP peer.
+
+    This field is optional; if you do not specify the IP address of the
+    ICP peer, you must specify the hostname.
+
+``ctype``
+    Use the following options:
+
+    -  1 to indicate an ICP parent cache
+    -  2 to indicate an ICP sibling cache
+    -  3 to indicate an ICP local cache
+
+``proxy_port``
+    The port number of the TCP port used by the ICP peer for proxy
+    communication.
+
+``icp_port``
+    The port number of the UDP port used by the ICP peer for ICP
+    communication.
+
+``MC_on``
+    Enable or disable MultiCast:
+
+    -  0 if multicast is disabled
+    -  1 if multicast is enabled
+
+``MC_ip``
+    The MultiCast IP address.
+
+``MC_ttl``
+    The multicast time to live. Use the following options:
+
+    -  1 if IP multicast datagrams will not be forwarded beyond a single
+       subnetwork
+    -  2 to allow delivery of IP multicast datagrams to more than one
+       subnet (if there are one or more multicast routers attached to
+       the first hop subnet).
+
+Examples
+========
+
+The following example configuration is for three nodes: the local host,
+one parent, and one sibling.
+
+::
+
+    localhost:0.0.0.0:3:8080:3130:0:0.0.0.0:1
+    host1:123.12.1.23:1:8080:3131:0:0.0.0.0:1
+    host2:123.12.1.24:2:8080:3131:0:0.0.0.0:1

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/index.en.rst b/doc/admin-guide/files/index.en.rst
new file mode 100644
index 0000000..38fc75f
--- /dev/null
+++ b/doc/admin-guide/files/index.en.rst
@@ -0,0 +1,44 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. include:: ../../common.defs
+
+.. _admin-configuration-files:
+
+Configuration Files
+*******************
+
+.. toctree::
+   :maxdepth: 2
+
+   cache.config.en
+   congestion.config.en
+   hosting.config.en
+   icp.config.en
+   ip_allow.config.en
+   log_hosts.config.en
+   logs_xml.config.en
+   parent.config.en
+   plugin.config.en
+   records.config.en
+   remap.config.en
+   splitdns.config.en
+   ssl_multicert.config.en
+   storage.config.en
+   update.config.en
+   volume.config.en
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/ip_allow.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/ip_allow.config.en.rst b/doc/admin-guide/files/ip_allow.config.en.rst
new file mode 100644
index 0000000..9f9a4fc
--- /dev/null
+++ b/doc/admin-guide/files/ip_allow.config.en.rst
@@ -0,0 +1,80 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+===============
+ip_allow.config
+===============
+
+.. configfile:: ip_allow.config
+
+The :file:`ip_allow.config` file controls client access to the Traffic
+Server proxy cache. You can specify ranges of IP addresses that are
+allowed to use the Traffic Server as a web proxy cache. After you modify
+the :file:`ip_allow.config` file, navigate to the Traffic Server bin
+directory and run the :option:`traffic_ctl config reload` command to apply changes. When
+you apply the changes to a node in a cluster, Traffic Server
+automatically applies the changes to all other nodes in the cluster.
+
+Format
+======
+
+Each line in the :file:`ip_allow.config` file must have the following
+format::
+
+    src_ip=<range of IP addresses> action=<action> [method=<list of methods separated by '|'>]
+
+where src_ip is the IP address or range of IP addresses of the
+client(s). The action ``ip_allow`` enables the specified client(s) to
+access the Traffic Server proxy cache, and ``ip_deny`` denies the
+specified client(s) to access the Traffic Server proxy cache. Multiple
+method keywords can be specified (method=GET method=HEAD), or multiple
+methods can be separated by an '\|' (method=GET\|HEAD). The method
+keyword is optional and it is defaulted to ALL. This supports ANY string
+as the HTTP method, meaning no validation is done to check wether it
+is a valid HTTP method. This allows you to create filters for any method
+that your origin may require, this is especially useful if you use newer
+methods that aren't know to trafficserver (such as PROPFIND) or if your
+origin uses an http-ish protocol.
+
+By default, the :file:`ip_allow.config` file contains the following lines,
+which allows all methods to localhost to access the Traffic Server proxy
+cache and denies PUSH, PURGE and DELETE to all IPs (note this allows all
+other methods to all IPs)::
+
+    src_ip=127.0.0.1                                  action=ip_allow method=ALL
+    src_ip=::1                                        action=ip_allow method=ALL
+    src_ip=0.0.0.0-255.255.255.255                    action=ip_deny  method=PUSH|PURGE|DELETE
+    src_ip=::-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff action=ip_deny  method=PUSH|PURGE|DELETE
+
+Examples
+========
+
+The following example enables all clients to access the Traffic Server
+proxy cache::
+
+    src_ip=0.0.0.0-255.255.255.255 action=ip_allow
+
+The following example allows all clients on a specific subnet to access
+the Traffic Server proxy cache::
+
+    src_ip=123.12.3.000-123.12.3.123 action=ip_allow
+
+The following example denies all clients on a specific subnet to access
+the Traffic Server proxy cache::
+
+    src_ip=123.45.6.0-123.45.6.123 action=ip_deny
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/log_hosts.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/log_hosts.config.en.rst b/doc/admin-guide/files/log_hosts.config.en.rst
new file mode 100644
index 0000000..659030d
--- /dev/null
+++ b/doc/admin-guide/files/log_hosts.config.en.rst
@@ -0,0 +1,65 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+================
+log_hosts.config
+================
+
+.. configfile:: log_hosts.config
+
+To record HTTP transactions for different origin servers in separate log
+files, you must list each origin server hostname in the
+:file:`log_hosts.config` file. In addition, you must enable the :ref:`httphostlogsplitting` foo! ... <../working-log-files#HTTPHostLogSplitting>`_ option. You
+should use the same :file:`log_hosts.config` file on every Traffic Server
+node in your cluster. After you modify the :file:`log_hosts.config` file,
+run the :option:`traffic_ctl config reload` command to apply the changes.
+When you apply the changes to a node in a cluster, Traffic Server automatically applies the
+changes to all other nodes in the cluster.
+
+Format
+======
+
+Each line in the :file:`log_hosts.config` file has the following format::
+
+    hostname
+
+where ``hostname`` is the hostname of the origin server.
+
+.. hint::
+
+    You can specify keywords in the :file:`log_hosts.config` file to
+    record all transactions from origin servers with the specified keyword
+    in their names in a separate log file. See the example below.
+
+Examples
+========
+
+The following example configures Traffic Server to create separate log
+files containing all HTTP transactions for the origin servers
+``webserver1``, ``webserver2``, and ``webserver3``::
+
+    webserver1
+    webserver2
+    webserver3
+
+The following example records all HTTP transactions from origin servers
+that contain ``sports`` in their names. For example:
+``sports.yahoo.com`` and ``www.foxsports.com`` in a log file called
+``squid-sport.log`` (the Squid format is enabled)::
+
+    sports
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/logs_xml.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/logs_xml.config.en.rst b/doc/admin-guide/files/logs_xml.config.en.rst
new file mode 100644
index 0000000..c676f59
--- /dev/null
+++ b/doc/admin-guide/files/logs_xml.config.en.rst
@@ -0,0 +1,396 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+===============
+logs_xml.config
+===============
+
+.. configfile:: logs_xml.config
+
+The :file:`logs_xml.config` file defines the custom log file formats,
+filters, and processing options. The format of this file is modeled
+after XML, the Extensible Markup Language.
+
+Format
+======
+
+The :file:`logs_xml.config` file contains the specifications below:
+
+-  ``LogFormat`` specifies the fields to be gathered from each protocol
+   event access.
+-  ``LogFilter`` specifies the filters that are used to include or
+   exclude certain entries being logged based on the value of a field
+   within that entry.
+-  ``LogObject`` specifies an object that contains a particular format,
+   a local filename, filters, and collation servers.
+
+The :file:`logs_xml.config` file ignores extra white space, blank lines, and
+all comments.
+
+.. _LogFormat:
+
+LogFormat
+=========
+
+The following list shows ``LogFormat`` specifications.
+
+.. _LogFormat-name:
+
+``<Name = "valid_format_name"/>``
+    Required
+    Valid format names include any name except ``squid``, ``common``,
+    ``extended``, or ``extended2``, which are pre-defined formats. There
+    is no default for this tag. The format object needs to be above the the LogObject object.
+
+.. _LogFormat-Format:
+
+``<Format = "valid_format_specification"/>``
+    Required
+    A valid format specification is a printf-style string describing
+    each log entry when formatted for ASCII output.
+
+    The printf-style could accept Oct/Hex escape representation:
+
+    -  ``\abc`` is Oct escape sequence, a,b,c should be one of [0-9], and
+       (a*8^2 + b*8 + c) should be greater than 0 and less than 255.
+    -  ``\xab`` is Hex escape sequence, a,b should be one of [0-9, a-f, A-F],
+       and (a*16 + b) should be greater than 0 and less than 255.
+
+    Use ``%<`` ``field`` ``>`` as a placeholder for valid field names. For more
+    information, refer to :ref:`custom-logging-fields`.
+
+    The specified field can be one of the following types:
+
+    Simple. For example: ``%<cqu>``
+    A field within a container, such as an HTTP header or a statistic.
+    Fields of this type have the syntax: ::
+
+         %<{ field } container>
+
+    Aggregates, such as ``COUNT``, ``SUM``, ``AVG``, ``FIRST``,
+    ``LAST``. Fields of this type have the syntax: ``%<operator (``
+    ``field`` ``)>``
+
+.. note::
+
+    You cannot create a format specification that contains both aggregate operators and regular fields.
+
+``<Interval = "aggregate_interval_secs"/>``
+    Optional
+    Use this tag when the format contains aggregate operators. The value
+    "``aggregate_interval_secs``\" represents the number of seconds
+    between individual aggregate values being produced.
+
+    The valid set of aggregate operators are:
+
+    -  COUNT
+    -  SUM
+    -  AVG
+    -  FIRST
+    -  LAST
+
+.. _LogFilter:
+
+LogFilter
+=========
+
+The following list shows the ``LogFilter`` specifications.
+
+``<Name = "valid_filter_name"/>``
+    Required
+    All filters must be uniquely named.
+
+``<Condition = "valid_log_field valid_operator valid_comparison_value"/>``
+    Required
+    This field contains the following elements:
+
+    ``valid_log_field`` - the field that will be compared against
+    the given value. For more information, refer to :ref:`logging-format-cross-reference`.
+
+    ``valid_operator_field`` - any one of the following: ``MATCH``,
+    ``CASE_INSENSITIVE_MATCH``, ``CONTAIN``,
+    ``CASE_INSENSITIVE_CONTAIN``.
+
+    -  ``MATCH`` is true if the field and value are identical
+       (case-sensitive).
+    -  ``CASE_INSENSITIVE_MATCH`` is similar to ``MATCH``, except that
+       it is case-insensitive.
+    -  ``CONTAIN`` is true if the field contains the value (the value is
+       a substring of the field).
+    -  ``CASE_INSENSITIVE_CONTAIN`` is a case-insensitive version of
+       ``CONTAIN``.
+
+    ``valid_comparison_value`` - any string or integer matching the
+    field type. For integer values, all of the operators are equivalent
+    and mean that the field must be equal to the specified value.
+
+   For IP address fields, this can be a list of IP addresses and include ranges. A range is an IP address, followed by a
+   dash '``-``', and then another IP address of the same family. For instance, the 10/8 network can be represented by
+   ``10.0.0.0-10.255.255.255``. Currently network specifiers are not supported.
+
+.. note::
+
+    There are no negative comparison operators. If you want to
+    specify a negative condition, then use the ``Action`` field to
+    ``REJECT`` the record.
+
+``<Action = "valid_action_field"/>``
+    Required: ``ACCEPT`` or ``REJECT`` or ``WIPE_FIELD_VALUE``.
+    ACCEPT or REJECT instructs Traffic Server to either accept or reject records
+    that satisfy the filter condition. WIPE_FIELD_VALUE wipes out
+    the values of the query params in the url fields specified in the Condition.
+
+NOTES: 1. WIPE_FIELD_VALUE action is only applied to the parameters in the query part.
+       2. Multiple parameters can be listed in a single WIPE_FIELD_VALUE filter
+       3. If the same parameter appears more than once in the query part , only
+          the value of the first occurance is wiped
+
+.. _LogObject:
+
+LogObject
+=========
+
+The following list shows the ``LogObject`` specifications.
+
+``<Format = "valid_format_name"/>``
+    Required
+    Valid format names include the predefined logging formats:
+    ``squid``, ``common``, ``extended``, and ``extended2``, as well as
+    any previously-defined custom log formats. There is no default for
+    this tag. The format object needs to be above the the LogObject object.
+
+``<Filename = "file_name"/>``
+    Required
+    The filename to which the given log file is written on the local
+    file system or on a remote collation server. No local log file will
+    be created if you fail to specify this tag. All filenames are
+    relative to the default logging directory.
+
+    If the name does not contain an extension (for example, ``squid``),
+    then the extension ``.log`` is automatically appended to it for
+    ASCII logs and ``.blog`` for binary logs (refer to :ref:`Mode =
+    "valid_logging_mode" <LogObject-Mode>`).
+
+    If you do not want an extension to be added, then end the filename
+    with a single (.) dot (for example: ``squid.`` ).
+
+.. _LogObject-Mode:
+
+``<Mode = "valid_logging_mode"/>``
+    Optional
+    Valid logging modes include ``ascii`` , ``binary`` , and
+    ``ascii_pipe`` . The default is ``ascii`` .
+
+    -  Use ``ascii`` to create event log files in human-readable form
+       (plain ASCII).
+    -  Use ``binary`` to create event log files in binary format. Binary
+       log files generate lower system overhead and occupy less space on
+       the disk (depending on the information being logged). You must
+       use the :program:`traffic_logcat` utility to translate binary log files to ASCII
+       format before you can read them.
+    -  Use ``ascii_pipe`` to write log entries to a UNIX named pipe (a
+       buffer in memory). Other processes can then read the data using
+       standard I/O functions. The advantage of using this option is
+       that Traffic Server does not have to write to disk, which frees
+       disk space and bandwidth for other tasks. In addition, writing to
+       a pipe does not stop when logging space is exhausted because the
+       pipe does not use disk space.
+
+    If you are using a collation server, then the log is written to a
+    pipe on the collation server. A local pipe is created even before a
+    transaction is processed, so you can see the pipe right after
+    Traffic Server starts. Pipes on a collation server, however, *are*
+    created when Traffic Server starts.
+
+``<Filters = "list_of_valid_filter_names"/>``
+    Optional
+    A comma-separated list of names of any previously-defined log
+    filters. If more than one filter is specified, then all filters must
+    accept a record for the record to be logged. The filters need
+    to be above the LogObject object.
+
+``<Protocols = "list_of_valid_protocols"/>``
+    Optional
+    A comma-separated list of the protocols this object should log.
+    Valid protocol names for this release are ``HTTP`` (FTP is
+    deprecated).
+
+``<ServerHosts = "list_of_valid_servers"/>``
+    Optional
+    A comma-separated list of valid hostnames.This tag indicates that
+    only entries from the named servers will be included in the file.
+
+.. _logs-xml-logobject-collationhost:
+
+``<CollationHosts = "list_of_valid_hostnames:port|failover hosts"/>``
+    Optional
+    A comma-separated list of collation servers (with pipe delimited
+    failover servers) to which all log entries (for this object) are
+    forwarded. Collation servers can be specified by name or IP address.
+    Specify the collation port with a colon after the name. For example,
+    in ``host1:5000|failhostA:5000|failhostB:6000, host2:6000`` logs
+    would be sent to host1 and host2, with failhostA and failhostB
+    acting as failover hosts for host1. When host1 disconnects,
+    logs would be sent to failhostA. If failhostA disconnects, log
+    entries would be sent to failhostB until host1 or failhostA comes
+    back. Logs would also be sent to host2.
+
+``<Header = "header"/>``
+    Optional
+    The header text you want the log files to contain. The header text
+    appears at the beginning of the log file, just before the first
+    record.
+
+``<RollingEnabled = "truth value"/>``
+    Optional
+    Enables or disables log file rolling for the ``LogObject``. This
+    setting overrides the value for the
+    :ts:cv:`proxy.config.log.rolling_enabled` variable in the
+    :file:`records.config` file. Set *truth value* to one of the
+    following values:
+
+    -  ``0`` to disable rolling for this particular ``LogObject``.
+    -  ``1`` to roll log files at specific intervals during the day (you
+       specify time intervals with the ``RollingIntervalSec`` and
+       ``RollingOffsetHr`` fields).
+    -  ``2`` to roll log files when they reach a certain size (you
+       specify the size with the ``RollingSizeMb`` field).
+    -  ``3`` to roll log files at specific intervals during the day or
+       when they reach a certain size (whichever occurs first).
+    -  ``4`` to roll log files at specific intervals during the day when
+       log files reach a specific size (at a specified time if the file
+       is of the specified size).
+
+.. XXX this is confusing ^ really, why is it a "truth value" but then it's 5 different integer values that means varias strange things?
+
+``<RollingIntervalSec = "seconds"/>``
+    Optional
+    The seconds between log file rolling for the ``LogObject``; enables
+    you to specify different rolling intervals for different
+    ``LogObjects``.
+
+    This setting overrides the value for
+    :ts:cv:`proxy.config.log.rolling_interval_sec` in the
+    :file:`records.config` file.
+
+``<RollingOffsetHr = "hour"/>``
+    Optional
+    Specifies an hour (from 0 to 23) at which rolling is guaranteed to
+    align. Rolling might start before then, but a rolled file will be
+    produced only at that time. The impact of this setting is only
+    noticeable if the rolling interval is larger than one hour. This
+    setting overrides the configuration setting for
+    :ts:cv:`proxy.config.log.rolling_offset_hr` in the :file:`records.config`
+    file.
+
+``<RollingSizeMb = "size_in_MB"/>``
+    Optional
+    The size at which log files are rolled.
+
+Examples
+========
+
+The following is an example of a ``LogFormat`` specification that
+collects information using three common fields: ::
+
+         <LogFormat>
+             <Name="minimal"/>
+             <Format = "%<chi> : %<cqu> : %<pssc>"/>
+         </LogFormat>
+
+The following is an example of a ``LogFormat`` specification that
+uses aggregate operators: ::
+
+         <LogFormat>
+             <Name = "summary"/>
+             <Format = "%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)>"/>
+             <Interval = "10"/>
+         </LogFormat>
+
+The following is an example of a ``LogFilter`` that will cause only
+``REFRESH_HIT`` entries to be logged: ::
+
+         <LogFilter>
+              <Name = "only_refresh_hits"/>
+              <Action = "ACCEPT"/>
+              <Condition = "%<pssc> MATCH REFRESH_HIT"/>
+         </LogFilter>
+
+.. note::
+
+    When specifying the field in the filter condition, you can
+    omit the ``%<>``. This means that the filter below is equivalent to the
+    example directly above: ::
+
+         <LogFilter>
+             <Name = "only_refresh_hits"/>
+             <Action = "ACCEPT"/>
+             <Condition = "pssc MATCH REFRESH_HIT"/>
+         </LogFilter>
+
+The following is an example of a ``LogFilter`` that will cause the value of
+passwd field be wiped in ``cquc`` ::
+
+         <LogFilter>
+             <Name = "wipe_password"/>
+             <Condition = "cquc CONTAIN passwd"/>
+             <Action = "WIPE_FIELD_VALUE"/>
+         </LogFilter>
+
+The following is an example of a ``LogObject`` specification that
+creates a local log file for the minimal format defined earlier. The log
+filename will be ``minimal.log`` because this is an ASCII log file (the
+default).::
+
+         <LogObject>
+             <Format = "minimal"/>
+             <Filename = "minimal"/>
+         </LogObject>
+
+The following is an example of a ``LogObject`` specification that
+includes only HTTP requests served by hosts in the domain
+``company.com`` or by the specific server ``server.somewhere.com``. Log
+entries are sent to port 4000 of the collation host ``logs.company.com``
+and to port 5000 of the collation host ``209.131.52.129.`` ::
+
+         <LogObject>
+              <Format = "minimal"/>
+              <Filename = "minimal"/>
+              <ServerHosts = "company.com,server.somewhere.com"/>
+              <Protocols = "http"/>
+              <CollationHosts = "logs.company.com:4000,209.131.52.129:5000"/>
+         </LogObject>
+
+.. _WELF:
+
+WELF
+====
+
+Traffic Server supports WELF (WebTrends Enhanced Log Format) so you can
+analyze Traffic Server log files with WebTrends reporting tools. A
+predefined ``<LogFormat>`` that is compatible with WELF is provided in
+the :file:`logs_xml.config` file (shown below). To create a WELF format log
+file, create a ``<LogObject>`` that uses this predefined format. ::
+
+         <LogFormat>
+             <Name = "welf"/>
+             <Format = "id=firewall time=\"%<cqtd> %<cqtt>\" fw=%<phn> pri=6
+                proto=%<cqus> duration=%<ttmsf> sent=%<psql> rcvd=%<cqhl>
+                src=%<chi> dst=%<shi> dstname=%<shn> user=%<caun> op=%<cqhm>
+                arg=\"%<cqup>\" result=%<pssc> ref=\"%<{Referer}cqh>\"
+                agent=\"%<{user-agent}cqh>\" cache=%<crc>"/>
+         </LogFormat>


Mime
View raw message