trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dra...@apache.org
Subject [trafficserver] branch master updated: Doc: Add documentation for a few C API functions, clean up doc build errors.
Date Thu, 23 May 2019 16:05:54 GMT
This is an automated email from the ASF dual-hosted git repository.

dragon pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new e2444b9  Doc: Add documentation for a few C API functions, clean up doc build errors.
e2444b9 is described below

commit e2444b9a6686bc81b0d5b0420e2810ba8455ec74
Author: Alan M. Carroll <amc@apache.org>
AuthorDate: Wed May 22 17:29:19 2019 -0500

    Doc: Add documentation for a few C API functions, clean up doc build errors.
---
 doc/admin-guide/performance/index.en.rst           |   2 +-
 doc/admin-guide/plugins/background_fetch.en.rst    | 103 ++++++++++-----------
 doc/admin-guide/security/index.en.rst              |   5 +-
 doc/appendices/glossary.en.rst                     |   6 ++
 .../api/functions/TSHttpHdrUrlGet.en.rst           |  18 ++++
 .../api/functions/TSHttpTxnClientReqGet.en.rst     |  20 ++++
 .../api/functions/TSHttpTxnIsCacheable.en.rst      |  38 ++++++++
 doc/developer-guide/api/functions/TSTypes.en.rst   |   2 -
 .../api/functions/TSUrlHostGet.en.rst              |   1 +
 .../api/functions/TSVConnSslVerifyCTXGet.en.rst    |   5 -
 doc/developer-guide/api/types/TSMgmtTypes.en.rst   |   6 +-
 doc/developer-guide/config-vars.en.rst             |   2 +-
 .../internal-libraries/Extendible.en.rst           |  28 +++---
 .../internal-libraries/scalar.en.rst               |   2 +-
 .../hooks-and-transactions/ssl-hooks.en.rst        |  92 ++++++++++--------
 15 files changed, 208 insertions(+), 122 deletions(-)

diff --git a/doc/admin-guide/performance/index.en.rst b/doc/admin-guide/performance/index.en.rst
index ed3d718..64520ee 100644
--- a/doc/admin-guide/performance/index.en.rst
+++ b/doc/admin-guide/performance/index.en.rst
@@ -488,7 +488,7 @@ Network Tuning
 :ts:cv:`proxy.config.net.connections_throttle`
 
 Error responses from origins are consistent and costly
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If error responses are costly for your origin server to generate, you may elect
 to have |TS| cache these responses for a period of time. The default behavior is
diff --git a/doc/admin-guide/plugins/background_fetch.en.rst b/doc/admin-guide/plugins/background_fetch.en.rst
index 2f62c19..1e2f511 100644
--- a/doc/admin-guide/plugins/background_fetch.en.rst
+++ b/doc/admin-guide/plugins/background_fetch.en.rst
@@ -1,91 +1,86 @@
-.. _admin-plugins-background-fetch:
+.. 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
 
-Background Fetch Plugin
-***********************
+   http://www.apache.org/licenses/LICENSE-2.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
+   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.
 
-   http://www.apache.org/licenses/LICENSE-2.0
+.. _admin-plugins-background-fetch:
+.. include:: /common.defs
 
-  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.
+Background Fetch Plugin
+***********************
 
 
-This is a plugin for Apache Traffic Server that allows you to proactively
-fetch content from Origin in a way that it will fill the object into
-cache. This is particularly useful when all (or most) of your client requests
-are of the byte-Range type. The underlying problem being that Traffic Server
-is not able to cache request / responses with byte ranges.
+This is a plugin for |TS| that allows you to proactively fetch content from Origin in a way
that it
+will fill the object into cache. This is particularly useful when all (or most) of your client
+requests are of the byte-Range type. The underlying problem being that Traffic Server is
not able to
+cache request / responses with byte ranges.
 
 Using the plugin
 ----------------
 
