Skip to content

doc: Convert miscased Traffic Server references to |TS| macro #8543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
randall merged 1 commit into from
Feb 8, 2022
Merged

doc: Convert miscased Traffic Server references to |TS| macro #8543

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/admin-guide/plugins/access_control.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -343,7 +343,7 @@ The following configuration can be used to implement `use case 1`_
Configuration files
~~~~~~~~~~~~~~~~~~~

* Apache traffic server ``remap.config``
* Apache |TS| ``remap.config``

:ref:`admin-plugins-cachekey` is used to add the access token `subject` into the cache key (``@TokenSubject``). and should always follow the :ref:`admin-plugins-access_control` in the remap rule in order for this mechanism to work properly.

Expand Down
2 changes: 1 addition & 1 deletion doc/admin-guide/plugins/cachekey.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ Detailed examples and troubleshooting

The following is an example of how the above sample keys were generated (``Sample 1`` and ``Sample 2``).

Traffic server configuration ::
|TS| configuration ::

$ cat etc/trafficserver/remap.config
map http://www.example.com http://www.origin.com \
Expand Down
4 changes: 3 additions & 1 deletion doc/admin-guide/plugins/cert_reporting_tool.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. include:: ../../common.defs

.. _admin-plugins-cert-reporting-tool:

Cert Reporting Tool Plugin
Expand Down Expand Up @@ -40,5 +42,5 @@ Plugin Configuration

Example Usage
=============
Start traffic server with cert_reporting_tool loaded, then use traffic_ctl to send plugin message:
Start |TS| with cert_reporting_tool loaded, then use traffic_ctl to send plugin message:
``traffic_ctl plugin msg cert_reporting_tool.client 1``
4 changes: 3 additions & 1 deletion doc/admin-guide/plugins/certifier.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. include:: ../../common.defs

.. _admin-plugins-certifier:

Certifier Plugin
Expand Down Expand Up @@ -77,7 +79,7 @@ To use this plugin, enable it in a :file:`plugin.config` rule, specifying certif

certifier.so --store=/home/zeyuan/certifier/certs --max=1000 --sign-cert=/home/zeyuan/certifier/root-ca.crt --sign-key=/home/zeyuan/certifier/root-ca.key --sign-serial=/home/zeyuan/certifier/ca-serial.txt

One use case would be routing incoming CONNECT request to another port on traffic server. With the certifier generating a trusted certificate, other plugins can act with a similar behavior to Man-In-The-Middle (logging interesting data for example).
One use case would be routing incoming CONNECT request to another port on |TS|. With the certifier generating a trusted certificate, other plugins can act with a similar behavior to Man-In-The-Middle (logging interesting data for example).

.. uml::
:align: center
Expand Down
4 changes: 3 additions & 1 deletion doc/admin-guide/plugins/memcache.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. include:: ../../common.defs

.. _admin-plugins-memcache:

Memcache Plugin
Expand Down Expand Up @@ -42,7 +44,7 @@ Alternatively, a configuration can also be specified::

tsmemcache.so <path-to-plugin>/sample.tsmemcache.config

