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:24 UTC
[2/2] trafficserver git commit: Docs: build cleanups and multiple
Jira issues.
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.