-This plugin functions as either a global or per remap plugin, and it takes
-an optional argument for specifying a config file with inclusion or
-exclusion criteria. The config file can be specified both via an absolute
-path or via a relative path to the install dir
+This plugin functions as either a global or per remap plugin, and it takes an optional argument
for
+specifying a config file with inclusion or exclusion criteria. The config file can be specified
both
+via an absolute path or via a relative path to the install dir
 
 To activate the plugin in global mode, in :file:`plugin.config`, simply add::
 
-  background_fetch.so --config <config-file>
+   background_fetch.so --config <config-file>
 
 To activate the plugin in per remap mode, in :file:`remap.config`, simply append the
 below to the specific remap line::
 
-  @plugin=background_fetch.so @pparam=<config-file>
+   @plugin=background_fetch.so @pparam=<config-file>
 
 Functionality
 -------------
 
-Examining the responses from origin, we decide to trigger a background fetch
-of the original (Client) request under these conditions:
+Examining the responses from origin, we decide to trigger a background fetch of the original
+(Client) request under these conditions:
+
+*  The request is a ``GET`` request (we only support these right now)
+
+*  The response is a ``206`` response
 
-- The request is a ``GET`` request (we only support these right now)
-- The response is a ``206`` response
-- The original client request, and the Origin server response, is clearly
-  indicating that the response is cacheable. This uses the new API
-  :c:func:`TSHttpTxnIsCacheable()`, which also implies honoring current
-  Traffic Server configurations.
+*  The original client request, and the Origin server response, is clearly indicating that
the
+   response is cacheable. This uses the new API :c:func:`TSHttpTxnIsCacheable()`, which also
implies
+   honoring current Traffic Server configurations.
 
 
-Once deemed a good candidate to performance a background fetch, we'll replay
-the original client request through the Traffic Server proxy again, except
-this time eliminating the ``Range`` header. This is transparent to the
-original client request, which continues as normal.
+Once deemed a good candidate to performance a background fetch, we'll replay the original
client
+request through the Traffic Server proxy again, except this time eliminating the ``Range``
header.
+This is transparent to the original client request, which continues as normal.
 
-Only one background fetch per URL is ever performed, making sure we do not
-accidentally put pressure on the origin servers.
+Only one background fetch per URL is ever performed, making sure we do not accidentally put
pressure
+on the origin servers.
 
-The plugin now supports a config file that can specify exclusion or inclusion of
-background fetch based on any arbitrary header or client-ip::
+The plugin now supports a config file that can specify exclusion or inclusion of background
fetch
+based on any arbitrary header or client-ip::
 
-  background_fetch.so --config <config-file>
+   background_fetch.so --config <config-file>
 
 The contents of the config-file could be as below::
 
-  include User-Agent ABCDEF
-  exclude User-Agent *
-  exclude Content-Type text
-  exclude X-Foo-Bar text
-  exclude Content-Length <1000
+   include User-Agent ABCDEF
+   exclude User-Agent *
+   exclude Content-Type text
+   exclude X-Foo-Bar text
+   exclude Content-Length <1000
 
-The plugin also now supports per remap activation. To activate the plugin for
-a given remap, add the below on the remap line::
+The plugin also now supports per remap activation. To activate the plugin for a given remap,
add the
+below on the remap line::
 
-  @plugin=background_fetch.so @pparam=<config-file>
+   @plugin=background_fetch.so @pparam=<config-file>
 
 Future additions
 ----------------
 
-- Limiting the background fetches to content of certain sizes
+*  Limiting the background fetches to content of certain sizes.
 
diff --git a/doc/admin-guide/security/index.en.rst b/doc/admin-guide/security/index.en.rst
index 7be8dd9..bbba4a8 100644
--- a/doc/admin-guide/security/index.en.rst
+++ b/doc/admin-guide/security/index.en.rst
@@ -284,9 +284,10 @@ Authority Information Access field of the signed certificate. For example::
 Traffic Server can also use prefetched OCSP stapling responses if ssl_ocsp_name parameter
 is used in :file:`ssl_multicert.config`. Take into account that when using prefetched
 OCSP stapling responses traffic server will not refresh them and it should be done
-externally. This can be done using openssl:
+externally. This can be done using openssl::
+
     $ openssl ocsp -issuer ca.crt -cert cert.crt -host ocsp.digicert.com:80 \
