You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2013/09/05 23:13:31 UTC
git commit: Doc: Fixup config var reference issues.
Updated Branches:
refs/heads/master d31a4f92e -> c6c817d01
Doc: Fixup config var reference issues.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/c6c817d0
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/c6c817d0
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/c6c817d0
Branch: refs/heads/master
Commit: c6c817d01c4bcd0a035b31a4196012d3ac2ebdc9
Parents: d31a4f9
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Thu Sep 5 16:13:15 2013 -0500
Committer: Alan M. Carroll <am...@network-geographics.com>
Committed: Thu Sep 5 16:13:15 2013 -0500
----------------------------------------------------------------------
doc/admin/configuring-cache.en.rst | 26 ++---
.../configuration/records.config.en.rst | 114 ++++++++++---------
doc/sdk/new-protocol-plugins.en.rst | 63 +++++-----
3 files changed, 107 insertions(+), 96 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/c6c817d0/doc/admin/configuring-cache.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/configuring-cache.en.rst b/doc/admin/configuring-cache.en.rst
index 7051192..3c6d1c4 100644
--- a/doc/admin/configuring-cache.en.rst
+++ b/doc/admin/configuring-cache.en.rst
@@ -5,20 +5,20 @@ Configuring the Cache
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
The Traffic Server cache consists of a high-speed object database called
the **object store** that indexes objects according to URLs and their
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/c6c817d0/doc/reference/configuration/records.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst
index b661e35..f92ed71 100644
--- a/doc/reference/configuration/records.config.en.rst
+++ b/doc/reference/configuration/records.config.en.rst
@@ -210,7 +210,9 @@ Network
Unless explicitly specified in `proxy.config.http.server_ports`_ the server port will be bound to one of these addresses, selected by IP address family. The built in default is any address. This is used if no address for a family is specified. This setting is useful if most or all server ports should be bound to the same address.
-.. note:: This is ignored for inbound transparent server ports because they must be able to accept connections on arbitrary IP addresses.
+.. note::
+
+ This is ignored for inbound transparent server ports because they must be able to accept connections on arbitrary IP addresses.
.. topic:: Example
@@ -230,7 +232,9 @@ Unless explicitly specified in `proxy.config.http.server_ports`_ the server port
Unless explicitly specified in `proxy.config.http.server_ports`_ one of these addresses, selected by IP address family, will be used as the local address for outbound connections. This setting is useful if most or all of the server ports should use the same outbound IP addresses.
-.. note:: This is ignore for outbound transparent ports as the local outbound address will be the same as the client local address.
+.. note::
+
+ This is ignored for outbound transparent ports as the local outbound address will be the same as the client local address.
.. topic:: Example
@@ -438,7 +442,9 @@ compress
Traffic Server allows tunnels only to the specified ports.
Supports both wildcards ('\*') and ranges ("0-1023").
-.. note:: These are the ports on the *origin server*, not Traffic Server :ts:cv:`proxy ports <proxy.config.http.server_ports>`.
+.. note::
+
+ These are the ports on the *origin server*, not Traffic Server :ts:cv:`proxy ports <proxy.config.http.server_ports>`.
.. ts:cv:: CONFIG proxy.config.http.insert_request_via_str INT 1
:reloadable:
@@ -453,7 +459,9 @@ Value Effect
2 some extra information is added.
===== ============================================
-.. note:: the ``Via`` header string interpretation can be `decoded here. </tools/via>`_
+.. note::
+
+ The ``Via`` header string interpretation can be `decoded here. </tools/via>`_
.. ts:cv:: CONFIG proxy.config.http.insert_response_via_str INT 1
:reloadable:
@@ -773,24 +781,24 @@ Negative Response Caching
.. note::
- ``Cache-Control`` directives from the server forbidding ache are ignored for the following HTTP response codes, regardless
- of the value specified for the `proxy.config.http.negative_caching_enabled`_ variable. The
- following negative responses are cached by Traffic Server:::
-
- 204 No Content
- 305 Use Proxy
- 400 Bad Request
- 403 Forbidden
- 404 Not Found
- 405 Method Not Allowed
- 500 Internal Server Error
- 501 Not Implemented
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
-
- The cache lifetime for objects cached from this setting is controlled via
- ``proxy.config.http.negative_caching_lifetime``.
+ ``Cache-Control`` directives from the server forbidding ache are ignored for the following HTTP response codes, regardless
+ of the value specified for the :ts:cv:`proxy.config.http.negative_caching_enabled` variable. The
+ following negative responses are cached by Traffic Server:::
+
+ 204 No Content
+ 305 Use Proxy
+ 400 Bad Request
+ 403 Forbidden
+ 404 Not Found
+ 405 Method Not Allowed
+ 500 Internal Server Error
+ 501 Not Implemented
+ 502 Bad Gateway
+ 503 Service Unavailable
+ 504 Gateway Timeout
+
+ The cache lifetime for objects cached from this setting is controlled via
+ :ts:cv:`proxy.config.http.negative_caching_lifetime`.
Proxy User Variables
====================
@@ -989,11 +997,11 @@ Cache Control
.. note::
- This option should only be enabled if you're having
- problems with caching *and* one of the following is true:
+ This option should only be enabled if you're having
+ problems with caching *and* one of the following is true:
- - Your origin server sets ``Vary: Accept`` when doing content negotiation with ``Accept`` *OR*
- - The server does not send a ``406 (Not Acceptable)`` response for types that it cannot serve.
+ - Your origin server sets ``Vary: Accept`` when doing content negotiation with ``Accept`` *OR*
+ - The server does not send a ``406 (Not Acceptable)`` response for types that it cannot serve.
.. ts:cv:: CONFIG proxy.config.http.cache.ignore_accept_language_mismatch INT 0
:reloadable:
@@ -1003,10 +1011,10 @@ Cache Control
.. note::
- This option should only be enabled if you're having
- problems with caching and your origin server is guaranteed to set
- ``Vary: Accept-Language`` when doing content negotiation with
- ``Accept-Language``.
+ This option should only be enabled if you're having
+ problems with caching and your origin server is guaranteed to set
+ ``Vary: Accept-Language`` when doing content negotiation with
+ ``Accept-Language``.
.. ts:cv:: CONFIG proxy.config.http.cache.ignore_accept_charset_mismatch INT 0
:reloadable:
@@ -1016,10 +1024,8 @@ Cache Control
.. note::
- This option should only be enabled if you're having
- problems with caching and your origin server is guaranteed to set
- ``Vary: Accept-Charset`` when doing content negotiation with
- ``Accept-Charset``.
+ This option should only be enabled if you're having problems with caching and your origin server is
+ guaranteed to set ``Vary: Accept-Charset`` when doing content negotiation with ``Accept-Charset``.
.. ts:cv:: CONFIG proxy.config.http.cache.ignore_client_cc_max_age INT 1
:reloadable:
@@ -1034,22 +1040,21 @@ Cache Control
RAM Cache
=========
-
-.. :ts:cv:: CONFIG proxy.config.cache.ram_cache.size INT -1
+.. ts:cv:: CONFIG proxy.config.cache.ram_cache.size INT -1
By default the RAM cache size is automatically determined, based on
disk cache size; approximately 10 MB of RAM cache per GB of disk cache.
Alternatively, it can be set to a fixed value such as
**20GB** (21474836480)
-.. :ts:cv:: CONFIG proxy.config.cache.ram_cache.algorithm INT 0
+.. ts:cv:: CONFIG proxy.config.cache.ram_cache.algorithm INT 0
Two distinct RAM caches are supported, the default (0) being the **CLFUS**
(*Clocked Least Frequently Used by Size*). As an alternative, a simpler
**LRU** (*Least Recently Used*) cache is also available, by changing this
configuration to 1.
-.. :ts:cv:: CONFIG proxy.config.cache.ram_cache.use_seen_filter INT 0
+.. ts:cv:: CONFIG proxy.config.cache.ram_cache.use_seen_filter INT 0
Enabling this option will filter inserts into the RAM cache to ensure that
they have been seen at least once. For the **LRU**, this provides scan
@@ -1057,7 +1062,7 @@ RAM Cache
before it is inserted, so for **CLFUS**, setting this option means that a
document must be seen three times before it is added to the RAM cache.
-.. :ts:cv:: CONFIG proxy.config.cache.ram_cache.compress INT 0
+.. ts:cv:: CONFIG proxy.config.cache.ram_cache.compress INT 0
The **CLFUS** RAM cache also supports an optional in-memory compression.
This is not to be confused with ``Content-Encoding: gzip`` compression.
@@ -1071,34 +1076,37 @@ RAM Cache
- ``2`` = libz (moderate speed, reasonable compression)
- ``3`` = liblzma (very slow, high compression)
- NOTE: compression runs on task threads. To use more cores for
- RAM cache compression, increase :ts:cv:`proxy.config.task_threads`.
+ .. note::
+
+ Compression runs on task threads. To use more cores for RAM cache compression, increase :ts:cv:`proxy.config.task_threads`.
Heuristic Expiration
====================
-.. :ts:cv:: proxy.config.http.cache.heuristic_min_lifetime INT 3600
+.. ts:cv:: CONFIG proxy.config.http.cache.heuristic_min_lifetime INT 3600
:reloadable:
- 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 an HTTP object without an expiration date can remain fresh in the cache before is
+ considered to be stale.
-.. :ts:cv:: proxy.config.http.cache.heuristic_max_lifetime INT 86400
+.. ts:cv:: CONFIG proxy.config.http.cache.heuristic_max_lifetime INT 86400
:reloadable:
- 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 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.10000
:reloadable:
- 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. Traffic Server stores an object for this percentage of the time that
+ elapsed since it last changed.
.. ts:cv:: CONFIG proxy.config.http.cache.fuzz.time INT 240
:reloadable:
- How often Traffic Server checks for an early refresh, during the period before the document stale time. The interval specified must
- be in seconds.
+ How often Traffic Server checks for an early refresh, during the period before the document stale time. The interval
+ specified must be in seconds.
.. ts:cv:: CONFIG proxy.config.http.cache.fuzz.probability FLOAT 0.00500
:reloadable:
@@ -1975,12 +1983,16 @@ Sockets
Undocumented
============
-.. ts:cv:: CONFIG proxy.config.http.cache.heuristic_min_lifetime INT 0
+These are referenced but not documented. Please contribute a definition.
+
+.. ts:cv:: CONFIG proxy.config.http.negative_caching_lifetime INT 0
-.. ts:cv:: CONFIG proxy.config.http.cache.heuristic_max_lifetime INT 0
+.. ts:cv:: CONFIG proxy.config.task_threads INT 0
.. ts:cv:: CONFIG proxy.config.cache.limits.http.max_alts INT 5
.. ts:cv:: CONFIG proxy.config.http.enabled INT 1
+.. ts:cv:: CONFIG proxy.configl.cache.max_doc_size INT 0
+
Enable caching HTTP content.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/c6c817d0/doc/sdk/new-protocol-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/new-protocol-plugins.en.rst b/doc/sdk/new-protocol-plugins.en.rst
index 13614a5..4ca91e7 100644
--- a/doc/sdk/new-protocol-plugins.en.rst
+++ b/doc/sdk/new-protocol-plugins.en.rst
@@ -5,20 +5,20 @@ New Protocol Plugins
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
.. toctree::
:maxdepth: 1
@@ -34,25 +34,23 @@ About the Sample Protocol
The sample protocol enables a client to ask a server for a file. Clients
send requests to a specific Traffic Server port (specified in
-``plugin.config``); each request has the following structure:
-
-::
+:file:`plugin.config`); each request has the following structure::
- server_name file_name
+ server_name file_name
Using the Protocol plugin, Traffic Server can accept these requests,
parse them, and act as a proxy cache (i.e., request the file from the
origin server on the client's behalf and store copies of response
messages in cache). The Protocol plugin is a state machine that flows
through the states illustrated in the `Sample Protocol State
-Diagram <#SampleProtocolStDiag>`__. This figure illustrates the steps
+Diagram <#SampleProtocolStDiag>`_. This figure illustrates the steps
that Traffic Server and the Protocol plugin go through in order to
support the sample protocol.
In more specific terms, Traffic Server and the Protocol plugin must:
- Listen for and accept client connections (on the accept port
- specified in ``plugin.config``)
+ specified in :file:`plugin.config`)
- Read incoming client requests
@@ -62,7 +60,7 @@ In more specific terms, Traffic Server and the Protocol plugin must:
example does not do freshness checking)
- Open a connection to the origin server if the request is a cache miss
- (on the server port specified in ``plugin.config``)
+ (on the server port specified in :file:`plugin.config`)
- Forward the request to the origin server
@@ -76,16 +74,17 @@ In more specific terms, Traffic Server and the Protocol plugin must:
:alt: Sample Protocol State Diagram
Sample Protocol State Diagram
+
Protocol Plugin Structure
~~~~~~~~~~~~~~~~~~~~~~~~~
To see how the Protocol plugin works, you need to understand some
broader concepts. This section assumes you're familiar with the concepts
-of **continuation**, Traffic Server's **asynchronous event model**, and
+of :term:`continuation`, Traffic Server's **asynchronous event model**, and
basic Traffic Server **plugin structure**. If you are not familiar with
these concepts, then reference `Getting
-Started <../getting-started#GettingStarted>`__ and `How to Create
-Traffic Server Plugins <../how-to-create-trafficserver-plugins>`__
+Started <../getting-started#GettingStarted>`_ and `How to Create
+Traffic Server Plugins <../how-to-create-trafficserver-plugins>`_
Continuations in the Protocol Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -96,7 +95,7 @@ connections on the appropriate port. When Traffic Server accepts a net
connection from a client on that port, the accept state machine is
activated. It then creates a new continuation: a transaction state
machine. The accept state machine creates one transaction state machine
-for each transaction (where a **transaction** consists of a client
+for each transaction (where a :term:`transaction` consists of a client
request and Traffic Server's response). Each transaction state machine
lives until the transaction completes; then it is destroyed. If the
client's request for content is a cache miss, then a transaction state
@@ -104,15 +103,16 @@ machine might need to open a connection to the origin server. This is
illustrated in the `Protocol Plugin
Overview <#ProtocolPluginOverview>`__ diagram below.
-**Protocol Plugin Overview** {#ProtocolPluginOverview}
+**Protocol Plugin Overview**
.. figure:: ../static/images/sdk/protocol_sm_big.jpg
:alt: Protocol Plugin Overview
Protocol Plugin Overview
+
The first steps for writing the Protocol plugin are now clear: in
``TSPluginInit``, you must create a continuation that listens for net
-connections on the client port specified in ``plugin.config`` (this
+connections on the client port specified in :file:`plugin.config` (this
continuation is the accept state machine).
Below is a summary of the continuations implemented for the Protocol
@@ -156,14 +156,15 @@ connect to the origin server, then the transaction state machine
initiates a net connection and waits for an event from the Net
Processor.
-**Protocol Plugin Flow of Events** {#ProtocolPluginFlow}
+**Protocol Plugin Flow of Events**
.. figure:: ../static/images/sdk/protocol_evt.jpg
:alt: Protocol Plugin Flow of Events
Protocol Plugin Flow of Events
+
The flow of events is illustrated in the `Protocol Plugin Flow of
-Events <#ProtocolPluginFlow>`__ diagram above. The thin straight lines
+Events <#ProtocolPluginFlow>`_ diagram above. The thin straight lines
show Net Processor event flow, the thin dashed lines represent Host
Database event flow, and the thick dashed lines show Cache event flow.
@@ -244,10 +245,10 @@ Plugin" <#ImplementTransStMachine>`__.
Plugin** {#ImplementTransStMachine}
.. figure:: /images/sdk/txn_sm.jpg
- :alt: How Transaction State Machines are Implemented in the Protocol
- Plugin
+ :alt: How Transaction State Machines are Implemented in the Protocol Plugin
How Transaction State Machines are Implemented in the Protocol Plugin
+
Processing a Typical Transaction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -357,5 +358,3 @@ typical transaction.
**``TS_EVENT_OPEN_READ``** (a cache hit) or
**``TS_EVENT_OPEN_READ_FAILED``** (a cache miss),
**``main_handler``** calls **``state_handle_cache_lookup``**.
-
-