You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by js...@apache.org on 2016/04/21 16:43:49 UTC
[trafficserver] branch master updated: TS-2354: docs: admin tuning
section on all available timeouts
This is an automated email from the ASF dual-hosted git repository.
jsime pushed a commit to branch master
in repository https://git-dual.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new c6afd54 TS-2354: docs: admin tuning section on all available timeouts
c6afd54 is described below
commit c6afd5443852789c82e024cd61e44c4fabbfd1ac
Author: Jon Sime <js...@apache.org>
AuthorDate: Thu Apr 21 14:04:23 2016 +0000
TS-2354: docs: admin tuning section on all available timeouts
---
doc/admin-guide/configuration/cache-basics.en.rst | 2 +
doc/admin-guide/files/records.config.en.rst | 64 +++++-
doc/admin-guide/performance/index.en.rst | 257 ++++++++++++++++++++++
doc/admin-guide/security/index.en.rst | 2 +
4 files changed, 319 insertions(+), 6 deletions(-)
diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst
index aff3770..97baccf 100644
--- a/doc/admin-guide/configuration/cache-basics.en.rst
+++ b/doc/admin-guide/configuration/cache-basics.en.rst
@@ -733,6 +733,8 @@ requests to the origin server, potentially overwhelming it or associated
resources. There are several features in Traffic Server that can be used to
avoid this scenario.
+.. _admin-config-read-while-writer:
+
Read While Writer
-----------------
diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst
index a5f5889..1122694 100644
--- a/doc/admin-guide/files/records.config.en.rst
+++ b/doc/admin-guide/files/records.config.en.rst
@@ -342,6 +342,8 @@ Network
`proxy.process.net.default_inactivity_timeout_applied` metric
is incremented.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.net.inactivity_check_frequency INT 1
How frequent (in seconds) to check for inactive connections. If you deal
@@ -1079,6 +1081,8 @@ Parent Proxy Configuration
The timeout value (in seconds) for parent cache connection attempts.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.http.forward.proxy_auth_to_parent INT 0
:reloadable:
:overridable:
@@ -1101,6 +1105,8 @@ HTTP Connection Timeouts
subsequent request after a transaction ends. A value of ``0`` will disable
the no activity timeout.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.http.keep_alive_no_activity_timeout_out INT 120
:reloadable:
:overridable:
@@ -1109,11 +1115,16 @@ HTTP Connection Timeouts
for a subsequent transfer of data after a transaction ends. A value of
``0`` will disable the no activity timeout.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.http.transaction_no_activity_timeout_in INT 30
:reloadable:
:overridable:
- Specifies how long Traffic Server keeps connections to clients open if a transaction stalls.
+ Specifies how long Traffic Server keeps connections to clients open if a
+ transaction stalls.
+
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
.. ts:cv:: CONFIG proxy.config.http.transaction_no_activity_timeout_out INT 30
:reloadable:
@@ -1121,25 +1132,33 @@ HTTP Connection Timeouts
Specifies how long Traffic Server keeps connections to origin servers open if the transaction stalls.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.websocket.no_activity_timeout INT 600
:reloadable:
:overridable:
Specifies how long Traffic Server keeps connections open if a websocket stalls.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.websocket.active_timeout INT 3600
:reloadable:
:overridable:
The maximum amount of time Traffic Server keeps websocket connections open.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.http.transaction_active_timeout_in INT 900
:reloadable:
The maximum amount of time Traffic Server can remain connected to a client. If the transfer to the client is not complete before this
timeout expires, then Traffic Server closes the connection.
-The value of ``0`` specifies that there is no timeout.
+ The value of ``0`` specifies that there is no timeout.
+
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
.. ts:cv:: CONFIG proxy.config.http.transaction_active_timeout_out INT 0
:reloadable:
@@ -1148,19 +1167,25 @@ The value of ``0`` specifies that there is no timeout.
The maximum amount of time Traffic Server waits for fulfillment of a connection request to an origin server. If Traffic Server does not
complete the transfer to the origin server before this timeout expires, then Traffic Server terminates the connection request.
-The default value of ``0`` specifies that there is no timeout.
+ The default value of ``0`` specifies that there is no timeout.
+
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
.. ts:cv:: CONFIG proxy.config.http.accept_no_activity_timeout INT 120
:reloadable:
The timeout interval in seconds before Traffic Server closes a connection that has no activity.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.http.background_fill_active_timeout INT 0
:reloadable:
:overridable:
Specifies how long Traffic Server continues a background fill before giving up and dropping the origin server connection.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.http.background_fill_completed_threshold FLOAT 0.0
:reloadable:
:overridable:
@@ -1262,7 +1287,10 @@ Origin Server Connect Attempts
:reloadable:
:overridable:
- The timeout value (in seconds) for **time to first byte** for an origin server connection.
+ The timeout value (in seconds) for time to first byte for an origin server
+ connection.
+
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
.. ts:cv:: CONFIG proxy.config.http.post_connect_attempts_timeout INT 1800
:reloadable:
@@ -1271,6 +1299,8 @@ Origin Server Connect Attempts
The timeout value (in seconds) for an origin server connection when the client request is a ``POST`` or ``PUT``
request.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.http.down_server.cache_time INT 60
:reloadable:
:overridable:
@@ -2106,6 +2136,8 @@ HostDB
Time to wait for a DNS response in seconds.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.hostdb.serve_stale_for INT
:metric: seconds
:reloadable:
@@ -2154,6 +2186,8 @@ HostDB
See :ts:cv:`proxy.config.hostdb.ttl_mode` for when this value is used.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.hostdb.strict_round_robin INT 0
:reloadable:
@@ -2757,6 +2791,8 @@ SSL Termination
when using the Traffic Server session cache (option ``2`` in
``proxy.config.ssl.session_cache``)
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.ssl.session_cache.auto_clear INT 1
This will set the OpenSSL auto clear flag. Auto clear is enabled by
@@ -2815,8 +2851,10 @@ SSL Termination
.. ts:cv:: CONFIG proxy.config.ssl.handshake_timeout_in INT 0
- When enabled this limits the total duration for the server side SSL
- handshake.
+ When enabled this limits the total duration for the server side SSL
+ handshake.
+
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
.. ts:cv:: CONFIG proxy.config.ssl.wire_trace_enabled INT 0
@@ -2892,10 +2930,14 @@ OCSP Stapling Configuration
Number of seconds before an OCSP response expires in the stapling cache.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.ssl.ocsp.request_timeout INT 10
Timeout (in seconds) for queries to OCSP responders.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.ssl.ocsp.update_period INT 60
Update period (in seconds) for stapling caches.
@@ -2948,6 +2990,8 @@ ICP Configuration
Specifies the timeout used for ICP queries.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
HTTP/2 Configuration
====================
@@ -3069,10 +3113,14 @@ SOCKS Processor
The activity timeout value (in seconds) for SOCKS server connections.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.socks.server_connect_timeout INT 10
The timeout value (in seconds) for SOCKS server connection attempts.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.socks.per_server_connection_attempts INT 1
The total number of connection attempts allowed per SOCKS server,
@@ -3087,6 +3135,8 @@ SOCKS Processor
The timeout value (in seconds) for SOCKS server connection retry attempts.
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.socks.default_servers STRING
Default list of SOCKS servers and their ports.
@@ -3259,6 +3309,8 @@ Sockets
CONFIG proxy.config.accept_threads INT 1
CONFIG proxy.config.cache.threads_per_disk INT 8
+ See :ref:`admin-performance-timeouts` for more discussion on |TS| timeouts.
+
.. ts:cv:: CONFIG proxy.config.task_threads INT 2
Specifies the number of task threads to run. These threads are used for
diff --git a/doc/admin-guide/performance/index.en.rst b/doc/admin-guide/performance/index.en.rst
index 4344ca9..3e099dd 100644
--- a/doc/admin-guide/performance/index.en.rst
+++ b/doc/admin-guide/performance/index.en.rst
@@ -209,6 +209,160 @@ Thread Stack Size
is there ever a need to fiddle with this, outside of possibly custom developed plugins?
+.. _admin-performance-timeouts:
+
+Timeout Settings
+----------------
+
+|TS| has a variety of timeout settings which may be modified to help tune the
+performance of various proxy components. In general it is recommended to leave
+the timeouts at their default values unless you have identified specific causes
+for an adjustment.
+
+Note that not all proxy configurations will be impacted by every timeout. For
+instance, if you are not using any hierarchical caching then the parent proxy
+timeouts will be irrelevant.
+
+While all of the timeouts described below may be set globally for your |TS|
+instance using :file:`records.config`, many of them are also overridable on a
+per-transaction basis by plugins (including :ref:`admin-plugins-conf-remap`).
+This allows the possibility for adjusting timeout value for individual subsets
+of your cache.
+
+For example, you may wish to be fairly lenient on activity timeouts for most of
+your cache, leaving the default at a minute or two, but enforce a much stricter
+timeout on a set of very small, incredibly heavily accessed objects for which
+you can construct a ``map`` rule with the goal of reducing the chances that a
+few bad actors (misconfigured or misbehaving clients) may generate too much
+connection pressure on your cache. The tradeoff may be that some perfectly
+innocent, but slow clients may have their connections terminated early. As with
+all performance tuning efforts, your needs are likely to vary from others' and
+should be carefully considered and closely monitored.
+
+Default Inactivity Timeout
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :ts:cv:`proxy.process.net.default_inactivity_timeout` setting is applied to
+the HTTP state machine when no other inactivity timeouts have been applied. In
+effect, it sets an upper limit, in seconds, on state machine inactivity.
+
+In addition to the timeout itself, there is a related statistic:
+:ts:stat:`proxy.process.net.default_inactivity_timeout_applied` which tracks
+the number of times the default inactivity timeout was applied to transactions
+(as opposed to a more specific timeout having been applied).
+
+::
+
+ CONFIG proxy.process.net.default_inactivity_timeout INT 86400
+
+Accept Timeout
+~~~~~~~~~~~~~~
+
+The variable :ts:cv:`proxy.config.http.accept_no_activity_timeout` sets, in
+seconds, the time after which |TS| will close incoming connections which remain
+inactive (have not sent data). Lowering this timeout can ease pressure on the
+proxy if misconfigured or misbehaving clients are opening a large number of
+connections without submitting requests.
+
+::
+
+ CONFIG proxy.config.http.accept_no_activity_timeout INT 120
+
+Background Fill Timeout
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When :ref:`background fills <admin-config-read-while-writer>` are enabled,
+:ts:cv:`proxy.config.http.background_fill_active_timeout` sets in seconds the
+time after which |TS| will abort the fill attempt and close the origin
+server connection that was being used. Setting this to zero disables the
+timeout, but modifying the value and enforcing a timeout may help in
+situtations where your origin servers stall connections without closing.
+
+::
+
+ CONFIG proxy.config.http.background_fill_active_timeout INT 0
+
+DNS Timeouts
+~~~~~~~~~~~~
+
+|TS| performs all DNS queries for origin servers through the HostDB subsystem.
+Two settings affect the potential frequency and amount of time |TS| will spend
+on these lookups. :ts:cv:`proxy.config.hostdb.timeout` is used to establish the
+time-to-live, in minutes, for all DNS records and
+:ts:cv:`proxy.config.hostdb.lookup_timeout` sets, in seconds, the timeout for
+actual DNS queries.
+
+Setting a higher ``timeout`` value will reduce the number of times |TS| needs
+to perform DNS queries for origin servers, but may also prevent your |TS|
+instance from updating its records to reflect external DNS record changes in a
+timely manner (refer to :ts:cv:`proxy.config.hostdb.ttl_mode` for more
+information on when this TTL value will actually be used).
+
+::
+
+ CONFIG proxy.config.hostdb.timeout INT 1440
+ CONFIG proxy.config.hostdb.lookup_timeout INT 30
+
+ICP Timeout
+~~~~~~~~~~~
+
+When using :ref:`admin-icp-peering` for hierarchical caching configurations, a
+global timeout on all inter-cache queries may be set, in seconds, using
+:ts:cv:`proxy.config.icp.query_timeout`.
+
+::
+
+ CONFIG proxy.config.icp.query_timeout INT 2
+
+Keepalive Timeouts
+~~~~~~~~~~~~~~~~~~
+
+|TS| keepalive timeouts may be set both for maintaining a client connection for
+subsequent requests, using
+:ts:cv:`proxy.config.http.keep_alive_no_activity_timeout_in`, as well as origin
+server connections for subsequent object requests (when not servable from the
+cache) using :ts:cv:`proxy.config.http.keep_alive_no_activity_timeout_out`.
+Both are specified in seconds. Keep in mind that
+``keep_alive_no_activity_timeout_out`` for origin server connections is
+effectively an advisory maximum, as the origin server may have its own
+keepalive timeout which (if set lower) will likely take precedence.
+
+::
+
+ CONFIG proxy.config.http.keep_alive_no_activity_timeout_in INT 115
+ CONFIG proxy.config.http.keep_alive_no_activity_timeout_out INT 120
+
+Origin Connection Timeouts
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Origin server connection timeouts are configured with :ts:cv:`proxy.config.http.connect_attempts_timeout`,
+which is applied both to the initial connection as well as any retries attempted,
+should an attempt timeout. The timeout applies from the moment |TS| begins the
+connection attempt until the origin returns the first byte.
+
+In the case where you wish to have a different (generally longer) timeout for
+``POST`` and ``PUT`` connections to an origin server, you may also adjust
+:ts:cv:`proxy.config.http.post_connect_attempts_timeout` which applies only to
+origin connections using those HTTP verbs.
+
+::
+
+ CONFIG proxy.config.http.connect_attempts_timeout INT 30
+ CONFIG proxy.config.http.post_connect_attempts_timeout INT 1800
+
+Parent Proxy Timeout
+~~~~~~~~~~~~~~~~~~~~
+
+In hierarchical caching configurations, the :ts:cv:`proxy.config.http.parent_proxy.connect_attempts_timeout`
+setting is used for all connection attempts to parent caches. It may be useful,
+in cases where you wish to have |TS| fall back to an alternate parent cache
+(in configurations where you have multiple parents for the same cache) more
+quickly, to lower this timeout.
+
+::
+
+ CONFIG proxy.config.http.parent_proxy.connect_attempts_timeout INT 30
+
Polling Timeout
~~~~~~~~~~~~~~~
@@ -218,6 +372,109 @@ idle workloads, you may consider adjusting the polling timeout with
CONFIG proxy.config.net.poll_timeout INT 60
+SOCKS Timeouts
+~~~~~~~~~~~~~~
+
+In |TS| configurations where SOCKS has been enabled, three timeouts are made
+available for tuning. Basic activity timeout for SOCKS server connections may
+be adjusted with :ts:cv:`proxy.config.socks.socks_timeout`, in seconds. Server
+connection attempts (initial connections attempts only) are covered by
+:ts:cv:`proxy.config.socks.server_connect_timeout`, again in seconds, and
+server connection retry attempts are set with
+:ts:cv:`proxy.config.socks.server_retry_timeout`. Note that the retry timeout
+is the timeout for the actual connection attempt on a retry, not the delay
+after which a retry will be performed (the delay is configured with
+:ts:cv:`proxy.config.socks.server_retry_time`).
+
+::
+
+ CONFIG proxy.config.socks.socks_timeout INT 100
+ CONFIG proxy.config.socks.server_connect_timeout INT 10
+ CONFIG proxy.config.socks.server_retry_timeout INT 300
+ CONFIG proxy.config.socks.server_retry_time INT 300
+
+SSL Timeouts
+~~~~~~~~~~~~
+
+|TS| offers a few timeouts specific to encrypted connections handled by the SSL
+engine.
+
+:ts:cv:`proxy.config.ssl.handshake_timeout_in` configures the time, in seconds,
+after which incoming client connections will abort should the SSL handshake not
+be completed. The default of ``0`` disables the timeout.
+
+When :ref:`admin-ocsp-stapling` is enabled in |TS|, you can configure two
+separate timeouts; one for setting the length of time which cached OCSP results
+will persist, specified in seconds using
+:ts:cv:`proxy.config.ssl.ocsp.cache_timeout`, and the timeout for requests to
+the remote OCSP responders, in seconds, with
+:ts:cv:`proxy.config.ssl.ocsp.request_timeout`.
+
+Lastly, you can control the number of seconds for which SSL sessions will be
+cached in |TS| using :ts:cv:`proxy.config.ssl.session_cache.timeout`.
+
+::
+
+ CONFIG proxy.config.ssl.handshake_timeout_in INT 0
+ CONFIG proxy.config.ssl.ocsp.cache_timeout INT 3600
+ CONFIG proxy.config.ssl.ocsp.request_timeout INT 10
+ CONFIG proxy.config.ssl.session_cache.timeout INT 0
+
+Transaction Activity Timeouts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|TS| specifies two sets of general transaction activity timeouts: a pair for
+active transactions, and a pair for inactive connections (ones which are not
+receiving or sending data during the timeout period). Each pair includes one
+timeout for client connections (the ``_in`` variant) and another for origin
+server transactions (``_out`` variants).
+
+For active transactions,
+:ts:cv:`proxy.config.http.transaction_active_timeout_in` and
+:ts:cv:`proxy.config.http.transaction_active_timeout_out` set the maximum time,
+in seconds, which |TS| will spend sending/receiving data with a client or
+origin server, respectively. If the data transfer has not completed within the
+time specified then the connection will be closed automatically. This may
+result in the lack of a cache update, or partial data transmitted to a client.
+Both timeouts are disabled (set to ``0``) by default.
+
+In general, it's unlikely you will want to enable either of these timeouts
+globally, especially if your cache contains objects of varying sizes and deals
+with clients which may support a range of speeds (and therefore take less or
+more time to complete normal, healthy data exchanges). However, there may be
+configurations in which small objects need to be exchanged in very short
+periods and you wish your |TS| cache to enforce these time resrictions by
+closing connections which exceed them.
+
+The variables :ts:cv:`proxy.config.http.transaction_no_activity_timeout_in` and
+:ts:cv:`proxy.config.http.transaction_no_activity_timeout_out` control the
+maximum amount of time which |TS| will spend in a transaction which is stalled
+and not transmitting data, for clients and origin servers respectively.
+
+Unlike the active transaction timeouts, these two inactive transaction timeout
+values prove somewhat more generally applicable.
+
+::
+
+ CONFIG proxy.config.http.transaction_active_timeout_in INT 0
+ CONFIG proxy.config.http.transaction_active_timeout_out INT 0
+ CONFIG proxy.config.http.transaction_no_activity_timeout_in INT 30
+ CONFIG proxy.config.http.transaction_no_activity_timeout_out INT 30
+
+WebSocket Timeouts
+~~~~~~~~~~~~~~~~~~
+
+|TS| provides two configurable timeouts for WebSocket connections. The setting
+:ts:cv:`proxy.config.websocket.no_activity_timeout` will establish the maximum
+length of time a stalled WebSocket connection will remain before |TS| closes
+it. :ts:cv:`proxy.config.websocket.active_timeout` sets the maximum duration
+for all WebSocket connections, regardless of their level of activity.
+
+::
+
+ CONFIG proxy.config.websocket.no_activity_timeout INT 600
+ CONFIG proxy.config.websocket.active_timeout INT 3600
+
Memory Optimization
-------------------
diff --git a/doc/admin-guide/security/index.en.rst b/doc/admin-guide/security/index.en.rst
index 06ca663..5bbdb62 100644
--- a/doc/admin-guide/security/index.en.rst
+++ b/doc/admin-guide/security/index.en.rst
@@ -257,6 +257,8 @@ a ticket key file as a reverse queue in 48-byte chunks.
#. Run the command :option:`traffic_ctl config reload` to apply the new ticket key.
+.. _admin-ocsp-stapling:
+
OCSP Stapling
=============
--
To stop receiving notification emails like this one, please contact
['"commits@trafficserver.apache.org" <co...@trafficserver.apache.org>'].