-      -header "Host=ocsp.digicert.com" -respout /var/cache/ocsp/cert.ocsp
+    -header "Host=ocsp.digicert.com" -respout /var/cache/ocsp/cert.ocsp
 
 Support for OCSP Stapling can be tested using the -status option of the OpenSSL client::
 
diff --git a/doc/appendices/glossary.en.rst b/doc/appendices/glossary.en.rst
index f4ae4b8..02318ae 100644
--- a/doc/appendices/glossary.en.rst
+++ b/doc/appendices/glossary.en.rst
@@ -55,6 +55,12 @@ Glossary
       cache. A transaction begins when |TS| receives a request, and ends when
       |TS| sends the response.
 
+   client request
+      The HTTP request sent from the user agent (the client) to |TS|.
+
+   proxy request
+      The HTTP request sent from |TS| (the proxy) to the upstream.
+
    cache volume
       A user defined unit of persistent storage for the cache. Cache volumes
       are defined in :file:`volume.config`. A cache volume is by default spread
diff --git a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst
index c6dbd0e..555ede1 100644
--- a/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpHdrUrlGet.en.rst
@@ -30,3 +30,21 @@ Synopsis
 
 Description
 ===========
+
+Get a URL object from an HTTP header. :arg:`bufp` and :arg:`offset` must have been retrieved
from
+a header object previously (such as via :func:`TSHttpTxnClientReqGet`). :arg:`locp` is updated
+on success to refer to the URL object. Note this is a URL *object*, from which URL related
+information can be extracted.
+
+The value placed in :arg:`locp` is stable only for a single callback, as other callbacks
can
+change the URL object itself (see :func:`TSHttpHdrUrlSet`), not just the data in it. That
value is
+also valid only if this function return ``TS_SUCCESS``.
+
+See Also
+========
+
+:manpage:`TSAPI(3ts)`,
+:manpage:`TSHttpTxnClientReqGet(3ts)`,
+:manpage:`TSHttpTxnServerReqGet(3ts)`,
+:manpage:`TSHttpTxnServerRespGet(3ts)`,
+:manpage:`TSHttpTxnClientRespGet(3ts)`
diff --git a/doc/developer-guide/api/functions/TSHttpTxnClientReqGet.en.rst b/doc/developer-guide/api/functions/TSHttpTxnClientReqGet.en.rst
index 96b8541..1d59ab1 100644
--- a/doc/developer-guide/api/functions/TSHttpTxnClientReqGet.en.rst
+++ b/doc/developer-guide/api/functions/TSHttpTxnClientReqGet.en.rst
@@ -30,3 +30,23 @@ Synopsis
 
 Description
 ===========
+
+Get the client request. The :arg:`txnp` must be passed in and the values in :arg:`bufp` and
+:arg:`offset` are updated to refer to the client request in the transaction. A typical use
case
+would look like ::
+
+   int
+   CB_Read_Req_Hdr_Hook(TSCont contp, TSEvent event, void* data) {
+      auto txnp = reinterpret_cast<TSHttpTxn>(data);
+      TSMBuffer creq_buff;
+      TSMLoc creq_loc;
+      if (TS_SUCCESS == TSHttpTxnClientReqGet(txnp, &creq_buff, &creq_loc)) {
+         // use the client request
+      } // else values in creq_buff, creq_loc are garbage.
+      TSHttpTxnReenable(txnp);
+      return 0;
+   }
+
+The values placed in :arg:`bufp` and :arg:`offset` are stable for the transaction and need
only be
+retrieved once per transaction. Note these values are valid only if this function returns
+``TS_SUCCESS``.
diff --git a/doc/developer-guide/api/functions/TSHttpTxnIsCacheable.en.rst b/doc/developer-guide/api/functions/TSHttpTxnIsCacheable.en.rst
new file mode 100644
index 0000000..58f40e4
--- /dev/null
+++ b/doc/developer-guide/api/functions/TSHttpTxnIsCacheable.en.rst
@@ -0,0 +1,38 @@
+.. 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
+
+.. default-domain:: c
+
+TSHttpTxnIsCacheable
+********************
+
+Synopsis
+========
+
+`#include <ts/ts.h>`
+
+.. function:: TSReturnCode TSHttpTxnIsCacheable(TSHttpTxn txnp, TSMBuffer request, TSMBuffer
response)
+
+Description
+===========
+
+Determine if an upstream response is cacheable according to the current |TS| configuration
and
+state. All of the arguments must have be obtained via other API calls prior to calling this
+function.
+
+The :arg:`request` and :arg:`response` arguments must refer to HTTP header objects. These
are
+treated as the request and response for a transaction respectively. Based on the transaction
state
+from :arg:`txnp` and the contents of the request and response, this returns ``TS_SUCCESS``
if the
+response is cacheable, ``TS_ERROR`` otherwise.
diff --git a/doc/developer-guide/api/functions/TSTypes.en.rst b/doc/developer-guide/api/functions/TSTypes.en.rst
index d0f85d9..6738202 100644
--- a/doc/developer-guide/api/functions/TSTypes.en.rst
+++ b/doc/developer-guide/api/functions/TSTypes.en.rst
@@ -58,8 +58,6 @@ more widely. Those are described on this page.
 
 .. type:: TSConfig
 
