You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by zw...@apache.org on 2016/01/13 19:40:23 UTC
[1/2] trafficserver git commit: Docs: build cleanups and multiple
Jira issues.
Repository: trafficserver
Updated Branches:
refs/heads/master fd25910f5 -> 40500c710
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/monitoring/logging/log-formats.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/monitoring/logging/log-formats.en.rst b/doc/admin-guide/monitoring/logging/log-formats.en.rst
index e2d497e..3fb8a3f 100644
--- a/doc/admin-guide/monitoring/logging/log-formats.en.rst
+++ b/doc/admin-guide/monitoring/logging/log-formats.en.rst
@@ -27,6 +27,8 @@ supports. Rather than just reading about those formats, you may also want to
try our `online event log builder <http://trafficserver.apache.org/logbuilder/>`_
for an interactive way of building and understanding log formats.
+.. _admin-logging-binary-v-ascii:
+
Binary or ASCII?
================
@@ -57,16 +59,10 @@ ASCII log file.
It is wise to consider the type of data that will be logged before you select
ASCII or binary for your log files, if your decision is being driven by storage
-space concerns. For example, you might try logging for one day using ASCII and
-then another day using binary. If the number of requests is roughly the same
-for both days, then you can calculate a rough metric that compares the two
-formats.
-
-For standard log formats, select Binary or ASCII (refer to `Using Standard
-Formats`_). For the custom log format, specify ASCII or Binary mode in the
-:ref:`LogObject` (refer to :ref:`using-custom-log-formats`). In addition to the
-ASCII and binary options, you can also write custom log entries to a UNIX-named
-pipe (a buffer in memory) with the `ASCII_PIPE File Mode`_ setting.
+space concerns. For example, you might try logging to both formats
+simultaneously for a representative period of time and compare the storage
+requirements of the two logs to determine whether one or the other provides
+any measurable savings.
Defining Log Objects
====================
@@ -98,44 +94,11 @@ variety of off-the-shelf log-analysis packages. You should use one of the
standard event log formats unless you need information that these formats do
not provide.
-Set standard log file format options by following the steps below:
-
-#. In the :file:`records.config` file, edit the following variables
-
-#. Edit the following variables to use the Squid format:
-
- - :ts:cv:`proxy.config.log.squid_log_enabled`
- - :ts:cv:`proxy.config.log.squid_log_is_ascii`
- - :ts:cv:`proxy.config.log.squid_log_name`
- - :ts:cv:`proxy.config.log.squid_log_header`
-
-#. To use the Netscape Common format, edit the following variables:
-
- - :ts:cv:`proxy.config.log.common_log_enabled`
- - :ts:cv:`proxy.config.log.common_log_is_ascii`
- - :ts:cv:`proxy.config.log.common_log_name`
- - :ts:cv:`proxy.config.log.common_log_header`
-
-#. To use the Netscape Extended format, edit the following variables:
+These formats may be used by enabling the :ts:cv:`proxy.config.log.custom_logs_enabled`
+setting in :file:`records.config` and adding appropriate entries to
+:file:`logs_xml.config`.
- - :ts:cv:`proxy.config.log.extended_log_enabled`
- - :ts:cv:`proxy.config.log.extended_log_is_ascii`
- - :ts:cv:`proxy.config.log.extended_log_name`
- - :ts:cv:`proxy.config.log.extended_log_header`
-
-#. To use the Netscape Extended-2 format, edit the following variables:
-
- - :ts:cv:`proxy.config.log.extended2_log_enabled`
- - :ts:cv:`proxy.config.log.extended2_log_is_ascii`
- - :ts:cv:`proxy.config.log.extended2_log_name`
- - :ts:cv:`proxy.config.log.extended2_log_header`
-
-#. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
-
-You may enable as many of the formats as you wish, keeping in mind the
-additional overhead, both in processing time to create the individual formats
-and storage space to keep them.
+.. _admin-logging-format-squid:
Squid
-----
@@ -161,8 +124,9 @@ Field Symbol Description
3 chi The IP address of the client’s host machine.
4 crc/pssc The cache result code; how the cache responded to the request:
``HIT``, ``MISS``, and so on. Cache result codes are described
- in :ref:`<squid-netscape-result-codes>`. The proxy response
- status code (HTTP response status code from |TS| to client).
+ in :ref:`admin-monitoring-logging-cache-result-codes`. The
+ proxy response status code (HTTP response status code from
+ |TS| to client).
5 psql The length of the |TS| response to the client in bytes,
including headers and content.
6 cqhm The client request method: ``GET``, ``POST``, and so on.
@@ -179,6 +143,8 @@ Field Symbol Description
from the |TS| response header.
====== ========= ==============================================================
+.. _admin-logging-format-common:
+
Netscape Common
---------------
@@ -203,6 +169,8 @@ Field Symbol Description
7 pscl The length of the |TS| response to the client in bytes.
====== ========= ==============================================================
+.. _admin-logging-format-extended:
+
Netscape Extended
-----------------
@@ -241,6 +209,8 @@ Field Symbol Description
of the response back to the client.
====== ========= ==============================================================
+.. _admin-logging-format-extended2:
+
Netscape Extended2
------------------
@@ -268,7 +238,7 @@ Field Symbol Description
request was interrupted.
20 crc The cache result code; how the |TS| cache responded to the
request: ``HIT``, ``MISS``, and so on. Cache result codes are
- listed in :ref:`<admin-monitoring-logging-cache-result-codes>`.
+ listed in :ref:`admin-monitoring-logging-cache-result-codes`.
====== ======== ===============================================================
.. _admin-monitoring-logging-format-custom:
@@ -634,7 +604,7 @@ The following list describes |TS| custom logging fields.
The timestamp in milliseconds of a specific milestone for this request.
see :c:func:`TSHttpTxnMilestoneGet` for milestone names.
-.. _msdms
+.. _msdms:
``{Milestone field name1-Milestone field name2}msdms``
The difference in milliseconds of between two milestones.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/monitoring/logging/managing-logs.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/monitoring/logging/managing-logs.en.rst b/doc/admin-guide/monitoring/logging/managing-logs.en.rst
index 5e56501..2ce9564 100644
--- a/doc/admin-guide/monitoring/logging/managing-logs.en.rst
+++ b/doc/admin-guide/monitoring/logging/managing-logs.en.rst
@@ -226,56 +226,6 @@ above.
Separating Logs by Origin
=========================
-HTTP host log splitting enables you to record HTTP transactions for different
-origin servers in separate log files. When HTTP host log splitting is enabled,
-|TS| creates a separate log file for each origin server that's listed in
-:file:`log_hosts.config`.
-
-To enable host log splitting, perform the following steps:
-
-- Adjust the setting :ts:cv:`proxy.config.log.separate_host_logs` in
- :file:`records.config`::
-
- CONFIG proxy.config.log.separate_host_logs INT 1
-
-- Run the command :option:`traffic_line -x` to apply the changes, or restart
- |TS|.
-
-When both ICP (covered in :ref:`admin-monitoring-logging-icp-split`) and HTTP
-host log splitting are enabled, |TS| generates separate log files for HTTP
-transactions (based on the origin server) and places all ICP transactions in
-their own respective log files. For example, if :file:`log_hosts.config`
-contains the two origin servers ``uni.edu`` and ``company.com`` and Squid
-format is enabled, then |TS| generates the following log files:
-
-=========================== ============================================
-Log File Contents
-=========================== ============================================
-``squid-uni.edu.log`` All HTTP transactions for ``uni.edu``.
-``squid-company.com.log`` All HTTP transactions for ``company.com``.
-``squid-icp.log`` All ICP transactions for all hosts.
-``squid.log`` All HTTP transactions for other hosts.
-=========================== ============================================
-
-If you disable ICP log splitting, then ICP transactions are placed in the same
-log file as HTTP transactions. Using the hosts and log format from the previous
-example, |TS| generates the log files below:
-
-=========================== ============================================
-Log File Contents
-=========================== ============================================
-``squid-uni.edu.log`` All entries for ``uni.edu``.
-``squid-company.com.log`` All entries for ``company.com``.
-``squid.log`` All other entries.
-=========================== ============================================
-
-|TS| also enables you to create XML-based
-:ref:`admin-monitoring-logging-custom-formats` that offer even greater control
-over log file generation.
-
-Defining Hosts in log_hosts.config
-----------------------------------
-
The default :file:`log_hosts.config` file is located in the |TS| ``config``
directory. To record HTTP transactions for different origin servers in separate
log files, you must specify the hostname of each origin server on a separate
@@ -286,7 +236,7 @@ line in :file:`log_hosts.config`. For example, if you specify the keyword
.. important::
- If Traffic Server is clustered and you enable log file collation, then you
+ If |TS| is clustered and you enable log file collation, then you
should use the same :file:`log_hosts.config` file on every |TS| node in the
cluster.
@@ -299,32 +249,5 @@ To edit the log hosts list:
webserver2
webserver3
-#. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
-
-.. _admin-monitoring-logging-icp-split:
-
-ICP Log Splitting
-=================
-
-By default, |TS| uses standard log formats and generates log
-files that contain HTTP and ICP transactions in the same file. However,
-you can enable log splitting if you prefer to log transactions for
-different protocols in separate log files.
-
-When ICP log splitting is enabled, |TS| records ICP transactions in a
-separate log file with a name that contains ``icp``. For example, if you enable
-the Squid format, then all ICP transactions are recorded in the
-``squid-icp.log`` file. When you disable ICP log splitting, |TS|
-records all ICP transactions in the same log file as HTTP transactions.
-
-To enable ICP log splitting, perform the following steps:
-
-- Adjust the setting :ts:cv:`proxy.config.log.separate_icp_logs` in
- :file:`records.config`::
-
- CONFIG proxy.config.log.separate_icp_logs INT 1
-
-- Run the command :option:`traffic_line -x` to apply the changes, or restart
- |TS|.
+#. Run the command :option:`traffic_ctl config reload` to apply the changes.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/monitoring/statistics/core/bandwidth.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/monitoring/statistics/core/bandwidth.en.rst b/doc/admin-guide/monitoring/statistics/core/bandwidth.en.rst
index 200cc8c..f876758 100644
--- a/doc/admin-guide/monitoring/statistics/core/bandwidth.en.rst
+++ b/doc/admin-guide/monitoring/statistics/core/bandwidth.en.rst
@@ -97,36 +97,36 @@ Bandwidth and Transfer
.. ts:stat:: global proxy.process.http.user_agent_speed_bytes_per_sec_100 integer
:type: derivative
- :unit; bytes
+ :unit: bytes
:ungathered:
.. ts:stat:: global proxy.process.http.user_agent_speed_bytes_per_sec_100K integer
:type: derivative
- :unit; bytes
+ :unit: bytes
:ungathered:
.. ts:stat:: global proxy.process.http.user_agent_speed_bytes_per_sec_100M integer
:type: derivative
- :unit; bytes
+ :unit: bytes
:ungathered:
.. ts:stat:: global proxy.process.http.user_agent_speed_bytes_per_sec_10K integer
:type: derivative
- :unit; bytes
+ :unit: bytes
:ungathered:
.. ts:stat:: global proxy.process.http.user_agent_speed_bytes_per_sec_10M integer
:type: derivative
- :unit; bytes
+ :unit: bytes
:ungathered:
.. ts:stat:: global proxy.process.http.user_agent_speed_bytes_per_sec_1K integer
:type: derivative
- :unit; bytes
+ :unit: bytes
:ungathered:
.. ts:stat:: global proxy.process.http.user_agent_speed_bytes_per_sec_1M integer
:type: derivative
- :unit; bytes
+ :unit: bytes
:ungathered:
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/monitoring/statistics/core/cache-volume.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/monitoring/statistics/core/cache-volume.en.rst b/doc/admin-guide/monitoring/statistics/core/cache-volume.en.rst
index 63b62f4..db5e051 100644
--- a/doc/admin-guide/monitoring/statistics/core/cache-volume.en.rst
+++ b/doc/admin-guide/monitoring/statistics/core/cache-volume.en.rst
@@ -22,7 +22,7 @@
Cache Volume
************
-Each configured :ref:`cache-volume` receives a complete set of statistics from
+Each configured :term:`cache volume` receives a complete set of statistics from
|TS|. They are differentiated from each other by the incrementing number that is
part of the statistic name. The volume number begins at :literal:`0` and
increments by :literal:`1` for each additional volume.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/plugins/healthchecks.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/healthchecks.en.rst b/doc/admin-guide/plugins/healthchecks.en.rst
index 52b5d35..a89b630 100644
--- a/doc/admin-guide/plugins/healthchecks.en.rst
+++ b/doc/admin-guide/plugins/healthchecks.en.rst
@@ -1,8 +1,3 @@
-.. _healthcheck-plugin:
-
-Health Check Plugin
-**************
-
.. 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
@@ -20,12 +15,20 @@ Health Check Plugin
specific language governing permissions and limitations
under the License.
+.. include:: ../../common.defs
+
+.. _healthcheck-plugin:
+
+Health Check Plugin
+*******************
+
This is a simple plugin, to provide basic (but configurable) health checks.
This is a server intercept plugin, and it takes one single configuration
option in plugin.config, the configuration file name.
Configuration
=============
+
To enable the healthchecks plugin, insert the following line in
:file:`plugin.config`::
@@ -57,6 +60,7 @@ http://www.example.com/__hc that would check if the file
a response is built with the contents of the ``ts-alive`` file, a mime
type of ``text/plain`` and a status code of ``200``. If the file does not
exist, a ``403`` response is sent::
+
/__hc /var/run/ts-alive text/plain 200 403
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/plugins/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/index.en.rst b/doc/admin-guide/plugins/index.en.rst
index 37845d6..54391a1 100644
--- a/doc/admin-guide/plugins/index.en.rst
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -82,6 +82,7 @@ directory of the Apache Traffic Server source tree. Experimental plugins can be
Generator: generate arbitrary response data <generator.en>
GeoIP ACLs: denying (or allowing) requests based on the source IP geo-location <geoip_acl.en>
MP4: mp4 streaming media <mp4.en>
+ Memcache: implements the memcache protocol for cache contents <memcache.en>
Metalink: implements the Metalink download description format in order to try not to download the same file twice. <metalink.en>
MySQL Remap: allows dynamic “remaps” from a database <mysql_remap.en>
SSL Headers: Populate request headers with SSL session information <sslheaders.en>
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/plugins/metalink.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/metalink.en.rst b/doc/admin-guide/plugins/metalink.en.rst
index b7de205..7b63701 100644
--- a/doc/admin-guide/plugins/metalink.en.rst
+++ b/doc/admin-guide/plugins/metalink.en.rst
@@ -79,7 +79,7 @@ cached. In future, the plugin should also check if the URL is fresh
or not.
The plugin implements the :c:data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`
-hook and :doc:`a null transformation <../../sdk/http-transformation-plugin/sample-null-transformation-plugin.en>`
+hook and :ref:`a null transformation <developer-plugins-http-transformations-null-transform>`
to compute the SHA-256 digest for
content as it's added to the cache. It uses SHA256_Init(),
SHA256_Update(), and SHA256_Final() from OpenSSL to compute the
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/plugins/stats_over_http.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/stats_over_http.en.rst b/doc/admin-guide/plugins/stats_over_http.en.rst
index 14cd35b..34326cd 100644
--- a/doc/admin-guide/plugins/stats_over_http.en.rst
+++ b/doc/admin-guide/plugins/stats_over_http.en.rst
@@ -29,7 +29,7 @@ part of the standard ATS build process, and should be available after install.
Enabling Stats Over HTTP
========================
-To enable this plugin, add to the :file:`plugin.conf` file::
+To enable this plugin, add to the :file:`plugin.config` file::
stats_over_http.so
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/plugins/xdebug.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/xdebug.en.rst b/doc/admin-guide/plugins/xdebug.en.rst
index 6d43369..1b39159 100644
--- a/doc/admin-guide/plugins/xdebug.en.rst
+++ b/doc/admin-guide/plugins/xdebug.en.rst
@@ -1,24 +1,26 @@
-.. _xdebug-plugin:
-
-XDebug Plugin
-*************
-
.. 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
+ 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.
+ 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
+
+.. _xdebug-plugin:
+
+XDebug Plugin
+*************
The `XDebug` plugin allows HTTP clients to debug the operation of
the Traffic Server cache using the default ``X-Debug`` header. The plugin
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/security/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/security/index.en.rst b/doc/admin-guide/security/index.en.rst
index 22365d8..06ca663 100644
--- a/doc/admin-guide/security/index.en.rst
+++ b/doc/admin-guide/security/index.en.rst
@@ -52,10 +52,10 @@ The following sections describe how to enable and configure the SSL
termination option.
- Enable and configure SSL termination for client/Traffic Server
- connections: :ref:`admin-client-and-traffic-server-connections`
+ connections: :ref:`client-and-traffic-server-connections`
- Enable and configure SSL termination for Traffic Server/origin server
- connections: :ref:`admin-traffic-server-and-origin-server-connections`
+ connections: :ref:`traffic-server-and-origin-server-connections`
.. _client-and-traffic-server-connections:
@@ -79,17 +79,17 @@ Server connections only.
The figure above depicts the following:
-1. The client sends an HTTPS request for content. Traffic Server receives the
+#. The client sends an HTTPS request for content. Traffic Server receives the
request and performs the SSL handshake to authenticate the client (depending
on the authentication options configured) and determine the encryption
method that will be used. If the client is allowed access, then Traffic
Server checks its cache for the requested content.
-2. If the request is a cache hit and the content is fresh, then Traffic Server
+#. If the request is a cache hit and the content is fresh, then Traffic Server
encrypts the content and sends it to the client. The client decrypts the
content (using the method determined during the handshake) and displays it.
-3. If the request is a cache miss or cached content is stale, then Traffic
+#. If the request is a cache miss or cached content is stale, then Traffic
Server communicates with the origin server via HTTP and obtains a plain text
version of the content. Traffic Server saves the plain text version of the
content in its cache, encrypts the content, and sends it to the client. The
@@ -173,17 +173,17 @@ Server/origin server connections.
The figure above depicts the following:
-1. If a client request is a cache miss or is stale, then Traffic Server sends
+#. If a client request is a cache miss or is stale, then Traffic Server sends
an HTTPS request for the content to the origin server. The origin server
receives the request and performs the SSL handshake to authenticate Traffic
Server and determine the encryption method to be used.
-2. If Traffic Server is allowed access, then the origin server encrypts the
+#. If Traffic Server is allowed access, then the origin server encrypts the
content and sends it to Traffic Server, where it is decrypted (using the
method determined during the handshake). A plain text version of the content
is saved in the cache, if Traffic Server deems the content cacheable.
-3. If SSL termination is enabled for Client/Traffic Server connections, then
+#. If SSL termination is enabled for Client/Traffic Server connections, then
Traffic Server re-encrypts the content and sends it to the client via HTTPS,
where it is decrypted and displayed. If SSL termination is not enabled for
Client/Traffic Server connections, then Traffic Server sends the plain text
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/storage/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/storage/index.en.rst b/doc/admin-guide/storage/index.en.rst
index 506a5b4..764167c 100644
--- a/doc/admin-guide/storage/index.en.rst
+++ b/doc/admin-guide/storage/index.en.rst
@@ -365,7 +365,7 @@ Inspector utility is a powerful tool that's capable of deleting all
the objects in your cache. Therefore, make sure that only authorized
administrators are allowed to access this utility through proper use
of the ``@src_ip`` option in :file:`remap.config` and the instructions
-detailed in :ref:`controlling-client-access-to-cache`.
+detailed in :ref:`admin-controlling-access`.
Accessing the Cache Inspector Utility
-------------------------------------
@@ -418,7 +418,6 @@ Regex Invalidate
.. note::
- Only one administrator should delete and invalidate cache
- entries from the Cache Inspector at any point in time. Changes made by
- multiple administrators at the same time can lead to unpredictable
- results.
+ Only one administrator should delete and invalidate cache entries from the
+ Cache Inspector at any point in time. Changes made by multiple
+ administrators at the same time can lead to unpredictable results.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/transparent-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/transparent-proxy.en.rst b/doc/admin-guide/transparent-proxy.en.rst
deleted file mode 100644
index 7cb76f3..0000000
--- a/doc/admin-guide/transparent-proxy.en.rst
+++ /dev/null
@@ -1,118 +0,0 @@
-.. _transparent-proxy:
-
-Transparent Proxying
-********************
-
-.. 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
-
- transparent-proxy/build.en
- transparent-proxy/bridge.en
- transparent-proxy/router-inline.en
- transparent-proxy/wccp-configuration.en
- transparent-proxy/wccp-service-config.en
-
-Transparent Proxying is the ability of a proxy (such as ATS) to
-intercept connections between clients and servers without being visible.
-
-The general network structure that will be used in this documentation is
-shown in the following figure.
-
-.. figure:: ../static/images/admin/ats-basic-traffic.png
- :align: center
- :alt: ATS basic traffic flow of Transparent Proxy
-
- ATS basic traffic flow of Transparent Proxy
-
-There must be a gateway device through which all network traffic passes
-from the client to the Internet (or external cloud). The gateway is
-responsible for effectively splicing ATS in to selected streams of that
-traffic. Each traffic stream is split in two, with ATS terminating
-both sides. That is, stream green-1, red-2, is split in to the green
-connection and the red connection. Note that ATS may or may not be on
-the gateway system, the redirected traffic can flow over other network
-infrastructure.
-
-Because ATS uses two connections, transparency can be set independently
-on the client and origin server (Internet / external cloud) side. We
-will define what is generally called "transparent proxy" as two aspects,
-*inbound transparency* and *outbound transparency*.
-
-Inbound transparency is a proxy that is transparent to connections that
-are inbound to the proxy, i.e. a connection initiated by a client which
-connects to the proxy (green-1). Similarly, outbound transparency is a
-proxy that is transparent to connections that are outbound from the
-proxy, i.e. a connection initiated by the proxy to an origin server
-(red-2).
-
-In most situations these two types of transparency are combined, but that is
-not required. Traffic Server supports transparency independently on the two
-sides.
-
-.. important::
-
- It is critical to note that any transparency requires specialized
- routing and cannot be done solely by configuring ATS. ATS transparency
- also requires support from the Linux kernel and therefore currently only
- works on sufficiently recent Linux kernels that support the following
- features:
-
- - TPROXY
- - POSIX capabilities
-
- In addition the specialized routing will require using ``iptables`` and
- in some cases ``ebtables``.
-
-Standard build procedures should work for transparency support but if
-not consult these :ref:`more detailed instructions <building-ats-for-transparency>`.
-
-Transparency is configured per server port, not globally. This is done
-via the configuration values :ts:cv:`proxy.config.http.server_ports`.
-In addition, :ts:cv:`proxy.config.reverse_proxy.enabled` must be enabled if the
-client side is transparent. That should be fixed in a future patch.
-
-.. XXX has that been fixed?
-
-.. XXX revisit section below
-
-In the first case use the attribute character (replacing the default
-'X')
-
-**Attribute** **Transparency Style** **Reverse Proxy**
-
-``=``
- Full transparency: either
-
-``>``
- Inbound (client) transparency: enabled
-
-``<``
- Outbound (origin server) transparency: either
-
-In the outbound transparent case clients must connect directly to ATS
-either through an explicit proxy mechanism or by advertising the IP
-address of the ATS server via DNS as the origin server address.
-
-Some tested scenarios --
-
-- :doc:`transparent-proxy/bridge.en`
-- :doc:`transparent-proxy/router-inline.en`
-- :doc:`transparent-proxy/wccp-configuration.en`
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/transparent-proxy/bridge.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/transparent-proxy/bridge.en.rst b/doc/admin-guide/transparent-proxy/bridge.en.rst
deleted file mode 100644
index 8435ad9..0000000
--- a/doc/admin-guide/transparent-proxy/bridge.en.rst
+++ /dev/null
@@ -1,177 +0,0 @@
-Inline on a Linux Bridge
-************************
-
-.. 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.
-
-
-
-A Linux can be configured to operate in `bridge mode <http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge>`_.
-Two or more physical interfaces are assigned to the bridge. A single IP
-address is shared across the interfaces. By default any packet that
-arrives on one interface is immediately routed out another bridge
-interface.
-
-Linux packages required:
-
-- bridge-utils
-- ebtables
-
-In our example of setting up bridge mode we will use a local address of
-192.168.1.11/24 and interfaces ``eth0`` and ``eth1`` as the bridge
-interfaces (more detailed documentation is available
-`here <http://www.tldp.org/HOWTO/BRIDGE-STP-HOWTO/preparing-the-bridge.html>`_).
-You may omit the '#' character and everything after it. ::
-
- brctl addbr br0 # create bridge device
- brctl stp br0 off # Disable spanning tree protocol
- brctl addif br0 eth0 # Add eth0 to bridge
- brctl addif br0 eth1 # Add eth1 to bridge
-
- ifconfig eth0 0 0.0.0.0 # Get rid of interface IP addresses
- ifconfig eth1 0 0.0.0.0 # ditto # Set the bridge IP address and enable it
- ifconfig br0 192.168.1.11 netmask 255.255.255.0 up
-
-If you have not already done so, remember to add a default route, such
-as this one for a gateway of 192.168.1.1. ::
-
- ip route add default via 192.168.1.1
-
-At this point it is a good idea to test connectivity to verify the basic
-bridge is functional.
-
-Once the bridge is verified to work, this is the basic traffic pattern
-of interest.
-
-.. figure:: ../../static/images/admin/ats-traffic-bridge.png
- :align: center
- :alt: Picture of traffic flow through a bridge with ATS
-
- Picture of traffic flow through a bridge with ATS
-
-The green arrows are packets originating from the client and the red
-arrows are packets originating from the origin server. All traffic not
-directed to the local address will pass through the bridge. We need to
-break into some of the traffic and subject it to routing so that it can
-be routed to ATS. This requires ``ebtables``. The flows we want to
-intercept are green 1 (from client to bridge) and red 1 (origin server
-to bridge).
-
-In this example we will intercept port 80 (HTTP) traffic. We will use
-the ``BROUTING`` chain because it is traversed only for packets that
-originated externally and arrived on a (forwarding enabled) interface.
-Although it looks like this will intercept all port 80 traffic it will
-only affect the two flows described above. ``-j redirect`` marks the
-packet as being diverted to the bridge and not forwarded, and the
-``DROP`` target puts the packets in the normal ``iptables`` routing so
-that we can use standard device tests on them [1]_. Although this
-example handles only port 80, other ports are the same except for the
-port value. Note also the port here is the port from the point of view
-of the clients and origin servers, not the Traffic Server server port. ::
-
- ebtables -t broute -F # Flush the table
- # inbound traffic
- ebtables -t broute -A BROUTING -p IPv4 --ip-proto tcp --ip-dport 80 \
- -j redirect --redirect-target DROP
- # returning outbound traffic
- ebtables -t broute -A BROUTING -p IPv4 --ip-proto tcp --ip-sport 80 \
- -j redirect --redirect-target DROP
-
-Traffic Server operates at layer 3 so we need to use ``iptables`` to
-handle IP packets appropriately.::
-
- iptables -t mangle -A PREROUTING -i eth1 -p tcp -m tcp --dport 80 \
- -j TPROXY --on-ip 0.0.0.0 --on-port 8080 --tproxy-mark 1/1
- iptables -t mangle -A PREROUTING -i eth0 -p tcp -m tcp --sport 80 \
- -j MARK --set-mark 1/1
-
-At this point the directionality of the interfaces matters. For the
-example ``eth1`` is the inbound (client side) interface, while ``eth0``
-is the outbound (origin server side) interface. We mark both flows of
-packets so that we can use policy routing on them. For inbound packets
-we need to use ``TPROXY`` to force acceptance of packets to foreign IP
-addresses. For returning outbound packets there will be a socket open
-bound to the foreign address, we need only force it to be delivered
-locally. The value for ``--on-ip`` is 0 because the target port is
-listening and not bound to a specific address. The value for
-``--on-port`` must match the Traffic Server server port. Otherwise its
-value is arbitrary. ``--dport`` and ``--sport`` specify the port from
-the point of view of the clients and origin servers.
-
-Once the flows are marked we can force them to be delivered locally via
-the loopback interface via a policy routing table.::
-
- ip rule add fwmark 1/1 table 1
- ip route add local 0.0.0.0/0 dev lo table 1
-
-The marking used is arbitrary but it must be consistent between
-``iptables`` and the routing rule. The table number must be in the range
-1..253.
-
-To configure Traffic Server set the following values in
-:file:`records.config`
-
-- :ts:cv:`proxy.config.http.server_ports` *value from* ``--on-port`` (see below)
-
-- :ts:cv:`proxy.config.reverse_proxy.enabled` ``1``
-
-- :ts:cv:`proxy.config.url_remap.remap_required` ``0``
-
-You may also need to set :ts:cv:`proxy.config.cluster.ethernet_interface` to
-"br0" (the name of the bridge interface from the Bridge Commands).
-
-Additional troubleshooting
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-* Check to make sure that ``iptables`` is not filtering (blocking)
- incoming HTTP connections.
-
- It is frequently the case that the default tables prevent incoming HTTP. You can clear all filters with the
- commands::
-
- iptables -t filter --flush FORWARD
- iptables -t filter --flush INPUT
-
- That is a bit drastic and should only be used for testing / debugging. A
- live system will likely need some filters in place but that is beyond
- the scope of this document. If this fixes the problem, then your filter
- set is too restrictive.
-
- Note that this problem will prevent the basic bridge (without ATS) from
- allowing HTTP traffic through.
-
-* Verify that IP packet forwarding is enabled.
-
- You can check this with::
-
- cat /proc/sys/net/ipv4/ip_forward
-
- The output should be a non-zero value (usually '1'). If it is zero, you
- can set it with::
-
- echo '1' > /proc/sys/net/ipv4/ip_forward
-
- This can setting can be persisted by putting it in ``/etc/sysctl.conf``: ::
-
- net/ipv4/ip_forward=1
-
-.. rubric:: Footnotes
-
-.. [1]
- The ``--redirect-target`` can be omitted, but then the ``iptables``
- rules would need to use ``--physdev`` instead of just ``-i``. The
- actual packet processing is identical.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/transparent-proxy/build.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/transparent-proxy/build.en.rst b/doc/admin-guide/transparent-proxy/build.en.rst
deleted file mode 100644
index e547a06..0000000
--- a/doc/admin-guide/transparent-proxy/build.en.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-.. _building-ats-for-transparency:
-
-Building ATS for transparency
-*****************************
-
-.. 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.
-
-
-In most cases, if your environment supports transparency then
-``configure`` will automatically enable it. For other environments you
-may need to twiddle the ``configure`` options.
-
-``--enable-posix-cap``
- This enables POSIX capabilities, which are required for
- transparency. These are compiled in by default. To check your
- system, look for the header file ``sys/capability.h`` and the system
- library ``libcap``. These are in the packages ``libcap`` and
- ``libcap-devel`` or ``libcap-dev`` (depending on the Distribution)
- contra-respectively.
-
-``--enable-tproxy[=value]``
- Enable TPROXY support, which is the Linux kernel feature used for
- transparency. This should be present in the base installation, there
- is no package associated with it. \* ``auto`` Do automatic checks
- for the the TPROXY header file (``linux/in.h``) and enable TPROXY
- support if the ``IP_TRANSPARENT`` definition is present. This is the
- default if this option is not specified or ``value`` is omitted. \*
- ``no`` Do not check for TPROXY support, disable support for it. \*
- ``force`` Do not check for TPROXY support, enable it using the $ats@
- built in value for ``IP_TRANSPARENT``. This is useful for systems
- that have it in the kernel for but some reason do not have the
- appropriate system header file. \* *number* Do not check for TPROXY
- support, use *number* as the ``IP_TRANSPARENT`` value. There are, at
- present, no known standard distributions of Linux that support
- TPROXY but use a value different from the built in ATS default.
- However, a custom built kernel may do so and in that case the
- specific value can be specified.
-
-In the default case, ATS configuration will automatically check for
-TPROXY support via the presence of the ``linux/in.h`` header file and
-compile in TPROXY support if it is available. If that fails, you may be
-able to recover by using one of the options above. Note that
-transparency may be built in by default but it is not active unless
-explicitly enabled in the ATS configuration files.
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/transparent-proxy/router-inline.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/transparent-proxy/router-inline.en.rst b/doc/admin-guide/transparent-proxy/router-inline.en.rst
deleted file mode 100644
index 0e9060a..0000000
--- a/doc/admin-guide/transparent-proxy/router-inline.en.rst
+++ /dev/null
@@ -1,87 +0,0 @@
-Inline on a Linux router
-************************
-
-.. 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 routed set up presumes the set of clients are on distinct networks
-behind a single physical interface. For the purposes of this example
-will we presume
-
-- The clients are on network 172.28.56.0/24
-- The router connects the networks 172.28.56.0/24 and 192.168.1.0/24
-- Interface ``eth0`` is on the network 192.168.1.0/24
-- Interface ``eth1`` is on the network 172.28.56.0/24
-- The router is already configured to route traffic correctly for the
- clients.
-
-In this example we will intercept port 80 (HTTP) traffic that traverses
-the router. The first step is to use ``iptables`` to handle IP packets
-appropriately.
-
-::
-
- # reflow client web traffic to TPROXY
- iptables -t mangle -A PREROUTING -i eth1 -p tcp -m tcp --dport 80 -j TPROXY \
- --on-ip 0.0.0.0 --on-port 8080 --tproxy-mark 1/1
- # Let locally directed traffic pass through.
- iptables -t mangle -A PREROUTING -i eth0 --source 192.168.1.0/24 -j ACCEPT
- iptables -t mangle -A PREROUTING -i eth0 --destination 192.168.1.0/24 -j ACCEPT
- # Mark presumed return web traffic
- iptables -t mangle -A PREROUTING -i eth0 -p tcp -m tcp --sport 80 -j MARK --set-mark 1/1
-
-We mark packets so that we can use policy routing on them. For inbound
-packets we use ``TPROXY`` to make it possible to accept packets sent to
-foreign IP addresses. For returning outbound packets there will be a
-socket open bound to the foreign address, we need only force it to be
-delivered locally. The value for ``--on-ip`` is 0 because the target
-port is listening and not bound to a specific address. The value for
-``--on-port`` must match the Traffic Server server port. Otherwise its
-value is arbitrary. ``--dport`` and ``--sport`` specify the port from
-the point of view of the clients and origin servers. The middle two
-lines exempt local web traffic from being marked for Traffic Server --
-these rules can be tightened or loosened as needed. They server by
-matching traffic and exiting the ``iptables`` processing via ``ACCEPT``
-before the last line is checked.
-
-Once the flows are marked we can force them to be delivered locally via
-the loopback interface via a policy routing table.
-
-::
-
- ip rule add fwmark 1/1 table 1
- ip route add local 0.0.0.0/0 dev lo table 1
-
-The marking used is arbitrary but it must be consistent between
-``iptables`` and the routing rule. The table number must be in the range
-1..253.
-
-To configure Traffic Server set the following values in
-:file:`records.config`
-
-``proxy.config.http.server_ports``
- ``STRING``
- Default: *value from* ``--on-port``
-
-``proxy.config.reverse_proxy.enabled``
- ``INT``
- Default: ``1``
-
-``proxy.config.url_remap.remap_required``
- ``INT``
- Default: ``0``
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/transparent-proxy/wccp-configuration.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/transparent-proxy/wccp-configuration.en.rst b/doc/admin-guide/transparent-proxy/wccp-configuration.en.rst
deleted file mode 100644
index a36401c..0000000
--- a/doc/admin-guide/transparent-proxy/wccp-configuration.en.rst
+++ /dev/null
@@ -1,156 +0,0 @@
-WCCP Configuration
-******************
-
-.. 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.
-
-.. _wccp-configuration:
-
-.. toctree::
- :maxdepth: 2
-
-`WCCP <http://cio.cisco.com/en/US/docs/ios/12_0t/12_0t3/feature/guide/wccp.html>`_
-is de-facto semi-standard used by routers to redirect network traffic to
-caches. It is available on most Cisco™ routers although it does not
-appear to be officially supported by Cisco. The primary benefits of WCCP
-are
-
-- If already have a router that supports WCCP inline you do not
- have to change your network topology.
-- WCCP fails open so that if the Traffic Server machine fails, it is
- bypassed and users continue to have Internet access.
-
-Use of WCCP only makes sense for client side transparency [1]_
-because if the clients are explicitly proxied by Traffic Server there's
-no benefit to WCCP fail open, as the clients will continue to directly
-access the unresponsive Traffic Server host. It would be better to
-adjust the routing tables on the router for explicit proxying.
-
-Because the router serves as the inline network element, Traffic Server
-must run on a separate host. This host can be located anywhere as long
-as Traffic Server is either on the same network segment or a GRE tunnel
-can be maintained between the Traffic Server host and the router.
-
-|important| This document presumes that the router is already properly
-configured to handle traffic between the clients and the origin servers.
-If you are not certain, verify it before attempting to configure Traffic
-Server with WCCP. This is also a good state to which to revert should
-the configuration go badly.
-
-Configuration overview
-======================
-
-Setting WCCP is a three step process, first configuring the router, the
-Traffic Server host, and Traffic Server.
-
-|image1| The router will **not** respond to WCCP protocol packets unless
-explicitly configured to do so. Via WCCP, the router can be made to
-perform packet interception and redirection needed by Traffic Server
-transparency. The WCCP protocol in effect acts as means of controlling a
-rough form of policy routing with positive heartbeat cutoff.
-
-The Traffic Server host system must also be configured using
-``iptables`` to accept connections on foreign addresses. This is done
-roughly the same way as the standard transparency use.
-
-Finally Traffic Server itself must be configured for transparency and
-use of WCCP. The former is again very similar to the standard use, while
-WCCP configuration is specific to WCCP and uses a separate configuration
-file, referred to by the :file:`records.config` file.
-
-The primary concern for configuration in which of three basic topologies
-are to be used.
-
-- Dedicated -- Traffic Server traffic goes over an interface that is
- not used for client nor origin server traffic.
-- Shared -- Traffic Server traffic shares an interface with client or
- server traffic.
-- Inside Shared -- Traffic Server and client traffic share an
- interface.
-- Outside Shared -- Traffic Server and
- origin server traffic share an interface.
-
-In general the dedicated topology is preferred. However, if the router
-has only two interfaces one of the shared topologies will be
-required [2]_ Click the links above for more detailed configuration
-information on a specific topology.
-
-Shared interface issues
------------------------
-
-A shared interface topology has additional issues compared to a
-dedicated topology that must be handled. Such a topology is required if
-the router has only two interfaces, and because of these additional
-issues it is normally only used in such cases, although nothing prevents
-it use even if the router has three or more interfaces.
-
-The basic concept for a shared interface is to use a tunnel to simulate
-the dedicated interface case. This enables the packets to be
-distinguished at layer 3. For this reason, layer 2 redirection cannot be
-used because the WCCP configuration cannot distinguish between packets
-returning from the origin server and packets returning from Traffic
-Server as they are distinguished only by layer 2 addressing [3]_.
-Fortunately the GRE tunnel used for packet forwarding and return can be
-used as the simulated interface for Traffic Server.
-
-Frequently encountered problems
--------------------------------
-
-MTU and fragmentation
-~~~~~~~~~~~~~~~~~~~~~
-
-In most cases the basic configuration using a tunnel in any topology can
-fail due to issues with fragmentation. The socket logic is unable to
-know that its packets will eventually be put in to a tunnel which will
-by its nature have a smaller
-`MTU <http://en.wikipedia.org/wiki/Maximum_transmission_unit>`_ than the
-physical interface which it uses. This can lead to pathological behavior
-or outright failure as the packets sent are just a little too big. It is
-not possible to solve easily by changing the MTU on the physical
-interface because the tunnel interface uses that to compute its own MTU.
-
-References
-==========
-
-- `WCCP Router Configuration Commands - IOS
- 12.2 <http://www.cisco.com/en/US/docs/ios/12_2/configfun/command/reference/frf018.html>`_
-
-
-
-
-
-
-
-
-.. [1]
- Server side transparency should also be used, but it is not as
- significant. In its absence, however, origin servers may see the
- source address of connections suddenly change from the Traffic Server
- address to client addresses, which could cause problems. Further, the
- primary reason for not having server side transparency is to hide
- client addresses which is defeated if the Traffic Server host fails.
-
-.. [2]
- If your router has only one interface, it's hardly a *router*.
-
-.. [3]
- This is not fundamentally impossible, as the packets are distinct in
- layer
-
-.. |important| image:: ../../static/images/docbook/important.png
-.. |image1| image:: ../../static/images/docbook/important.png
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/transparent-proxy/wccp-service-config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/transparent-proxy/wccp-service-config.en.rst b/doc/admin-guide/transparent-proxy/wccp-service-config.en.rst
deleted file mode 100644
index 7726ebe..0000000
--- a/doc/admin-guide/transparent-proxy/wccp-service-config.en.rst
+++ /dev/null
@@ -1,75 +0,0 @@
-WCCP Service Configuration
-**************************
-
-.. 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.
-
-.. _wccp-service-configuration:
-
-The service definition file is used by
-:ref:`traffic_wccp` and :ref:`traffic-server` directly.
-The elements in the security definition file are inspired by the `WCCP RFC (8/2012) <http://tools.ietf.org/html/draft-mclaggan-wccp-v2rev1-00>`_. There is also an older version of the RFC that shows up commonly in search results, `WCCP (4/2001) <https://tools.ietf.org/id/draft-wilson-wrec-wccp-v2-01.txt>`_, and was the RFC reference used in the original WCCP support for Traffic Server several years ago.
-
-A sample service group file is included in the source tree under cmd/traffic_wccp.
-
-Security Section
-================
-
-In the security section, you can define a password shared between the WCCP Client and the WCCP router. This password is used to encrypt the WCCP traffic. It is optional, but highly recommended.
-
-Attributes in this section
-
-* option - Must be set to MD5 if you want to encrypt your WCCP traffic
-
-* key – The same password that you set with the associated WCCP router.
-
-Services Section
-================
-
-In the services section you can define a list of service groups. Each top level entry is a separate service group.
-
-Service group attributes include
-
-* name – A name for the service. Not used in the rest of the WCCP processing.
-
-* description – A description of the service. Again, not used in the rest of the WCCP processing.
-
-* id - The security group ID. It must match the service group ID that has been defined on the associated WCCP router. This is the true service group identifier from the WCCP perspective.
-
-* type – This defines the type of service group either “STANDARD” or “DYNAMIC”. There is one standard defined service group, HTTP with the id of 0. The 4/2001 RFC indicates that id’s 0-50 are reserved for well known service groups. But more recent 8/2012 RFC indicates that values 0 through 254 are valid service id’s for dynamic services. To avoid differences with older WCCP routers, you probably want to avoid dynamic service ID’s 0 through 50.
-
-* priority – This is a value from 0 to 255. The higher number is a higher priority. Well known (STANDARD) services are set to a value of 240. If there are multiple service groups that could match a given packet, the higher priority service group is applied. RFC For example, you have service group 100 defined for packets with destination port 80, and service group 101 defined for packets with source port 1024. For a packet with destination port set to 80 and source port set to 1024, the priorities of the service groups would need to be compared to determine which service group applies.
-
-* protocol – This is IP protocol number that should match. Generally this is set to 6 (TCP) or 17 (UDP).
-
-* assignment – WCCP supports multiple WCCP clients supporting a single service group. However, the current WCCP client implementation in Traffic Server assumes there is only a single WCCP client, and so creates assignment tables that will direct all traffic to that WCCP client. The assignment type is either hash or mask, and if it is not set, it defaults to hash. If Traffic Server ever supports more than one cache, it will likely only support a balanced hash assignment. The mask/value assignment seems to be better suited to situations where the traffic needs to be more strongly controlled.
-
-* primary-hash – This is the element of the packet that is used to compute the primary key. The value options are src_ip, dst_ip, src_port, or dst_port. This entry is a list, so multiple values can be specified. In that case, all the specified packet attributes will be used to compute the hash bucket. In the current implementation, the primary hash value does not matter, since the client always generates a hash table that directs all matching traffic to it. But if multiple clients are ever supported, knowledge of the local traffic distribution could be used to pick a packet attribute that will better spread traffic over the WCCP clients.
-* alt-hash – The protocol supports a two level hash. This attribute is a list with the same value options as for primary-hash. Again, since the current Traffic Server implementation only creates assignment tables to a single client, specifying the alt-hash values does nothing.
-
-* ports – This is a list of port values. Up to 8 port values may be included in a service group definition.
-
-* port-type – This attribute can have the value of src or dst. If not specified, it defaults to dst. It indicates whether the port values should be interpreted as source ports or destination ports.
-
-* forward – This is a list. The list of the values can be GRE or L2. This advertises how the client wants to process WCCP packets. GRE means that the packets will be delivered in a GRE tunnel. This is the default. L2 means that the client is on the same network and can get traffic delivered to it from the router by L2 routing (MAC addresses).
-
-* return – The WCCP protocol allows a WCCP client to decline a packet and return it back to the router. The current WCCP client implementation never does this. The value options are the same as for the forward attribute.
-
-* routers – This is the list of router addresses the WCCP client communicates with. The WCCP protocols allows for multiple WCCP routers to be involved in a service group. The multiple router scenario has at most been lightly tested in the Traffic Server implementation.
-
-* proc-name – This attribute is only used by traffic_wccp. It is not used in the traffic_server WCCP support. This is the path to a process’ PID file. The service group is advertised to the WCCP router if the process identified in the PID file is currently operational.
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/appendices/command-line/traffic_ctl.en.rst
----------------------------------------------------------------------
diff --git a/doc/appendices/command-line/traffic_ctl.en.rst b/doc/appendices/command-line/traffic_ctl.en.rst
index 5ac8a7b..e1b5a2a 100644
--- a/doc/appendices/command-line/traffic_ctl.en.rst
+++ b/doc/appendices/command-line/traffic_ctl.en.rst
@@ -15,9 +15,12 @@
specific language governing permissions and limitations
under the License.
-===========
+.. include:: ../../common.defs
+
+.. _traffic_ctl:
+
traffic_ctl
-===========
+***********
Synopsis
========
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/appendices/command-line/traffic_via.en.rst
----------------------------------------------------------------------
diff --git a/doc/appendices/command-line/traffic_via.en.rst b/doc/appendices/command-line/traffic_via.en.rst
index ec6beb2..275d46e 100644
--- a/doc/appendices/command-line/traffic_via.en.rst
+++ b/doc/appendices/command-line/traffic_via.en.rst
@@ -72,7 +72,7 @@ Decode the Via header from command-line arguments::
Parent proxy connection status :no parent proxy or unknown
Origin server connection status :connection open failed
-Decode the Via header from a curl request, using the :ref:`X-Debug <_xdebug_plugin>` plugin::
+Decode the Via header from a curl request, using the :ref:`X-Debug <xdebug-plugin>` plugin::
$ curl -H "X-Debug: Via" -I http://test.example.com | traffic_via -
Via header is uScMsSf pSeN:t cCMi p sS, Length is 24
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/appendices/command-line/traffic_wccp.en.rst
----------------------------------------------------------------------
diff --git a/doc/appendices/command-line/traffic_wccp.en.rst b/doc/appendices/command-line/traffic_wccp.en.rst
index 8340ab6..3530f75 100644
--- a/doc/appendices/command-line/traffic_wccp.en.rst
+++ b/doc/appendices/command-line/traffic_wccp.en.rst
@@ -54,11 +54,11 @@ Options
.. option:: --daemon Run as daemon.
-You need to run at least with the --service arguments.
-An example service definition file, service-nogre-example.config, is included
-in the cmd/traffic_wccp directory. In this file you define your MD5 security password
-(highly recommended), and you define your service groups. The details
-of the service file are defined at :ref:`WCCP Service Configuration <wccp-service-configuration>`.
+You need to run at least with the ``--service`` arguments. An example service
+definition file, ``service-nogre-example.config``, is included in the
+``cmd/traffic_wccp`` directory. In this file you define your MD5 security
+password (highly recommended), and you define your service groups. The details
+of the service file are defined at :ref:`admin-wccp-service-config`.
Limitations
===========
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/appendices/faq.en.rst
----------------------------------------------------------------------
diff --git a/doc/appendices/faq.en.rst b/doc/appendices/faq.en.rst
index 0bcbf02..d8646c5 100644
--- a/doc/appendices/faq.en.rst
+++ b/doc/appendices/faq.en.rst
@@ -60,7 +60,7 @@ the request for the objects), and do not execute on the server.
In Squid- and Netscape-format log files, what do the cache result codes mean?
-----------------------------------------------------------------------------
-This is described in detail in the :ref:`log-formats-squid-format` documentation.
+This is described in detail in the :ref:`admin-logging-format-squid` documentation.
What is recorded by the ``cqtx`` field in a custom log file?
------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/appendices/glossary.en.rst
----------------------------------------------------------------------
diff --git a/doc/appendices/glossary.en.rst b/doc/appendices/glossary.en.rst
index a8301cf..eaa2a58 100644
--- a/doc/appendices/glossary.en.rst
+++ b/doc/appendices/glossary.en.rst
@@ -147,3 +147,5 @@ Glossary
cache partition
+ global plugin
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/api/functions/TSHttpHdrCopy.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/api/functions/TSHttpHdrCopy.en.rst b/doc/developer-guide/api/functions/TSHttpHdrCopy.en.rst
index 3054395..feff3e2 100644
--- a/doc/developer-guide/api/functions/TSHttpHdrCopy.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpHdrCopy.en.rst
@@ -21,8 +21,9 @@
TSHttpHdrCopy
*************
-Copies the contents of the HTTP header located at src_loc within
-src_bufp to the HTTP header located at dest_loc within dest_bufp.
+Copies the contents of the HTTP header located at :arg:`src_loc` within
+:arg:`src_bufp` to the HTTP header located at :arg:`dest_loc` within
+:arg:`dest_bufp`.
Synopsis
========
@@ -34,9 +35,9 @@ Synopsis
Description
===========
-:c:func:`TSHttpHdrCopy` works correctly even if :arg:`src_bufp` and
-:arg:`dest_bufp` point to different :ref:`developer-plugins-marshal-buffers`.
-Make sure that you create the destination HTTP header before copying into it.
+:c:func:`TSHttpHdrCopy` works correctly even if :arg:`src_bufp` and :arg:`dest_bufp`
+point to different :ref:`developer-plugins-http-headers-marshal-buffers`. Make
+sure that you create the destination HTTP header before copying into it.
.. note::
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst b/doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst
index 298124d..7405c32 100644
--- a/doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst
@@ -19,6 +19,8 @@
.. default-domain:: c
+.. _ts-overridable-config:
+
TSHttpOverridableConfig
***********************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/architecture/architecture.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/architecture/architecture.en.rst b/doc/developer-guide/architecture/architecture.en.rst
index e7f8dcf..ba72d99 100644
--- a/doc/developer-guide/architecture/architecture.en.rst
+++ b/doc/developer-guide/architecture/architecture.en.rst
@@ -38,8 +38,8 @@ discussed only to the extent needed to understand the internal mechanisms. This
document will be useful primarily to |TS| developers working on the |TS|
codebase or plugins for |TS|. It is assumed the reader is already familiar with
the :ref:`admin-guide` and specifically with :ref:`http-proxy-caching` and
-:ref:`configuring-the-cache` along with the associated configuration files and
-values.
+:ref:`admin-configuration` along with the associated :ref:`configuration files
+<admin-configuration-files>`.
Unfortunately, the internal terminology is not particularly consistent, so this
document will frequently use terms in different ways than they are used in the
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/documentation/building.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/documentation/building.en.rst b/doc/developer-guide/documentation/building.en.rst
index 1b1be2d..59fde26 100644
--- a/doc/developer-guide/documentation/building.en.rst
+++ b/doc/developer-guide/documentation/building.en.rst
@@ -27,8 +27,8 @@ All documentation and related files are located in the source tree under the
script. For simplicity's sake, it is recommended that contributors new to the
documentation make use of the included Vagrant configurations, as these will
take care of providing all dependencies. Please refer to the
-:ref:`dev-testing-with-vagrant` chapter for complete details on using Vagrant to
-build and test the |TS| source tree.
+:ref:`developer-testing-with-vagrant` chapter for complete details on using
+Vagrant to build and test the |TS| source tree.
With a configured source tree, building the documentation requires only the
invocation ``make html`` from within ``doc/``. For repeated builds while working
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/documentation/ts-markup.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/documentation/ts-markup.en.rst b/doc/developer-guide/documentation/ts-markup.en.rst
index 8b3b2bd..32642da 100644
--- a/doc/developer-guide/documentation/ts-markup.en.rst
+++ b/doc/developer-guide/documentation/ts-markup.en.rst
@@ -119,7 +119,7 @@ Definition
Collection
The key name of the collection in the returned JSON data from the
- :ref:`plugin-stats-over-http` plugin. For most statistics, this is the
+ :ref:`admin-plugins-stats-over-http` plugin. For most statistics, this is the
literal sting :literal:`global`. *Required*
Statistic Name
@@ -189,9 +189,10 @@ deprecated
ungathered
A simple flag option, without any associated values, indicating that while
- the statistic is included in the output of plugins like :ref:`plugin-stats-over-http`
- there is no underlying data gathered for the statistic. If a statistic is
- thus marked, it should be assumed to be invalid or simply unimplemented.
+ the statistic is included in the output of plugins like
+ :ref:`admin-plugins-stats-over-http` there is no underlying data gathered
+ for the statistic. If a statistic is thus marked, it should be assumed to
+ be invalid or simply unimplemented.
References
~~~~~~~~~~
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/introduction/audience.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/introduction/audience.en.rst b/doc/developer-guide/introduction/audience.en.rst
deleted file mode 100644
index 540d08e..0000000
--- a/doc/developer-guide/introduction/audience.en.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-.. 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
-
-.. _developer-preface:
-
-Preface
-********
-
-.. toctree::
- :maxdepth: 2
-
- preface/how-to-use-this-book.en
- preface/typographical-conventions.en
-
-The |TS| Software Developer's Kit is a reference for creating plugins.
-*Plugins* are programs that add services (such as filtering or content
-transformation) or entire features (such as new protocol support) to |TS|. If
-you are new to writing |TS| plugins, then read the first two chapters,
-:ref:`developer-plugins-getting-started` and
-:ref:`developer-plugins-introduction`, and use the remaining chapters as
-needed. :ref:`developer-plugins-header-based-examples` provides details about
-plugins that work on HTTP headers, while
-:ref:`developer-plugins-http-transformations` explains how to write a plugin
-that transforms or scans the body of an HTTP response. If you want to support
-your own protocol on Traffic Server, then reference
-:ref:`developer-plugins-new-protocol-plugins`.
-
-.. _developer-audience:
-
-Audience
---------
-
-This manual is intended for programmers who want to write plugin
-programs that add services or features to Traffic Server. It assumes a
-cursory knowledge of the C programming language, Hyper-Text Transfer
-Protocol (HTTP), and Multipurpose Internet Mail Extensions (MIME).
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/introduction/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/introduction/index.en.rst b/doc/developer-guide/introduction/index.en.rst
index d5f2415..00ec7c9 100644
--- a/doc/developer-guide/introduction/index.en.rst
+++ b/doc/developer-guide/introduction/index.en.rst
@@ -22,16 +22,16 @@
Introduction
************
-This book has the following basic components:
+This guide has the following basic components:
-- Introduction and overview
+- Introduction and overview.
- Tutorials about writing specific kinds of plugins: HTTP header-based
- plugins, content transformation plugins, and protocol plugins
+ plugins, content transformation plugins, and protocol plugins.
-- Guides about specific interfaces
+- Guides about specific interfaces.
-- Reference material
+- Reference material.
If you're new to writing |TS| plugins, :ref:`developer-plugins-getting-started`
should be your starting point. :ref:`developer-plugins-header-based-examples`
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/plugins/adding-statistics.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/adding-statistics.en.rst b/doc/developer-guide/plugins/adding-statistics.en.rst
index b0c5480..ffbc622 100644
--- a/doc/developer-guide/plugins/adding-statistics.en.rst
+++ b/doc/developer-guide/plugins/adding-statistics.en.rst
@@ -31,13 +31,6 @@ would any other Traffic Server statistic, using Traffic Line (Traffic
Server's command line interface). This chapter contains the following
topics:
-.. toctree::
- :maxdepth: 2
-
- adding-statistics/coupled-statistics.en
- adding-statistics/viewing-statistics-using-traffic-line.en
-
-
Uncoupled Statistics
====================
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/plugins/hooks-and-transactions/trafficserver-timers.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/trafficserver-timers.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/trafficserver-timers.en.rst
new file mode 100644
index 0000000..194f380
--- /dev/null
+++ b/doc/developer-guide/plugins/hooks-and-transactions/trafficserver-timers.en.rst
@@ -0,0 +1,37 @@
+HTTP Transaction Timers
+***********************
+
+.. 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.
+
+Transaction Timers at various states
+------------------------------------
+
+Traffic Server runs a variety of timers at various states of a transaction. Typically,
+a given transaction may include upto two connections (one on the UA/client side and the
+other on the Origin side). Traffic Server supports two kinds of timers "Active" and
+"Inactive" timers for each side respectively, as applicable at a given state. The below
+picture illustrates the specific timers run at various states in the current implementation.
+The picture only depicts the HTTP transaction level timers and does not include the TLS handshake
+states and other more detailed/internal timers in each individual state.
+
+.. figure:: ../../../static/images/admin/transaction_states_timers.svg
+ :align: center
+ :alt: Transaction Timers in various states
+
+ Transaction Timers in various states
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/plugins/new-protocol-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/plugins/new-protocol-plugins.en.rst b/doc/developer-guide/plugins/new-protocol-plugins.en.rst
index b7150d6..72c1925 100644
--- a/doc/developer-guide/plugins/new-protocol-plugins.en.rst
+++ b/doc/developer-guide/plugins/new-protocol-plugins.en.rst
@@ -76,7 +76,7 @@ In more specific terms, Traffic Server and the Protocol plugin must:
.. _SampleProtocolStDiag:
-.. figure:: ../static/images/sdk/Protocol_state_diagram.jpg
+.. figure:: ../../static/images/sdk/Protocol_state_diagram.jpg
:alt: Sample Protocol State Diagram
Sample Protocol State Diagram
@@ -112,7 +112,7 @@ Overview <ProtocolPluginOverview>` diagram below.
.. _ProtocolPluginOverview:
-.. figure:: ../static/images/sdk/protocol_sm_big.jpg
+.. figure:: ../../static/images/sdk/protocol_sm_big.jpg
:alt: Protocol Plugin Overview
Protocol Plugin Overview
@@ -167,7 +167,7 @@ Processor.
.. _ProtocolPluginFlow:
-.. figure:: ../static/images/sdk/protocol_evt.jpg
+.. figure:: ../../static/images/sdk/protocol_evt.jpg
:alt: Protocol Plugin Flow of Events
Protocol Plugin Flow of Events
@@ -257,7 +257,7 @@ Plugin**
.. _ImplementTransStMachine:
-.. figure:: ../static/images/sdk/txn_sm.jpg
+.. figure:: ../../static/images/sdk/txn_sm.jpg
:alt: How Transaction State Machines are Implemented in the Protocol Plugin
How Transaction State Machines are Implemented in the Protocol Plugin
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/troubleshooting-tips.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/troubleshooting-tips.en.rst b/doc/developer-guide/troubleshooting-tips.en.rst
deleted file mode 100644
index 3a312bf..0000000
--- a/doc/developer-guide/troubleshooting-tips.en.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-Troubleshooting Tips
-********************
-
-.. 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.
-
-This appendix lists the following troubleshooting tips.
-
-.. toctree::
- :maxdepth: 2
-
- troubleshooting-tips/unable-to-load-plugins.en
- troubleshooting-tips/unable-to-debug-tags.en
- troubleshooting-tips/using-a-debugger.en
- troubleshooting-tips/debugging-memory-leaks.en
-
-
-Unable to Compile Plugins
--------------------------
-
-The process for compiling a shared library varies with the platform
-used, so the Traffic Server API includes the :program:`tsxs` script you can use
-to create shared libraries on all supported Traffic Server platforms.
-
-Example
-~~~~~~~
-
-Assuming the sample program is stored in the file ``hello-world.c``, you
-could use the following commands to building a shared library:
-
-::
-
- tsxs -c hello-world.c -o hello-world.so
-
-To install this plugin in your ``plugindir`` use the equivalent of sudo
-on your platform to execute:
-
-::
-
- sudo tsxs -o hello-world.so -i
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst b/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst
deleted file mode 100644
index 6d360b4..0000000
--- a/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-.. 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
-
-.. _developer-troubleshooting-unable-to-load-plugins:
-
-Unable to Load Plugins
-**********************
-
-To load plugins, follow the steps below.
-
-#. Make sure that your plugin source code contains an ``TSPluginInit``
- initialization function.
-
-#. Compile your plugin source code, creating a shared library.
-
-#. Add an entry to the ``plugin.config`` file for your plugin.
-
-#. Add the path to your plugin shared library to the :file:`records.config`
- file.
-
-#. Restart Traffic Server.
-
-For detailed information about each step above, refer to
-:ref:`developer-plugins-getting-started-simple-plugin`.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/getting-started/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/getting-started/index.en.rst b/doc/getting-started/index.en.rst
index 8ab6adb..66a5cb4 100644
--- a/doc/getting-started/index.en.rst
+++ b/doc/getting-started/index.en.rst
@@ -422,7 +422,7 @@ Extended-2* format you may wish to enable that logging format in addition to,
or instead of, the default |TS| logs.
The Administrator's Guide discusses logging options in great detail in
-:ref:`working-with-log-files`.
+:ref:`admin-monitoring-logging`.
Using Traffic Top
-----------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/sdk/trafficserver-timers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/trafficserver-timers.en.rst b/doc/sdk/trafficserver-timers.en.rst
deleted file mode 100644
index c5cef60..0000000
--- a/doc/sdk/trafficserver-timers.en.rst
+++ /dev/null
@@ -1,37 +0,0 @@
-HTTP Transaction Timers
-***********************
-
-.. 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.
-
-Transaction Timers at various states
-------------------------------------
-
-Traffic Server runs a variety of timers at various states of a transaction. Typically,
-a given transaction may include upto two connections (one on the UA/client side and the
-other on the Origin side). Traffic Server supports two kinds of timers "Active" and
-"Inactive" timers for each side respectively, as applicable at a given state. The below
-picture illustrates the specific timers run at various states in the current implementation.
-The picture only depicts the HTTP transaction level timers and does not include the TLS handshake
-states and other more detailed/internal timers in each individual state.
-
-.. figure:: ../static/images/admin/transaction_states_timers.svg
- :align: center
- :alt: Transaction Timers in various states
-
- Transaction Timers in various states
-
[2/2] trafficserver git commit: Docs: build cleanups and multiple
Jira issues.
Posted by zw...@apache.org.
Docs: build cleanups and multiple Jira issues.
[TS-4037] Table of Contents fixes
[TS-4086] Minimum size for proxy.config.log.rolling_size_mb
[TS-4077] Doc build warnings and errors
[TS-3704] ^^
[TS-3703] ^^
[TS-3288] Confirmed documentation is accurate that any uid != 0 is accepted by traffic_manager
This closes #419
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/40500c71
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/40500c71
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/40500c71
Branch: refs/heads/master
Commit: 40500c710b8b4aad0bf223c1ae4962cdf0725973
Parents: fd25910
Author: Jon Sime <jo...@gmail.com>
Authored: Wed Jan 13 17:19:45 2016 +0000
Committer: Leif Hedstrom <zw...@apache.org>
Committed: Wed Jan 13 10:38:55 2016 -0800
----------------------------------------------------------------------
.../configuration/hierachical-caching.en.rst | 2 +-
doc/admin-guide/configuration/index.en.rst | 1 +
.../configuration/session-protocol.en.rst | 18 +-
.../configuration/transparent-proxy.en.rst | 118 ++++
.../transparent-proxy/bridge.en.rst | 177 ++++++
.../transparent-proxy/build.en.rst | 60 ++
.../transparent-proxy/router-inline.en.rst | 87 +++
.../transparent-proxy/wccp-configuration.en.rst | 156 ++++++
.../wccp-service-config.en.rst | 84 +++
doc/admin-guide/files/log_hosts.config.en.rst | 49 +-
doc/admin-guide/files/records.config.en.rst | 546 +++++++++++++------
doc/admin-guide/index.en.rst | 1 -
doc/admin-guide/introduction.en.rst | 5 +-
.../monitoring/error-messages.en.rst | 2 +-
.../monitoring/logging/log-formats.en.rst | 72 +--
.../monitoring/logging/managing-logs.en.rst | 81 +--
.../monitoring/statistics/core/bandwidth.en.rst | 14 +-
.../statistics/core/cache-volume.en.rst | 2 +-
doc/admin-guide/plugins/healthchecks.en.rst | 14 +-
doc/admin-guide/plugins/index.en.rst | 1 +
doc/admin-guide/plugins/metalink.en.rst | 2 +-
doc/admin-guide/plugins/stats_over_http.en.rst | 2 +-
doc/admin-guide/plugins/xdebug.en.rst | 34 +-
doc/admin-guide/security/index.en.rst | 16 +-
doc/admin-guide/storage/index.en.rst | 9 +-
doc/admin-guide/transparent-proxy.en.rst | 118 ----
doc/admin-guide/transparent-proxy/bridge.en.rst | 177 ------
doc/admin-guide/transparent-proxy/build.en.rst | 60 --
.../transparent-proxy/router-inline.en.rst | 87 ---
.../transparent-proxy/wccp-configuration.en.rst | 156 ------
.../wccp-service-config.en.rst | 75 ---
doc/appendices/command-line/traffic_ctl.en.rst | 7 +-
doc/appendices/command-line/traffic_via.en.rst | 2 +-
doc/appendices/command-line/traffic_wccp.en.rst | 10 +-
doc/appendices/faq.en.rst | 2 +-
doc/appendices/glossary.en.rst | 2 +
.../api/functions/TSHttpHdrCopy.en.rst | 11 +-
.../functions/TSHttpOverridableConfig.en.rst | 2 +
.../architecture/architecture.en.rst | 4 +-
.../documentation/building.en.rst | 4 +-
.../documentation/ts-markup.en.rst | 9 +-
.../introduction/audience.en.rst | 53 --
doc/developer-guide/introduction/index.en.rst | 10 +-
.../plugins/adding-statistics.en.rst | 7 -
.../trafficserver-timers.en.rst | 37 ++
.../plugins/new-protocol-plugins.en.rst | 8 +-
doc/developer-guide/troubleshooting-tips.en.rst | 55 --
.../unable-to-load-plugins.en.rst | 40 --
doc/getting-started/index.en.rst | 2 +-
doc/sdk/trafficserver-timers.en.rst | 37 --
50 files changed, 1242 insertions(+), 1286 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/configuration/hierachical-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/hierachical-caching.en.rst b/doc/admin-guide/configuration/hierachical-caching.en.rst
index ee0f5d6..3bbf197 100644
--- a/doc/admin-guide/configuration/hierachical-caching.en.rst
+++ b/doc/admin-guide/configuration/hierachical-caching.en.rst
@@ -15,7 +15,7 @@
specific language governing permissions and limitations
under the License.
-.. include:: ../common.defs
+.. include:: ../../common.defs
.. _admin-hierarchical-caching:
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/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
index 66d7138..3a6d3ad 100644
--- a/doc/admin-guide/configuration/index.en.rst
+++ b/doc/admin-guide/configuration/index.en.rst
@@ -29,6 +29,7 @@ Proxy Cache Configuration
cache-basics.en
redirecting-http-requests.en
explicit-forward-proxying.en
+ transparent-proxy.en
transparent-forward-proxying.en
multi-server-caches.en
hierachical-caching.en
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/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
index 20a3bf1..bbaf33e 100644
--- a/doc/admin-guide/configuration/session-protocol.en.rst
+++ b/doc/admin-guide/configuration/session-protocol.en.rst
@@ -1,8 +1,3 @@
-.. _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
@@ -20,9 +15,16 @@ Session Protocol
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
+.. include:: ../../common.defs
+
+.. _session-protocol:
+
+Session Protocol
+****************
+
+|TS| supports some session level protocols in place of or on top of HTTP. These
+can be provided by a plugin (see :ref:`developer-plugins-new-protocol-plugins`)
+or be one that is supported directly by |TS|. 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.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/configuration/transparent-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/transparent-proxy.en.rst b/doc/admin-guide/configuration/transparent-proxy.en.rst
new file mode 100644
index 0000000..7937f53
--- /dev/null
+++ b/doc/admin-guide/configuration/transparent-proxy.en.rst
@@ -0,0 +1,118 @@
+.. _transparent-proxy:
+
+Transparent Proxying
+********************
+
+.. 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
+
+ transparent-proxy/build.en
+ transparent-proxy/bridge.en
+ transparent-proxy/router-inline.en
+ transparent-proxy/wccp-configuration.en
+ transparent-proxy/wccp-service-config.en
+
+Transparent Proxying is the ability of a proxy (such as ATS) to
+intercept connections between clients and servers without being visible.
+
+The general network structure that will be used in this documentation is
+shown in the following figure.
+
+.. figure:: ../../static/images/admin/ats-basic-traffic.png
+ :align: center
+ :alt: ATS basic traffic flow of Transparent Proxy
+
+ ATS basic traffic flow of Transparent Proxy
+
+There must be a gateway device through which all network traffic passes
+from the client to the Internet (or external cloud). The gateway is
+responsible for effectively splicing ATS in to selected streams of that
+traffic. Each traffic stream is split in two, with ATS terminating
+both sides. That is, stream green-1, red-2, is split in to the green
+connection and the red connection. Note that ATS may or may not be on
+the gateway system, the redirected traffic can flow over other network
+infrastructure.
+
+Because ATS uses two connections, transparency can be set independently
+on the client and origin server (Internet / external cloud) side. We
+will define what is generally called "transparent proxy" as two aspects,
+*inbound transparency* and *outbound transparency*.
+
+Inbound transparency is a proxy that is transparent to connections that
+are inbound to the proxy, i.e. a connection initiated by a client which
+connects to the proxy (green-1). Similarly, outbound transparency is a
+proxy that is transparent to connections that are outbound from the
+proxy, i.e. a connection initiated by the proxy to an origin server
+(red-2).
+
+In most situations these two types of transparency are combined, but that is
+not required. Traffic Server supports transparency independently on the two
+sides.
+
+.. important::
+
+ It is critical to note that any transparency requires specialized
+ routing and cannot be done solely by configuring ATS. ATS transparency
+ also requires support from the Linux kernel and therefore currently only
+ works on sufficiently recent Linux kernels that support the following
+ features:
+
+ - TPROXY
+ - POSIX capabilities
+
+ In addition the specialized routing will require using ``iptables`` and
+ in some cases ``ebtables``.
+
+Standard build procedures should work for transparency support but if
+not consult these :ref:`more detailed instructions <building-ats-for-transparency>`.
+
+Transparency is configured per server port, not globally. This is done
+via the configuration values :ts:cv:`proxy.config.http.server_ports`.
+In addition, :ts:cv:`proxy.config.reverse_proxy.enabled` must be enabled if the
+client side is transparent. That should be fixed in a future patch.
+
+.. XXX has that been fixed?
+
+.. XXX revisit section below
+
+In the first case use the attribute character (replacing the default
+'X')
+
+**Attribute** **Transparency Style** **Reverse Proxy**
+
+``=``
+ Full transparency: either
+
+``>``
+ Inbound (client) transparency: enabled
+
+``<``
+ Outbound (origin server) transparency: either
+
+In the outbound transparent case clients must connect directly to ATS
+either through an explicit proxy mechanism or by advertising the IP
+address of the ATS server via DNS as the origin server address.
+
+Some tested scenarios --
+
+- :doc:`transparent-proxy/bridge.en`
+- :doc:`transparent-proxy/router-inline.en`
+- :doc:`transparent-proxy/wccp-configuration.en`
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/configuration/transparent-proxy/bridge.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/transparent-proxy/bridge.en.rst b/doc/admin-guide/configuration/transparent-proxy/bridge.en.rst
new file mode 100644
index 0000000..f6ea982
--- /dev/null
+++ b/doc/admin-guide/configuration/transparent-proxy/bridge.en.rst
@@ -0,0 +1,177 @@
+Inline on a Linux Bridge
+************************
+
+.. 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.
+
+
+
+A Linux can be configured to operate in `bridge mode <http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge>`_.
+Two or more physical interfaces are assigned to the bridge. A single IP
+address is shared across the interfaces. By default any packet that
+arrives on one interface is immediately routed out another bridge
+interface.
+
+Linux packages required:
+
+- bridge-utils
+- ebtables
+
+In our example of setting up bridge mode we will use a local address of
+192.168.1.11/24 and interfaces ``eth0`` and ``eth1`` as the bridge
+interfaces (more detailed documentation is available
+`here <http://www.tldp.org/HOWTO/BRIDGE-STP-HOWTO/preparing-the-bridge.html>`_).
+You may omit the '#' character and everything after it. ::
+
+ brctl addbr br0 # create bridge device
+ brctl stp br0 off # Disable spanning tree protocol
+ brctl addif br0 eth0 # Add eth0 to bridge
+ brctl addif br0 eth1 # Add eth1 to bridge
+
+ ifconfig eth0 0 0.0.0.0 # Get rid of interface IP addresses
+ ifconfig eth1 0 0.0.0.0 # ditto # Set the bridge IP address and enable it
+ ifconfig br0 192.168.1.11 netmask 255.255.255.0 up
+
+If you have not already done so, remember to add a default route, such
+as this one for a gateway of 192.168.1.1. ::
+
+ ip route add default via 192.168.1.1
+
+At this point it is a good idea to test connectivity to verify the basic
+bridge is functional.
+
+Once the bridge is verified to work, this is the basic traffic pattern
+of interest.
+
+.. figure:: ../../../static/images/admin/ats-traffic-bridge.png
+ :align: center
+ :alt: Picture of traffic flow through a bridge with ATS
+
+ Picture of traffic flow through a bridge with ATS
+
+The green arrows are packets originating from the client and the red
+arrows are packets originating from the origin server. All traffic not
+directed to the local address will pass through the bridge. We need to
+break into some of the traffic and subject it to routing so that it can
+be routed to ATS. This requires ``ebtables``. The flows we want to
+intercept are green 1 (from client to bridge) and red 1 (origin server
+to bridge).
+
+In this example we will intercept port 80 (HTTP) traffic. We will use
+the ``BROUTING`` chain because it is traversed only for packets that
+originated externally and arrived on a (forwarding enabled) interface.
+Although it looks like this will intercept all port 80 traffic it will
+only affect the two flows described above. ``-j redirect`` marks the
+packet as being diverted to the bridge and not forwarded, and the
+``DROP`` target puts the packets in the normal ``iptables`` routing so
+that we can use standard device tests on them [1]_. Although this
+example handles only port 80, other ports are the same except for the
+port value. Note also the port here is the port from the point of view
+of the clients and origin servers, not the Traffic Server server port. ::
+
+ ebtables -t broute -F # Flush the table
+ # inbound traffic
+ ebtables -t broute -A BROUTING -p IPv4 --ip-proto tcp --ip-dport 80 \
+ -j redirect --redirect-target DROP
+ # returning outbound traffic
+ ebtables -t broute -A BROUTING -p IPv4 --ip-proto tcp --ip-sport 80 \
+ -j redirect --redirect-target DROP
+
+Traffic Server operates at layer 3 so we need to use ``iptables`` to
+handle IP packets appropriately.::
+
+ iptables -t mangle -A PREROUTING -i eth1 -p tcp -m tcp --dport 80 \
+ -j TPROXY --on-ip 0.0.0.0 --on-port 8080 --tproxy-mark 1/1
+ iptables -t mangle -A PREROUTING -i eth0 -p tcp -m tcp --sport 80 \
+ -j MARK --set-mark 1/1
+
+At this point the directionality of the interfaces matters. For the
+example ``eth1`` is the inbound (client side) interface, while ``eth0``
+is the outbound (origin server side) interface. We mark both flows of
+packets so that we can use policy routing on them. For inbound packets
+we need to use ``TPROXY`` to force acceptance of packets to foreign IP
+addresses. For returning outbound packets there will be a socket open
+bound to the foreign address, we need only force it to be delivered
+locally. The value for ``--on-ip`` is 0 because the target port is
+listening and not bound to a specific address. The value for
+``--on-port`` must match the Traffic Server server port. Otherwise its
+value is arbitrary. ``--dport`` and ``--sport`` specify the port from
+the point of view of the clients and origin servers.
+
+Once the flows are marked we can force them to be delivered locally via
+the loopback interface via a policy routing table.::
+
+ ip rule add fwmark 1/1 table 1
+ ip route add local 0.0.0.0/0 dev lo table 1
+
+The marking used is arbitrary but it must be consistent between
+``iptables`` and the routing rule. The table number must be in the range
+1..253.
+
+To configure Traffic Server set the following values in
+:file:`records.config`
+
+- :ts:cv:`proxy.config.http.server_ports` *value from* ``--on-port`` (see below)
+
+- :ts:cv:`proxy.config.reverse_proxy.enabled` ``1``
+
+- :ts:cv:`proxy.config.url_remap.remap_required` ``0``
+
+You may also need to set :ts:cv:`proxy.config.cluster.ethernet_interface` to
+"br0" (the name of the bridge interface from the Bridge Commands).
+
+Additional troubleshooting
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Check to make sure that ``iptables`` is not filtering (blocking)
+ incoming HTTP connections.
+
+ It is frequently the case that the default tables prevent incoming HTTP. You can clear all filters with the
+ commands::
+
+ iptables -t filter --flush FORWARD
+ iptables -t filter --flush INPUT
+
+ That is a bit drastic and should only be used for testing / debugging. A
+ live system will likely need some filters in place but that is beyond
+ the scope of this document. If this fixes the problem, then your filter
+ set is too restrictive.
+
+ Note that this problem will prevent the basic bridge (without ATS) from
+ allowing HTTP traffic through.
+
+* Verify that IP packet forwarding is enabled.
+
+ You can check this with::
+
+ cat /proc/sys/net/ipv4/ip_forward
+
+ The output should be a non-zero value (usually '1'). If it is zero, you
+ can set it with::
+
+ echo '1' > /proc/sys/net/ipv4/ip_forward
+
+ This can setting can be persisted by putting it in ``/etc/sysctl.conf``: ::
+
+ net/ipv4/ip_forward=1
+
+.. rubric:: Footnotes
+
+.. [1]
+ The ``--redirect-target`` can be omitted, but then the ``iptables``
+ rules would need to use ``--physdev`` instead of just ``-i``. The
+ actual packet processing is identical.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/configuration/transparent-proxy/build.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/transparent-proxy/build.en.rst b/doc/admin-guide/configuration/transparent-proxy/build.en.rst
new file mode 100644
index 0000000..e547a06
--- /dev/null
+++ b/doc/admin-guide/configuration/transparent-proxy/build.en.rst
@@ -0,0 +1,60 @@
+.. _building-ats-for-transparency:
+
+Building ATS for transparency
+*****************************
+
+.. 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.
+
+
+In most cases, if your environment supports transparency then
+``configure`` will automatically enable it. For other environments you
+may need to twiddle the ``configure`` options.
+
+``--enable-posix-cap``
+ This enables POSIX capabilities, which are required for
+ transparency. These are compiled in by default. To check your
+ system, look for the header file ``sys/capability.h`` and the system
+ library ``libcap``. These are in the packages ``libcap`` and
+ ``libcap-devel`` or ``libcap-dev`` (depending on the Distribution)
+ contra-respectively.
+
+``--enable-tproxy[=value]``
+ Enable TPROXY support, which is the Linux kernel feature used for
+ transparency. This should be present in the base installation, there
+ is no package associated with it. \* ``auto`` Do automatic checks
+ for the the TPROXY header file (``linux/in.h``) and enable TPROXY
+ support if the ``IP_TRANSPARENT`` definition is present. This is the
+ default if this option is not specified or ``value`` is omitted. \*
+ ``no`` Do not check for TPROXY support, disable support for it. \*
+ ``force`` Do not check for TPROXY support, enable it using the $ats@
+ built in value for ``IP_TRANSPARENT``. This is useful for systems
+ that have it in the kernel for but some reason do not have the
+ appropriate system header file. \* *number* Do not check for TPROXY
+ support, use *number* as the ``IP_TRANSPARENT`` value. There are, at
+ present, no known standard distributions of Linux that support
+ TPROXY but use a value different from the built in ATS default.
+ However, a custom built kernel may do so and in that case the
+ specific value can be specified.
+
+In the default case, ATS configuration will automatically check for
+TPROXY support via the presence of the ``linux/in.h`` header file and
+compile in TPROXY support if it is available. If that fails, you may be
+able to recover by using one of the options above. Note that
+transparency may be built in by default but it is not active unless
+explicitly enabled in the ATS configuration files.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/configuration/transparent-proxy/router-inline.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/transparent-proxy/router-inline.en.rst b/doc/admin-guide/configuration/transparent-proxy/router-inline.en.rst
new file mode 100644
index 0000000..0e9060a
--- /dev/null
+++ b/doc/admin-guide/configuration/transparent-proxy/router-inline.en.rst
@@ -0,0 +1,87 @@
+Inline on a Linux router
+************************
+
+.. 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 routed set up presumes the set of clients are on distinct networks
+behind a single physical interface. For the purposes of this example
+will we presume
+
+- The clients are on network 172.28.56.0/24
+- The router connects the networks 172.28.56.0/24 and 192.168.1.0/24
+- Interface ``eth0`` is on the network 192.168.1.0/24
+- Interface ``eth1`` is on the network 172.28.56.0/24
+- The router is already configured to route traffic correctly for the
+ clients.
+
+In this example we will intercept port 80 (HTTP) traffic that traverses
+the router. The first step is to use ``iptables`` to handle IP packets
+appropriately.
+
+::
+
+ # reflow client web traffic to TPROXY
+ iptables -t mangle -A PREROUTING -i eth1 -p tcp -m tcp --dport 80 -j TPROXY \
+ --on-ip 0.0.0.0 --on-port 8080 --tproxy-mark 1/1
+ # Let locally directed traffic pass through.
+ iptables -t mangle -A PREROUTING -i eth0 --source 192.168.1.0/24 -j ACCEPT
+ iptables -t mangle -A PREROUTING -i eth0 --destination 192.168.1.0/24 -j ACCEPT
+ # Mark presumed return web traffic
+ iptables -t mangle -A PREROUTING -i eth0 -p tcp -m tcp --sport 80 -j MARK --set-mark 1/1
+
+We mark packets so that we can use policy routing on them. For inbound
+packets we use ``TPROXY`` to make it possible to accept packets sent to
+foreign IP addresses. For returning outbound packets there will be a
+socket open bound to the foreign address, we need only force it to be
+delivered locally. The value for ``--on-ip`` is 0 because the target
+port is listening and not bound to a specific address. The value for
+``--on-port`` must match the Traffic Server server port. Otherwise its
+value is arbitrary. ``--dport`` and ``--sport`` specify the port from
+the point of view of the clients and origin servers. The middle two
+lines exempt local web traffic from being marked for Traffic Server --
+these rules can be tightened or loosened as needed. They server by
+matching traffic and exiting the ``iptables`` processing via ``ACCEPT``
+before the last line is checked.
+
+Once the flows are marked we can force them to be delivered locally via
+the loopback interface via a policy routing table.
+
+::
+
+ ip rule add fwmark 1/1 table 1
+ ip route add local 0.0.0.0/0 dev lo table 1
+
+The marking used is arbitrary but it must be consistent between
+``iptables`` and the routing rule. The table number must be in the range
+1..253.
+
+To configure Traffic Server set the following values in
+:file:`records.config`
+
+``proxy.config.http.server_ports``
+ ``STRING``
+ Default: *value from* ``--on-port``
+
+``proxy.config.reverse_proxy.enabled``
+ ``INT``
+ Default: ``1``
+
+``proxy.config.url_remap.remap_required``
+ ``INT``
+ Default: ``0``
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/configuration/transparent-proxy/wccp-configuration.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/transparent-proxy/wccp-configuration.en.rst b/doc/admin-guide/configuration/transparent-proxy/wccp-configuration.en.rst
new file mode 100644
index 0000000..99da91c
--- /dev/null
+++ b/doc/admin-guide/configuration/transparent-proxy/wccp-configuration.en.rst
@@ -0,0 +1,156 @@
+WCCP Configuration
+******************
+
+.. 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.
+
+.. _wccp-configuration:
+
+.. toctree::
+ :maxdepth: 2
+
+`WCCP <http://cio.cisco.com/en/US/docs/ios/12_0t/12_0t3/feature/guide/wccp.html>`_
+is de-facto semi-standard used by routers to redirect network traffic to
+caches. It is available on most Cisco™ routers although it does not
+appear to be officially supported by Cisco. The primary benefits of WCCP
+are
+
+- If already have a router that supports WCCP inline you do not
+ have to change your network topology.
+- WCCP fails open so that if the Traffic Server machine fails, it is
+ bypassed and users continue to have Internet access.
+
+Use of WCCP only makes sense for client side transparency [1]_
+because if the clients are explicitly proxied by Traffic Server there's
+no benefit to WCCP fail open, as the clients will continue to directly
+access the unresponsive Traffic Server host. It would be better to
+adjust the routing tables on the router for explicit proxying.
+
+Because the router serves as the inline network element, Traffic Server
+must run on a separate host. This host can be located anywhere as long
+as Traffic Server is either on the same network segment or a GRE tunnel
+can be maintained between the Traffic Server host and the router.
+
+|important| This document presumes that the router is already properly
+configured to handle traffic between the clients and the origin servers.
+If you are not certain, verify it before attempting to configure Traffic
+Server with WCCP. This is also a good state to which to revert should
+the configuration go badly.
+
+Configuration overview
+======================
+
+Setting WCCP is a three step process, first configuring the router, the
+Traffic Server host, and Traffic Server.
+
+|image1| The router will **not** respond to WCCP protocol packets unless
+explicitly configured to do so. Via WCCP, the router can be made to
+perform packet interception and redirection needed by Traffic Server
+transparency. The WCCP protocol in effect acts as means of controlling a
+rough form of policy routing with positive heartbeat cutoff.
+
+The Traffic Server host system must also be configured using
+``iptables`` to accept connections on foreign addresses. This is done
+roughly the same way as the standard transparency use.
+
+Finally Traffic Server itself must be configured for transparency and
+use of WCCP. The former is again very similar to the standard use, while
+WCCP configuration is specific to WCCP and uses a separate configuration
+file, referred to by the :file:`records.config` file.
+
+The primary concern for configuration in which of three basic topologies
+are to be used.
+
+- Dedicated -- Traffic Server traffic goes over an interface that is
+ not used for client nor origin server traffic.
+- Shared -- Traffic Server traffic shares an interface with client or
+ server traffic.
+- Inside Shared -- Traffic Server and client traffic share an
+ interface.
+- Outside Shared -- Traffic Server and
+ origin server traffic share an interface.
+
+In general the dedicated topology is preferred. However, if the router
+has only two interfaces one of the shared topologies will be
+required [2]_ Click the links above for more detailed configuration
+information on a specific topology.
+
+Shared interface issues
+-----------------------
+
+A shared interface topology has additional issues compared to a
+dedicated topology that must be handled. Such a topology is required if
+the router has only two interfaces, and because of these additional
+issues it is normally only used in such cases, although nothing prevents
+it use even if the router has three or more interfaces.
+
+The basic concept for a shared interface is to use a tunnel to simulate
+the dedicated interface case. This enables the packets to be
+distinguished at layer 3. For this reason, layer 2 redirection cannot be
+used because the WCCP configuration cannot distinguish between packets
+returning from the origin server and packets returning from Traffic
+Server as they are distinguished only by layer 2 addressing [3]_.
+Fortunately the GRE tunnel used for packet forwarding and return can be
+used as the simulated interface for Traffic Server.
+
+Frequently encountered problems
+-------------------------------
+
+MTU and fragmentation
+~~~~~~~~~~~~~~~~~~~~~
+
+In most cases the basic configuration using a tunnel in any topology can
+fail due to issues with fragmentation. The socket logic is unable to
+know that its packets will eventually be put in to a tunnel which will
+by its nature have a smaller
+`MTU <http://en.wikipedia.org/wiki/Maximum_transmission_unit>`_ than the
+physical interface which it uses. This can lead to pathological behavior
+or outright failure as the packets sent are just a little too big. It is
+not possible to solve easily by changing the MTU on the physical
+interface because the tunnel interface uses that to compute its own MTU.
+
+References
+==========
+
+- `WCCP Router Configuration Commands - IOS
+ 12.2 <http://www.cisco.com/en/US/docs/ios/12_2/configfun/command/reference/frf018.html>`_
+
+
+
+
+
+
+
+
+.. [1]
+ Server side transparency should also be used, but it is not as
+ significant. In its absence, however, origin servers may see the
+ source address of connections suddenly change from the Traffic Server
+ address to client addresses, which could cause problems. Further, the
+ primary reason for not having server side transparency is to hide
+ client addresses which is defeated if the Traffic Server host fails.
+
+.. [2]
+ If your router has only one interface, it's hardly a *router*.
+
+.. [3]
+ This is not fundamentally impossible, as the packets are distinct in
+ layer
+
+.. |important| image:: ../../../static/images/docbook/important.png
+.. |image1| image:: ../../../static/images/docbook/important.png
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/configuration/transparent-proxy/wccp-service-config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/configuration/transparent-proxy/wccp-service-config.en.rst b/doc/admin-guide/configuration/transparent-proxy/wccp-service-config.en.rst
new file mode 100644
index 0000000..eb7d44c
--- /dev/null
+++ b/doc/admin-guide/configuration/transparent-proxy/wccp-service-config.en.rst
@@ -0,0 +1,84 @@
+.. 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-wccp-service-config:
+
+WCCP Service Configuration
+**************************
+
+The service definition file is used by :program:`traffic_wccp` and
+:program:`traffic_server` directly.
+
+The elements in the security definition file are inspired by the
+`WCCP RFC (8/2012) <http://tools.ietf.org/html/draft-mclaggan-wccp-v2rev1-00>`_.
+There is also an older version of the RFC that shows up commonly in search results,
+`WCCP (4/2001) <https://tools.ietf.org/id/draft-wilson-wrec-wccp-v2-01.txt>`_,
+and was the RFC reference used in the original WCCP support for |TS| several
+years ago.
+
+A sample service group file is included in the source tree under
+:program:`traffic_wccp`.
+
+Security Section
+================
+
+In the security section, you can define a password shared between the WCCP Client and the WCCP router. This password is used to encrypt the WCCP traffic. It is optional, but highly recommended.
+
+Attributes in this section
+
+* option - Must be set to MD5 if you want to encrypt your WCCP traffic
+
+* key – The same password that you set with the associated WCCP router.
+
+Services Section
+================
+
+In the services section you can define a list of service groups. Each top level entry is a separate service group.
+
+Service group attributes include
+
+* name – A name for the service. Not used in the rest of the WCCP processing.
+
+* description – A description of the service. Again, not used in the rest of the WCCP processing.
+
+* id - The security group ID. It must match the service group ID that has been defined on the associated WCCP router. This is the true service group identifier from the WCCP perspective.
+
+* type – This defines the type of service group either “STANDARD” or “DYNAMIC”. There is one standard defined service group, HTTP with the id of 0. The 4/2001 RFC indicates that id’s 0-50 are reserved for well known service groups. But more recent 8/2012 RFC indicates that values 0 through 254 are valid service id’s for dynamic services. To avoid differences with older WCCP routers, you probably want to avoid dynamic service ID’s 0 through 50.
+
+* priority – This is a value from 0 to 255. The higher number is a higher priority. Well known (STANDARD) services are set to a value of 240. If there are multiple service groups that could match a given packet, the higher priority service group is applied. RFC For example, you have service group 100 defined for packets with destination port 80, and service group 101 defined for packets with source port 1024. For a packet with destination port set to 80 and source port set to 1024, the priorities of the service groups would need to be compared to determine which service group applies.
+
+* protocol – This is IP protocol number that should match. Generally this is set to 6 (TCP) or 17 (UDP).
+
+* assignment – WCCP supports multiple WCCP clients supporting a single service group. However, the current WCCP client implementation in Traffic Server assumes there is only a single WCCP client, and so creates assignment tables that will direct all traffic to that WCCP client. The assignment type is either hash or mask, and if it is not set, it defaults to hash. If Traffic Server ever supports more than one cache, it will likely only support a balanced hash assignment. The mask/value assignment seems to be better suited to situations where the traffic needs to be more strongly controlled.
+
+* primary-hash – This is the element of the packet that is used to compute the primary key. The value options are src_ip, dst_ip, src_port, or dst_port. This entry is a list, so multiple values can be specified. In that case, all the specified packet attributes will be used to compute the hash bucket. In the current implementation, the primary hash value does not matter, since the client always generates a hash table that directs all matching traffic to it. But if multiple clients are ever supported, knowledge of the local traffic distribution could be used to pick a packet attribute that will better spread traffic over the WCCP clients.
+* alt-hash – The protocol supports a two level hash. This attribute is a list with the same value options as for primary-hash. Again, since the current Traffic Server implementation only creates assignment tables to a single client, specifying the alt-hash values does nothing.
+
+* ports – This is a list of port values. Up to 8 port values may be included in a service group definition.
+
+* port-type – This attribute can have the value of src or dst. If not specified, it defaults to dst. It indicates whether the port values should be interpreted as source ports or destination ports.
+
+* forward – This is a list. The list of the values can be GRE or L2. This advertises how the client wants to process WCCP packets. GRE means that the packets will be delivered in a GRE tunnel. This is the default. L2 means that the client is on the same network and can get traffic delivered to it from the router by L2 routing (MAC addresses).
+
+* return – The WCCP protocol allows a WCCP client to decline a packet and return it back to the router. The current WCCP client implementation never does this. The value options are the same as for the forward attribute.
+
+* routers – This is the list of router addresses the WCCP client communicates with. The WCCP protocols allows for multiple WCCP routers to be involved in a service group. The multiple router scenario has at most been lightly tested in the Traffic Server implementation.
+
+* proc-name – This attribute is only used by traffic_wccp. It is not used in the traffic_server WCCP support. This is the path to a process’ PID file. The service group is advertised to the WCCP router if the process identified in the PID file is currently operational.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/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
index 659030d..e712d7a 100644
--- a/doc/admin-guide/files/log_hosts.config.en.rst
+++ b/doc/admin-guide/files/log_hosts.config.en.rst
@@ -1,33 +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
-
+ 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
-================
+
+ 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
.. 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
+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.
+
+You should use the same :file:`log_hosts.config` file on every |TS| 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, |TS| automatically applies the
changes to all other nodes in the cluster.
Format
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/files/records.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst
index 40a2d20..86e156d 100644
--- a/doc/admin-guide/files/records.config.en.rst
+++ b/doc/admin-guide/files/records.config.en.rst
@@ -15,12 +15,13 @@
specific language governing permissions and limitations
under the License.
-==============
-records.config
-==============
+.. include:: ../../common.defs
.. configfile:: records.config
+records.config
+**************
+
The :file:`records.config` file (by default, located in
``/usr/local/etc/trafficserver/``) is a list of configurable variables used by
the Traffic Server software. Many of the variables in the
@@ -45,7 +46,7 @@ the cluster) or ``LOCAL`` (only the local machine)
``DATATYPE`` is one of ``INT`` (integer), ``STRING`` (string), ``FLOAT``
(floating point).
-:
+
A variable marked as ``Deprecated`` is still functional but should be avoided
as it may be removed in a future release without warning.
@@ -179,7 +180,9 @@ System Variables
.. ts:cv:: CONFIG proxy.config.syslog_facility STRING LOG_DAEMON
- The facility used to record system log files. Refer to :ref:`understanding-traffic-server-log-files`.
+ The facility used to record system log files. Refer to
+ :ref:`admin-monitoring-logging-understanding` for more in-depth discussion
+ of the contents and interpretations of log files.
.. ts:cv:: CONFIG proxy.config.cop.core_signal INT 0
@@ -469,21 +472,25 @@ Local Manager
.. ts:cv:: CONFIG proxy.config.admin.user_id STRING nobody
- Option used to specify who to run the :program:`traffic_server` process as; also used to specify ownership of config and log files.
+ Designates the non-privileged account to run the :program:`traffic_server`
+ process as, which also has the effect of setting ownership of configuration
+ and log files.
-The nonprivileged user account designated to Traffic Server.
+ As of version 2.1.1 if the user_id is prefixed with pound character (``#``)
+ the remainder of the string is considered to be a
+ `numeric user identifier <http://en.wikipedia.org/wiki/User_identifier>`_.
+ If the value is set to ``#-1`` |TS| will not change the user during startup.
-As of version 2.1.1 if the user_id is prefixed with pound character (#) the remaining of the string is considered to be
-a `numeric user identifier <http://en.wikipedia.org/wiki/User_identifier>`_. If the value is set to ``#-1`` Traffic
-Server will not change the user during startup.
+ .. important::
+
+ Attempting to set this option to ``root`` or ``#0`` is now forbidden, as
+ a measure to increase security. Doing so will cause a fatal failure upon
+ startup in :program:`traffic_server`. However, there are two ways to
+ bypass this restriction:
-Setting ``user_id`` to ``root`` or ``#0`` is now forbidden to
-increase security. Trying to do so, will cause the
-:program:`traffic_server` fatal failure. However there are two ways to
-bypass that restriction
+ * Specify ``-DBIG_SECURITY_HOLE`` in ``CXXFLAGS`` during compilation.
-* Specify ``-DBIG_SECURITY_HOLE`` in ``CXXFLAGS`` during compilation.
-* Set the ``user_id=#-1`` and start trafficserver as root.
+ * Set the ``user_id=#-1`` and start trafficserver as root.
.. ts:cv:: CONFIG proxy.config.admin.api.restricted INT 0
@@ -761,76 +768,116 @@ Value Effect
:reloadable:
:overridable:
- Specifies whether Traffic Sever can generate a chunked response:
+ Specifies whether |TS| can generate a chunked response:
- - ``0`` Never
- - ``1`` Always
- - ``2`` Generate a chunked response if the server has returned HTTP/1.1 before
- - ``3`` = Generate a chunked response if the client request is HTTP/1.1 and the origin server has returned HTTP/1.1 before
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Never respond with chunked encoding.
+ ``1`` Always respond with chunked encoding.
+ ``2`` Generate a chunked response if the origin server has previously
+ returned HTTP/1.1.
+ ``3`` Generate a chunked response if the client request is HTTP/1.1 and the
+ origin server has previously returned HTTP/1.1.
+ ===== ======================================================================
.. note::
- If HTTP/1.1 is used, then Traffic Server can use
- keep-alive connections with pipelining to origin servers. If
- HTTP/0.9 is used, then Traffic Server does not use ``keep-alive``
- connections to origin servers. If HTTP/1.0 is used, then Traffic
- Server can use ``keep-alive`` connections without pipelining to
- origin servers.
+ If HTTP/1.1 is used, then |TS| can use keep-alive connections with
+ pipelining to origin servers.
+
+ If HTTP/1.0 is used, then |TS| can use keep-alive connections without
+ pipelining to origin servers.
+
+ If HTTP/0.9 is used, then |TS| does not use keep-alive connections to
+ origin servers.
+
+.. ts:cv:: CONFIG proxy.config.http.chunking.size INT 4096
+ :overridable:
+
+ If chunked transfer encoding is enabled with :ts:cv:`proxy.config.http.chunking_enabled`,
+ and the conditions specified by that option's setting are met by the current
+ request, this option determines the size of the chunks, in bytes, to use
+ when sending content to an HTTP/1.1 client.
.. ts:cv:: CONFIG proxy.config.http.send_http11_requests INT 1
:reloadable:
:overridable:
- Specifies when and how Traffic Sever uses HTTP/1.1 to communicate with the origin server
+ Specifies when and how |TS| uses HTTP/1.1 to communicate with the origin
+ server.
- - ``0`` Never
- - ``1`` Always
- - ``2`` If the server has returned HTTP/1.1 before
- - ``3`` If the client request is HTTP/1.1 and the server has returned HTTP/1.1 before
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Never use HTTP/1.1.
+ ``1`` Always use HTTP/1.1.
+ ``2`` Use HTTP/1.1 with origin connections only if the server has previously
+ eturned HTTP/1.1.
+ ``3`` If the client request is HTTP/1.1 and the origin server has previously
+ returned HTTP/1.1, then use HTTP/1.1 for origin server connections.
+ ===== ======================================================================
.. note::
- If :ts:cv:`proxy.config.http.use_client_target_addr` is set to 1, options 2 and 3 cause the proxy to use
- the client HTTP version for upstream requests.
-
-.. ts:cv:: CONFIG proxy.config.http.auth_server_session_private INT 1
-
- If enabled (``1``) anytime a request contains a (``Authorization``), (``Proxy-Authorization``)
- or (``Www-Authenticate``) header the connection will be closed and not reused. This marks
- the connection as private. When disabled (``0``) the connection will be available for reuse.
+ If :ts:cv:`proxy.config.http.use_client_target_addr` is set to ``1``, then
+ options ``2`` and ``3`` for this configuration variable cause the proxy
+ to use the client HTTP version for upstream requests.
-.. ts:cv:: CONFIG proxy.config.http.server_session_sharing.match STRING both
+.. ts:cv:: CONFIG proxy.config.http.server_tcp_init_cwnd INT 0
+ :overridable:
- Enable and set the ability to re-use server connections across client connections. The valid values are
+ Configures the size, in packets, of the initial TCP congestion window on
+ sockets used by the HTTP engine. This option may only be used on operating
+ systems which support the ``TCP_INIT_CWND`` option on TCP sockets.
- none
- Do not match, do not re-use server sessions.
+.. ts:cv:: CONFIG proxy.config.http.auth_server_session_private INT 1
- ip
- Re-use server sessions, check only that the IP address and port of the origin server matches.
+ If enabled (``1``) anytime a request contains a ``Authorization``,
+ ``Proxy-Authorization``, or ``Www-Authenticate`` header the connection will
+ be closed and not reused. This marks the connection as private. When disabled
+ (``0``) the connection will be available for reuse.
- host
- Re-use server sessions, check only that the fully qualified domain name matches.
+.. ts:cv:: CONFIG proxy.config.http.server_session_sharing.match STRING both
- both
- Re-use server sessions, but only if the IP address and fully qualified domain name match.
+ Enable and set the ability to re-use server connections across client
+ connections. The valid values are:
+
+ ======== ===================================================================
+ Value Description
+ ======== ===================================================================
+ ``none`` Do not match and do not re-use server sessions.
+ ``ip`` Re-use server sessions, checking only that the IP address and port
+ of the origin server matches.
+ ``host`` Re-use server sessions, checking only that the fully qualified
+ domain name matches.
+ ``both`` Re-use server sessions, if *both* the IP address and fully qualified
+ domain name match.
+ ======== ===================================================================
+
+ It is strongly recommended to use either ``none`` or ``both`` for this value
+ unless you have a specific need for the other settings. The most common
+ reason is virtual hosts that share an IP address in which case performance
+ can be enhanced if those sessions can be re-used. However, not all web
+ servers support requests for different virtual hosts on the same connection
+ so use with caution.
- It is strongly recommended to use either *none* or *both* for this value unless you have a specific need to use *ip*
- or *host*. The most common reason is virtual hosts that share an IP address in which case performance can be enhanced
- if those sessions can be re-used. However, not all web servers support requests for different virtual hosts on the
- same connection so use with caution.
+ .. note::
- .. note: Server sessions to different ports never match even if the FQDN and IP address match.
+ Server sessions to different ports never match even if the FQDN and IP
+ address match.
.. ts:cv:: CONFIG proxy.config.http.server_session_sharing.pool STRING thread
- Control the scope of server session re-use if it is enabled by :ts:cv:`proxy.config.http.server_session_sharing.match`. The valid values are
-
- global
- Re-use sessions from a global pool of all server sessions.
+ Control the scope of server session re-use if it is enabled by
+ :ts:cv:`proxy.config.http.server_session_sharing.match`. Valid values are:
- thread
- Re-use sessions from a per-thread pool.
+ ========== =================================================================
+ Value Description
+ ========== =================================================================
+ ``global`` Re-use sessions from a global pool of all server sessions.
+ ``thread`` Re-use sessions from a per-thread pool.
+ ========== =================================================================
.. ts:cv:: CONFIG proxy.config.http.attach_server_session_to_client INT 0
@@ -860,64 +907,65 @@ Value Effect
For fully transparent ports use the same origin server address as the client.
-This option causes Traffic Server to avoid where possible doing DNS
-lookups in forward transparent proxy mode. The option is only
-effective if the following three conditions are true -
-
-* Traffic Server is in forward proxy mode.
-* The proxy port is inbound transparent.
-* The target URL has not been modified by either remapping or a plugin.
-
-If any of these conditions are not true, then normal DNS processing
-is done for the connection.
-
-There are three valid values.
-* 0 - Disables the feature.
-* 1 - Enables the feature with address verification. The Proxy does the
-regular DNS processing. If the client-specified origin address is not in the
-set of addresses found by the Proxy, the request continues to the client
-specified address, but the result is not cached.
-* 2 - Enables the feature with no address verification. No DNS processing
-is performed. The result is cached (if allowed otherwise). This option is
-vulnerable to cache poisoning if an incorrect Host header is specified, so
-this option should be used with extreme caution. See bug TS-2954 for
-details.
-
-If all of these conditions are met, then the origin server IP
-address is retrieved from the original client connection, rather
-than through HostDB or DNS lookup. In effect, client DNS resolution
-is used instead of Traffic Server DNS.
-
-This can be used to be a little more efficient (looking up the
-target once by the client rather than by both the client and Traffic
-Server) but the primary use is when client DNS resolution can differ
-from that of Traffic Server. Two known uses cases are:
-
-#. Embedded IP addresses in a protocol with DNS load sharing. In
- this case, even though Traffic Server and the client both make
- the same request to the same DNS resolver chain, they may get
- different origin server addresses. If the address is embedded in
- the protocol then the overall exchange will fail. One current
- example is Microsoft Windows update, which presumably embeds the
- address as a security measure.
-
-#. The client has access to local DNS zone information which is not
- available to Traffic Server. There are corporate nets with local
- DNS information for internal servers which, by design, is not
- propagated outside the core corporate network. Depending a
- network topology it can be the case that Traffic Server can
- access the servers by IP address but cannot resolve such
- addresses by name. In such as case the client supplied target
- address must be used.
-
-This solution must be considered interim. In the longer term, it
-should be possible to arrange for much finer grained control of DNS
-lookup so that wildcard domain can be set to use Traffic Server or
-client resolution. In both known use cases, marking specific domains
-as client determined (rather than a single global switch) would
-suffice. It is possible to do this crudely with this flag by
-enabling it and then use identity URL mappings to re-disable it for
-specific domains.
+ This option causes |TS| to avoid where possible doing DNS lookups in forward
+ transparent proxy mode. The option is only effective if the following three
+ conditions are true:
+
+ * |TS| is in forward proxy mode.
+ * The proxy port is inbound transparent.
+ * The target URL has not been modified by either remapping or a plugin.
+
+ If any of these conditions are not true, then normal DNS processing is done
+ for the connection.
+
+ There are three valid values.
+
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Disables the feature.
+ ``1`` Enables the feature with address verification. The proxy does the
+ regular DNS processing. If the client-specified origin address is not
+ in the set of addresses found by the proxy, the request continues to
+ the client specified address, but the result is not cached.
+ ``2`` Enables the feature with no address verification. No DNS processing is
+ performed. The result is cached (if allowed otherwise). This option is
+ vulnerable to cache poisoning if an incorrect ``Host`` header is
+ specified, so this option should be used with extreme caution. See
+ bug TS-2954 for details.
+ ===== ======================================================================
+
+ If all of these conditions are met, then the origin server IP address is
+ retrieved from the original client connection, rather than through HostDB or
+ DNS lookup. In effect, client DNS resolution is used instead of |TS| DNS.
+
+ This can be used to be a little more efficient (looking up the target once
+ by the client rather than by both the client and |TS|) but the primary use
+ is when client DNS resolution can differ from that of |TS|. Two known uses
+ cases are:
+
+ #. Embedded IP addresses in a protocol with DNS load sharing. In this case,
+ even though |TS| and the client both make the same request to the same
+ DNS resolver chain, they may get different origin server addresses. If
+ the address is embedded in the protocol then the overall exchange will
+ fail. One current example is Microsoft Windows update, which presumably
+ embeds the address as a security measure.
+
+ #. The client has access to local DNS zone information which is not
+ available to |TS|. There are corporate nets with local DNS information
+ for internal servers which, by design, is not propagated outside the core
+ corporate network. Depending a network topology it can be the case that
+ |TS| can access the servers by IP address but cannot resolve such
+ addresses by name. In such as case the client supplied target address
+ must be used.
+
+ This solution must be considered interim. In the longer term, it should be
+ possible to arrange for much finer grained control of DNS lookup so that
+ wildcard domain can be set to use |TS| or client resolution. In both known
+ use cases, marking specific domains as client determined (rather than a
+ single global switch) would suffice. It is possible to do this crudely with
+ this flag by enabling it and then use identity URL mappings to re-disable it
+ for specific domains.
.. ts:cv:: CONFIG proxy.config.http.keep_alive_enabled_in INT 1
:overridable:
@@ -940,6 +988,13 @@ specific domains.
Controls wether new POST requests re-use keep-alive sessions (``1``) or
create new connections per request (``0``).
+.. ts:cv:: CONFIG proxy.config.http.accept_encoding_filter_enabled INT 0
+
+ Enables (``1``) or disables (``0``) additional handling of ``Accept-encoding``
+ header on incoming requests based on the ``User-Agent`` header, to account
+ for known deficiencies in legacy browsers which mis-report the encodings
+ they are able to accept.
+
.. ts:cv:: CONFIG proxy.config.http.disallow_post_100_continue INT 0
Allows you to return a 405 Method Not Supported with Posts also
@@ -948,6 +1003,31 @@ specific domains.
When a Post w/ Expect: 100-continue is blocked the stat
proxy.process.http.disallowed_post_100_continue will be incremented.
+.. ts:cv:: CONFIG proxy.config.http.default_buffer_size INT 8
+
+ Configures the default buffer size, in bytes, to allocate for incoming
+ request bodies which lack a ``Content-length`` header.
+
+.. ts:cv:: CONFIG proxy.config.http.default_buffer_water_mark INT 32768
+
+.. ts:cv:: CONFIG proxy.config.http.request_header_max_size INT 131072
+
+ Controls the maximum size, in bytes, of an HTTP header in requests. Headers
+ in a request which exceed this size will cause the entire request to be
+ treated as invalid and rejected by the proxy.
+
+.. ts:cv:: CONFIG proxy.config.http.response_header_max_size INT 131072
+
+ Controls the maximum size, in bytes, of headers in HTTP responses from the
+ proxy. Any responses with a header exceeding this limit will be treated as
+ invalid and a client error will be returned instead.
+
+.. ts:cv:: CONFIG proxy.config.http.global_user_agent_header STRING null
+ :overridable:
+
+ An arbitrary string value that, if set, will be used to replace any request
+ ``User-Agent`` header.
+
Parent Proxy Configuration
==========================
@@ -1233,6 +1313,17 @@ Negative Response Caching
How long (in seconds) Traffic Server keeps the negative responses valid in cache. This value only affects negative
responses that do NOT have explicit ``Expires:`` or ``Cache-Control:`` lifetimes set by the server.
+.. ts:cv:: CONFIG proxy.config.http.negative_revalidating_enabled INT 0
+
+ Enables (``1``) or disables (``0``) forcing revalidation of cached documents
+ when |TS| receives a negative (``5xx`` only) response from the origin server.
+
+.. ts:cv:: CONFIG proxy.config.http.negative_revalidating_lifetime INT 1800
+
+ How long, in seconds, to consider a stale cached document valid if during the
+ revalidation attempt |TS| receives a negative (``5xx`` only) response from
+ the origin server.
+
Proxy User Variables
====================
@@ -1328,9 +1419,14 @@ Cache Control
here is to avoid multiple origin connections for the same cacheable object
upon a cache miss. The possible values of this config are:
- - ``0`` = never read while writing
- - ``1`` = always read while writing
- - ``2`` = always read while writing, but allow non-cached Range requests through to the origin
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Never read while writing.
+ ``1`` Always read while writing.
+ ``2`` Always read while writing, but allow non-cached ``Range`` requests
+ through to the origin server.
+ ===== ======================================================================
The ``2`` option is useful to avoid delaying requests which can not easily
be satisfied by the partially written response.
@@ -1405,6 +1501,12 @@ Cache Control
with a ``Location`` header but no document body. This only works if the
origin response also has a ``Content-Length`` header.
+.. ts:cv:: CONFIG proxy.config.http.doc_in_cache_skip_dns INT 1
+
+ Do not perform origin server DNS resolution if a fresh copy of the requested
+ document is available in the cache. This setting has no effect if HTTP
+ caching is disabled or if there are IP based ACLs configured.
+
.. ts:cv:: CONFIG proxy.config.http.cache.ignore_client_no_cache INT 1
:reloadable:
:overridable:
@@ -1429,11 +1531,16 @@ Cache Control
Specifies how cookies are cached:
- - ``0`` = do not cache any responses to cookies
- - ``1`` = cache for any content-type
- - ``2`` = cache only for image types
- - ``3`` = cache for all but text content-types
- - ``4`` = cache for all but text content-types except OS response without "Set-Cookie" or with "Cache-Control: public"
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Do not cache any responses to cookies.
+ ``1`` Cache for any content-type.
+ ``2`` Cache only for image types.
+ ``3`` Cache for all but text content-types.
+ ``4`` Cache for all but text content-types; except origin server response
+ without ``Set-Cookie`` or with ``Cache-Control: public``.
+ ===== ======================================================================
.. ts:cv:: CONFIG proxy.config.http.cache.ignore_authentication INT 0
:overridable:
@@ -1460,16 +1567,20 @@ Cache Control
Specifies when to revalidate content:
- - ``0`` = use cache directives or heuristic (the default value)
- - ``1`` = stale if heuristic
- - ``2`` = always stale (always revalidate)
- - ``3`` = never stale
- - ``4`` = use cache directives or heuristic (0) unless the request
- has an ``If-Modified-Since`` header
-
- If the request contains the ``If-Modified-Since`` header, then
- Traffic Server always revalidates the cached content and uses the
- client's ``If-Modified-Since`` header for the proxy request.
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Use cache directives or heuristic (the default value).
+ ``1`` Stale if heuristic.
+ ``2`` Always stale (always revalidate).
+ ``3`` Never stale.
+ ``4`` Use cache directives or heuristic (0) unless the request has an
+ ``If-Modified-Since`` header.
+ ===== ======================================================================
+
+ If the request contains the ``If-Modified-Since`` header, then |TS| always
+ revalidates the cached content and uses the client's ``If-Modified-Since``
+ header for the proxy request.
.. ts:cv:: CONFIG proxy.config.http.cache.required_headers INT 2
:reloadable:
@@ -1576,6 +1687,12 @@ Cache Control
Specifies the maximum object size that will be cached. ``0`` is unlimited.
+.. ts:cv:: CONFIG proxy.config.cache.min_average_object_size INT 8000
+
+ Specifies the lower boundary of average object sizes in the cache and is
+ used in determining the number of :term:`directory buckets <directory bucket>`
+ to allocate for the in-memory cache directory.
+
.. ts:cv:: CONFIG proxy.config.cache.permit.pinning INT 0
:reloadable:
@@ -1611,6 +1728,13 @@ Cache Control
When setting this, consider that larger numbers could waste memory on slow
connections, but smaller numbers could increase (waste) seeks.
+.. ts:cv:: CONFIG proxy.config.cache.alt_rewrite_max_size INT 4096
+
+ Configures the size, in bytes, of an alternate that will be considered
+ small enough to trigger a rewrite of the resident alt fragment within a
+ write vector. For further details on cache write vectors, refer to the
+ developer documentation for :cpp:class:`CacheVC`.
+
RAM Cache
=========
@@ -1668,41 +1792,69 @@ Heuristic Expiration
:reloadable:
:overridable:
- The minimum amount of time an HTTP object without an expiration date can remain fresh in the cache before is
- considered to be stale.
+ The minimum amount of time, in seconds, an HTTP object without an expiration
+ date can remain fresh in the cache before is considered to be stale.
.. ts:cv:: CONFIG proxy.config.http.cache.heuristic_max_lifetime INT 86400
:reloadable:
:overridable:
- The maximum amount of time an HTTP object without an expiration date can remain fresh in the cache before is
- considered to be stale.
+ The maximum amount of time, in seconds, an HTTP object without an expiration
+ date can remain fresh in the cache before is considered to be stale.
.. ts:cv:: CONFIG proxy.config.http.cache.heuristic_lm_factor FLOAT 0.10
:reloadable:
:overridable:
- The aging factor for freshness computations. Traffic Server stores an object for this percentage of the time that
- elapsed since it last changed.
+ The aging factor for freshness computations. |TS| stores an object for this
+ percentage of the time that elapsed since it last changed.
+
+.. ts:cv:: CONFIG proxy.config.http.cache.guaranteed_min_lifetime INT 0
+ :reloadable:
+ :overridable:
+
+ Establishes a guaranteed minimum lifetime boundary for freshness heuristics.
+ When heuristics are used, and the :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`
+ aging factor is applied, the final minimum age calculated will never be
+ lower than the value in this variable.
+
+.. ts:cv:: CONFIG proxy.config.http.cache.guaranteed_max_lifetime INT 31536000
+ :reloadable:
+ :overridable:
+
+ Establishes a guaranteed maximum lifetime boundary for freshness heuristics.
+ When heuristics are used, and the :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`
+ aging factor is applied, the final maximum age calculated will never be
+ higher than the value in this variable.
.. ts:cv:: CONFIG proxy.config.http.cache.fuzz.time INT 240
:reloadable:
:overridable:
- How often Traffic Server checks for an early refresh, during the period before the document stale time. The interval
- specified must be in seconds. See :ref:`fuzzy-revalidation`
+ How often |TS| checks for an early refresh, during the period before the
+ document stale time. The interval specified must be in seconds. See the
+ section on :ref:`fuzzy-revalidation` for more details.
.. ts:cv:: CONFIG proxy.config.http.cache.fuzz.probability FLOAT 0.005
:reloadable:
:overridable:
- The probability that a refresh is made on a document during the specified fuzz time.
+ The probability that a refresh is made on a document during the fuzz time
+ specified in :ts:cv:`proxy.config.http.cache.fuzz.time`.
.. ts:cv:: CONFIG proxy.config.http.cache.fuzz.min_time INT 0
:reloadable:
:overridable:
- Handles requests with a TTL less than fuzz.time – it allows for different times to evaluate the probability of revalidation for small TTLs and big TTLs. Objects with small TTLs will start "rolling the revalidation dice" near the fuzz.min_time, while objects with large TTLs would start at fuzz.time. A logarithmic like function between determines the revalidation evaluation start time (which will be between fuzz.min_time and fuzz.time). As the object gets closer to expiring, the window start becomes more likely. By default this setting is not enabled, but should be enabled anytime you have objects with small TTLs. The default value is ``0``.
+ Handles requests with a TTL less than :ts:cv:`proxy.config.http.cache.fuzz.time`.
+ It allows for different times to evaluate the probability of revalidation
+ for small TTLs and big TTLs. Objects with small TTLs will start "rolling the
+ revalidation dice" near the ``fuzz.min_time``, while objects with large TTLs
+ would start at ``fuzz.time``. A logarithmic-like function between determines
+ the revalidation evaluation start time (which will be between
+ ``fuzz.min_time`` and ``fuzz.time``). As the object gets closer to expiring,
+ the window start becomes more likely. By default this setting is not enabled,
+ but should be enabled any time you have objects with small TTLs.
Dynamic Content & Content Negotiation
=====================================
@@ -1832,15 +1984,18 @@ DNS
.. ts:cv:: CONFIG proxy.config.dns.search_default_domains INT 0
:Reloadable:
- - ``0`` = disables local domain expansion
- - ``1`` = enable local domain expansion
- - ``2`` = enable local domain expansion, but restrain splitting local domain name
+ |TS| can attempt to resolve unqualified hostnames by expanding to the local
+ domain. For example if a client makes a request to an unqualified host (e.g.
+ ``host_x``) and the |TS| local domain is ``y.com``, then |TS| will expand
+ the hostname to ``host_x.y.com``.
-Traffic Server can attempt to resolve unqualified hostnames by
-expanding to the local domain. For example if a client makes a
-request to an unqualified host (``host_x``) and the Traffic Server
-local domain is ``y.com`` , then Traffic Server will expand the
-hostname to ``host_x.y.com``.
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Disable local domain expansion.
+ ``1`` Enable local domain expansion.
+ ``2`` Enable local domain expansion, but do not split local domain name.
+ ===== ======================================================================
.. ts:cv:: CONFIG proxy.config.dns.splitDNS.enabled INT 0
:reloadable:
@@ -2054,12 +2209,16 @@ Logging Configuration
Enables and disables event logging:
- - ``0`` = logging disabled
- - ``1`` = log errors only
- - ``2`` = log transactions only
- - ``3`` = full logging (errors + transactions)
+ ======== ===================================================================
+ Value Effect
+ ======== ===================================================================
+ ``0`` Logging disabled.
+ ``1`` Log errors only.
+ ``2`` Log transactions only.
+ ``3`` Dull logging (errors and transactions).
+ ======== ===================================================================
- Refer to :ref:`working-with-log-files`.
+ Refer to :ref:`admin-monitoring-logging` for more information on event logging.
.. ts:cv:: CONFIG proxy.config.log.max_secs_per_buffer INT 5
:reloadable:
@@ -2143,13 +2302,15 @@ Logging Configuration
- ``0`` = binary
- ``log_name`` STRING [format]
- The filename (ex. :ref:`squid log <log-formats-squid-format>`).
+ The filename (ex. :ref:`squid log <admin-logging-format-squid>`).
- ``log_header`` STRING NULL
- The file header text (ex. :ref:`squid log <log-formats-squid-format>`).
+ The file header text (ex. :ref:`squid log <admin-logging-format-squid>`).
- The format can be either ``squid`` (Squid Format), ``common`` (Netscape Common), ``extended`` (Netscape Extended),
- or ``extended2`` (Netscape Extended-2).
+ The format can be either ``squid`` (:ref:`admin-logging-format-squid`),
+ ``common`` (:ref:`admin-logging-format-common`),
+ ``extended`` (:ref:`admin-logging-format-extended`),
+ or ``extended2`` (:ref:`admin-logging-format-extended2`).
.. ts:cv:: LOCAL proxy.local.log.collation_mode INT 0
:reloadable:
@@ -2159,17 +2320,20 @@ Logging Configuration
===== ======
Value Effect
===== ======
-0 collation is disabled
-1 this host is a log collation server
-2 this host is a collation client and sends entries using standard formats to the collation server
-3 this host is a collation client and sends entries using the traditional custom formats to the collation server
-4 this host is a collation client and sends entries that use both the standard and traditional custom formats to the collation server
+0 Log collation is disabled.
+1 This host is a log collation server.
+2 This host is a collation client and sends entries using standard formats to the collation server.
+3 This host is a collation client and sends entries using the traditional custom formats to the collation server.
+4 This host is a collation client and sends entries that use both the standard and traditional custom formats to the collation server.
===== ======
-For information on sending XML-based custom formats to the collation
-server, refer to :file:`logs_xml.config`.
+For information on sending XML-based custom formats to the collation server,
+refer to :ref:`admin-monitoring-logging-formats` and :file:`logs_xml.config`.
+
+.. note::
-.. note:: Although Traffic Server supports traditional custom logging, you should use the more versatile XML-based custom formats.
+ Although Traffic Server supports traditional custom logging, you should use
+ the more versatile XML-based custom formats.
.. ts:cv:: CONFIG proxy.config.log.collation_host STRING NULL
@@ -2223,7 +2387,8 @@ server, refer to :file:`logs_xml.config`.
.. ts:cv:: CONFIG proxy.config.log.rolling_size_mb INT 10
:reloadable:
- The size that log files must reach before rolling takes place.
+ The size, in megabytes, that log files must reach before rolling takes place.
+ The minimum value for this setting is ``10``.
.. ts:cv:: CONFIG proxy.config.log.auto_delete_rolled_files INT 1
:reloadable:
@@ -2373,6 +2538,19 @@ URL Remap Rules
SSL Termination
===============
+.. ts:cv:: CONFIG proxy.config.ssl.server.cipher_suite STRING <see notes>
+
+ Configures the set of encryption, digest, authentication, and key exchange
+ algorithms provided by OpenSSL which |TS| will use for SSL connections. For
+ the list of algorithms and instructions on constructing an appropriately
+ formatting cipher_suite string, see
+ `OpenSSL Ciphers <https://www.openssl.org/docs/manmaster/apps/ciphers.html>`_.
+
+ The current default, included in the ``records.config.default`` example
+ configuration is:
+
+ ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-DSS-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA256:DHE-RSA-AES128-SHA256:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA:AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-SHA256:AES128-SHA256:AES256-SHA:AES128-SHA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA
+
.. ts:cv:: CONFIG proxy.config.ssl.SSLv2 INT 0
Enables (``1``) or disables (``0``) SSLv2. Please don't enable it.
@@ -2671,11 +2849,25 @@ ICP Configuration
Sets ICP mode for hierarchical caching:
- - ``0`` = disables ICP
- - ``1`` = allows Traffic Server to receive ICP queries only
- - ``2`` = allows Traffic Server to send and receive ICP queries
+ ===== ======================================================================
+ Value Description
+ ===== ======================================================================
+ ``0`` Disables ICP.
+ ``1`` Allows |TS| to receive ICP queries only, but not send them.
+ ``2`` Allows |TS| to both send and receive ICP queries.
+ ===== ======================================================================
+
+ Refer to :ref:`admin-icp-peering` for a fuller discussion..
+
+.. ts:cv:: CONFIG proxy.config.icp.multicast_enabled INT 0
+
+ By enabling ICP multicasting, you permit |TS| to send a single ICP message
+ over a multicast channel, instead of having to send individual ICP messages
+ to each of its peers. This requires functioning multicast support on your
+ network.
- Refer to :ref:`admin-icp-peering`.
+ ICP multicasting does not have any impact on the volume of ICP reply
+ messages, only on queries.
.. ts:cv:: CONFIG proxy.config.icp.icp_interface STRING NULL
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/index.en.rst b/doc/admin-guide/index.en.rst
index e4fe617..fa39855 100644
--- a/doc/admin-guide/index.en.rst
+++ b/doc/admin-guide/index.en.rst
@@ -38,7 +38,6 @@ Table of Contents:
configuring-traffic-server.en
performance/index.en
files/index.en
- troubleshooting.en
Audience
========
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/introduction.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/introduction.en.rst b/doc/admin-guide/introduction.en.rst
index 7fbed69..5a13503 100644
--- a/doc/admin-guide/introduction.en.rst
+++ b/doc/admin-guide/introduction.en.rst
@@ -256,9 +256,8 @@ monitoring:
help with log file analysis, you can separate log files so that they
contain information specific to protocol or hosts.
-Traffic analysis options are described in more detail in :ref:`monitoring-traffic`.
-
-Traffic Server logging options are described in :ref:`working-with-log-files`.
+|TS| event and error logging, monitoring, and analysis is covered in greater
+detail in :ref:`admin-monitoring`.
Traffic Server Security Options
===============================
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/40500c71/doc/admin-guide/monitoring/error-messages.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/monitoring/error-messages.en.rst b/doc/admin-guide/monitoring/error-messages.en.rst
index 498ba65..dd7afb6 100644
--- a/doc/admin-guide/monitoring/error-messages.en.rst
+++ b/doc/admin-guide/monitoring/error-messages.en.rst
@@ -62,7 +62,7 @@ Process Warnings
``Log format symbol <symbol name> not found``
Custom log format references a field symbol that does not exist.
- Refer to :ref:`admin-event-logging-formats`.
+ Refer to :ref:`admin-monitoring-logging-formats`.
``Missing field for field marker``
Error reading a log buffer.