This is an automated email from the ASF dual-hosted git repository.
rrm 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 7aad29c Fixes various issues found in docs
7aad29c is described below
commit 7aad29c90a9fe0dc46d4edf8b60f285806685d5f
Author: Randall Meyer <[email protected]>
AuthorDate: Mon Aug 12 09:21:11 2019 -0700
Fixes various issues found in docs
Including:
* broken links
* issues included in warnings
* spelling
---
.../monitoring/statistics/core/dns.en.rst | 2 +-
doc/admin-guide/plugins/cookie_remap.en.rst | 2 +-
.../api/functions/TSSslClientContext.en.rst | 24 ++--
.../cache-architecture/architecture.en.rst | 3 +-
.../testing/blackbox-testing.en.rst | 156 ++++++++++-----------
5 files changed, 88 insertions(+), 99 deletions(-)
diff --git a/doc/admin-guide/monitoring/statistics/core/dns.en.rst
b/doc/admin-guide/monitoring/statistics/core/dns.en.rst
index 414eb2d..0e0f93e 100644
--- a/doc/admin-guide/monitoring/statistics/core/dns.en.rst
+++ b/doc/admin-guide/monitoring/statistics/core/dns.en.rst
@@ -40,7 +40,7 @@ DNS
:units: milliseconds
:ungathered:
- The average time spent performaning DNS lookups per host.
+ The average time spent performing DNS lookups per host.
.. ts:stat:: global proxy.process.dns.lookup_failures integer
:type: counter
diff --git a/doc/admin-guide/plugins/cookie_remap.en.rst
b/doc/admin-guide/plugins/cookie_remap.en.rst
index 8973316..c06d2c3 100644
--- a/doc/admin-guide/plugins/cookie_remap.en.rst
+++ b/doc/admin-guide/plugins/cookie_remap.en.rst
@@ -78,7 +78,7 @@ Limitations
----
-* Does not support `plugin chaining
<http://trafficserver.apache.org/docs/v2/admin/files.htm#remap.config>`_.
+* Does not support :ref:`remap-config-plugin-chaining`
Setup
-----
diff --git a/doc/developer-guide/api/functions/TSSslClientContext.en.rst
b/doc/developer-guide/api/functions/TSSslClientContext.en.rst
index a024827..f8d4db4 100644
--- a/doc/developer-guide/api/functions/TSSslClientContext.en.rst
+++ b/doc/developer-guide/api/functions/TSSslClientContext.en.rst
@@ -28,32 +28,32 @@ Synopsis
.. function:: TSReturnCode TSSslClientContextsNamesGet(int n, const char
**result, int *actual)
.. function:: TSSslContext TSSslClientContextFindByName(const char *ca_paths,
const char *ck_paths)
-
+
Description
===========
These functions are used to explore the client contexts that |TS| uses to
connect to upstreams.
-:func:`TSSslClientContextsNamesGet` can be used to retrieve the entire client
context mappings. Note
-that in traffic server, client contexts are stored in a 2-level mapping with
ca paths and cert/key
+:func:`TSSslClientContextsNamesGet` can be used to retrieve the entire client
context mappings. Note
+that in |TS|, client contexts are stored in a 2-level mapping with ca paths
and cert/key
paths as keys. Hence every 2 null-terminated string in :arg:`result` can be
used to lookup one context.
-:arg:`result` points to an user allocated array that will hold pointers to
lookup key strings and
+:arg:`result` points to an user allocated array that will hold pointers to
lookup key strings and
:arg:`n` is the size for :arg:`result` array. :arg:`actual`, if valid, will be
filled with actual number
of lookup keys (2 for each context).
-:func:`TSSslClientContextFindByName` can be used to retrieve the client
context pointed by the lookup
-key pairs. User should call :func:`TSSslClientContextsNamesGet` first to
determine which lookup keys are
-present before quering for the context. :arg:`ca_paths` should be the first
key and :arg:`ck_paths`
-should be the second. This function returns NULL if the client context mapping
are changed and no valid
-context exists for the key pair. The caller is responsible for releasing the
context returned by this
+:func:`TSSslClientContextFindByName` can be used to retrieve the client
context pointed by the lookup
+key pairs. User should call :func:`TSSslClientContextsNamesGet` first to
determine which lookup keys are
+present before querying for the context. :arg:`ca_paths` should be the first
key and :arg:`ck_paths`
+should be the second. This function returns NULL if the client context mapping
are changed and no valid
+context exists for the key pair. The caller is responsible for releasing the
context returned by this
function with :func:`TSSslContextDestroy`.
Examples
========
-The example below is excerpted from
`example/plugins/c-api/client_context_dump/client_context_dump.cc` in the
Traffic
-Server source distribution. It demonstrates how to use
:func:`TSSslClientContextsNamesGet` and
-:func:`TSSslClientContextFindByName` to retreive all contextxs.
+The example below is excerpted from
`example/plugins/c-api/client_context_dump/client_context_dump.cc` in the
Traffic
+Server source distribution. It demonstrates how to use
:func:`TSSslClientContextsNamesGet` and
+:func:`TSSslClientContextFindByName` to retrieve all contexts.
.. literalinclude::
../../../../example/plugins/c-api/client_context_dump/client_context_dump.cc
:language: c
diff --git a/doc/developer-guide/cache-architecture/architecture.en.rst
b/doc/developer-guide/cache-architecture/architecture.en.rst
index f09e79c..0b03e7e 100644
--- a/doc/developer-guide/cache-architecture/architecture.en.rst
+++ b/doc/developer-guide/cache-architecture/architecture.en.rst
@@ -367,8 +367,7 @@ along with overall object properties (such as content
length).
|TS| supports `varying content
<http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44>`_
for objects. These are called :term:`alternates <alternate>`. All metadata for
all alternates is stored in the first fragment including the set of alternates
-and the HTTP headers for them. This enables `alternate selection
-<http://trafficserver.apache.org/docs/trunk/sdk/http-hooks-and-transactions/http-alternate-selection.en.html>`_
+and the HTTP headers for them. This enables :doc:`"alternate selection"
<../plugins/hooks-and-transactions/http-alternate-selection.en>`
to be done after the *first Doc* is read from disk. An object that has more
than
one alternate will have the alternate content stored separately from the first
fragment. For objects with only one alternate the content may or may not be in
diff --git a/doc/developer-guide/testing/blackbox-testing.en.rst
b/doc/developer-guide/testing/blackbox-testing.en.rst
index 0542d97..eba8240 100644
--- a/doc/developer-guide/testing/blackbox-testing.en.rst
+++ b/doc/developer-guide/testing/blackbox-testing.en.rst
@@ -19,31 +19,29 @@
.. _blackbox-testing:
-Traffic Server Blackbox Testing
+|TS| Blackbox Testing
********************************
-Traffic Server uses the Reusable Gold Testing System (`AuTest
<https://bitbucket.org/autestsuite/reusable-gold-testing-system/src/master/>`_)
+|TS| uses the Reusable Gold Testing System (`AuTest
<https://bitbucket.org/autestsuite/reusable-gold-testing-system/src/master/>`_)
for functional testing. The current layout is:
::
gold_tests/ - contains all the TSQA v4 based tests that run on the
Reusable Gold Testing System (AuTest)
-
tools/ - contains programs used to help with testing.
-
Scripts
-========
-To ease the process of running Autest, there is *autest.sh* and
*bootstrap.py*.
+========
+To ease the process of running Autest, there is *autest.sh* and *bootstrap.py*.
-**autest.sh** - This file is a simple wrapper that will call the Reusable Gold
Testing System (Autest) program in a pipenv.
-If the pipenv is not setup, the script will prompt user the missing
components.
-That will set up the Autest on most systems in a Python virtual environment.
-The wrapper adds some basic options to the command to point to the location of
the tests.
+**autest.sh** - This file is a simple wrapper that will call the Reusable Gold
Testing System (Autest) program in a pipenv.
+If the pipenv is not setup, the script will prompt user the missing components.
+That will set up the Autest on most systems in a Python virtual environment.
+The wrapper adds some basic options to the command to point to the location of
the tests.
Run the script from the ``tests/`` directory followed by ``--ats-bin`` and the
bin directory where ATS is located (e.g. ``~/ats/bin``)
Use ``--help`` for more details on options for running Autest.
-**bootstrap.py** - This script will check for the necessary packages needed to
create a pipenv that can run Autest.
-If any package is missing, the script will alert the user.
+**bootstrap.py** - This script will check for the necessary packages needed to
create a pipenv that can run Autest.
+If any package is missing, the script will alert the user.
If all packages are available, it will install a virtual environment using the
provided Pipfile.
@@ -59,16 +57,15 @@ To run autest manually, the recommended way is to follow
these steps:
Advanced Setup
===============
-AuTest and the relevant tools can be install manually instead of using the
wrapper script.
-By doing this, it is often easier to debug issues with the testing system, or
the tests.
+AuTest and the relevant tools can be install manually instead of using the
wrapper script.
+By doing this, it is often easier to debug issues with the testing system, or
the tests.
There are two ways this can be done.
1. Run the bootstrap script then source the path with a ``source
./env-test/bin/activate`` command. At this point autest command should run
without the wrapper script.
2. Make sure you install python 3.5 or better on your system. From there
install these python packages (e.g. ``pip install``):
- - hyper
- - git+https://bitbucket.org/autestsuite/reusable-gold-testing-system.git
- - `traffic-replay
<https://bitbucket.org/autestsuite/trafficreplay/src/master/>`_ (This will
automatically install `MicroDNS
<https://bitbucket.org/autestsuite/microdns/src/master/>`_, `MicroServer
<https://bitbucket.org/autestsuite/microserver/src/master/>`_,
`TrafficReplayLibrary
<https://bitbucket.org/autestsuite/trafficreplaylibrary/src/master/>`_, and
dnslib as part of the dependencies.)
-
+ - hyper
+ - git+https://bitbucket.org/autestsuite/reusable-gold-testing-system.git
+ - `traffic-replay
<https://bitbucket.org/autestsuite/trafficreplay/src/master/>`_ (This will
automatically install `MicroDNS
<https://bitbucket.org/autestsuite/microdns/src/master/>`_, `MicroServer
<https://bitbucket.org/autestsuite/microserver/src/master/>`_,
`TrafficReplayLibrary
<https://bitbucket.org/autestsuite/trafficreplaylibrary/src/master/>`_, and
dnslib as part of the dependencies.)
Writing Tests
==============
@@ -77,12 +74,12 @@ When writing tests, please refer to the current
`documentation <https://autestsu
Testing Environment
--------------------
-The environment of the testing process will have a number of added environment
variables to control trafficserver running the in the sandbox location
correctly.
+The environment of the testing process will have a number of added environment
variables to control |TS| running the in the sandbox location correctly.
This can be used to easily setup other commands that should run under same
environment.
-Autest Extensions
+Autest Extensions
------------------
-Autest allows the user to create extensions to help specialize and simplify
test writing for a given application domain.
+Autest allows the user to create extensions to help specialize and simplify
test writing for a given application domain.
TrafficServer
~~~~~~~~~~~~~~
@@ -102,18 +99,18 @@ For TrafficServer, we have defined the following functions
and objects in ``test
- targetname - the name of the file when copied to the correct configuration
location
- process - optional process object to use for getting path location to copy
to. Only needed if the Setup object call is not in the scope of the process
object created with the MakeATSProcess(...) API.
-This function copies a given configuration file to the location of the
trafficserver sandbox used in a test. Given a test might have more than on
trafficserver instance, it can be difficult to understand the correct location
to copy to. This function will deal with the details correctly.
+This function copies a given configuration file to the location of the |TS|
sandbox used in a test. Given a test might have more than on |TS| instance, it
can be difficult to understand the correct location to copy to. This function
will deal with the details correctly.
When automatically selected, the following ports will be allocated for TS:
-- port
+- port
- portv6
- ssl_port
- admin_port - this is set even if select_port is **False**
A number of file objects are also defined to help test TrafficServer. Files
that are currently defined are:
-- squid.log
+- squid.log
- error.log
- diags.log
- records.config
@@ -146,19 +143,19 @@ Origin Server
- ``Test.MakeOriginServer(name, port, s_port, ip, delay, ssl, lookup_key,
clientcert, clientkey)``
- name - A name for this instance of origin server.
- - port - option to specify the nonSSL port. If left unspecified, the port
will be autoselected.
- - s_port - option to specify the SSL port. If left unspecified, the port
will be autoselected (SSL has to be True).
+ - port - option to specify the nonSSL port. If left unspecified, the port
will be autoselected.
+ - s_port - option to specify the SSL port. If left unspecified, the port
will be autoselected (SSL has to be True).
- ip - option to specify IP address. Defaults to ``127.0.0.1``.
- - delay - option to have MicroServer delay for set amount of seconds before
returning response. Defaults to ``0``.
- - ssl - option to enable SSL
+ - delay - option to have MicroServer delay for set amount of seconds before
returning response. Defaults to ``0``.
+ - ssl - option to enable SSL
- lookup_key - option to change the unique identifier that MicroServer uses
to identify each transaction. Defaults to ``PATH``.
- clientcert - path to cert used for SSL. Defaults to the included cert in
``tests/tools/microserver/ssl``.
- - clientkey - path to key used for SSL. Same default as above.
+ - clientkey - path to key used for SSL. Same default as above.
-This function returns a AuTest process object that launches the python-based
Microserver.
-Microserver is a mock server which responds to client http requests.
-Microserver needs to be setup for the tests that require an origin server
behind ATS.
-The server reads a JSON-formatted data file that contains request headers and
the corresponding response headers.
+This function returns a AuTest process object that launches the python-based
Microserver.
+Microserver is a mock server which responds to client http requests.
+Microserver needs to be setup for the tests that require an origin server
behind ATS.
+The server reads a JSON-formatted data file that contains request headers and
the corresponding response headers.
Microserver responds with payload if the response header contains
Content-Length or Transfer-Encoding specified.
- ``Test.addResponse(filename, request_header, response_header)``
@@ -167,10 +164,10 @@ Microserver responds with payload if the response header
contains Content-Length
- request_header - dictionary of request header
- response_header - dictionary of response header corresponding to the
request header.
-This function adds the request header and response header to a file which is
then read by the microserver to populate request-response map.
+This function adds the request header and response header to a file which is
then read by the microserver to populate request-response map.
The key-fields required for the header dictionary are 'headers', 'timestamp'
and 'body'.
-Example
+Example
++++++++
.. code-block:: python
@@ -194,7 +191,7 @@ DNS
- port - option for the DNS port. Autoselected if left unspecified.
- ip - option for IP address. Defaults to ``127.0.0.1``
- rr - option to enable round robin IP. Defaults to ``False``
- - default - option to specify a default IP response when MicroDNS can't find
a domain:IP pair.
+ - default - option to specify a default IP response when MicroDNS can't find
a domain:IP pair.
- ``dns.addRecords(records, jsonFile)``
@@ -212,6 +209,7 @@ The JSON file must take the form of
]
}
+
Example
++++++++
.. code-block:: python
@@ -228,47 +226,44 @@ Example
Condition Testing
-------------------
-- ``Condition.HasCurlFeature(feature)``
-This function tests Curl for possible features it has been compiled with.
Consult Curl documentation for possible features.
-
-- ``Condition.PluginExists(pluginname)``
-This function tests for the existence of a certain plugin in ATS.
-
-- ``Condition.HasATSFeature(feature)``
-
-This function tests TrafficServer for possible features it has been compiled
with. Current features you can test for are:
-
-- TS_HAS_LIBZ
-- TS_HAS_LZMA
-- TS_HAS_JEMALLOC
-- TS_HAS_TCMALLOC
-- TS_HAS_IN6_IS_ADDR_UNSPECIFIED
-- TS_HAS_BACKTRACE
-- TS_HAS_PROFILER
-- TS_USE_FAST_SDK
-- TS_USE_DIAGS
-- TS_USE_EPOLL
-- TS_USE_KQUEUE
-- TS_USE_PORT
-- TS_USE_POSIX_CAP
-- TS_USE_TPROXY
-- TS_HAS_SO_MARK
-- TS_HAS_IP_TOS
-- TS_USE_HWLOC
-- TS_USE_SET_RBIO
-- TS_USE_LINUX_NATIVE_AIO
-- TS_HAS_SO_PEERCRED
-- TS_USE_REMOTE_UNWINDING
-- TS_HAS_128BIT_CAS
-- TS_HAS_TESTS
-- TS_HAS_WCCP
-- SPLIT_DNS
-
-
-Examples
++++++++++++++++++
+ - ``Condition.HasCurlFeature(feature)``
+ This function tests Curl for possible features it has been compiled
with. Consult Curl documentation for possible features.
+ - ``Condition.PluginExists(pluginname)``
+ This function tests for the existence of a certain plugin in ATS.
+ - ``Condition.HasATSFeature(feature)``
+ This function tests TrafficServer for possible features it has been
compiled with. Current features you can test for are:
+
+ - TS_HAS_LIBZ
+ - TS_HAS_LZMA
+ - TS_HAS_JEMALLOC
+ - TS_HAS_TCMALLOC
+ - TS_HAS_IN6_IS_ADDR_UNSPECIFIED
+ - TS_HAS_BACKTRACE
+ - TS_HAS_PROFILER
+ - TS_USE_FAST_SDK
+ - TS_USE_DIAGS
+ - TS_USE_EPOLL
+ - TS_USE_KQUEUE
+ - TS_USE_PORT
+ - TS_USE_POSIX_CAP
+ - TS_USE_TPROXY
+ - TS_HAS_SO_MARK
+ - TS_HAS_IP_TOS
+ - TS_USE_HWLOC
+ - TS_USE_SET_RBIO
+ - TS_USE_LINUX_NATIVE_AIO
+ - TS_HAS_SO_PEERCRED
+ - TS_USE_REMOTE_UNWINDING
+ - TS_HAS_128BIT_CAS
+ - TS_HAS_TESTS
+ - TS_HAS_WCCP
+ - SPLIT_DNS
+
+
+Examples:
+++++++++
-.. code-block:: python
+.. code-block:: python
Test.SkipUnless(
Condition.HasATSFeature('TS_USE_LINUX_NATIVE_AIO'),
@@ -279,10 +274,5 @@ Examples
)
Test.SkipUnless(
- Condition.PluginExists('a-plugin.so'),
- )
-
-
-
-
-
+ Condition.PluginExists('a-plugin.so'),
+ )
