This is an automated email from the ASF dual-hosted git repository. bcall pushed a commit to branch 7.0.x in repository https://git-dual.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/7.0.x by this push: new bbe16c4 Doc: tweaks and cleanup bbe16c4 is described below commit bbe16c47f36b4b04808b4bf9c27c421f525df5a8 Author: Alan M. Carroll <solidwallofc...@yahoo-inc.com> AuthorDate: Thu Oct 20 11:11:27 2016 -0500 Doc: tweaks and cleanup (cherry picked from commit 0376486474f756ec79e2c4e964464f60b96c38cc) --- 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 4ac9e40..57331ee 100644 --- a/doc/admin-guide/files/records.config.en.rst +++ b/doc/admin-guide/files/records.config.en.rst @@ -2117,9 +2117,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 91878e1..c5e71cd 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 50d45de..edcf993 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" <commits@trafficserver.apache.org>'].