-.. type:: TSConfigDestroyFunc
-
 .. type:: TSCont
 
    An opaque type that represents a Traffic Server :term:`continuation`.
diff --git a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst
index 30f38f0..d5d2db1 100644
--- a/doc/developer-guide/api/functions/TSUrlHostGet.en.rst
+++ b/doc/developer-guide/api/functions/TSUrlHostGet.en.rst
@@ -77,6 +77,7 @@ See Also
 
 :manpage:`TSAPI(3ts)`,
 :manpage:`TSUrlCreate(3ts)`,
+:manpage:`TSHttpHdrUrlGet(3ts)`,
 :manpage:`TSUrlHostSet(3ts)`,
 :manpage:`TSUrlStringGet(3ts)`,
 :manpage:`TSUrlPercentEncode(3ts)`
diff --git a/doc/developer-guide/api/functions/TSVConnSslVerifyCTXGet.en.rst b/doc/developer-guide/api/functions/TSVConnSslVerifyCTXGet.en.rst
index f2dd6ea..c35a25c 100644
--- a/doc/developer-guide/api/functions/TSVConnSslVerifyCTXGet.en.rst
+++ b/doc/developer-guide/api/functions/TSVConnSslVerifyCTXGet.en.rst
@@ -40,11 +40,6 @@ invoked from the TS_SSL_VERIFY_SERVER_HOOK and TS_SSL_VERIFY_CLIENT_HOOK.
 Types
 =====
 
-.. type:: TSSslConnection
-
-	The SSL (per connection) object. This is an opaque type that can be cast to the
-	appropriate type (:code:`SSL *` for the OpenSSL library).
-
 .. type:: TSSslVerifyCTX
 
         The SSL object that corresponds to the peer certificates being verified.  This is
an
diff --git a/doc/developer-guide/api/types/TSMgmtTypes.en.rst b/doc/developer-guide/api/types/TSMgmtTypes.en.rst
index 435fe95..854163b 100644
--- a/doc/developer-guide/api/types/TSMgmtTypes.en.rst
+++ b/doc/developer-guide/api/types/TSMgmtTypes.en.rst
@@ -83,8 +83,10 @@ Management Events
 .. c:macro:: MGMT_EVENT_LIFECYCLE_MESSAGE
 
 
-OpTypes (Possible operations or messages that can be sent between TM and remote clients)
-====================================================================================
+OpTypes
+=======
+
+Possible operations or messages that can be sent between TM and remote clients.
 
 .. cpp:type:: OpType
 
diff --git a/doc/developer-guide/config-vars.en.rst b/doc/developer-guide/config-vars.en.rst
index 5a25e64..11fd9c8 100644
--- a/doc/developer-guide/config-vars.en.rst
+++ b/doc/developer-guide/config-vars.en.rst
@@ -265,7 +265,7 @@ action.
 .. _http-config-var-impl:
 
 HTTP Configuration Values