After modifying plugin.config, restart traffic server (sudo traffic_ctl
After modifying plugin.config, restart |TS| (sudo traffic_ctl
server restart) the configuration is also re-read when a management
update is given (sudo traffic_ctl config reload)

Expand Down
4 changes: 3 additions & 1 deletion doc/admin-guide/plugins/slice.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@
specific language governing permissions and limitations
under the License.

.. include:: ../../common.defs

.. _admin-plugins-slice:

Slice Plugin
Expand Down Expand Up @@ -140,7 +142,7 @@ following options are provided to help with log overrun::
slice.so -p 1
slice.so --disable-errorlog

After modifying :file:`remap.config`, restart or reload traffic server
After modifying :file:`remap.config`, restart or reload |TS|
(sudo traffic_ctl config reload) or (sudo traffic_ctl server restart)
to activate the new configuration values.

Expand Down
90 changes: 45 additions & 45 deletions doc/admin-guide/security/index.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,11 @@ Security
Controlling Access
==================

Traffic Server can be configured to allow only certain clients to use
|TS| can be configured to allow only certain clients to use
the proxy cache.

#. Add a line to :file:`ip_allow.yaml` for each IP address or
range of IP addresses allowed to access Traffic Server.
range of IP addresses allowed to access |TS|.

#. Run the command :option:`traffic_ctl config reload` to apply the configuration
changes.
Expand All @@ -46,17 +46,17 @@ the proxy cache.
Basic SSL Termination
=====================

The Traffic Server *SSL termination* option enables you to secure
connections in reverse proxy mode between a client and a Traffic Server
and/or Traffic Server and an origin server.
The |TS| *SSL termination* option enables you to secure
connections in reverse proxy mode between a client and a |TS|
and/or |TS| and an origin server.

The following sections describe how to enable and configure the SSL
termination option.

- Enable and configure SSL termination for client/Traffic Server
- Enable and configure SSL termination for client/|TS|
connections: :ref:`client-and-traffic-server-connections`

- Enable and configure SSL termination for Traffic Server/origin server
- Enable and configure SSL termination for |TS|/origin server
connections: :ref:`traffic-server-and-origin-server-connections`

.. _client-and-traffic-server-connections:
Expand All @@ -66,43 +66,43 @@ Client and Traffic Server Connections

.. XXX sanity check/second opinions on example paths used for certs/keys below

The figure below illustrates communication between a client and Traffic
Server (and between Traffic Server and an origin server) when the SSL
The figure below illustrates communication between a client and |TS|
(and between |TS| and an origin server) when the SSL
termination option is enabled and configured for Client/Traffic
Server connections only.

.. figure:: ../../static/images/admin/ssl_c.jpg
:align: center
:alt: Client and Traffic Server communication using SSL termination
:alt: Client and |TS| communication using SSL termination

Client and Traffic Server communication using SSL termination
Client and |TS| communication using SSL termination

.. Manual list numbering below corresponds to figure markings above.

The figure above depicts the following:

#. The client sends an HTTPS request for content. Traffic Server receives the
#. The client sends an HTTPS request for content. |TS| receives the
request and performs the SSL handshake to authenticate the client (depending
on the authentication options configured) and determine the encryption
method that will be used. If the client is allowed access, then Traffic
Server checks its cache for the requested content.

#. If the request is a cache hit and the content is fresh, then Traffic Server
#. If the request is a cache hit and the content is fresh, then |TS|
encrypts the content and sends it to the client. The client decrypts the
content (using the method determined during the handshake) and displays it.

#. If the request is a cache miss or cached content is stale, then Traffic
Server communicates with the origin server via HTTP and obtains a plain text
version of the content. Traffic Server saves the plain text version of the
version of the content. |TS| saves the plain text version of the
content in its cache, encrypts the content, and sends it to the client. The
client decrypts and displays the content.

To configure Traffic Server to use the SSL termination option for
Client/Traffic Server connections, you must do the following:
To configure |TS| to use the SSL termination option for
Client/|TS| connections, you must do the following:

#. Obtain and install an SSL server certificate from a recognized
certificate authority. The SSL server certificate contains
information that enables the client to authenticate Traffic Server
information that enables the client to authenticate |TS|
and exchange encryption keys.

#. Set the port number used for SSL communication using
Expand All @@ -115,20 +115,20 @@ Client/Traffic Server connections, you must do the following:
CONFIG proxy.config.ssl.server.private_key.path STRING /opt/ts/etc/ssl/keys/

#. Add an entry to :file:`ssl_multicert.config` for each certificate and key
which your Traffic Server system will be using to terminate SSL connections
which your |TS| system will be using to terminate SSL connections
with clients. ::

dest_ip=1.2.3.4 ssl_cert_name=example.com.pem
dest_ip=* ssl_cert_name=default.pem

#. *Optional*: Configure the use of client certificates using the variable
:ts:cv:`proxy.config.ssl.client.certification_level` in :file:`records.config`.
If you configure Traffic Server to require client certificates, then Traffic
If you configure |TS| to require client certificates, then Traffic
Server verifies the client certificate during the SSL handshake that
authenticates the client. If you configure Traffic Server to not require
authenticates the client. If you configure |TS| to not require
client certificates, or if you configure certificates to be optional and the
connecting client does not present one, then access to Traffic Server is
managed through other Traffic Server options that have been set (such as
connecting client does not present one, then access to |TS| is
managed through other |TS| options that have been set (such as
rules in :file:`ip_allow.yaml`). ::

CONFIG proxy.config.ssl.client.certification_level INT 0
Expand All @@ -150,54 +150,54 @@ Client/Traffic Server connections, you must do the following:

CONFIG proxy.config.ssl.CA.cert.path STRING /opt/CA/certs/private-ca.pem

#. Run the command :option:`traffic_ctl server restart` to restart Traffic Server.
#. Run the command :option:`traffic_ctl server restart` to restart |TS|.

.. _traffic-server-and-origin-server-connections:

Traffic Server and Origin Server Connections
|TS| and Origin Server Connections
--------------------------------------------

.. XXX sanity check/second opinions on example paths used for certs/keys below

The figure below illustrates communication between Traffic Server and an
The figure below illustrates communication between |TS| and an
origin server when the SSL termination option is enabled for Traffic
Server/origin server connections.

.. figure:: ../../static/images/admin/ssl_os.jpg
:align: center
:alt: Traffic Server and origin server communication using SSL termination
:alt: |TS| and origin server communication using SSL termination

Traffic Server and origin server communication using SSL termination
|TS| and origin server communication using SSL termination

.. Manual list numbering below corresponds to figure markings above.

The figure above depicts the following:

#. If a client request is a cache miss or is stale, then Traffic Server sends
#. If a client request is a cache miss or is stale, then |TS| sends
an HTTPS request for the content to the origin server. The origin server
receives the request and performs the SSL handshake to authenticate Traffic
Server and determine the encryption method to be used.

#. If Traffic Server is allowed access, then the origin server encrypts the
content and sends it to Traffic Server, where it is decrypted (using the
#. If |TS| is allowed access, then the origin server encrypts the
content and sends it to |TS|, where it is decrypted (using the
method determined during the handshake). A plain text version of the content
is saved in the cache, if Traffic Server deems the content cacheable.
is saved in the cache, if |TS| deems the content cacheable.

#. If SSL termination is enabled for Client/Traffic Server connections, then
Traffic Server re-encrypts the content and sends it to the client via HTTPS,
#. If SSL termination is enabled for Client/|TS| connections, then
|TS| re-encrypts the content and sends it to the client via HTTPS,
where it is decrypted and displayed. If SSL termination is not enabled for
Client/Traffic Server connections, then Traffic Server sends the plain text
Client/|TS| connections, then |TS| sends the plain text
version of the content to the client via HTTP.

To configure Traffic Server to use the SSL termination option for Traffic Server
To configure |TS| to use the SSL termination option for |TS|
and origin server connections, you must do the following:

#. Ensure first that your origin server responds properly to SSL requests, and
configure it for client certificate validation if you intend to use that as
part of your access control scheme.

Refer to your origin server's documentation for details. If your origin
server is another Traffic Server system, then you may follow the steps
server is another |TS| system, then you may follow the steps
outlined in `Client and Traffic Server Connections`_ for configuring the
origin server to validate client certificates.

Expand Down Expand Up @@ -235,7 +235,7 @@ and origin server connections, you must do the following:
CONFIG proxy.config.ssl.client.CA.cert.path STRING /opt/ts/etc/ssl/certs/
CONFIG proxy.config.ssl.client.CA.cert.filename STRING CAs.pem

#. Run the command :option:`traffic_ctl server restart` to restart Traffic Server.
#. Run the command :option:`traffic_ctl server restart` to restart |TS|.

:doc:`mtls.en`
==============
Expand Down Expand Up @@ -276,21 +276,21 @@ significant load on the CA servers since they were required to
provide a response to every client of a given certificate in real
time.

Enabling OCSP Stapling instructs Traffic Server to retrieve and cache the
Enabling OCSP Stapling instructs |TS| to retrieve and cache the
revocation status of all configured SSL certificates, and present them to the
client when the client requests the status. Traffic Server will automatically
client when the client requests the status. |TS| will automatically
query the OCSP responder specified in the SSL certificate to gather the latest
revocation status. Traffic Server will then cache the results for each
revocation status. |TS| will then cache the results for each
configured certificate. The location of the OCSP responder is taken from the
Authority Information Access field of the signed certificate. For example::

Authority Information Access:
OCSP - URI:http://ocsp.digicert.com
CA Issuers - URI:http://cacerts.digicert.com/DigiCertSHA2SecureServerCA.crt

Traffic Server can also use prefetched OCSP stapling responses if ssl_ocsp_name parameter
|TS| 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
OCSP stapling responses, |TS| will not refresh them and it should be done
externally. This can be done using OpenSSL::

$ openssl ocsp -issuer ca.crt -cert cert.crt -host ocsp.digicert.com:80 \
Expand All @@ -309,7 +309,7 @@ Support for OCSP Stapling can be tested using the -status option of the OpenSSL

Details of the OCSP Stapling TLS extension can be found in :rfc:`6961`.

To configure Traffic Server to use OCSP Stapling, edit the following variables
To configure |TS| to use OCSP Stapling, edit the following variables
in :file:`records.config` file:

* :ts:cv:`proxy.config.ssl.ocsp.enabled`
Expand All @@ -323,9 +323,9 @@ in :file:`records.config` file:
Split DNS
=========

The *Split DNS* option enables you to configure Traffic Server to use
The *Split DNS* option enables you to configure |TS| to use
multiple DNS servers, as dictated by your security requirements. For
example, you might configure Traffic Server to use one set of DNS
example, you might configure |TS| to use one set of DNS
servers to resolve hostnames on your internal network, while allowing
DNS servers outside the firewall to resolve hosts on the Internet. This
maintains the security of your intranet, while continuing to provide
Expand Down
2 changes: 1 addition & 1 deletion doc/admin-guide/security/mtls.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ Guidance for testing
--------------------
You will want to verify that |TS| will accurately reload to pick up new client certificate files.
As time goes one, the life time of certificates shrink from months to weeks or days, so you will most likely need
to have |TS| reload configurations to load up new certificates without restarting the traffic server process (and interrupting
to have |TS| reload configurations to load up new certificates without restarting the |TS| process (and interrupting
customer traffic). The following command should cause updated client certificates and keys to be loaded into the traffic_server process.
From there you can verify via your origins that the updated certificates are being offered. ::

Expand Down
6 changes: 3 additions & 3 deletions doc/appendices/command-line/traffic_layout.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ Environment
Description
===========

Document for the :program:`traffic_layout` about the ``runroot``. This feature is for the setup of traffic server runroot.
It will create a runtime sandbox for any program of traffic server to run under.
Document for the :program:`traffic_layout` about the ``runroot``. This feature is for the setup of |TS| runroot.
It will create a runtime sandbox for any program of |TS| to run under.
For details about runroot for programs, please refer to ``developer-guide/layout/runroot.en``.

Usage
Expand Down Expand Up @@ -127,7 +127,7 @@ Example: ::
If a custom layout is used and system files are included in some directories, ``--fix`` option might potentially have unexpected behaviors.
For example, if sysconfdir is defined as ``/etc`` instead of ``/etc/trafficserver`` in ``runroot.yaml``,
``--fix`` may perform permission changes on the system configuration files. With normally created runroot with default layout,
there is no such issue since traffic server related files are filtered.
there is no such issue since |TS| related files are filtered.

Options
=======
Expand Down
3 changes: 1 addition & 2 deletions doc/developer-guide/api/functions/TSAcceptor.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,7 @@ An acceptor thread listens for incoming connections and creates the virtual conn

:func:`TSAcceptorGet` returns :type:`TSAcceptor` object that created :arg:`sslp`.

:func:`TSAcceptorGetbyID` returns the :type:`TSAcceptor` object identified by :arg:`id`. :type:`TSAcceptor` represents the acceptor object created by the core
traffic server.
:func:`TSAcceptorGetbyID` returns the :type:`TSAcceptor` object identified by :arg:`id`. :type:`TSAcceptor` represents the acceptor object created by the server.
Copy link
Contributor

@ywkaras ywkaras Dec 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a mistake? What server?

Copy link
Contributor Author

@randall randall Dec 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is a core traffic server?

Copy link
Contributor

@ywkaras ywkaras Dec 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The traffic_server executable plus libtscore and libtscpputil.

Copy link
Member

@SolidWallOfCode SolidWallOfCode Dec 7, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Walt's right - that should be "proxy" or "core". "server" will cause people to think it is on a remote box.

Copy link
Contributor

@bneradt bneradt Dec 7, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We discussed this in the PR/issue meeting today, we suggest simply using |TS|.

Copy link
Contributor

@ywkaras ywkaras Dec 7, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we just delete the word "core"? "server" seems too ambiguous.


:func:`TSAcceptorIDGet` returns the Integer number that identifies :arg:`acceptor`. All the cloned :type:`TSAcceptor` objects will have the same identifying number.

Expand Down
2 changes: 1 addition & 1 deletion doc/developer-guide/plugins/remap-plugins.en.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ or :macro:`TSREMAP_CONFIG_RELOAD_SUCCESS_PLUGIN_UNUSED`. This is an optional ent

These calls are called per *plugin*, not per invocation of the plugin in :file:`remap.config`
and only will be called if the plugin was instantiated by at least one configuration loaded
after the traffic server started and at least one configuration using it is still loaded.
after |TS| started and at least one configuration using it is still loaded.

:func:`TSRemapPreConfigReload` will be called serially for all loaded plugins
before any call to :func:`TSRemapNewInstance` during parsing of the new configuration.
Expand Down