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/11/01 15:22:40 UTC
[trafficserver] 01/03: Doc: tweaks and cleanup
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
commit 0376486474f756ec79e2c4e964464f60b96c38cc
Author: Alan M. Carroll <so...@yahoo-inc.com>
AuthorDate: Thu Oct 20 11:11:27 2016 -0500
Doc: tweaks and cleanup
---
doc/admin-guide/configuration/index.en.rst | 1 -
.../configuration/multi-server-caches.en.rst | 180 ------------------
doc/admin-guide/files/cluster.config.en.rst | 85 ---------
doc/admin-guide/files/index.en.rst | 4 -
doc/admin-guide/files/records.config.en.rst | 4 +-
.../monitoring/statistics/core-statistics.en.rst | 1 -
.../monitoring/statistics/core/cluster.en.rst | 209 ---------------------
doc/appendices/faq.en.rst | 3 +-
doc/checkvers.py | 19 +-
doc/conf.py | 7 +-
.../api/functions/TSHttpTxnInfoIntGet.en.rst | 42 +++--
.../api/functions/TSHttpTxnIsInternal.en.rst | 4 +-
.../api/functions/TSHttpTxnServerAddrSet.en.rst | 2 +-
.../api/functions/TSMBufferCreate.en.rst | 2 +-
.../api/functions/TSSslContextFindBy.en.rst | 8 +-
doc/developer-guide/api/functions/TSTypes.en.rst | 18 +-
.../api/functions/TSVConnTunnel.en.rst | 4 +-
doc/ext/traffic-server.py | 27 ++-
doc/manpages.py | 1 -
19 files changed, 74 insertions(+), 547 deletions(-)
diff --git a/doc/admin-guide/configuration/index.en.rst b/doc/admin-guide/configuration/index.en.rst
index 3a6d3ad..cc2e3f6 100644
--- a/doc/admin-guide/configuration/index.en.rst
+++ b/doc/admin-guide/configuration/index.en.rst
@@ -31,5 +31,4 @@ Proxy Cache Configuration
explicit-forward-proxying.en
transparent-proxy.en
transparent-forward-proxying.en
- multi-server-caches.en
hierachical-caching.en
diff --git a/doc/admin-guide/configuration/multi-server-caches.en.rst b/doc/admin-guide/configuration/multi-server-caches.en.rst
deleted file mode 100644
index aa37530..0000000
--- a/doc/admin-guide/configuration/multi-server-caches.en.rst
+++ /dev/null
@@ -1,180 +0,0 @@
-.. _traffic-server-cluster:
-
-Traffic Server Cluster
-**********************
-
-.. 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.
-
-Traffic Server scales from a single node to multiple nodes that form a
-cluster allowing you to improve system performance and reliability.
-
-.. toctree::
- :maxdepth: 1
-
-Understanding Traffic Server Clusters
-=====================================
-
-A Traffic Server cluster consists of multiple Traffic Server nodes. The
-nodes in a cluster share configuration information and can form a single
-logical cache. Traffic Server detects the addition and deletion of nodes
-in the cluster automatically and can detect when a node is unavailable.
-Traffic Server uses its own protocol for clustering, which is multicast
-for node location and heartbeat, but unicast for all data exchange
-within the cluster. Traffic Server has two clustering modes:
-
-- Management-only mode; refer to `Management-Only Clustering`_ below.
-- Full-clustering mode; refer to `Full Clustering`_
-
-Management-Only Clustering
-==========================
-
-In management-only clustering mode, Traffic Server cluster nodes share
-configuration information. You can administer all the nodes at the same
-time. Traffic Server uses a multicast management protocol to provide a
-single system image of your Traffic Server cluster. Information about
-cluster membership, configuration, and exceptions is shared across all
-nodes, and the :program:`traffic_manager` process automatically propagates
-configuration changes to all the nodes.
-
-Full Clustering
-===============
-
-In full-clustering mode, as well as sharing configuration information, a
-Traffic Server cluster distributes its cache across its nodes into a
-single, virtual object store, rather than replicating the cache node by
-node. Traffic Server can provide an enormous aggregate cache size and
-can maximize cache hit rate by storing objects only once across the
-entire cluster.
-
-A fully clustered Traffic Server maps objects to specific nodes in the
-cluster. When a node receives a request, it checks to see if the request
-is a hit somewhere in the cluster. If the request is a hit on a
-different node, the node handling the request obtains the object from
-the hit node and serves it to the client. Traffic Server uses its own
-communication protocol to obtain an object from sibling cluster nodes.
-
-If a node fails or is shut down and removed, Traffic Server removes
-references to the missing node on all nodes in the cluster.
-
-Full clustering recommends a dedicated network interface for cluster
-communication to achieve better performance.
-
-Enabling Clustering Mode
-========================
-
-Before a node is added into a cluster, please ensure that the following
-conditions are being met:
-
-- All nodes are running the same operating system:
-
- - The same distribution, e.g.: RHEL 6.6
- - The same kernel, e.g.: 2.6.32-504.23.4.el6
- - The same architecture, e.g.: x86_64
-
-- All nodes have the same version of Traffic Server installed
-- All nodes are composed of the same hardware
-- All nodes are on the same switch or same VLAN.
-
-Traffic Server does not apply the clustering mode change to all the
-nodes in the cluster. You must change the clustering mode on each node
-individually. You may following these instructions:
-
-1. Setup the same cluster name, with :ts:cv:`proxy.config.proxy_name`, e.g. ``MyCluster``.
-
-2. Set :ts:cv:`proxy.local.cluster.type` to ``1`` to enable cluster mode. The
- following values of this configuration are valid:
-
-================= ==================================================
-Value Description
-================= ==================================================
-1 Full-Clustering mode
-2 Management-Only mode
-3 No clustering (*default*)
-================= ==================================================
-
-3. Configure :ts:cv:`proxy.config.cluster.ethernet_interface`, e.g.: ``eth0``.
- This should be replaced with the node's real interface. We recommends a
- dedicated physical interface here. Refer to :ts:cv:`proxy.local.cluster.type`
- for a full description.
-
-4. Enable configuration changes::
-
- traffic_ctl config reload
-
-5. Restart traffic server::
-
- traffic_ctl server restart
-
- The :program:`traffic_server` and :program:`traffic_manager` processes will need to
- restart after the change of :ts:cv:`proxy.local.cluster.type` and
- :ts:cv:`proxy.config.cluster.ethernet_interface` have taken place.
-
-Traffic Server will join the cluster in about 10 seconds. To verify the hosts in the
-cluster, you can run::
-
- traffic_ctl metric get proxy.process.cluster.nodes
-
-Cluster node status is also tracked in ``cluster.config`` in the configuration
-directory. This configuration is generated by the system and should not be
-edited. It contains a list of the machines that are currently members of the
-cluster, for example::
-
- # 3
- 127.1.2.3:80
- 127.1.2.4:80
- 127.1.2.5:80
-
-After successfully joining a cluster, all changes of global configurations
-performed on any node in that cluster will take effect on all nodes, removing
-the need to manually duplicate configuration changes across each node individually.
-
-Deleting Nodes from a Cluster
-=============================
-
-To delete a node from the Traffic Server cluster, return the setting
-:ts:cv:`proxy.local.cluster.type` to the default value ``3`` and reload.
-
-Common issues for Cluster setup
-===============================
-
-1. The Cluster member auto discovery is built upon multi-casting UDP, and as such
- is impossible to setup where multi-casting is not avaliable, such as AWS EC2.
-
-2. The Cluster will depend on ports 8088, 8089, and 8086. These ports must not be
- blocked by any network configurations or firewalls on the network used for
- internal cluster communication.
-
-Performance Tuning for Busy Clusters
-====================================
-
-Beginning with version 3.2.0, Apache Traffic Server can handle multiple internal
-cluster connections and the number of Cluster Threads is configurable. Each
-of the threads will keep one connection open to all peering cluster nodes.
-
-Increasing Cluster Threads
---------------------------
-
-In the cluster environment, the current performance of the cluster threads
-will consume the same cpu usage as a normal network thread. It's reasonable
-to keep roughly the same number of cluster threads as network threads. For
-example, if you are running a system with 10 network processing threads,
-you can set the number of cluster threads by modifying
-:ts:cv:`proxy.config.cluster.threads` to ``10``::
-
- traffic_ctl config set proxy.config.cluster.threads 10
-
diff --git a/doc/admin-guide/files/cluster.config.en.rst b/doc/admin-guide/files/cluster.config.en.rst
deleted file mode 100644
index c08c296..0000000
--- a/doc/admin-guide/files/cluster.config.en.rst
+++ /dev/null
@@ -1,85 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-.. include:: ../../common.defs
-
-.. configfile:: cluster.config
-
-cluster.config
-**************
-
-The :file:`cluster.config` tracks |TS| cluster membership, allowing more than
-one server running |TS| to coordinate and either replicate or distribute cache
-operations.
-
-For the contents of this file to reflect any clustering peers, |TS| clustering
-must first be enabled by adjusting :ts:cv:`proxy.local.cluster.type`.
-
-For information on how to enable and configure |TS| clustering, refer to the
-:ref:`traffic-server-cluster` section.
-
-.. danger::
-
- The :file:`cluster.config` configuration file is generated and managed by
- |TS| itself and should not be modified directly.
-
-Format
-======
-
-The format of :file:`cluster.config` is simple. Lines beginning with ``#`` are
-comments and, as such, will be ignored by |TS|. The first non-comment,
-non-empty line is an integer indicating the number of |TS| cluster peers for
-the current node. If the current node is not a member of a cluster, this value
-will be ``0``.
-
-Following lines provide the ``<address>:<port>`` of each peer in the cluster.
-By default, |TS| uses ``8086`` for cluster communication. This may be adjusted
-with :ts:cv:`proxy.config.cluster.cluster_port`. Note that this setting is in
-the ``CONFIG`` scope, which means it must be set to the same value on all
-cluster peers.
-
-Examples
-========
-
-Stand-alone Proxy
------------------
-
-When running a single |TS| node without a cluster, the configuration file will
-simply contain a zero, indicating that there are no cluster peers, as so::
-
- 0
-
-Because there are zero peers in the (non-existent) cluster, no address lines
-follow.
-
-Multiple Peers
---------------
-
-In a cluster with four members (including the current node), the configuration
-will appear as::
-
- 3
- 127.1.2.3:8086
- 127.1.2.4:8086
- 127.1.2.5:8086
-
-Though, of course, the IP addresses will be appropriate for your network. If
-you have configured your |TS| nodes to use a cluster management port other than
-the default ``8086`` the port numbers will differ, as well.
-
-The configuration will not include the current |TS| node's address, only its
-peers' addresses.
diff --git a/doc/admin-guide/files/index.en.rst b/doc/admin-guide/files/index.en.rst
index 2fe38a7..bd62751 100644
--- a/doc/admin-guide/files/index.en.rst
+++ b/doc/admin-guide/files/index.en.rst
@@ -26,7 +26,6 @@ Configuration Files
:hidden:
cache.config.en
- cluster.config.en
congestion.config.en
hosting.config.en
ip_allow.config.en
@@ -46,9 +45,6 @@ Configuration Files
Defines if, how, and for what durations |TS| caches objects, based on
destinations, clients, URL components, and more.
-:doc:`cluster.config.en`
- Manages |TS| cluster configuration and membership on each node.
-
:doc:`congestion.config.en`
Defines network conditions under which clients will receive retry messages
instead of |TS| contacting origin servers.
diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst
index ecf52a7..a02a858 100644
--- a/doc/admin-guide/files/records.config.en.rst
+++ b/doc/admin-guide/files/records.config.en.rst
@@ -2119,9 +2119,9 @@ Heuristic Expiration
These fuzzing options are marked as deprecated as of v6.2.0, and will be
removed for v7.0.0. Instead, we recommend looking at the new
- :ts:cv:`proxy-config-http-cache-open-write-fail-action` configuration and
+ :ts:cv:`proxy.config.http.cache.open_write_fail_action` configuration and
the features around thundering heard avoidance (see
- :ref:`cache-basics` for details).
+ :ref:`http-proxy-caching` for details).
Dynamic Content & Content Negotiation
=====================================
diff --git a/doc/admin-guide/monitoring/statistics/core-statistics.en.rst b/doc/admin-guide/monitoring/statistics/core-statistics.en.rst
index abb8ccc..2947ec7 100644
--- a/doc/admin-guide/monitoring/statistics/core-statistics.en.rst
+++ b/doc/admin-guide/monitoring/statistics/core-statistics.en.rst
@@ -36,7 +36,6 @@ component to which they're related.
core/hierarchical.en
core/hostdb.en
core/dns.en
- core/cluster.en
core/origin.en
core/network-io.en
core/ssl.en
diff --git a/doc/admin-guide/monitoring/statistics/core/cluster.en.rst b/doc/admin-guide/monitoring/statistics/core/cluster.en.rst
deleted file mode 100644
index 1bce07b..0000000
--- a/doc/admin-guide/monitoring/statistics/core/cluster.en.rst
+++ /dev/null
@@ -1,209 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-.. include:: ../../../../common.defs
-
-.. _admin-stats-core-cluster:
-
-Cluster
-*******
-
-The statistics documented in this section relate to |TS| clusters, which are
-synchronized sets of |TS| instances running across multiple hosts. For more
-information on configuring and using the clustering feature, please refer to
-the :ref:`traffic-server-cluster` chapter of the :ref:`admin-guide`.
-
-.. ts:stat:: global proxy.node.cluster.nodes integer
- :type: gauge
-
- Represents the number of |TS| instances which are members of the same cluster
- as this node.
-
-.. ts:stat:: global proxy.process.cluster.alloc_data_news integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.byte_bank_used integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.cache_callbacks integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.cache_callback_time float
-.. ts:stat:: global proxy.process.cluster.cache_outstanding integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.chan_inuse integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.cluster_ping_time float
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.configuration_changes integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.connections_avg_time float
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.connections_bumped integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.connections_closed integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.connections_opened integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.connections_open integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.connections_read_locked integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.connections_write_locked integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.control_messages_avg_receive_time float
-.. ts:stat:: global proxy.process.cluster.control_messages_avg_send_time float
-.. ts:stat:: global proxy.process.cluster.control_messages_received integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.control_messages_sent integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.delayed_reads integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.level1_bank integer
-.. ts:stat:: global proxy.process.cluster.lkrmt_cache_callbacks integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.lkrmt_cache_callback_time float
-.. ts:stat:: global proxy.process.cluster.local_connections_closed integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.local_connection_time float
-.. ts:stat:: global proxy.process.cluster.machines_allocated integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.machines_freed integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.multilevel_bank integer
-.. ts:stat:: global proxy.process.cluster.net_backup integer
-.. ts:stat:: global proxy.process.cluster.nodes integer
- :type: gauge
-
-.. ts:stat:: global proxy.process.cluster.no_remote_space integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.op_delayed_for_lock integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.open_delays integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.open_delay_time float
-.. ts:stat:: global proxy.process.cluster.partial_reads integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.partial_writes integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.rdmsg_assemble_time float
-.. ts:stat:: global proxy.process.cluster.read_bytes integer
- :type: counter
- :unit: bytes
-
-.. ts:stat:: global proxy.process.cluster.reads integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.remote_connections_closed integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.remote_connection_time float
-.. ts:stat:: global proxy.process.cluster.remote_op_reply_timeouts integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.remote_op_timeouts integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.rmt_cache_callbacks integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.rmt_cache_callback_time float
-.. ts:stat:: global proxy.process.cluster.setdata_no_cachevc integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.setdata_no_cluster integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.setdata_no_clustervc integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.setdata_no_tunnel integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.slow_ctrl_msgs_sent integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_insert_lock_misses integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_inserts integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_lookup_hits integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_lookup_lock_misses integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_lookup_misses integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_purges integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_scan_lock_misses integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_cache_scans integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_read_list_len integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_write_list_len integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.vc_write_stall integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.write_bb_mallocs integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.write_bytes integer
- :type: counter
- :unit: bytes
-
-.. ts:stat:: global proxy.process.cluster.write_lock_misses integer
- :type: counter
-
-.. ts:stat:: global proxy.process.cluster.writes integer
- :type: counter
-
-
diff --git a/doc/appendices/faq.en.rst b/doc/appendices/faq.en.rst
index 861f69a..5697e4e 100644
--- a/doc/appendices/faq.en.rst
+++ b/doc/appendices/faq.en.rst
@@ -348,7 +348,7 @@ minutes to transfer the object. This inaccuracy is more noticeable with
a light load. A heavier load yields a more accurate statistic.
You are unable to execute Traffic Control commands
------------------------------------------------
+--------------------------------------------------
:program:`traffic_ctl` commands do not execute under the following conditions:
@@ -595,4 +595,3 @@ origin servers. If you cannot avoid such timeouts by otherwise addressing the
performance on your origin servers, you may adjust the origin connection timeout
in Traffic Server by changing :ts:cv:`proxy.config.http.connect_attempts_timeout`
in :file:`records.config` to a larger value.
-
diff --git a/doc/checkvers.py b/doc/checkvers.py
index c648f4e..cc95053 100644
--- a/doc/checkvers.py
+++ b/doc/checkvers.py
@@ -28,15 +28,20 @@ if __name__ == '__main__':
# Check whether we have a recent version of sphinx. EPEL and CentOS are completely crazy and I don't understand their
# packaging at all. The test below works on Ubuntu and places where sphinx is installed sanely AFAICT.
if options.checkvers:
- print 'checking for sphinx version >= 1.1... ',
+ print 'checking for sphinx version >= 1.2... ',
+ # Need at least 1.2 because of some command line options stuff HRP added.
+ # Also 1.2 guarantees sphinx.version_info is available.
try:
import sphinx
-
- version = sphinx.__version__
- print 'found ' + sphinx.__version__
-
- (major, minor, micro) = version.split('.')
- if (int(major) < 1) or (int(major) == 1 and int(minor) < 1):
+
+ if 'version_info' in dir(sphinx) :
+ print 'Found Sphinx version {0}'.format(sphinx.version_info)
+ else :
+ version = sphinx.__version__
+ print 'Found Sphinx version (old) {0}'.format(sphinx.__version__)
+ sphinx.version_info = version.split('.')
+
+ if sphinx.version_info < (1,2) :
sys.exit(1)
except Exception as e:
diff --git a/doc/conf.py b/doc/conf.py
index c34ad4f..dd26cd7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -28,6 +28,7 @@
# serve to show the default.
import sys, os
+from sphinx import version_info
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
@@ -51,11 +52,15 @@ extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
- 'sphinx.ext.pngmath',
'sphinx.ext.viewcode',
'traffic-server',
]
+if version_info >= (1,4) :
+ extensions.append('sphinx.ext.imgmath')
+else :
+ extensions.append('sphinx.ext.pngmath')
+
# XXX Disabling docxygen for now, since it make RTD documentation builds time
# out, eg. https://readthedocs.org/projects/trafficserver/builds/3525976/
# extensions += [
diff --git a/doc/developer-guide/api/functions/TSHttpTxnInfoIntGet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnInfoIntGet.en.rst
index 4fa9c9e..a8d2eea 100644
--- a/doc/developer-guide/api/functions/TSHttpTxnInfoIntGet.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpTxnInfoIntGet.en.rst
@@ -23,11 +23,11 @@ Synopsis
`#include <ts/ts.h>`
-.. c:function:: TSReturnCode TSHttpTxnInfoIntGet(TSHttpTxn txnp, TSHttpTxnInfoKey key, TSMgmtInt *value)
-
+.. c:function:: TSReturnCode TSHttpTxnInfoIntGet(TSHttpTxn txnp, TSHttpTxnInfoKey key, TSMgmtInt * value)
Description
-----------
+
:c:func:`TSHttpTxnInfoIntGet` returns arbitrary integer-typed info about a transaction as defined in
:c:type:`TSHttpTxnInfoKey`. The API will be part of a generic API umbrella that can support returning
arbitrary info about a transaction using custom log tags. It works on multiple hooks depending on the
@@ -35,35 +35,37 @@ requested info. For example, cache related info may be available only at or afte
The :c:type:`TSHttpTxnInfoKey` currently supports the below integer-based info about a transaction
- :c:data:`TS_TXN_INFO_CACHE_HIT_RAM`
+.. c:type:: TSHttpTxnInfoKey
+
+ .. c:member:: TS_TXN_INFO_CACHE_HIT_RAM
- This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
- is returned from RAM cache. A value of 0 indicates otherwise.
+ This info is available at or after :c:member:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of :literal:`1` indicates that the response
+ is returned from RAM cache. A value of :literal:`0` indicates otherwise.
- :c:data:`TS_TXN_INFO_CACHE_COMPRESSED_IN_RAM`
+ .. c:member:: TS_TXN_INFO_CACHE_COMPRESSED_IN_RAM
- This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
- is returned from RAM cache and is compressed. A value of 0 indicates otherwise.
+ This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
+ is returned from RAM cache and is compressed. A value of 0 indicates otherwise.
- :c:data:`TS_TXN_INFO_CACHE_HIT_RWW`
+ .. c:member:: TS_TXN_INFO_CACHE_HIT_RWW
- This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
- is returned via Read-While-Writer functionality. A value of 0 indicates otherwise.
+ This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. A value of 1 indicates that the response
+ is returned via Read-While-Writer functionality. A value of 0 indicates otherwise.
- :c:data:`TS_TXN_INFO_CACHE_OPEN_READ_TRIES`
+ .. c:member:: TS_TXN_INFO_CACHE_OPEN_READ_TRIES
- This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the number of cache open
- read reattempts made by the transaction on cache open read failure.
+ This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the number of cache open
+ read reattempts made by the transaction on cache open read failure.
- :c:data:`TS_TXN_INFO_CACHE_OPEN_WRITE_TRIES`
+ .. c:member:: TS_TXN_INFO_CACHE_OPEN_WRITE_TRIES
- This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the number of cache open
- write reattempts made by the transaction on cache open write failure.
+ This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the number of cache open
+ write reattempts made by the transaction on cache open write failure.
- :c:data:`TS_TXN_INFO_CACHE_VOLUME`
+ .. c:member:: TS_TXN_INFO_CACHE_VOLUME
- This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the cache volume ID used
- for the cache object associated with the transaction.
+ This info is available at or after :c:data:`TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK` hook. The value indicates the cache volume ID used
+ for the cache object associated with the transaction.
Return values
-------------
diff --git a/doc/developer-guide/api/functions/TSHttpTxnIsInternal.en.rst b/doc/developer-guide/api/functions/TSHttpTxnIsInternal.en.rst
index f884a45..d0804bb 100644
--- a/doc/developer-guide/api/functions/TSHttpTxnIsInternal.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpTxnIsInternal.en.rst
@@ -42,7 +42,7 @@ Return Values
=============
Both these APIs return a :type:`int`, indicating whether the
-request was internal (:data:`1`) or not (:data:`0`).
+request was internal (:literal:`1`) or not (:literal:`0`).
Examples
========
@@ -50,7 +50,7 @@ Examples
The ESI plugin uses :func:`TSHttpTxnIsInternal` to ignore requests that is
had generated while fetching portions of an ESI document:
-.. literalinclude:: ../../../../plugins/experimental/esi/esi.cc
+.. literalinclude:: ../../../../plugins/esi/esi.cc
:language: c
:lines: 1395-1398
diff --git a/doc/developer-guide/api/functions/TSHttpTxnServerAddrSet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnServerAddrSet.en.rst
index 0ddd306..5100513 100644
--- a/doc/developer-guide/api/functions/TSHttpTxnServerAddrSet.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpTxnServerAddrSet.en.rst
@@ -26,7 +26,7 @@ Synopsis
`#include <ts/ts.h>`
-.. function:: TSReturnCode TSHttpTxnServerAddrGet(TSHttpTxn txnp, struct sockaddr const* addr)
+.. function:: TSReturnCode TSHttpTxnServerAddrSet(TSHttpTxn txnp, struct sockaddr const* addr)
Description
===========
diff --git a/doc/developer-guide/api/functions/TSMBufferCreate.en.rst b/doc/developer-guide/api/functions/TSMBufferCreate.en.rst
index 5277a05..4b7e3c7 100644
--- a/doc/developer-guide/api/functions/TSMBufferCreate.en.rst
+++ b/doc/developer-guide/api/functions/TSMBufferCreate.en.rst
@@ -40,7 +40,7 @@ out of marshal buffers, and change the values within the marshal buffer.
Whenever you manipulate an object, you require the handle to the object
(:type:`TSMLoc`) and the marshal buffer containing the object (:type:`TSMBuffer`).
-Any marshal buffer fetched by :func:`TSHttpTxn*Get` will be used by other parts
+Any marshal buffer fetched by transaction getters will be used by other parts
of the system. Be careful not to destroy these shared, transaction marshal buffers.
:func:`TSMBufferCreate` creates a new marshal buffer and initializes
diff --git a/doc/developer-guide/api/functions/TSSslContextFindBy.en.rst b/doc/developer-guide/api/functions/TSSslContextFindBy.en.rst
index ffc1d27..b9bc07e 100644
--- a/doc/developer-guide/api/functions/TSSslContextFindBy.en.rst
+++ b/doc/developer-guide/api/functions/TSSslContextFindBy.en.rst
@@ -29,6 +29,7 @@ Synopsis
`#include <ts/ts.h>`
.. function:: TSSslContext TSSslContextFindByName(const char * name)
+
.. function:: TSSslContext TSSslContextFindByAddr(const struct sockaddr * address)
Description
@@ -42,13 +43,6 @@ server :arg:`name`.
created from :file:`ssl_multicert.config` matchin against the server
:arg:`address`.
-Type
-====
-
-.. type:: TSSslContext
-
-The SSL context object. This is an opaque type that can be cast to
-the underlying SSL library type (SSL_CTX * for the OpenSSL library).
See also
========
diff --git a/doc/developer-guide/api/functions/TSTypes.en.rst b/doc/developer-guide/api/functions/TSTypes.en.rst
index 9d76101..c3c069f 100644
--- a/doc/developer-guide/api/functions/TSTypes.en.rst
+++ b/doc/developer-guide/api/functions/TSTypes.en.rst
@@ -48,15 +48,6 @@ more widely. Those are described on this page.
An opaque type that represents a Traffic Server :term:`continuation`.
-.. type:: TSEvent
-
- :type:`TSEvents` are sent to continuations when they are called
- back.
-
- The :type:`TSEvent` provides the continuation's handler function
- with information about the callback. Based on the event it
- receives, the handler function can decide what to do.
-
.. type:: TSEventFunc
.. type:: TSFile
@@ -69,10 +60,6 @@ more widely. Those are described on this page.
A 64 bit time value, measured in nanoseconds.
-.. type:: TSHttpHookID
-
- An enumeration that identifies a specific type of hook for HTTP transactions.
-
.. type:: TSHttpParser
.. type:: TSHttpSsn
@@ -137,6 +124,10 @@ more widely. Those are described on this page.
.. type:: TSMLoc
+.. var:: TSMLoc TS_NULL_MLOC
+
+ A predefined null valued :type:`TSMLoc` used to indicate the absence of an :type:`TSMLoc`.
+
.. type:: TSMutex
.. type:: TSParseResult
@@ -188,3 +179,4 @@ more widely. Those are described on this page.
.. type:: TSVConn
.. type:: TSVIO
+
diff --git a/doc/developer-guide/api/functions/TSVConnTunnel.en.rst b/doc/developer-guide/api/functions/TSVConnTunnel.en.rst
index abe0d7c..0669b9a 100644
--- a/doc/developer-guide/api/functions/TSVConnTunnel.en.rst
+++ b/doc/developer-guide/api/functions/TSVConnTunnel.en.rst
@@ -32,8 +32,8 @@ Description
===========
Set the SSL connection :arg:`svc` to convert to a blind tunnel. Can be called
-from :data:`TS_VCONN_PRE_ACCEPT_HOOK` or :data:`TS_SSL_SNI_HOOK/TS_SSL_CERT_HOOK`.
+from :member:`TS_VCONN_PRE_ACCEPT_HOOK` or :member:`TS_SSL_SNI_HOOK` / :member:`TS_SSL_CERT_HOOK`.
-For this to work from the :data:`TS_SSL_SNI_HOOK` or :data:`TS_SSL_CERT_HOOK`,
+For this to work from the :member:`TS_SSL_SNI_HOOK` or :member:`TS_SSL_CERT_HOOK`,
either the server must be running OpenSSL 1.0.2 or a version of OpenSSL 1.0.1
with the appropriate patch installed.
diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py
index 91f286e..0711f0e 100644
--- a/doc/ext/traffic-server.py
+++ b/doc/ext/traffic-server.py
@@ -19,9 +19,9 @@
"""
TS Sphinx Directives
~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
Sphinx Docs directives for Apache Traffic Server
-
+
:copyright: Copyright 2013 by the Apache Software Foundation
:license: Apache
"""
@@ -133,9 +133,14 @@ class TSConfVar(std.Target):
# index. nodes.make_id() specifies the link anchor name that is
# implicitly generated by the anchor node above.
indexnode = sphinx.addnodes.index(entries=[])
- indexnode['entries'].append(
- ('single', _('%s') % cv_name, nodes.make_id(cv_name), '')
- )
+ if sphinx.version_info >= (1, 4) :
+ indexnode['entries'].append(
+ ('single', _('%s') % cv_name, nodes.make_id(cv_name), '', '')
+ )
+ else :
+ indexnode['entries'].append(
+ ('single', _('%s') % cv_name, nodes.make_id(cv_name), '')
+ )
return [ indexnode, node, fl, nn ]
@@ -252,9 +257,15 @@ class TSStat(std.Target):
# index. nodes.make_id() specifies the link anchor name that is
# implicitly generated by the anchor node above.
indexnode = sphinx.addnodes.index(entries=[])
- indexnode['entries'].append(
- ('single', _('%s') % stat_name, nodes.make_id(stat_name), '')
- )
+
+ if sphinx.version_info >= (1, 4) :
+ indexnode['entries'].append(
+ ('single', _('%s') % stat_name, nodes.make_id(stat_name), '', '')
+ )
+ else :
+ indexnode['entries'].append(
+ ('single', _('%s') % stat_name, nodes.make_id(stat_name), '')
+ )
return [ indexnode, node, fl, nn ]
diff --git a/doc/manpages.py b/doc/manpages.py
index 7b0aae2..3ccd9de 100644
--- a/doc/manpages.py
+++ b/doc/manpages.py
@@ -35,7 +35,6 @@ man_pages = [
('appendices/command-line/traffic_via.en', 'traffic_via', u'Traffic Server Via header decoder', None, '1'),
('admin-guide/files/cache.config.en', 'cache.config', u'Traffic Server cache configuration file', None, '5'),
- ('admin-guide/files/cluster.config.en', 'cluster.config', u'Traffic Server cluster configuration file', None, '5'),
('admin-guide/files/congestion.config.en', 'congestion.config', u'Traffic Server congestion control configuration file', None, '5'),
('admin-guide/files/hosting.config.en', 'hosting.config', u'Traffic Server domain hosting configuration file', None, '5'),
('admin-guide/files/ip_allow.config.en', 'ip_allow.config', u'Traffic Server IP access control configuration file', None, '5'),
--
To stop receiving notification emails like this one, please contact
"commits@trafficserver.apache.org" <co...@trafficserver.apache.org>.