trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject git commit: Doc: Fixup config var reference issues.
Date Thu, 05 Sep 2013 21:13:31 GMT
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 <amc@network-geographics.com>
Authored: Thu Sep 5 16:13:15 2013 -0500
Committer: Alan M. Carroll <amc@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``**.
-
-


Mime
View raw message