-------------------------
+-------------------------
 
 Variables used for HTTP processing should be declared as members of the
 ``HTTPConfigParams`` structure (but see :ref:`overridable-config-vars` for
diff --git a/doc/developer-guide/internal-libraries/Extendible.en.rst b/doc/developer-guide/internal-libraries/Extendible.en.rst
index f386fe0..c8850f1 100644
--- a/doc/developer-guide/internal-libraries/Extendible.en.rst
+++ b/doc/developer-guide/internal-libraries/Extendible.en.rst
@@ -45,14 +45,12 @@ In C++, the |FieldId| are strongly typed field handles, which allows you
to use
 Use Case:
 
   TSCore
-
     Defines class ``Host`` as |Extendible|
 
   TSPlugin ``HealthStatus``
-
     Extend the ``Host`` datatype with field ``<int> down reason code``. API returns
a handle.
 
-    Use the (Data*, handle) to read & write fields.
+    Use :arg:`Data` and :arg:`handle` to read & write fields.
 
 
 Description
@@ -96,9 +94,9 @@ Memory Layout
 One block of memory is allocated per |Extendible|, which included all member variables and
extended fields.
 Within the block, memory is arranged in the following order:
 
-   #. Derived members (+padding align next field)
-   #. Fields (largest to smallest)
-   #. Packed Bits
+#. Derived members (+padding align next field)
+#. Fields (largest to smallest)
+#. Packed Bits
 
 When using inheritance, all base cases arranged from most super to most derived,
 then all |Extendible| blocks are arranged from most super to most derived.
@@ -196,18 +194,19 @@ Inheritance
    C &x = *(ext::alloc<C>());
    ext::viewFormat(x);
 
-:func:`viewFormat` prints a diagram of the position and size of bytes used within the allocated
memory.
-::
+:func:`viewFormat` prints a diagram of the position and size of bytes used within the allocated
+memory.
 
-   1A | EXT  | 2b | ##________##__
-   1A | BASE | 2b | __##__________
-   1B | BASE | 2b | ____##________
-   1C | EXT  | 2b | ______##____##
-   1C | BASE | 2b | ________##____
+.. code-block:: text
 
+   1A | EXT  | 2b | ##________##__ |
+   1A | BASE | 2b | __##__________ |
+   1B | BASE | 2b | ____##________ |
+   1C | EXT  | 2b | ______##____## |
+   1C | BASE | 2b | ________##____ |
 
 
-See src/tscore/unit_tests/test_Extendible.cc for more examples.
+See :ts:git:`src/tscore/unit_tests/test_Extendible.cc` for more examples.
 
 Reference
 +++++++++
@@ -236,7 +235,6 @@ Namespace `ext`
 
       one schema instance per |Extendible| to define contained |FieldDesc|
 
-
 .. function:: template<typename Derived_t> Extendible* alloc()
 
    Allocate a block of memory. Construct the base data.
diff --git a/doc/developer-guide/internal-libraries/scalar.en.rst b/doc/developer-guide/internal-libraries/scalar.en.rst
index 84c28ff..f1f4cca 100644
--- a/doc/developer-guide/internal-libraries/scalar.en.rst
+++ b/doc/developer-guide/internal-libraries/scalar.en.rst
@@ -92,7 +92,7 @@ instance that appears to store unscaled values in a quantized way. The count
is
 needed.
 
 Assignment
-=========
+==========
 
 Assigning values to, from, and between :class:`Scalar` instances is usually straightforward
with a few simple rules.
 
diff --git a/doc/developer-guide/plugins/hooks-and-transactions/ssl-hooks.en.rst b/doc/developer-guide/plugins/hooks-and-transactions/ssl-hooks.en.rst
index d164cb2..b5c91d3 100644
--- a/doc/developer-guide/plugins/hooks-and-transactions/ssl-hooks.en.rst
+++ b/doc/developer-guide/plugins/hooks-and-transactions/ssl-hooks.en.rst
@@ -48,90 +48,104 @@ The following actions are valid from these callbacks.
 TS_VCONN_START_HOOK
 ------------------------
 
-This hook is invoked after the client has connected to ATS and before the SSL handshake is
started, i.e., before any bytes have been read from the client. The data for the callback
is a TSVConn instance which represents the client connection. There is no HTTP transaction
as no headers have been read.
+This hook is invoked after the client has connected to ATS and before the SSL handshake is
started,
+i.e., before any bytes have been read from the client. The data for the callback is a TSVConn
+instance which represents the client connection. There is no HTTP transaction as no headers
have
+been read.
 
-In theory this hook could apply and be useful for non-SSL connections as well, but at this
point this hook is only called in the SSL sequence.
+In theory this hook could apply and be useful for non-SSL connections as well, but at this
point
+this hook is only called in the SSL sequence.
 
-The TLS handshake processing will not proceed until :c:func:`TSVConnReenable()` is called
either from within the hook
-callback or from another piece of code.
+The TLS handshake processing will not proceed until :c:func:`TSVConnReenable()` is called
either
+from within the hook callback or from another piece of code.
 
 TS_VCONN_CLOSE_HOOK
 ------------------------
 
-This hook is invoked after the SSL handshake is done and when the IO is closing. The TSVConnArgs
should be cleaned up here. A callback at this point must reenable.
+This hook is invoked after the SSL handshake is done and when the IO is closing. The TSVConnArgs
+should be cleaned up here. A callback at this point must reenable.
 
 TS_SSL_CLIENT_HELLO_HOOK
 ------------------------
-This hook is called when the client hello arrived for the TLS handshake. If called it will
always be called after TS_VCONN_START_HOOK. The plugin callback can execute code to examine
client hello information.
+
+This hook is called when the client hello arrived for the TLS handshake. If called it will
always be
+called after TS_VCONN_START_HOOK. The plugin callback can execute code to examine client
hello
+information.
 
 TLS handshake processing will pause until the hook callback executes :c:func:`TSVConnReenable()`.
 
 TS_SSL_SERVERNAME_HOOK
 ----------------------
 
-This hook is called if the client provides SNI information in the SSL handshake. If called
it will always be called after TS_VCONN_START_HOOK.
+This hook is called if the client provides SNI information in the SSL handshake. If called
it will
+always be called after TS_VCONN_START_HOOK.
 
-The Traffic Server core first evaluates the settings in the ssl_multicert.config file based
on the server name. Then the core SNI callback executes the plugin registered SNI callback
code. The plugin callback can access the servername by calling the openssl function SSL_get_servername().
+The Traffic Server core first evaluates the settings in the ssl_multicert.config file based
on the
+server name. Then the core SNI callback executes the plugin registered SNI callback code.
The plugin
+callback can access the servername by calling the openssl function SSL_get_servername().
 
-Processing will continue regardless of whether the hook callback executes :c:func:`TSVConnReenable()`
since the openssl
-implementation does not allow for pausing processing during the openssl servername callback.
+Processing will continue regardless of whether the hook callback executes
+:c:func:`TSVConnReenable()` since the openssl implementation does not allow for pausing processing
+during the openssl servername callback.
 
 TS_SSL_CERT_HOOK
 ----------------
 
-This hook is called as the server certificate is selected for the TLS handshake. The plugin
callback can execute
-code to create or select the certificate that should be used for the TLS handshake.  This
will override the default
-Traffic Server certificate selection.
+This hook is called as the server certificate is selected for the TLS handshake. The plugin
callback
+can execute code to create or select the certificate that should be used for the TLS handshake.
+This will override the default Traffic Server certificate selection.
 
-If you are running with openssl 1.0.2 or later, you can control whether the TLS handshake
processing will
-continue after the certificate hook callback execute by calling :c:func:`TSVConnReenable()`
or not.  The TLS
-handshake processing will not proceed until :c:func:`TSVConnReenable()` is called.
+If you are running with openssl 1.0.2 or later, you can control whether the TLS handshake
processing
+will continue after the certificate hook callback execute by calling :c:func:`TSVConnReenable()`
or
+not.  The TLS handshake processing will not proceed until :c:func:`TSVConnReenable()` is
called.
 
-It may be useful to delay the TLS handshake processing if other resources must be consulted
to select or create
-a certificate.
+It may be useful to delay the TLS handshake processing if other resources must be consulted
to
+select or create a certificate.
 
 TS_SSL_VERIFY_CLIENT_HOOK
 -------------------------
 
-This hook is called when a client connects to Traffic Server and presents a
-client certificate in the case of a mutual TLS handshake.  The callback can
-use the TSVConn argument and fetch the TSSslVerifyCTX object using the :c:func:`TXVConnSslVerifyCTXGet()`
-method and fetch the peer's certificates to make any additional checks.
+This hook is called when a client connects to |TS| and presents a client certificate in the
case of
+a mutual TLS handshake.  The callback can use the TSVConn argument and fetch the TSSslVerifyCTX
+object using the :c:func:`TSVConnSslVerifyCTXGet()` method and fetch the peer's certificates
to make
+any additional checks.
 
 Processing will continue regardless of whether the hook callback executes
-:c:func:`TSVConnReenable()` since the openssl implementation does not allow
-for pausing processing during the certificate verify callback.  The plugin can
-use the :c:func:`TSConnReenableEx()` function to pass in the TS_EVENT_ERROR and
-stop the TLS handshake.
+:c:func:`TSVConnReenable()` since the openssl implementation does not allow for pausing processing
+during the certificate verify callback.  The plugin can use the :c:func:`TSVConnReenableEx()`
+function to pass in the TS_EVENT_ERROR and stop the TLS handshake.
 
 TS_SSL_VERIFY_SERVER_HOOK
 -------------------------
 
-This hook is called when a Traffic Server connects to an origin and the origin
-presents a certificate.  The callback can use the TSVConn argument and fetch the 
-TSSslVerifyCTX object using the :c:func:`TXVConnSslVerifyCTXGet()`
-method and fetch the peer's certificates to make any additional checks.
+This hook is called when a Traffic Server connects to an origin and the origin presents a
+certificate.  The callback can use the TSVConn argument and fetch the TSSslVerifyCTX object
using
+the :c:func:`TSVConnSslVerifyCTXGet()` method and fetch the peer's certificates to make any
+additional checks.
 
 Processing will continue regardless of whether the hook callback executes
-:c:func:`TSVConnReenable()` since the openssl implementation does not allow
-for pausing processing during the certificate verify callback.  The plugin can use
-the :c:func:`TSConnReenableEx()` function to pass in the TS_EVENT_ERROR and
+:c:func:`TSVConnReenable()` since the openssl implementation does not allow for pausing processing
+during the certificate verify callback.  The plugin can use the :c:func:`TSVConnReenableEx()`
+function to pass in the TS_EVENT_ERROR and
 
 TS_VCONN_OUTBOUND_START_HOOK
 ----------------------------
 
-This hook is invoked after ATS has connected to the upstream server and before the SSL handshake
has started.  This gives the plugin the option of
-overriding the default SSL connection options on the SSL object.
+This hook is invoked after ATS has connected to the upstream server and before the SSL handshake
has
+started.  This gives the plugin the option of overriding the default SSL connection options
on the
+SSL object.
 
-In theory this hook could apply and be useful for non-SSL connections as well, but at this
point this hook is only called in the SSL sequence.
+In theory this hook could apply and be useful for non-SSL connections as well, but at this
point
+this hook is only called in the SSL sequence.
 
-The TLS handshake processing will not proceed until :c:func:`TSVConnReenable()` is called
either from within the hook
-callback or from another piece of code.
+The TLS handshake processing will not proceed until :c:func:`TSVConnReenable()` is called
either
+from within the hook callback or from another piece of code.
 
 TS_VCONN_OUTBOUND_CLOSE_HOOK
 -----------------------------
 
-This hook is invoked after the SSL handshake is done and right before the outbound connection
closes.  A callback at this point must reenable.
+This hook is invoked after the SSL handshake is done and right before the outbound connection
+closes.  A callback at this point must reenable.
 
 TLS Inbound Hook State Diagram
 ------------------------------


Mime
View raw message