You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2015/11/03 07:10:19 UTC
[43/51] trafficserver git commit: Documentation reorganization
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>