You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2014/10/22 18:25:26 UTC
[1/4] Documentation editorial update
Repository: trafficserver
Updated Branches:
refs/heads/master 39f9ded92 -> 9fbd42017
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/working-log-files.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/working-log-files.en.rst b/doc/admin/working-log-files.en.rst
index 16b645e..209e5d2 100644
--- a/doc/admin/working-log-files.en.rst
+++ b/doc/admin/working-log-files.en.rst
@@ -20,7 +20,6 @@ Working with Log Files
specific language governing permissions and limitations
under the License.
-
Traffic Server generates log files that contain information about every
request it receives and every error it detects. This chapter will examine the
various log features, the configuration formats and also examine the various
@@ -35,14 +34,14 @@ Traffic Server records information about every transaction (or request)
it processes and every error it detects in log files. Traffic Server
keeps three types of log files:
-- **Error log files** record information about why a particular
+- *Error log files* record information about why a particular
transaction was in error.
-- **Event log files** (also called **access log files**) record
+- *Event log files* (also called *access log files*) record
information about the state of each transaction Traffic Server
processes.
-- **System log files** record system information, including messages
+- *System log files* record system information, including messages
about the state of Traffic Server and errors/warnings it produces.
This kind of information might include a note that event log files
were rolled, a warning that cluster communication timed out, or an
@@ -70,13 +69,17 @@ keeps three types of log files:
By default, Traffic Server creates both error and event log files and
records system information in system log files. You can disable event
logging and/or error logging by setting the configuration variable
-:ts:cv:`proxy.config.log.logging_enabled` (in the :file:`records.config` file)
+:ts:cv:`proxy.config.log.logging_enabled` in :file:`records.config`
to one of the following values:
-- ``0`` to disable both event and error logging
-- ``1`` to enable error logging only
-- ``2`` to enable transaction logging only
-- ``3`` to enable both transaction and error logging
+======= =================================================
+Value Description
+======= =================================================
+``0`` Disable both event and error logging.
+``1`` Enable error logging only.
+``2`` Enable event logging only.
+``3`` Enable both event and error logging.
+======= =================================================
Understanding Event Log Files
=============================
@@ -96,54 +99,47 @@ when they reach a certain size.
The following sections describe the Traffic Server logging system
features and discuss how to:
-- **Manage your event log files**
-
+*Manage your event log files*
You can choose a central location for storing log files, set how much
disk space to use for log files, and set how and when to roll log
files. Refer to `Managing Event Log Files`_.
-- **Choose different event log file formats**
-
+*Choose different event log file formats*
You can choose which standard log file formats you want to use for
traffic analysis, such as Squid or Netscape. Alternatively, you can
use the Traffic Server custom format, which is XML-based and enables
you to institute more control over the type of information recorded
in log files. Refer to `Choosing Event Log File Formats`_.
-- **Roll event log files automatically**
-
+*Roll event log files automatically*
Configure Traffic Server to roll event log files at specific
- intervals during the day or when they reach a certain size; this
+ intervals during the day or when they reach a certain size. This
enables you to identify and manipulate log files that are no longer
active. Refer to `Rolling Event Log Files`_.
-- **Separate log files according to protocols and hosts**
-
+*Separate log files according to protocols and hosts*
Configure Traffic Server to create separate log files for different
protocols. You can also configure Traffic Server to generate separate
log files for requests served by different hosts. Refer to `Splitting Event Log Files`_.
-- **Collate log files from different Traffic Server nodes**
-
+*Collate log files from different Traffic Server nodes*
Designate one or more nodes on the network to serve as log collation
servers. These servers, which might be standalone or part of Traffic
Server, enable you to keep all logged information in well-defined
locations. Refer to `Collating Event Log Files`_.
-- **View statistics about the logging system**
-
+*View statistics about the logging system*
Traffic Server provides statistics about the logging system; you can
access these statistics via Traffic Line. Refer to `Viewing Logging Statistics`_.
-- **Interpret log file entries for the log file formats**
-
+*Interpret log file entries for the log file formats*
Refer to `Example Event Log File Entries`_.
Managing Event Log Files
------------------------
Traffic Server enables you to control where event log files are located
-and how much space they can consume. Additionally you can specify how to
+and how much space they can consume. Additionally, you can specify how to
handle low disk space in the logging directory.
Choosing the Logging Directory
@@ -166,7 +162,7 @@ a low space state and takes the following actions:
- If the autodelete option (discussed in `Rolling Event Log Files`_)
is *enabled*, then Traffic Server
- identifies previously-rolled log files (i.e., log files with the
+ identifies previously-rolled log files (log files with the
``.old`` extension). It starts deleting files one by one, beginning
with the oldest file, until it emerges from the low state. Traffic
Server logs a record of all deleted files in the system error log.
@@ -187,19 +183,18 @@ a temporary partition, where you can run a variety of log analysis
scripts. Following analysis, either compress the logs and move to an
archive location, or simply delete them.
-
Setting Log File Management Options
-----------------------------------
To set log management options, follow the steps below:
-1. In the :file:`records.config` file, edit the following variables
+#. In the :file:`records.config` file, edit the following variables
- :ts:cv:`proxy.config.log.logfile_dir`
- :ts:cv:`proxy.config.log.max_space_mb_for_logs`
- :ts:cv:`proxy.config.log.max_space_mb_headroom`
-2. Run the command :option:`traffic_line -x` to apply the configuration
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
Choosing Event Log File Formats
@@ -207,11 +202,12 @@ Choosing Event Log File Formats
Traffic Server supports the following log file formats:
-- Standard formats, such as Squid or Netscape; refer to `Using Standard Formats`_.
-- The Traffic Server custom format; refer to `Using the Custom Format`_.
+- Standard formats, such as Squid or Netscape. Refer to `Using Standard Formats`_.
+- The Traffic Server custom format. Refer to `Using the Custom Format`_.
In addition to the standard and custom log file format, you can choose
-whether to save log files in binary or ASCII; refer to `Choosing Binary or ASCII`_.
+whether to save log files in binary or ASCII. Refer to `Choosing Binary or ASCII`_
+for more details on the benefits and drawbacks of the two storage formats.
Event log files consume substantial disk space. Creating log entries in
multiple formats at the same time can consume disk resources very
@@ -228,39 +224,39 @@ information that these formats do not provide. Refer to `Using the Custom Format
Set standard log file format options by following the steps below:
-1. In the :file:`records.config` file, edit the following variables
-2. Edit the following variables to use the Squid format:
+#. In the :file:`records.config` file, edit the following variables
+
+#. Edit the following variables to use the Squid format:
- :ts:cv:`proxy.config.log.squid_log_enabled`
- :ts:cv:`proxy.config.log.squid_log_is_ascii`
- :ts:cv:`proxy.config.log.squid_log_name`
- :ts:cv:`proxy.config.log.squid_log_header`
-3. To use the Netscape Common format, edit the following variables:
+#. To use the Netscape Common format, edit the following variables:
- :ts:cv:`proxy.config.log.common_log_enabled`
- :ts:cv:`proxy.config.log.common_log_is_ascii`
- :ts:cv:`proxy.config.log.common_log_name`
- :ts:cv:`proxy.config.log.common_log_header`
-4. To use the Netscape Extended format, edit the following variables:
+#. To use the Netscape Extended format, edit the following variables:
- :ts:cv:`proxy.config.log.extended_log_enabled`
- :ts:cv:`proxy.config.log.extended_log_is_ascii`
- :ts:cv:`proxy.config.log.extended_log_name`
- :ts:cv:`proxy.config.log.extended_log_header`
-5. To use the Netscape Extended-2 format, edit the following variables:
+#. To use the Netscape Extended-2 format, edit the following variables:
- :ts:cv:`proxy.config.log.extended2_log_enabled`
- :ts:cv:`proxy.config.log.extended2_log_is_ascii`
- :ts:cv:`proxy.config.log.extended2_log_name`
- :ts:cv:`proxy.config.log.extended2_log_header`
-6. Run the command :option:`traffic_line -x` to apply the configuration
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
-
.. _using-custom-log-formats:
Using the Custom Format
@@ -281,72 +277,84 @@ log files, as detailed below. To generate a custom log format, you must
specify at least one ``LogObject`` definition (one log file is produced
for each ``LogObject`` definition).
-- The ``LogFormat`` object defines the content of the log file
- using printf-style format strings.
-- The ``LogFilter`` object defines a filter so that you include or
- exclude certain information from the log file.
-- The ``LogObject`` object specifies all the information needed to
- produce a log file.
-
- - The name of the log file. (required)
- - The format to be used (required). This can be a standard format
- (Squid or Netscape) or
- - a previously-defined custom format (i.e., a previously-defined
- ``LogFormat`` object).
- - The file mode: ``ASCII``, ``Binary``, or ``ASCII_PIPE``. The
- default is ``ASCII``.
- The ``ASCII_PIPE`` mode writes log entries to a UNIX-named pipe
- (a buffer in memory); other processes can then read the data using
- standard I/O functions. The advantage of this option is that
- Traffic Server does not have to write to disk, which frees disk
- space and bandwidth for other tasks. When the buffer is full,
- Traffic Server drops log entries and issues an error message
- indicating how many entries were dropped. Because Traffic Server
- only writes complete log entries to the pipe, only full records
- are dropped.
- - Any filters you want to use (i.e., previously-defined
- ``LogFilter`` objects).
- - The collation servers that are to receive the log files.
- - The protocols you want to log. If the protocols tag is used, then
+:ref:`LogFormat`
+ Defines the content of the log file using printf-style format strings.
+
+:ref:`LogFilter`
+ Defines a filter so that you include or exclude certain information from
+ the log file.
+
+:ref:`LogObject`
+ Specifies all the information needed to produce a log file:
+
+ - The name of the log file. *Required*.
+
+ - The format to be used. This can be a standard format (Squid or Netscape)
+ or a previously-defined custom format (a :ref:`LogFormat`). *Required*.
+
+ - The file mode: ``ASCII``, ``Binary``, or ``ASCII_PIPE``. The
+ default is ``ASCII``. Refer to `ASCII_PIPE File Mode`_ for more details
+ on sending entries to a named pipe.
+
+ - Any filters you want to use (:ref:`LogFilter` objects).
+
+ - The collation servers that are to receive the log files.
+
+ - The protocols you want to log. If the ``protocols`` tag is used, then
Traffic Server will only log transactions from the protocols
listed; otherwise, all transactions for all protocols are logged.
- - The origin servers you want to log. If the ``servers`` tag is
+
+ - The origin servers you want to log. If the ``servers`` tag is
used, then Traffic Server will only log transactions for the
origin servers listed; otherwise, transactions for all origin
servers are logged.
- - The header text you want the log files to contain. The header text
+
+ - The header text you want the log files to contain. The header text
appears at the beginning of the log file, just before the first
record.
- - The log file rolling options.
-
-In order to accomplish this, we
-
-1. edit the following variables in the
- :file:`records.config` file:
-2. :ts:cv:`proxy.config.log.custom_logs_enabled`
-3. In the
- :file:`logs_xml.config` file
-4. Add :ref:`LogFormat`, :ref:`LogFilters`, and :ref:`LogObject`
- specifications to the configuration file.
-5. Save and close the :file:`logs_xml.config` file.
-6. Run the command :option:`traffic_line -x` to apply your configuration
+
+ - The log file rolling options.
+
+In order to accomplish this, we:
+
+#. Enable :ts:cv:`proxy.config.log.custom_logs_enabled` in
+ :file:`records.config`. ::
+
+ CONFIG proxy.config.log.custom_logs_enabled INT 1
+
+#. Add :ref:`LogFormat`, :ref:`LogFilter`, and :ref:`LogObject`
+ specifications to the configuration file :file:`logs_xml.config`.
+
+#. Run the command :option:`traffic_line -x` to apply your configuration
changes.
+ASCII_PIPE File Mode
+~~~~~~~~~~~~~~~~~~~~
+
+In addition to ``ASCII`` and ``BINARY`` file modes for custom log formats, Traffic
+Server can output log entries in ``ASCII_PIPE`` mode. This mode writes the log
+entries to a UNIX named pipe (a buffer in memory). Other processes may read
+from this named pipe using standard I/O functions.
+
+The advantage of this mode is that Traffic Server does not need to write the
+entries to disk, which frees disk space and bandwidth for other tasks. When the
+buffer is full, Traffic Server drops log entries and issues an error message
+indicating how many entries were dropped. Because Traffic Server only writes
+complete log entries to the pipe, only full records are dropped.
+
Creating Summary Log Files
~~~~~~~~~~~~~~~~~~~~~~~~~~
-Traffic Server performs several hundred operations per second;
-therefore, event log files can quickly grow to large sizes. Using
-SQL-like aggregate operators, you can configure Traffic Server to create
-summary log files that summarize a set of log entries over a specified
-period of time. This can significantly reduce the size of the log files
-generated.
+Due to the speed and efficiency of Traffic Server, a heavily-loaded node will
+generate many events and the event logs can quickly grow to very large sizes.
+Using SQL-like aggregate operators, you can configure Traffic Server to create
+summary log files that summarize a set of log entries over a specified period
+of time. This can significantly reduce the size of the log files generated.
-To generate a summary log file, create a
-:ref:`LogFormat` object in the XML-based logging configuration file
-(:file:`logs_xml.config`) using
-the SQL-like aggregate operators below. You can apply each of these
-operators to specific fields, over a specified interval.
+To generate a summary log file, create a :ref:`LogFormat` object in the
+XML-based logging configuration file (:file:`logs_xml.config`) using the
+SQL-like aggregate operators below. You can apply each of these operators to
+specific fields, over a specified interval.
- ``COUNT``
- ``SUM``
@@ -354,11 +362,9 @@ operators to specific fields, over a specified interval.
- ``FIRST``
- ``LAST``
-To create a summary log file format, we
+To create a summary log file format:
-1. Define the format of the log file in
- :file:`logs_xml.config` as
- follows:
+#. Define the format of the log file in :file:`logs_xml.config` as follows:
.. code-block:: xml
@@ -368,19 +374,22 @@ To create a summary log file format, we
<Interval = "n"/>
</LogFormat>
- where ``operator`` is one of the five aggregate operators
- (``COUNT``, ``SUM``, ``AVERAGE``, ``FIRST``, ``LAST``), ``field``
- is the logging field you want to aggregate, and ``n`` is the
- interval (in seconds) between summary log entries. You can specify
- more than one ``operator`` in the format line. For more
+ Where ``operator`` is one of the five aggregate operators (``COUNT``,
+ ``SUM``, ``AVERAGE``, ``FIRST``, ``LAST``); ``field`` is the logging field
+ you want to aggregate; and ``n`` is the interval (in seconds) between
+ summary log entries.
+
+ You can specify more than one ``operator`` in the format line. For more
information, refer to :file:`logs_xml.config`.
-2. Run the command :option:`traffic_line -x` to apply configuration changes .
+#. Run the command :option:`traffic_line -x` to apply configuration changes .
-The following example format generates one entry every 10 seconds. Each
-entry contains the timestamp of the last entry of the interval, a count
-of the number of entries seen within that 10-second interval, and the
-sum of all bytes sent to the client: ::
+The following example format generates one entry every 10 seconds. Each entry
+contains the timestamp of the last entry of the interval, a count of the number
+of entries seen within that 10-second interval, and the sum of all bytes sent
+to the client:
+
+.. code-block:: xml
<LogFormat>
<Name = "summary"/>
@@ -392,7 +401,7 @@ sum of all bytes sent to the client: ::
You cannot create a format specification that contains
both aggregate operators and regular fields. For example, the following
- specification would be **invalid**: ::
+ specification would be invalid: ::
<Format = "%<LAST(cqts)> : %<COUNT(*)> : %<SUM(psql)> : %<cqu>"/>
@@ -402,8 +411,7 @@ Choosing Binary or ASCII
You can configure Traffic Server to create event log files in either of
the following:
-- **ASCII**
-
+ASCII
These files are human-readable and can be processed using standard,
off-the-shelf log analysis tools. However, Traffic Server must
perform additional processing to create the files in ASCII, which
@@ -411,8 +419,7 @@ the following:
than the equivalent binary files. By default, ASCII log files have a
``.log`` filename extension.
-- **Binary**
-
+Binary
These files generate lower system overhead and generally occupy less
space on the disk than ASCII files (depending on the type of
information being logged). However, you must use a converter
@@ -423,48 +430,47 @@ the following:
While binary log files typically require less disk space, there are
exceptions.
-For example: the value ``0`` (zero) requires only one byte to store in
+For example, the value ``0`` (zero) requires only one byte to store in
ASCII, but requires four bytes when stored as a binary integer.
-Conversely: if you define a custom format that logs IP addresses, then a
+Conversely, if you define a custom format that logs IP addresses, then a
binary log file would only require four bytes of storage per 32-bit
address. However, the same IP address stored in dot notation would
-require around 15 characters (bytes) in an ASCII log file. Therefore,
-it's wise to consider the type of data that will be logged before you
-select ASCII or binary for your log files. For example, you might try
-logging for one day using ASCII and then another day using binary. If
-the number of requests is roughly the same for both days, then you can
-calculate a rough metric that compares the two formats.
-
-For standard log formats, select Binary or ASCII (refer to `Setting
-Standard Log File Format Options`). For the custom log
-format, specify ASCII or Binary mode in the
-:ref:`LogObject`
-(refer to :ref:`Using the Custom Format <using-custom-log-formats>`). In addition
+require around 15 characters (bytes) in an ASCII log file.
+
+It is wise to consider the type of data that will be logged before you
+select ASCII or binary for your log files, if your decision is being driven by
+storage space concerns. For example, you might try logging for one day using
+ASCII and then another day using binary. If the number of requests is roughly
+the same for both days, then you can calculate a rough metric that compares
+the two formats.
+
+For standard log formats, select Binary or ASCII (refer to
+`Setting Standard Log File Format Options`_). For the custom log
+format, specify ASCII or Binary mode in the :ref:`LogObject`
+(refer to :ref:`using-custom-log-formats`). In addition
to the ASCII and binary options, you can also write custom log entries
-to a UNIX-named pipe (i.e., a buffer in memory). Other processes can
-then read the data using standard I/O functions. The advantage of using
-this option is that Traffic Server does not have to write to disk, which
-frees disk space and bandwidth for other tasks. In addition, writing to
-a pipe does not stop when logging space is exhausted because the pipe
-does not use disk space. Refer to
-:file:`logs_xml.config` for more information about the ``ASCII_PIPE`` option.
-
+to a UNIX-named pipe (a buffer in memory) with the `ASCII_PIPE File Mode`_
+setting.
Rolling Event Log Files
-----------------------
-Traffic Server provides automatic log file rolling. This means that at
-specific intervals during the day or when log files reach a certain
-size, Traffic Server closes its current set of log files and opens new
-log files. Depending on the amount of traffic your servers are exposed
-to, you should roll log files several times a day. Rolling every six
-hours is a good guideline to start with.
+Traffic Server provides automatic log file rolling. At specific intervals
+during the day or when log files reach a certain size, Traffic Server closes
+its current set of log files and opens new log files. Depending on the amount
+of traffic your servers are exposed to, you may find that increasing the
+frequency of log rolling is beneficial, or even necessary, to maintain
+manageable log file sets. Traffic Server nodes processing moderately high
+levels of traffic may want to start by rolling logs every six hours, and
+adjusting from there.
Log file rolling offers the following benefits:
-- It defines an interval over which log analysis can be performed.
+- It defines an consistent interval over which log analysis can be performed.
+
- It keeps any single log file from becoming too large and helps to
keep the logging system within the specified space limits.
+
- It provides an easy way to identify files that are no longer being
used so that an automated script can clean the logging directory and
run log analysis programs.
@@ -479,16 +485,19 @@ file. Traffic Server renames the old file to include the following
information:
- The format of the file (such as ``squid.log``).
+
- The hostname of the Traffic Server that generated the log file.
+
- Two timestamps separated by a hyphen (``-``). The first timestamp is
- a **lower bound** for the timestamp of the first record in the log
+ a *lower bound* for the timestamp of the first record in the log
file. The lower bound is the time when the new buffer for log records
is created. Under low load, the first timestamp in the filename can
be different from the timestamp of the first entry. Under normal
load, the first timestamp in the filename and the timestamp of the
- first entry are similar. The second timestamp is an **upper bound**
+ first entry are similar. The second timestamp is an *upper bound*
for the timestamp of the last record in the log file (this is
normally the rolling time).
+
- The suffix ``.old``, which makes it easy for automated scripts to
find rolled log files.
@@ -498,23 +507,18 @@ Timestamps have the following format: ::
The following table describes the format:
-``%Y``
- The year in four-digit format. For example: 2000.
+====== ================================================== ==============
+Format Description Sample
+====== ================================================== ==============
+``%Y`` The year in four-digit format. 2000
+``%M`` The month in two-digit format, from 01-12. 07
+``%D`` The day in two-digit format, from 01-31. 19
+``%H`` The hour in two-digit format, from 00-23. 21
+``%M`` The minute in two-digit format, from 00-59. 52
+``%S`` The second in two-digit format, from 00-59. 36
+====== ================================================== ==============
-``%M``
- The month in two-digit format, from 01-12. For example: 07.
-
-``%D``
- The day in two-digit format, from 01-31. For example: 19.
-
-``%H``
- The hour in two-digit format, from 00-23. For example: 21.
-
-``%M``
- The minute in two-digit format, from 00-59. For example: 52.
-
-``%S``
- The second in two-digit format, from 00-59. For example: 36.
+.. XXX can %S ever be 60, on account of leap seconds, or does ATS have leap-second related issues that otherwise interfere?
The following is an example of a rolled log filename: ::
@@ -547,8 +551,9 @@ Rolling Intervals
Log files are rolled at specific intervals relative to a given hour of
the day. Two options control when log files are rolled:
-- The offset hour, which is an hour between 0 (midnight) and 23
-- The rolling interval
+- The offset hour, which is an hour between ``0`` (midnight) and ``23``.
+
+- The rolling interval.
Both the offset hour and the rolling interval determine when log file
rolling starts. Rolling occurs every rolling interval and at the offset
@@ -562,26 +567,35 @@ Setting Log File Rolling Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To set log file rolling options and/or configure Traffic Server to roll
-log files when they reach a certain size, follow the steps below:
+log files when they reach a certain size, adjust the following setting in
+:file:`records.config`:
+
+#. Enable log rolling with :ts:cv:`proxy.config.log.rolling_enabled`. ::
+
+ CONFIG proxy.config.log.rolling_enabled INT 1
+
+#. Configure the upper limit on log file size with
+ :ts:cv:`proxy.config.log.rolling_size_mb`. ::
+
+ CONFIG proxy.config.log.rolling_size_mb INT 1024
+
+#. Set the offset hour with :ts:cv:`proxy.config.log.rolling_offset_hr`. ::
+
+ CONFIG proxy.config.log.rolling_offset_hr INT 0
-1. In the :file:`records.config` file, edit the following variables
+#. Set the interval (in seconds) with
+ :ts:cv:`proxy.config.log.rolling_interval_sec`. ::
- - :ts:cv:`proxy.config.log.rolling_enabled`
- - :ts:cv:`proxy.config.log.rolling_size_mb`
- - :ts:cv:`proxy.config.log.rolling_offset_hr`
- - :ts:cv:`proxy.config.log.rolling_interval_sec`
+ CONFIG proxy.config.log.rolling_interval_sec INT 21600
-2. Run the command :option:`traffic_line -x` to apply the configuration
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
You can fine-tune log file rolling settings for a custom log file in the
-:ref:`LogObject`
-specification in the
-:file:`logs_xml.config` file.
-The custom log file uses the rolling settings in its
-:ref:`LogObject`,
-which override the default settings you specify in Traffic Manager or
-the :file:`records.config` file described above.
+:ref:`LogObject` specification in :file:`logs_xml.config`. The custom log file
+uses the rolling settings in its :ref:`LogObject`, which override the default
+settings you specify in Traffic Manager or :file:`records.config` described
+above.
Splitting Event Log Files
-------------------------
@@ -594,12 +608,11 @@ different protocols in separate log files.
ICP Log Splitting
~~~~~~~~~~~~~~~~~
-When ICP log splitting is enabled, Traffic Server records ICP
-transactions in a separate log file with a name that contains
-``icp``. For example: if you enable the Squid format, then all ICP
-transactions are recorded in the ``squid-icp.log`` file. When you
-disable ICP log splitting, Traffic Server records all ICP transactions
-in the same log file as HTTP transactions.
+When ICP log splitting is enabled, Traffic Server records ICP transactions in a
+separate log file with a name that contains ``icp``. For example, if you enable
+the Squid format, then all ICP transactions are recorded in the
+``squid-icp.log`` file. When you disable ICP log splitting, Traffic Server
+records all ICP transactions in the same log file as HTTP transactions.
HTTP Host Log Splitting
~~~~~~~~~~~~~~~~~~~~~~~
@@ -607,53 +620,50 @@ HTTP Host Log Splitting
HTTP host log splitting enables you to record HTTP transactions for
different origin servers in separate log files. When HTTP host log
splitting is enabled, Traffic Server creates a separate log file for
-each origin server that's listed in the :file:`log_hosts.config` file.
+each origin server that's listed in :file:`log_hosts.config`.
When both ICP and HTTP host log splitting are enabled, Traffic Server generates
separate log files for HTTP transactions (based on the origin server)
and places all ICP transactions in their own respective log files. For
-example, if the :file:`log_hosts.config` file contains the two origin
+example, if :file:`log_hosts.config` contains the two origin
servers ``uni.edu`` and ``company.com`` and Squid format is enabled,
then Traffic Server generates the following log files:
-``squid-uni.edu.log``
- All HTTP transactions for ``uni.edu``
-
-``squid-company.com.log``
- All HTTP transactions for ``company.com``
-
-``squid-icp.log``
- All ICP transactions for all hosts
-
-``squid.log``
- All HTTP transactions for other hosts
+=========================== ============================================
+Log File Contents
+=========================== ============================================
+``squid-uni.edu.log`` All HTTP transactions for ``uni.edu``.
+``squid-company.com.log`` All HTTP transactions for ``company.com``.
+``squid-icp.log`` All ICP transactions for all hosts.
+``squid.log`` All HTTP transactions for other hosts.
+=========================== ============================================
If you disable ICP log splitting, then ICP transactions are placed in
the same log file as HTTP transactions. Using the hosts and log format
from the previous example, Traffic Server generates the log files below:
-``squid-uni.edu.log``
- All entries for ``uni.edu``
-
-``squid-company.com.log``
- All entries for ``company.com``
+=========================== ============================================
+Log File Contents
+=========================== ============================================
+``squid-uni.edu.log`` All entries for ``uni.edu``.
+``squid-company.com.log`` All entries for ``company.com``.
+``squid.log`` All other entries.
+=========================== ============================================
-``squid.log``
- All other entries
-
-Traffic Server also enables you to create XML-based :ref:`Custom Log Formats <using-custom-log-formats>`
-that offer even greater control over log file generation.
+Traffic Server also enables you to create XML-based
+:ref:`Custom Log Formats <using-custom-log-formats>` that offer even greater
+control over log file generation.
Setting Log Splitting Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To set log splitting options, follow the steps below:
-1. In the :file:`records.config` file, edit the following variables
+#. In the :file:`records.config` file, edit the following variables
- :ts:cv:`proxy.config.log.separate_icp_logs`
- :ts:cv:`proxy.config.log.separate_host_logs`
-2. Run the command :option:`traffic_line -x` to apply the configuration
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
Editing the log_hosts.config File
@@ -662,8 +672,8 @@ Editing the log_hosts.config File
The default :file:`log_hosts.config` file is located in the Traffic Server
``config`` directory. To record HTTP transactions for different origin
servers in separate log files, you must specify the hostname of each
-origin server on a separate line in the :file:`log_hosts.config` file. For
-example, if you specify the keyword sports, then Traffic Server records
+origin server on a separate line in :file:`log_hosts.config`. For
+example, if you specify the keyword ``sports``, then Traffic Server records
all HTTP transactions from ``sports.yahoo.com`` and
``www.foxsports.com`` in a log file called ``squid-sports.log`` (if the
Squid format is enabled).
@@ -674,17 +684,16 @@ Squid format is enabled).
collation, then you should use the same :file:`log_hosts.config` file on
every Traffic Server node in the cluster.
-To edit the :file:`log_hosts.config` file follow the steps below:
+To edit the log hosts list:
-1. In the :file:`log_hosts.config` file,
- enter the hostname of each origin server on a separate line in the
- file, e.g.: ::
+#. Enter the hostname of each origin server on a separate line in
+ :file:`log_hosts.config`. ::
webserver1
webserver2
webserver3
-2. Run the command :option:`traffic_line -x` to apply the configuration
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
Collating Event Log Files
@@ -732,30 +741,39 @@ To configure Traffic Server to collate event log files, you must perform
the following tasks:
- Either `Configure Traffic Server Node to Be a Collation
- Server <Configuring Traffic Server to Be a Collation Server>`_ or install & configure a
- `Standalone Collator <Using a Standalone Collator>`_
+ Server <Configuring Traffic Server to Be a Collation Server>`_ or install
+ and configure a `Standalone Collator <Using a Standalone Collator>`_.
+
- `Configure Traffic Server Nodes to Be a Collation
Clients <Configuring Traffic Server to Be a Collation Server>`_.
-- Add an attribute to the
- :ref:`LogObject`
- specification in the
- :file:`logs_xml.config` file
- if you are using custom log file formats; refer to `Collating Custom
- Event Log Files`_.
+
+- Add an attribute to the :ref:`LogObject` specification in
+ :file:`logs_xml.config` if you are using custom log file formats. Refer to
+ `Collating Custom Event Log Files`_.
Configuring Traffic Server to Be a Collation Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To configure a Traffic Server node to be a collation server, simply edit
-a configuration file via the steps below.
+To configure a Traffic Server node to be a collation server, perform the
+following configuration adjustments in :file:`records.config`:
-1. In the :file:`records.config` file, edit the following variables
+#. Set :ts:cv:`proxy.local.log.collation_mode` to ``1`` to indicate this node
+ will be a server. ::
- - :ts:cv:`proxy.local.log.collation_mode` (``1`` for server mode)
- - :ts:cv:`proxy.config.log.collation_port`
- - :ts:cv:`proxy.config.log.collation_secret`
+ CONFIG proxy.local.log.collation_mode INT 1
-2. Run the command :option:`traffic_line -x` to apply the configuration
+#. Configure the port on which the server will listen to incoming collation
+ transfers from clients, using :ts:cv:`proxy.config.log.collation_port`. If
+ omitted, this defaults to port ``8085``. ::
+
+ CONFIG proxy.config.log.collation_port INT 8085
+
+#. Configure the shared secret (password) used by collation clients to authenticate
+ their sessions, using :ts:cv:`proxy.config.log.collation_secret`. ::
+
+ CONFIG proxy.config.log.collation_secret STRING "seekrit"
+
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
.. note::
@@ -774,34 +792,47 @@ files.
To install and configure a standalone collator:
-1. Configure your Traffic Server nodes as log collation clients; refer
- to `Configuring Traffic Server to Be a Collation
- Client <#ConfiguringTSCollationClient>`_.
-2. Copy the :program:`traffic_sac` binary from the Traffic Server ``bin``
- directory and
-3. Copy the ``libtsutil.so`` libraries from the Traffic Server ``lib``
+#. Configure your Traffic Server nodes as log collation clients. Refer
+ to `Configuring Traffic Server to Be a Collation Client`_.
+
+#. Copy the :program:`traffic_sac` binary from the Traffic Server ``bin``
+ directory, and place in a suitable location on the system that will
+ act as the standalone collator.
+
+#. Copy the ``libtsutil.so`` libraries from the Traffic Server ``lib``
directory to the machine serving as the standalone collator.
-4. Create a directory called ``config`` in the directory that contains
+
+#. Create a directory called ``config`` in the directory that contains
the :program:`traffic_sac` binary.
-5. Create a directory called ``internal`` in the ``config`` directory
- you created in Step 4 (above). This directory is used internally by
- the standalone collator to store lock files.
-6. Copy the :file:`records.config` file from a Traffic Server node
+
+#. Create a directory called ``internal`` in the ``config`` directory
+ you created above. This directory is used internally by the standalone
+ collator to store lock files.
+
+#. Copy the :file:`records.config` file from a Traffic Server node
configured to be a log collation client to the ``config`` directory
- you created in Step 4 on the standalone collator.
+ you created on the standalone collator.
+
The :file:`records.config` file contains the log collation secret and
the port you specified when configuring Traffic Server nodes to be
collation clients. The collation port and secret must be the same for
all collation clients and servers.
-7. In the :file:`records.config`
- file, edit the following variable
- - :ts:cv:`proxy.config.log.logfile_dir`
+#. Edit :ts:cv:`proxy.config.log.logfile_dir` in :file:`records.config` to
+ specify a location on your standalone collator where the collected log files
+ should be stored. ::
+
+ CONFIG proxy.config.log.logfile_dir STRING "/var/log/trafficserver/"
-8. Enter the following command::
+#. Enter the following command to start the standalone collator process::
traffic_sac -c config
+You will likely want to configure this program to run at server startup, as
+well as configure a service monitor in the event the process terminates
+abnormally. Please consult your operating system's documentation for how to
+achieve this.
+
Configuring Traffic Server to Be a Collation Client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -810,7 +841,7 @@ steps below. If you modify the ``collation_port`` or ``secret`` after
connections between the collation clients and the collation server have
been established, then you must restart Traffic Server.
-1. In the :file:`records.config` file, edit the following variables:
+#. In the :file:`records.config` file, edit the following variables:
- :ts:cv:`proxy.local.log.collation_mode`: ``2`` to configure this node as log collation client and send
standard formatted log entries to the collation server.
@@ -822,23 +853,22 @@ been established, then you must restart Traffic Server.
- :ts:cv:`proxy.config.log.collation_host_tagged`
- :ts:cv:`proxy.config.log.max_space_mb_for_orphan_logs`
-2. Run the command :option:`traffic_line -x` to apply the configuration
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
Collating Custom Event Log Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you use custom event log files, then you must edit the
-:file:`logs_xml.config` file (in addition to configuring a collation server
-and collation clients).
+If you use custom event log files, then you must edit :file:`logs_xml.config`,
+in addition to configuring a collation server and collation clients.
-To collate custom event log files
+To collate custom event log files:
-1. On each collation client, edit the `:file:`logs_xml.config`
-2. Add the
- :ref:`CollationHost <logs-xml-logobject-collationhost>` attribute to the
- :ref:`LogObject`
- specification: ::
+#. On each collation client, edit :file:`logs_xml.config` and add the
+ :ref:`CollationHosts <logs-xml-logobject-collationhost>` attribute to the
+ :ref:`LogObject` specification:
+
+ .. code-block:: xml
<LogObject>
<Format = "squid"/>
@@ -846,12 +876,12 @@ To collate custom event log files
<CollationHosts="ipaddress:port"/>
</LogObject>
- where ``ipaddress`` is the hostname or IP address of the collation
+ Where ``ipaddress`` is the hostname or IP address of the collation
server to which all log entries (for this object) are forwarded, and
``port`` is the port number for communication between the collation
server and collation clients.
-3. Run the command :option:`traffic_line -L` to restart Traffic Server on the
+#. Run the command :option:`traffic_line -L` to restart Traffic Server on the
local node or :option:`traffic_line -M` to restart Traffic Server on all
the nodes in a cluster.
@@ -862,19 +892,23 @@ Traffic Server generates logging statistics that enable you to see the
following information:
- How many log files (formats) are currently being written.
+
- The current amount of space used by the logging directory, which
contains all event and error logs.
+
- The number of access events written to log files since Traffic Server
- installation. This counter represents one entry in one file; if
+ installation. This counter represents one entry in one file. If
multiple formats are being written, then a single event creates
multiple event log entries.
+
- The number of access events skipped (because they were filtered)
since Traffic Server installation.
+
- The number of access events written to the event error log since
Traffic Server installation.
You can retrieve the statistics via the Traffic Line command-line
-interface; refer to `Monitoring Traffic <../monitoring-traffic>`_.
+interface. Refer to `Monitoring Traffic <../monitoring-traffic>`_.
Viewing Log Files
=================
@@ -890,8 +924,8 @@ Online Event Log XML Builder
============================
If you need any assistance building your event log, you can try out our
-`online log builder <http://trafficserver.apache.org/logbuilder/>`_. This is a work in progress, so any
-comments, critique or suggestions are most welcome.
+`online log builder <http://trafficserver.apache.org/logbuilder/>`_. This is a
+work in progress, so any comments, critique or suggestions are most welcome.
Example Event Log File Entries
==============================
@@ -916,16 +950,16 @@ The following figure shows a sample log entry in a ``squid.log`` file.
====== ========= =============================================================================
Field Symbol Description
====== ========= =============================================================================
-1 cqtq The client request timestamp in Squid format; the time of the client
+1 cqtq The client request timestamp in Squid format. The time of the client
request in seconds since January 1, 1970 UTC (with millisecond resolution).
-2 ttms The time Traffic Server spent processing the client request; the
+2 ttms The time Traffic Server spent processing the client request. The
number of milliseconds between the time the client established the
connection with Traffic Server and the time Traffic Server sent the
last byte of the response back to the client.
3 chi The IP address of the client’s host machine.
4 crc/pssc The cache result code; how the cache responded to the request:
- ``HIT``, ``MISS``, and so on. Cache result codes are described
- :ref:`here <squid-netscape-result-codes>`.
+ ``HIT``, ``MISS``, and so on. Cache result codes are described in
+ :ref:`<squid-netscape-result-codes>`.
The proxy response status code (the HTTP response status code from
Traffic Server to client).
5 psql The length of the Traffic Server response to the client in bytes,
@@ -937,9 +971,9 @@ Field Symbol Description
ASCII code number of the replaced character in hex.
8 caun The username of the authenticated client. A hyphen (``-``) means
that no authentication was required.
-9 phr/pqsn The proxy hierarchy route; the route Traffic Server used to retrieve
+9 phr/pqsn The proxy hierarchy route. The route Traffic Server used to retrieve
the object.
-10 psct The proxy response content type; the object content type taken from
+10 psct The proxy response content type. The object content type taken from
the Traffic Server response header.
====== ========= =============================================================================
@@ -1055,7 +1089,7 @@ Field Symbol Description
interrupted.
19 pfsc The proxy finish status code: ``FIN`` if the Traffic Server request
to the origin server completed successfully or ``INTR`` if the
- request was interrupted.
+ request was interrupted.
20 crc The cache result code; how the Traffic Server cache responded to the
request: HIT, MISS, and so on. Cache result codes are described
:ref:`here <squid-netscape-result-codes>`.
@@ -1090,7 +1124,7 @@ Netscape log files.
the client.
``TCP_REFRESH_HIT``
- The object was in the cache, but it was stale. Traffic Server made an
+ The object was in the cache, but it was stale. Traffic Server made an
``if-modified-since`` request to the origin server and the
origin server sent a ``304`` not-modified response. Traffic
Server sent the cached object to the client.
@@ -1115,14 +1149,14 @@ Netscape log files.
``TCP_IMS_HIT``
The client issued an ``if-modified-since`` request and the object
- was in cache & fresher than the IMS date, **or** an
+ was in cache and fresher than the IMS date, or an
``if-modified-since`` request to the origin server revealed the
cached object was fresh. Traffic Server served the cached object to
the client.
``TCP_IMS_MISS``
The client issued an
- ``if-modified-since request``, and the object was either not in
+ ``if-modified-since request`` and the object was either not in
cache or was stale in cache. Traffic Server sent an
``if-modified-since request`` to the origin server and received the
new object. Traffic Server sent the updated object to the client.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/reference/commands/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/commands/index.en.rst b/doc/reference/commands/index.en.rst
index ce4b341..f8681cf 100644
--- a/doc/reference/commands/index.en.rst
+++ b/doc/reference/commands/index.en.rst
@@ -19,14 +19,14 @@ Command Reference
=================
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
- traffic_cop.en
- traffic_line.en
- traffic_logcat.en
- traffic_logstats.en
- traffic_manager.en
- traffic_server.en
- traffic_top.en
- tspush.en
- tsxs.en
+ traffic_cop.en
+ traffic_line.en
+ traffic_logcat.en
+ traffic_logstats.en
+ traffic_manager.en
+ traffic_server.en
+ traffic_top.en
+ tspush.en
+ tsxs.en
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/reference/configuration/logs_xml.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/logs_xml.config.en.rst b/doc/reference/configuration/logs_xml.config.en.rst
index 7924458..b2c08ac 100644
--- a/doc/reference/configuration/logs_xml.config.en.rst
+++ b/doc/reference/configuration/logs_xml.config.en.rst
@@ -103,10 +103,10 @@ The following list shows ``LogFormat`` specifications.
- FIRST
- LAST
-.. _LogFilters:
+.. _LogFilter:
-LogFilters
-==========
+LogFilter
+=========
The following list shows the ``LogFilter`` specifications.
[4/4] git commit: Documentation editorial update
Posted by jp...@apache.org.
Documentation editorial update
This is a first editorial pass through things (grammar, spelling,
etc.) as well as putting to page a lot of the style guide suggestions.
But it does also include some section reworkings, and more substantial
reordering of the step-by-step examples (e.g. the commented-as-clunky
Security Options guides).
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/9fbd4201
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/9fbd4201
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/9fbd4201
Branch: refs/heads/master
Commit: 9fbd4201766e98435f94eb4ce29b2e99ef64a284
Parents: 39f9ded
Author: Jon Sime <js...@omniti.com>
Authored: Wed Oct 22 09:24:08 2014 -0700
Committer: James Peach <jp...@apache.org>
Committed: Wed Oct 22 09:24:08 2014 -0700
----------------------------------------------------------------------
doc/admin/cluster-howto.en.rst | 111 ++--
doc/admin/configuring-cache.en.rst | 213 +++---
doc/admin/configuring-traffic-server.en.rst | 22 +-
doc/admin/event-logging-formats.en.rst | 228 +++++--
doc/admin/explicit-proxy-caching.en.rst | 34 +-
doc/admin/faqs.en.rst | 187 +++---
doc/admin/forward-proxy.en.rst | 146 +++--
doc/admin/getting-started.en.rst | 155 ++---
doc/admin/hierachical-caching.en.rst | 137 ++--
doc/admin/http-proxy-caching.en.rst | 657 +++++++++++--------
doc/admin/index.en.rst | 114 ++--
doc/admin/monitoring-traffic.en.rst | 54 +-
doc/admin/performance-tuning.en.rst | 30 +-
doc/admin/reverse-proxy-http-redirects.en.rst | 190 +++---
doc/admin/security-options.en.rst | 268 ++++----
doc/admin/session-protocol.en.rst | 50 +-
doc/admin/traffic-server-error-messages.en.rst | 99 +--
doc/admin/transparent-proxy.en.rst | 69 +-
doc/admin/working-log-files.en.rst | 574 ++++++++--------
doc/reference/commands/index.en.rst | 20 +-
.../configuration/logs_xml.config.en.rst | 6 +-
21 files changed, 1873 insertions(+), 1491 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/cluster-howto.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/cluster-howto.en.rst b/doc/admin/cluster-howto.en.rst
index 3a3a186..1c00616 100644
--- a/doc/admin/cluster-howto.en.rst
+++ b/doc/admin/cluster-howto.en.rst
@@ -5,22 +5,20 @@ 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.
+ 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.
@@ -74,44 +72,45 @@ 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 get better performance.
+communication to achieve better performance.
Enabling Clustering Mode
========================
-Before you put a node into a cluster, please make sure the following
-things are in order:
+Before a node is added into a cluster, please ensure that the following
+conditions are being met:
-- You are using the same operation system on all nodes:
+- All nodes are running the same operating system:
- - Using the same distribution, e.g.: RHEL 5.5
- - Have same kernel, e.g.: 2.6.18-194.17.1.el5
- - The same architecture, e.g.: ``x86_64``
+ - The same distribution, e.g.: RHEL 5.5
+ - The same kernel, e.g.: 2.6.18-194.17.1.el5
+ - The same architecture, e.g.: x86_64
-- You have the same version of Traffic Server installed
-- The same hardware
-- On the same switch or same VLAN.
+- 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.
+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
+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*)
+1 Full-Clustering mode
+2 Management-Only mode
+3 No clustering (*default*)
================= ==================================================
-3. Setup a :ts:cv:`proxy.config.cluster.ethernet_interface`, e.g.: ``eth0``.
- This should be replaced by your real interface; we recommends a
- dedicated interface here. Refer to :ts:cv:`proxy.local.cluster.type` for a full description.
+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::
@@ -125,10 +124,13 @@ Value Description
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, and you can
-run :option:`traffic_line -r` `proxy.process.cluster.nodes` to check the hosts
-in the cluster, or check out the ``cluster.config`` in the configuration
-directory. This configuration is generated by the system, and should not be
+Traffic Server will join the cluster in about 10 seconds. To verify the hosts in the
+cluster, you can run::
+
+ traffic_line -r 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::
@@ -137,34 +139,34 @@ cluster, for example::
127.1.2.4:80
127.1.2.5:80
-After successfully joining of a cluster, all changes of global
-configurations on any node, will take effect on **all** nodes. This means you
-can make changes on any cluster node member, and they are automatically
-distributed to all members.
+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, just roll back
-:ts:cv:`proxy.local.cluster.type` to the default value 3 and reload.
+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 build upon from multi-casting of the UDP,
- so imposible to setup where multi-casting is not avaliable, such as AWS EC2.
+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 some internal ports: 8088 8089 and 8086, you should
- make sure the firewall will not ban them.
+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 tweak for busy Cluster
-==================================
+Performance Tuning for Busy Clusters
+====================================
-Starting from v3.2.0, Apache Traffic Server can handle multiple internal
-cluster connections, and we can tweak the number of Cluster threads. Each
-of the thread will keep one connection to all of peering cluster machines.
+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
+Increasing Cluster Threads
--------------------------
In the cluster environment, the current performance of the cluster threads
@@ -172,6 +174,7 @@ 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``. E.g.::
+:ts:cv:`proxy.config.cluster.threads` to ``10``::
traffic_line -s proxy.config.cluster.threads -v 10
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/configuring-cache.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/configuring-cache.en.rst b/doc/admin/configuring-cache.en.rst
index 4df5bc0..dc009d2 100644
--- a/doc/admin/configuring-cache.en.rst
+++ b/doc/admin/configuring-cache.en.rst
@@ -9,7 +9,7 @@ Configuring the Cache
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
+ with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
@@ -21,7 +21,7 @@ Configuring the Cache
under the License.
The Traffic Server cache consists of a high-speed object database called
-the **object store** that indexes objects according to URLs and their
+the *object store* that indexes objects according to URLs and their
associated headers.
.. toctree::
@@ -31,7 +31,7 @@ The Traffic Server Cache
========================
The Traffic Server cache consists of a high-speed object database called
-the **object store**. The object store indexes objects according to URLs
+the *object store*. The object store indexes objects according to URLs
and associated headers. This enables Traffic Server to store, retrieve,
and serve not only web pages, but also parts of web pages - which
provides optimum bandwidth savings. Using sophisticated object
@@ -53,11 +53,11 @@ You can perform the following cache configuration tasks:
- Change the total amount of disk space allocated to the cache: refer
to `Changing Cache Capacity`_.
- Partition the cache by reserving cache disk space for specific
- protocols and origin servers/domains: refer to `Partitioning the Cache`_.
-- Delete all data in the cache: refer to `Clearing the Cache`_.
+ protocols and origin servers/domains; refer to `Partitioning the Cache`_.
+- Delete all data in the cache; refer to `Clearing the Cache`_.
- Override cache directives for a requested domain name, regex on a url,
- hostname or ip, with extra filters for time, port, method of the request
- (and more). ATS can be configured to never cache; always cache;
+ hostname or ip, with extra filters for time, port, method of the request,
+ and more. ATS can be configured to never cache, always cache,
ignore no-cache directives, etc. These are configured in :file:`cache.config`.
The RAM Cache
@@ -69,28 +69,37 @@ and reduces load on disks, especially during temporary traffic peaks.
You can configure the RAM cache size to suit your needs, as described in
:ref:`changing-the-size-of-the-ram-cache` below.
-The RAM cache supports two cache eviction algorithms, a regular **LRU**
-(*Least Recently Used*) and the more advanced **CLFUS** (*Clocked Least
-Frequently Used by Size*, which balances recentness, frequency and size
-to maximize hit rate -- similar to a most frequently used algorithm).
-The default is to use **CLFUS**, and this is controlled via
+The RAM cache supports two cache eviction algorithms, a regular *LRU*
+(Least Recently Used) and the more advanced *CLFUS* (Clocked Least
+Frequently Used by Size; which balances recentness, frequency, and size
+to maximize hit rate, similar to a most frequently used algorithm).
+The default is to use *CLFUS*, and this is controlled via
:ts:cv:`proxy.config.cache.ram_cache.algorithm`.
-Both the **LRU** and **CLFUS** RAM caches support a configuration to increase
-scan resistance. In a typical **LRU**, if you request all possible objects in
+Both the *LRU* and *CLFUS* RAM caches support a configuration to increase
+scan resistance. In a typical *LRU*, if you request all possible objects in
sequence, you will effectively churn the cache on every request. The option
:ts:cv:`proxy.config.cache.ram_cache.use_seen_filter` can be set to add some
resistance against this problem.
-In addition, **CLFUS** also supports compressing in the RAM cache itself.
+In addition, *CLFUS* also supports compressing in the RAM cache itself.
This can be useful for content which is not compressed by itself (e.g.
-images). This should not be confused with *Content-Encoding: gzip*, this
+images). This should not be confused with ``Content-Encoding: gzip``, this
feature is only thereto save space internally in the RAM cache itself. As
such, it is completely transparent to the User-Agent. The RAM cache
compression is enabled with the option
-:ts:cv:`proxy.config.cache.ram_cache.compress`. The default is 0, which means
-no compression. Other possible values are 1 for **fastlz**, 2 for **libz** and
-3 for **liblzma**.
+:ts:cv:`proxy.config.cache.ram_cache.compress`.
+
+Possible values are:
+
+======= =============================
+Value Meaning
+======= =============================
+0 No compression (*default*)
+1 *fastlz* compression
+2 *libz* compression
+3 *liblzma* compression
+======= =============================
.. _changing-the-size-of-the-ram-cache:
@@ -114,17 +123,15 @@ its previous value.
To change the RAM cache size:
-1. Stop Traffic Server.
-2. Set the variable :ts:cv:`proxy.config.cache.ram_cache.size`
- to specify the size of the RAM cache. The default value of -1 means
+#. Stop Traffic Server.
+#. Set the variable :ts:cv:`proxy.config.cache.ram_cache.size`
+ to specify the size of the RAM cache. The default value of ``-1`` means
that the RAM cache is automatically sized at approximately 1MB per
gigabyte of disk.
-3. Restart Traffic Server. If you increase the RAM cache to a size of
+#. Restart Traffic Server. If you increase the RAM cache to a size of
1GB or more, then restart with the :program:`trafficserver` command
(refer to :ref:`start-traffic-server`).
-
-
Changing Cache Capacity
=======================
@@ -136,27 +143,25 @@ Increasing Cache Capacity
-------------------------
To increase the total amount of disk space allocated to the cache on
-existing disks or to add new disks to a Traffic Server node, follow the
-steps below:
+existing disks, or to add new disks to a Traffic Server node:
-1. Stop Traffic Server.
-2. Add hardware, if necessary.
-3. Edit :file:`storage.config` to increase the amount of disk space allocated
+#. Stop Traffic Server.
+#. Add hardware, if necessary.
+#. Edit :file:`storage.config` to increase the amount of disk space allocated
to the cache on existing disks or describe the new hardware you are adding.
-4. Restart Traffic Server.
+#. Restart Traffic Server.
Reducing Cache Capacity
-----------------------
To reduce the total amount of disk space allocated to the cache on an
-existing disk or to remove disks from a Traffic Server node, follow the
-steps below:
+existing disk, or to remove disks from a Traffic Server node:
-1. Stop Traffic Server.
-2. Remove hardware, if necessary.
-3. Edit :file:`storage.config` to reduce the amount of disk space allocated
+#. Stop Traffic Server.
+#. Remove hardware, if necessary.
+#. Edit :file:`storage.config` to reduce the amount of disk space allocated
to the cache on existing disks or delete the reference to the hardware you're removing.
-4. Restart Traffic Server.
+#. Restart Traffic Server.
.. important:: In :file:`storage.config`, a formatted or raw disk must be at least 128 MB.
@@ -177,15 +182,15 @@ Creating Cache Partitions for Specific Protocols
You can create separate volumes for your cache that vary in size to
store content according to protocol. This ensures that a certain amount
of disk space is always available for a particular protocol. Traffic
-Server currently supports the **http** partition type for HTTP objects.
+Server currently supports the ``http`` partition type for HTTP objects.
.. XXX: but not https?
To partition the cache according to protocol:
-1. Enter a line in the :file:`volume.config` file for
+#. Enter a line in the :file:`volume.config` file for
each volume you want to create
-2. Restart Traffic Server.
+#. Restart Traffic Server.
Making Changes to Partition Sizes and Protocols
-----------------------------------------------
@@ -203,17 +208,19 @@ note the following:
recreated, even if the size and protocol type remain the same.
- When you add new disks to your Traffic Server node, volume sizes
specified in percentages will increase proportionately.
-- A lot of changes to volume sizes might result in disk fragmentation,
- which affects performance and hit rate. You should clear the cache
+- Substantial changes to volume sizes can result in disk fragmentation,
+ which affects performance and cache hit rate. You should clear the cache
before making many changes to cache volume sizes (refer to `Clearing the Cache`_).
Partitioning the Cache According to Origin Server or Domain
-----------------------------------------------------------
+.. XXX: rewrite to remove repetitious single-v-multiple points; break out global partition note for clarify; fix up plurality
+
After you have partitioned the cache according to size and protocol, you
can assign the volumes you created to specific origin servers and/or
-domains. You can assign a volumes to a single origin server or to
-multiple origin servers. However, if a volumes is assigned to multiple
+domains. You can assign a volume to a single origin server or to
+multiple origin servers. However, if a volume is assigned to multiple
origin servers, then there is no guarantee on the space available in the
volumes for each origin server. Content is stored in the volumes
according to popularity. In addition to assigning volumes to specific
@@ -225,7 +232,7 @@ then Traffic Server will run in proxy-only mode.
.. note::
- You do *not* need to stop Traffic Server before you assign
+ You do not need to stop Traffic Server before you assign
volumes to particular hosts or domains. However, this type of
configuration is time-consuming and can cause a spike in memory usage.
Therefore, it's best to configure partition assignment during periods of
@@ -233,20 +240,20 @@ then Traffic Server will run in proxy-only mode.
To partition the cache according to hostname and domain:
-1. Configure the cache volumes according to size and protocol, as
+#. Configure the cache volumes according to size and protocol, as
described in `Creating Cache Partitions for Specific Protocols`_.
-2. Create a separate volume based on protocol for each host and domain,
+#. Create a separate volume based on protocol for each host and domain,
as well as an additional generic partition to use for content that
does not belong to these origin servers or domains. The volumes do
not need to be the same size.
-3. Enter a line in the :file:`hosting.config` file to
- allocate the volume(s) used for each origin server and/or domain
-4. Assign a generic volume to use for content that does not belong to
+#. Enter a line in the :file:`hosting.config` file to
+ allocate the volume(s) used for each origin server and/or domain.
+#. Assign a generic volume to use for content that does not belong to
any of the origin servers or domains listed in the file. If all
volumes for a particular origin server become corrupt, then Traffic
Server will also use the generic volume to store content for that
origin server as per :file:`hosting.config`.
-5. Run the command :option:`traffic_line -x` to apply the configuration
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
Configuring the Cache Object Size Limit
@@ -256,10 +263,10 @@ By default, Traffic Server allows objects of any size to be cached. You
can change the default behavior and specify a size limit for objects in
the cache via the steps below:
-1. Set :ts:cv:`proxy.config.cache.max_doc_size`
- to specify the maximum size allowed for objects in the cache in
- bytes. ``0`` (zero) if you do not want a size limit.
-2. Run the command :option:`traffic_line -x` to apply the configuration
+#. Set :ts:cv:`proxy.config.cache.max_doc_size`
+ to specify the maximum size in bytes allowed for objects in the cache.
+ A setting of ``0`` (zero) will permit cache objects to be unlimited in size.
+#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
.. _clearing-the-cache:
@@ -269,13 +276,13 @@ Clearing the Cache
When you clear the cache, you remove all data from the entire cache -
including data in the host database. You should clear the cache before
-performing certain cache configuration tasks, such as partitioning. You
+performing certain cache configuration tasks such as partitioning. You
cannot clear the cache when Traffic Server is running.
To clear the cache:
-1. Stop Traffic Server (refer to :ref:`Stopping Traffic Server <stop-traffic-server>`)
-2. Enter the following command to clear the cache: ::
+#. Stop Traffic Server (see :ref:`stop-traffic-server`)
+#. Enter the following command to clear the cache::
traffic_server -Cclear
@@ -283,7 +290,7 @@ To clear the cache:
host database. Traffic Server does not prompt you to confirm the
deletion.
-3. Restart Traffic Server (refer to :ref:`Starting Traffic Server <start-traffic-server>`).
+#. Restart Traffic Server (see :ref:`start-traffic-server`).
Removing an Object From the Cache
=================================
@@ -294,6 +301,11 @@ cache and is successfully removed, then Traffic Server responds with a
``200 OK`` HTTP message; otherwise, a ``404 File Not Found`` message is
returned.
+.. note::
+
+ By default, the PURGE request method is only processed if received on
+ the localhost interface.
+
In the following example, Traffic Server is running on the domain
``example.com`` and you want to remove the image ``remove_me.jpg``
from cache. Because by default we do not permit ``PURGE`` requests from
@@ -314,12 +326,12 @@ any other IP, we connect to the daemon via localhost: ::
< Connection: keep-alive
The next time Traffic Server receives a request for the removed object,
-it will contact the origin server to retrieve it (i.e., it has been
-purged from the Traffic Server cache).
+it will contact the origin server to retrieve a new copy, which will replace
+the previously cached version in Traffic Server.
-Note: The procedure above only removes an object from a *specific*
-Traffic Server cache. Users may still see the old (removed) content if
-it was cached by intermediary caches or by the end-users' web browser.
+This procedure only removes an object from a specific Traffic Server cache.
+Users may still see the old (removed) content if it was cached by intermediary
+caches or by the end-users' web browser.
.. _inspecting-the-cache:
@@ -328,14 +340,16 @@ Inspecting the Cache
Traffic Server provides a Cache Inspector utility that enables you to
view, delete, and invalidate URLs in the cache (HTTP only). The Cache
-Inspector utility is a powerful tool that's capable of deleting *all*
-the objects in your cache; therefore, make sure that only authorized
-administrators are allowed to access this utility, see :ref:`controlling-client-access-to-cache` and the ``@src_ip`` option in :file:`remap.config`.
+Inspector utility is a powerful tool that's capable of deleting all
+the objects in your cache. Therefore, make sure that only authorized
+administrators are allowed to access this utility through proper use
+of the ``@src_ip`` option in :file:`remap.config` and the instructions
+detailed in :ref:`controlling-client-access-to-cache`.
Accessing the Cache Inspector Utility
-------------------------------------
-To access the Cache Inspector utility, follow the steps below:
+To access the Cache Inspector utility:
#. Set :ts:cv:`proxy.config.http_ui_enabled` to ``1``.
#. To access the cache inspector in reverse proxy mode, you must add a
@@ -345,45 +359,46 @@ To access the Cache Inspector utility, follow the steps below:
map http://yourhost.com/myCI/ http://{cache} @action=allow @src_ip=172.28.56.1-172.28.56.254
-#. From the Traffic Server ``bin`` directory, enter the following
- command to re-read the configuration file: ``traffic_line -x``
+#. Reload the Traffic Server configuration by running :option:`traffic_line -x`.
#. Open your web browser and configure it to use your Traffic Server as
a proxy server. Type the following URL::
http://yourhost/myCI/
-#. The Cache page opens.
-
-Using the Cache Page
---------------------
-
-The **Cache page** provides several options that enable you to view and
-delete the contents of your cache:
-
-- Click **Lookup url** to search for a particular URL in the cache.
- When Traffic Server finds the URL in the cache, it displays details
- about the object that corresponds to the URL (such as the header
- length and the number of alternates). From the display page, you can
- delete the URL from the cache.
-- Click **Delete url** to delete a particular URL or list of URLs from
- the cache. Traffic Server indicates if a delete is successful.
-- Click **Regex lookup** to search for URLs that match one or more
- regular expressions. From the display page, you can delete the URLs
- listed. For example, enter the following to search for all URLs that
- end in html and are prefixed with ``http://www.dianes.com``:
- ``http://www.dianes.com/.*\.html$``
-- Click **Regex delete** to delete all URLs that match a specified
- regular expression. For example, enter the following to delete all
- HTTP URLs that end in ``html``: ``http://.*\.html$``
-- Click **Regex invalidate** to invalidate URLs that match a specified
- regular expression. When you invalidate a URL, Traffic Server marks
- the object that corresponds to the URL as stale in the cache. Traffic
- Server then contacts the origin server to check if the object is
- still fresh (revalidates) before serving it from the cache.
+ You will now be presented with the Cache Inspector interface.
+
+Using the Cache Inspector Utility
+---------------------------------
+
+The Cache Inspector Utility provides several options that enable you to view and
+delete the contents of your cache.
+
+Lookup URL
+ Search for a particular URL in the cache. When Traffic Server finds the URL
+ in the cache, it will display details of the object that corresponds to the
+ URL (e.g. header length and number of alternates). The option to delete the
+ URL from the cache will be presented.
+
+Delete URL
+ Delete the object from the cache which corresponds to the given URL. Success
+ or failure will be indicated after a delete has been attempted.
+
+Regex Lookup
+ Search URLs within the cache using one or more regular expressions.
+
+Regex Delete
+ Deletes all objects from the cache which match the provided regular
+ expressions.
+
+Regex Invalidate
+ Marks any objects in the cache which match the given regular expressions as
+ stale. Traffic Server will contact the relevant origin server(s) to confirm
+ the validity and freshness of the cached object, updating the cached object
+ if necessary.
.. note::
Only one administrator should delete and invalidate cache
- entries from the Cache page at any point in time. Changes made by
+ entries from the Cache Inspector at any point in time. Changes made by
multiple administrators at the same time can lead to unpredictable
results.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/configuring-traffic-server.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/configuring-traffic-server.en.rst b/doc/admin/configuring-traffic-server.en.rst
index 2fe0443..0e23a7c 100644
--- a/doc/admin/configuring-traffic-server.en.rst
+++ b/doc/admin/configuring-traffic-server.en.rst
@@ -1,4 +1,3 @@
-
.. _configuring-traffic-server:
Configuring Traffic Server
@@ -41,7 +40,7 @@ To view a configuration setting, enter the following command::
traffic_line -r var
-where ``var`` is the variable associated with the configuration
+where *var* is the variable associated with the configuration
option. For a list of variables, refer to :ref:`configuration-variables`.
Change Configuration Options in Traffic Line
@@ -52,8 +51,8 @@ command::
traffic_line -s var -v value
-where ``var`` is the variable associated with the configuration option
-and ``value`` is the value you want to use. For a list of the
+where *var* is the variable associated with the configuration option
+and *value* is the value you want to use. For a list of the
variables, see :ref:`configuration-variables`.
Configure Traffic Server Using Configuration Files
@@ -61,14 +60,13 @@ Configure Traffic Server Using Configuration Files
As an alternative to using Traffic Line or Traffic Shell, you can change
Traffic Server configuration options by manually editing specific
-variables in the :file:`records.config` file.
-After modifying the :file:`records.config` file,
-Traffic Server must reread the configuration files: enter the Traffic
-Line command :option:`traffic_line -x`. You may need to restart Traffic Server
-to apply some of the configuration changes.
+variables in :file:`records.config`.
+
+Traffic Server must reread the configuration files for any changes to take effect.
+This is done with :option:`traffic_line -x`. Some configuration changes require a
+full restart of Traffic Server.
-The following is a sample portion of the
-:file:`records.config` file:
+The following is a sample portion of :file:`records.config`:
.. figure:: ../static/images/admin/records.jpg
:align: center
@@ -76,7 +74,7 @@ The following is a sample portion of the
Sample records.config file
-In addition to the :file:`records.config` file,
+In addition to :file:`records.config`,
Traffic Server provides other configuration files that are used to
configure specific features. You can manually edit all configuration
files as described in :ref:`configuration-file-reference`.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/event-logging-formats.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/event-logging-formats.en.rst b/doc/admin/event-logging-formats.en.rst
index b81a4e7..50c5b0b 100644
--- a/doc/admin/event-logging-formats.en.rst
+++ b/doc/admin/event-logging-formats.en.rst
@@ -5,20 +5,20 @@ Event Logging Formats
.. 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
-
+ 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.
+
+ 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.
This document provides a reference for all the different logging formats
Traffic Server supports.
@@ -37,103 +37,146 @@ Custom Logging Fields
The following list describes Traffic Server custom logging fields.
+.. _cqh:
+
``{HTTP header field name}cqh``
Logs the information in the requested field of the client request
HTTP header. For example, ``%<{Accept-Language}cqh>`` logs the
``Accept-Language:`` field in client request headers.
+.. _pqh:
+
``{HTTP header field name}pqh``
Logs the information in the requested field of the proxy request
HTTP header. For example, ``%<{Authorization}pqh>`` logs
the ``Authorization:`` field in proxy request headers.
+.. _psh:
+
``{HTTP header field name}psh``
Logs the information in the requested field of the proxy response
HTTP header. For example, ``%<{Retry-After}psh>`` logs the
``Retry-After:`` field in proxy response headers.
+.. _ssh:
+
``{HTTP header field name}ssh``
Logs the information in the requested field of the server response
HTTP header. For example, ``%<{Age}ssh>`` logs the ``Age:`` field in
server response headers.
+.. _caun:
+
``caun``
The client authenticated username; result of the RFC931/ident lookup
of the client username.
+.. _cfsc:
+
``cfsc``
The client finish status code; specifies whether the client request
to Traffic Server was successfully completed (``FIN``) or
interrupted (``INTR``).
+.. _chi:
+
``chi``
The IP address of the client's host machine.
+.. _chih:
+
``chih``
The IP address of the client's host machine in hexadecimal.
+.. _chp:
+
``chp``
The port number of the client's host machine.
+.. _cps:
+
``cps``
Client Protocol Stack, the output would be the conjunction of
protocol names in the stack spliced with '+', such as "TLS+SPDY".
+.. _cqbl:
+
``cqbl``
The client request transfer length; the body length in the client
request to Traffic Server (in bytes).
+.. _cqhl:
+
``cqhl``
The client request header length; the header length in the client
request to Traffic Server.
+.. _cqhm:
+
``cqhm``
The HTTP method in the client request to Traffic Server: ``GET``,
``POST``, and so on (subset of ``cqtx``).
+.. _cqhv:
+
``cqhv``
The client request HTTP version.
+.. _cqtd:
+
``cqtd``
The client request timestamp. Specifies the date of the client
request in the format yyyy-mm-dd, where yyyy is the 4-digit year, mm
is the 2-digit month, and dd is the 2-digit day.
+.. _cqtn:
+
``cqtn``
The client request timestamp; date and time of the client's request
(in the Netscape timestamp format).
+.. _cqtq:
+
``cqtq``
The client request timestamp, with millisecond resolution.
+.. _cqts:
+
``cqts``
The client-request timestamp in Squid format; the time of the client
request since January 1, 1970 UTC. Time is expressed in seconds,
with millisecond resolution.
+.. _cqtt:
+
``cqtt``
The client request timestamp. The time of the client request in the
format hh:mm:ss, where hh is the two-digit hour in 24-hour format,
mm is the two-digit minutes value, and ss is the 2-digit seconds
value (for example, 16:01:19).
+.. _cqtx:
+
``cqtx``
The full HTTP client request text, minus headers; for example, ::
GET http://www.company.com HTTP/1.0
In reverse proxy mode, Traffic Server logs the rewritten/mapped URL
- (according to the rules in the
- :file:`remap.config` file), _not_ the pristine/unmapped URL.
+ (according to the rules in :file:`remap.config`), _not_ the
+ pristine/unmapped URL.
+
+.. _cqu:
``cqu``
The universal resource identifier (URI) of the request from client
to Traffic Server (subset of ``cqtx`` ).
In reverse proxy mode, Traffic Server logs the rewritten/mapped URL
- (according to the rules in the
- :file:`remap.config` file),
- _not_ the pristine/unmapped URL.
+ (according to the rules in :file:`remap.config`), _not_ the
+ pristine/unmapped URL.
+
+.. _cquc:
``cquc``
The client request canonical URL. This differs from ``cqu`` in that
@@ -144,6 +187,8 @@ The following list describes Traffic Server custom logging fields.
See `cquuc`_.
+.. _cqup:
+
``cqup``
The client request URL path; specifies the argument portion of the
URL (everything after the host). For example, if the URL is
@@ -152,6 +197,8 @@ The following list describes Traffic Server custom logging fields.
See `cquup`_.
+.. _cqus:
+
``cqus``
The client request URL scheme.
@@ -173,50 +220,76 @@ The following list describes Traffic Server custom logging fields.
The client request unmapped URL host. This field records a URL's
host before it is remapped (reverse proxy mode).
+.. _crat:
+
``crat``
The Retry-After time in seconds, if specified by the origin server.
+.. _crc:
+
``crc``
The cache result code; specifies how the cache responded to the
request (``HIT``, ``MISS``, and so on).
+.. _csscl:
+
``csscl``
The cached response length (in bytes) from origin server to Traffic
Server.
+.. _csshl:
+
``csshl``
The cached header length in the origin server response to Traffic
Server (in bytes).
+.. _csshv:
+
``csshv``
The cached server response HTTP version (1.0, 1.1, etc.).
+.. _csssc:
+
``csssc``
The cached HTTP response status code from origin server to Traffic
Server.
+.. _cwr:
+
``cwr``
The cache write result (``-``, ``WL_MISS``, ``INTR```, ``ERR`` or ``FIN``)
+.. _cwtr:
+
``cwtr``
The cache write transform result
+.. _fsiz:
+
``fsiz``
The size of the file (*n* bytes) as seen by the origin server.
+.. _pfsc:
+
``pfsc``
The proxy finish status code; specifies whether the Traffic Server
request to the origin server was successfully completed (``FIN``),
interrupted (``INTR``) or timed out (``TIMEOUT``).
+.. _phn:
+
``phn``
The hostname of the Traffic Server that generated the log entry in
collated log files.
+.. _phi:
+
``phi``
The IP of the Traffic Server that generated the log entry in
collated log files.
+.. _phr:
+
``phr``
The proxy hierarchy route; the route Traffic Server used to retrieve
the object.
@@ -231,75 +304,110 @@ The following list describes Traffic Server custom logging fields.
``pitag``
The plugin tag for the transaction. This is set for plugin driven transactions via :c:func:`TSHttpConnectWithPluginId`.
+.. _pqbl:
+
``pqbl``
The proxy request transfer length; the body length in Traffic
Server's request to the origin server.
+.. _pqhl:
+
``pqhl``
The proxy request header length; the header length in Traffic
Server's request to the origin server.
+.. _pqsi:
+
``pqsi``
The proxy request server IP address (0 on cache hits and parent-ip
for requests to parent proxies).
+.. _pqsn:
+
``pqsn``
The proxy request server name; the name of the server that fulfilled
the request.
+.. _pscl:
+
``pscl``
The length of the Traffic Server response to the client (in bytes).
+.. _psct:
+
``psct``
The content type of the document from server response header: (for
example, ``img/gif`` ).
+.. _pshl:
+
``pshl``
The header length in Traffic Server's response to the client.
+.. _psql:
+
``psql``
The proxy response transfer length in Squid format (includes header
and content length).
+.. _pssc:
+
``pssc``
The HTTP response status code from Traffic Server to the client.
+.. _shi:
+
``shi``
The IP address resolved from the DNS name lookup of the host in the
request. For hosts with multiple IP addresses, this field records
the IP address resolved from that particular DNS lookup.
This can be misleading for cached documents. For example: if the
- first request was a cache miss and came from **``IP1``** for server
- **``S``** and the second request for server **``S``** resolved to
- **``IP2``** but came from the cache, then the log entry for the
- second request will show **``IP2``**.
+ first request was a cache miss and came from *IP1* for server
+ *S* and the second request for server *S* resolved to
+ *IP2* but came from the cache, then the log entry for the
+ second request will show *IP2*.
+
+.. _shn:
``shn``
The hostname of the origin server.
+.. _sscl:
+
``sscl``
The response length (in bytes) from origin server to Traffic Server.
+.. _sshl:
+
``sshl``
- The header length in the origin server response to Traffic Server
- (in bytes).
+ The header length (in bytes) in the origin server response to Traffic Server.
+
+.. _sshv:
``sshv``
The server response HTTP version (1.0, 1.1, etc.).
+.. _sssc:
+
``sssc``
The HTTP response status code from origin server to Traffic Server.
+.. _ttms:
+
``ttms``
The time Traffic Server spends processing the client request; the
number of milliseconds between the time the client establishes the
connection with Traffic Server and the time Traffic Server sends the
last byte of the response back to the client.
+.. _ttmsh:
+
``ttmsh``
Same as ``ttms`` but in hexadecimal.
+.. _ttmsf:
+
``ttmsf``
The time Traffic Server spends processing the client request as a
fractional number of seconds. Time is specified in millisecond
@@ -311,6 +419,8 @@ The following list describes Traffic Server custom logging fields.
displays 1.5 while the ``ttms`` field displays 1500 and the ``tts``
field displays 1.
+.. _tts:
+
``tts``
The time Traffic Server spends processing the client request; the
number of seconds between the time at which the client establishes
@@ -333,20 +443,20 @@ Squid Logging Formats
The following is a list of the Squid logging fields and the
corresponding logging field symbols.
-================== =============
-Squid Field Symbols
-================== =============
-``time`` ``cqts``
-``elapsed`` ``ttms``
-``client`` ``chi``
-``action/code`` ``crc/pssc``
-``size`` ``psql``
-``method`` ``cqhm``
-``url`` ``cquc``
-``ident`` ``caun``
-``hierarchy/from`` ``phr/pqsn``
-``content`` ``psct``
-================== =============
+============== =============
+Squid Field Symbols
+============== =============
+time `cqts`_
+elapsed `ttms`_
+client `chi`_
+action/code `crc`_/`pssc`_
+size `psql`_
+method `cqhm`_
+url `cquc`_
+ident `caun`_
+hierarchy/from `phr`_/`pqsn`_
+content `psct`_
+============== =============
Netscape Common Logging Formats
-------------------------------
@@ -357,12 +467,12 @@ corresponding Traffic Server logging field symbols.
=============== =============
Netscape Common Field Symbols
=============== =============
-``host`` ``chi``
-``usr`` ``caun``
-``[time]`` ``[cqtn]``
-``"req"`` ``"cqtx"``
-``s1`` ``pssc``
-``c1`` ``pscl``
+host `chi`_
+usr `caun`_
+[time] [`cqtn`_]
+"req" "`cqtx`_"
+s1 `pssc`_
+c1 `pscl`_
=============== =============
Netscape Extended Logging Formats
@@ -374,21 +484,21 @@ corresponding Traffic Server logging field symbols.
================= =============
Netscape Extended Field Symbols
================= =============
-``host`` ``chi``
-``usr`` ``caun``
-``[time]`` ``[cqtn]``
-``"req"`` ``"cqtx"``
-``s1`` ``pssc``
-``c1`` ``pscl``
-``s2`` ``sssc``
-``c2`` ``sscl``
-``b1`` ``cqbl``
-``b2`` ``pqbl``
-``h1`` ``cqhl``
-``h2`` ``pshl``
-``h3`` ``pqhl``
-``h4`` ``sshl``
-``xt`` ``tts``
+host `chi`_
+usr `caun`_
+[time] [`cqtn`_]
+"req" "`cqtx`_"
+s1 `pssc`_
+c1 `pscl`_
+s2 `sssc`_
+c2 `sscl`_
+b1 `cqbl`_
+b2 `pqbl`_
+h1 `cqhl`_
+h2 `pshl`_
+h3 `pqhl`_
+h4 `sshl`_
+xt `tts`_
================= =============
Netscape Extended-2 Logging Formats
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/explicit-proxy-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/explicit-proxy-caching.en.rst b/doc/admin/explicit-proxy-caching.en.rst
index 60341b4..86dd503 100644
--- a/doc/admin/explicit-proxy-caching.en.rst
+++ b/doc/admin/explicit-proxy-caching.en.rst
@@ -5,20 +5,20 @@ Explicit Proxy Caching
.. 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
-
+ 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.
+
+ 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.
.. toctree::
:maxdepth: 2
@@ -42,9 +42,9 @@ To manually configure a browser to send HTTP requests to Traffic Server,
clients must provide the following information:
- The fully-qualified hostname or IP address of the Traffic Server node
-- The Traffic Server proxy server port (port 8080)
+- The Traffic Server proxy server port (by default, 8080)
-In addition, clients can specify *not* to use Traffic Server for certain
+In addition, clients can specify not to use Traffic Server for certain
sites - in such cases, requests to the listed sites go directly to the
origin server. The procedures for manual configuration vary among
browser versions; refer to specific browser documentation for complete
@@ -57,13 +57,13 @@ from manually-configured browsers.
Using a PAC File
================
-A **PAC file** is a specialized JavaScript function definition that a
+A *PAC file* is a specialized JavaScript function definition that a
browser calls to determine how requests are handled. Clients must
specify (in their browser settings) the URL from which the PAC file is
loaded. You can store a PAC file on Traffic Server (or on any server in
your network) and then provide the URL for this file to your clients.
-If you want to store a PAC file on the Traffic Server system, then you
+If you want to store a PAC file on the Traffic Server system, you
must perform the following configuration:
- Either copy an existing PAC file into the Traffic Server ``config``
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/faqs.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/faqs.en.rst b/doc/admin/faqs.en.rst
index cc19c29..d6dd259 100644
--- a/doc/admin/faqs.en.rst
+++ b/doc/admin/faqs.en.rst
@@ -1,4 +1,4 @@
-.. _admin-faqs:
+.. _faqs:
FAQ and Troubleshooting Tips
****************************
@@ -59,9 +59,9 @@ Can Traffic Server cache Java applets, JavaScript programs, or other application
Yes, Traffic Server can store and serve Java applets, JavaScript
programs, VBScripts, and other executable objects from its cache
according to the freshness and cacheability rules for HTTP objects.
-Traffic Server does not execute the applets, scripts, or programs,
-however - these objects run only when the client system (ie, the one
-that sent the request) loads them.
+Traffic Server does not execute the applets, scripts, or programs.
+These objects run entirely client-side (the system which originated
+the request for the objects), and do not execute on the server.
In Squid- and Netscape-format log files, what do the cache result codes mean?
-----------------------------------------------------------------------------
@@ -71,9 +71,9 @@ This is described in detail in the :ref:`log-formats-squid-format` documentation
What is recorded by the ``cqtx`` field in a custom log file?
------------------------------------------------------------
-- In **forward proxy mode**, the cqtx field records the complete client
+- In *forward proxy mode*, the ``cqtx`` field records the complete client
request in the log file (for example, ``GET http://www.company.com HTTP/1.0``).
-- In **reverse proxy mode**, the cqtx field records the hostname or IP
+- In *reverse proxy mode*, the ``cqtx`` field records the hostname or IP
address of the origin server because Traffic Server first remaps the
request as per map rules in the :file:`remap.config` file.
@@ -88,7 +88,7 @@ to compare the ``ttl`` value set by the name server with the ``ttl``
value set by Traffic Server, and then use either the lower or the higher
value.
-see :ts:cv:`proxy.config.hostdb.ttl_mode` for more info
+Refer to :ts:cv:`proxy.config.hostdb.ttl_mode` for more info.
Can you improve the look of your custom response pages by using images, animated .gifs, and Java applets?
---------------------------------------------------------------------------------------------------------
@@ -105,14 +105,14 @@ Can Traffic Server run in forward proxy and reverse proxy modes at the same time
---------------------------------------------------------------------------------
Yes. When you enable reverse proxy mode, Traffic Server remaps incoming
-requests according to the map rules in the :file:`remap.config` file. All
-other requests that do not match a map rule are simply served in forward
+requests according to the map rules in :file:`remap.config`. All
+other requests that do not match a map rule are served in forward
proxy mode.
If you want to run in reverse proxy only mode (wherein Traffic Server
-does *not* serve requests that fail to match a map rule), then you must
+does not serve requests that fail to match a map rule), then you must
set the configuration variable :ts:cv:`proxy.config.url_remap.remap_required`
-to ``1`` in the :file:`records.config` file.
+to ``1`` in :file:`records.config`.
How do I enable forward proxy mode
----------------------------------
@@ -325,24 +325,23 @@ blank no server connection
Support for HTTP Expect: Header
-------------------------------
-Traffic Server currently does not handle request Expect: headers
+Traffic Server currently does not handle Expect: request headers
according to the HTTP/1.1 spec.
-Note that clients such as cURL automatically send Expect: for POST
+Clients such as cURL automatically send Expect: for POST
requests with large POST bodies, with a 1 second timeout if a 100
Continue response is not received. To avoid the timeout when using cURL
-as a client to Traffic Server, you can turn off the Expect: header as
-follows::
+as a client to Traffic Server, you can turn off the Expect: header::
curl -H"Expect:" http://www.example.com/
-C (libcurl)::
+Or with the C (libcurl) library from within your own applications::
struct curl_slist *header_list=NULL;
header_list = curl_slist_append(header_list, "Expect:");
curl_easy_setopt(my_curlp, CURLOPT_HTTPHEADER, header_list);
-php::
+Or with the PHP cURL library::
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));
@@ -364,28 +363,31 @@ You are unable to execute Traffic Line commands
Traffic Line commands do not execute under the following conditions:
-- **When the traffic_manager process is not running** Check to see
- if the :program:`traffic_manager` process is running by entering the
- following command: ``pgrep -l traffic_manager``
+**When the traffic_manager process is not running**
+ Check to see if the :program:`traffic_manager` process is running by entering the
+ following command::
- If the :program:`traffic_manager` process is not running, then enter the
- following command from the Traffic Server ``bin`` directory to start it:
- ``./traffic_manager``
+ pgrep -l traffic_manager
- .. this is wrong
+ If the :program:`traffic_manager` process is not running, then enter the
+ following command from the Traffic Server ``bin`` directory to start it::
- You should always start and stop Traffic Server with the
- :program:`trafficserver start`` and :program:`trafficserver stop` commands to ensure
- that all the processes start and stop correctly. For more information,
- refer to :ref:`getting-started`.
+ ./traffic_manager
-- **When you are not executing the command from $TSHome/bin** If the Traffic Server
- ``bin`` directory is not in your path, then prepend the Traffic Line
- commands with ``./`` (for example, ``./traffic_line -h``).
+.. XXX: this is wrong
-- **When multiple Traffic Server installations are present and you are not
- executing the Traffic Line command from the active Traffic Server path
- specified in ``/etc/trafficserver``**
+ You should always start and stop Traffic Server with the
+ :program:`trafficserver start`` and :program:`trafficserver stop` commands to ensure
+ that all the processes start and stop correctly. For more information,
+ refer to :ref:`getting-started`.
+
+**When you are not executing the command from $TSHome/bin**
+ If the Traffic Server ``bin`` directory is not in your path, then prepend the
+ Traffic Line commands with ``./`` (for example, ``./traffic_line -h``).
+
+**When multiple Traffic Server installations are present and you are not
+executing the Traffic Line command from the active Traffic Server path
+specified in ``/etc/trafficserver``**
You observe inconsistent behavior when one node obtains an object from another node in the cluster
@@ -397,7 +399,7 @@ problems, but differences of more than a few minutes can affect Traffic
Server operation.
You should run a clock synchronization daemon such as xntpd. To obtain
-the latest version of xntpd, go to ``http://www.eecis.udel.edu/~ntp/``
+the latest version of xntpd, go to `<http://www.eecis.udel.edu/~ntp/>`_.
Web browsers display an error document with a 'data missing' message
--------------------------------------------------------------------
@@ -411,7 +413,7 @@ A message similar to the following might display in web browsers: ::
This is a Web browser issue and not a problem specific to (or caused by)
Traffic Server. Because Web browsers maintain a separate local cache in
memory and/or disk on the client system, messages about documents that
-have expired from cache refer to the browser's local cache and *not*
+have expired from cache refer to the browser's local cache and not
to the Traffic Server cache. There is no Traffic Server message or
condition that can cause such messages to appear in a web browser.
@@ -437,8 +439,8 @@ read the name resolution file:
then you must add a name server entry for ``127.0.0.1`` or
``0.0.0.0`` in the :manpage:`resolv.conf(5)` file.
- Check that the Traffic Server user account has permission to read the
- /etc/resolv.conf file. If it does not, then change the file
- permissions to ``rw-r--r--`` (``644``)
+ :manpage:`resolv.conf(5)` file. If it does not, then change the file
+ permissions to ``rw-r--r--`` (``644``).
'Maximum document size exceeded' message in the system log file
---------------------------------------------------------------
@@ -465,11 +467,11 @@ The following messages may appear in the system log file: ::
Feb 20 23:53:58 louis traffic_manager[4414]: ERROR ==> [drainIncomingChannel] Unknown message: 'GET http://www.ip.pt/ HTTP/1.0'
These error messages indicate that a browser is sending HTTP requests to
-one of the Traffic Server cluster ports - either ``rsport`` (default
+one of the Traffic Server cluster ports, either ``rsport`` (default
port 8088) or ``mcport`` (default port 8089). Traffic Server discards
-the request; this error does not cause any Traffic Server problems. The
+these requests. This error does not cause any Traffic Server problems. The
misconfigured browser must be reconfigured to use the correct proxy
-port. Traffic Server clusters work best when configured to use a
+port. Traffic Server clusters should ideally be configured to use a
separate network interface and cluster on a private subnet, so that
client machines have no access to the cluster ports.
@@ -487,77 +489,84 @@ starting :program:`traffic_manager` or performing any health checks. The
it has been stopped with the option:`trafficserver stop` command. Without
this static control, Traffic Server would restart automatically upon
system reboot. The ``no_cop`` control keeps Traffic Server off until it
-is explicitly restarted with the ::
+is explicitly restarted with: ::
trafficserver start
-command.
-
-
Warning in the system log file when manually editing vaddrs.config
------------------------------------------------------------------
-If you manually edit the vaddrs.config file as a non-root user, then
+If you manually edit :file:`vaddrs.config` as a non-root user, then
Traffic Server issues a warning message in the system log file similar
to the following::
WARNING: interface is ignored: Operation not permitted
-You can safely ignore this message; Traffic Server *does* apply your
+You can safely ignore this message as Traffic Server will still apply your
configuration edits.
Traffic Server is running but no log files are created
------------------------------------------------------
Traffic Server only writes event log files when there is information to
-record. If Traffic Server is idle, then it's possible/probable that no
-log files exist. In addition:
-
-Make sure you're looking in the correct directory. By default, Traffic
-Server creates log files in the logs directory. Check the location of
-log files by checking the value of the variable
-proxy.config.log.logfile_dir in the records.config file. Check that the
-log directory has read/write permissions for the Traffic Server user
-account. If the log directory does not have the correct permissions,
-then the traffic_server process is unable to open or create log files.
-Check that logging is enabled by checking the value of the
-proxy.config.log.logging_enabled variable in the records.config file.
-Check that a log format is enabled. In the records.config file, select
-the standard or custom format by editing variables in the Logging Config
-section.
+record. If Traffic Server is idle, then it's possible that no log files
+exist.
+
+If Traffic Server is not idle, and you still do not see log files being
+generated, verify the following:
+
+- Make sure you're looking in the correct directory. By default, Traffic
+ Server creates log files in the ``logs`` directory. This can be modified
+ by changing :ts:cv:`proxy.config.log.logfile_dir` in :file:`records.config`.
+
+- Check that the log directory has read/write permissions for the Traffic
+ Server user account. If the log directory does not have the correct
+ permissions, then the :program:`traffic_server` process will be unable to
+ open or create log files.
+
+- Check that logging is enabled by checking the value of the
+ :ts:cv:`proxy.config.log.logging_enabled` variable in :file:`records.config`.
+
+- Check that a log format is enabled. In :file:`records.config`, select
+ the standard or custom format by editing variables in the Logging Config
+ section.
Traffic Server shows an error indicating too many network connections
---------------------------------------------------------------------
-By default, Traffic Server supports 8000 network connections: half of
+By default, Traffic Server supports 8000 network connections. Half of
this number is allocated for client connections and the remaining half
-is for origin server connections. A **connection throttle event** occurs
-when client or origin server connections reach 90% of half the
-configured limit (3600 by default). When a connection throttle event
+is for origin server connections. A *connection throttle event* occurs
+when either client or origin server connections reach 90% of half the
+configured total limit (3600 by default). When a connection throttle event
occurs, Traffic Server continues processing all existing connections but
will not accept new client connection requests until the connection
count falls below the limit.
Connection throttle events can occur under the following conditions:
-- If there is a **connection spike** (e.g., if thousands of client
- requests all reach Traffic Server at the same time). Such events are
- typically transient and require no corrective action.
-- If there is a **service overload** (e.g., if client requests
- continuously arrive faster than Traffic Server can service them).
- Service overloads often indicate network problems between Traffic
- Server and origin servers. Conversely, it may indicate that Traffic
- Server needs more memory, CPU, cache disks, or other resources to
- handle the client load.
-
-If necessary, you can reset the maximum number of connections supported
-by Traffic Server by editing the value of the
-:ts:cv:`proxy.config.net.connections_throttle` configuration variable in
-the records.config file. Do not increase the connection throttle limit
-unless the system has adequate memory to handle the client connections
-required. A system with limited RAM might need a throttle limit lower
-than the default value. Do not set this variable below the minimum value
-of 100.
+Connection Spike
+ Too many client requests (enough to exceed your configured maximum connections)
+ all reach Traffic Server at the same time. Such events are typically transient
+ and require no corrective action if your connection limits are already
+ configured appropriately for your Traffic Server and origin resources.
+
+Service Overload
+ Client requests are arriving at a rate faster than that which Traffic
+ Server can service them. This may indicate network problems between Traffic
+ Server and origin servers or that Traffic Server may require more memory, CPU,
+ cache disks, or other resources to handle the client load.
+
+If necessary, you can adjust the maximum number of connections supported
+by Traffic Server by editing :ts:cv:`proxy.config.net.connections_throttle` in
+:file:`records.config`.
+
+.. note::
+
+ Do not increase the connection throttle limit unless the system has adequate
+ memory to handle the client connections required. A system with limited RAM
+ might need a throttle limit lower than the default value. Do not set this
+ variable below the minimum value of ``100``.
Low memory symptoms
-------------------
@@ -582,9 +591,9 @@ load on Traffic Server.
Connection timeouts with the origin server
------------------------------------------
-Certain origin servers take longer than 30 seconds to post HTTP
-requests, which results in connection timeouts with Traffic Server. To
-prevent such connection timeouts, you must change the value of the
-configuration variable proxy.config.http.connect_attempts_timeout in
-the records.config file to 60 seconds or more.
+By default, Traffic Server will timeout after 30 seconds when contacting
+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.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/forward-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/forward-proxy.en.rst b/doc/admin/forward-proxy.en.rst
index 03c3d77..8420b1b 100644
--- a/doc/admin/forward-proxy.en.rst
+++ b/doc/admin/forward-proxy.en.rst
@@ -5,76 +5,120 @@ Forward Proxy
.. 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
-
+ 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.
-The Apache Traffic Server is a general purpose *proxy*. As such it can
-also be used as forward proxy.
+ 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.
+
+The Apache Traffic Server is a general purpose proxy, configurable as both a
+reverse and forward proxy.
+
+A forward proxy can be used as a central tool in your infrastructure
+to access the web and it may be combined with a cache to lower your overall
+bandwidth usage. Forward proxies act as a gatekeeper between client browsers
+on your local network and all (or some, at your configuration's discretion)
+web sites accessed by those clients. The forward proxy will receive the
+HTTP requests, perform any filtering or request alteration rules you
+establish, and when appropriate forward the request on to its destination
+website. The response will return through your proxy, where it may optionally
+be cached and/or modified, and then returned to the original client.
+
+There are two modes in which your forward proxy may operate:
+
+Forward Proxy
+ Each client must be configured explicitly to use the forward proxy. Client
+ browsers will be aware of the fact they are using a proxy and will form their
+ HTTP requests appropriately. This results in the initial HTTP command being
+ issued with fully qualified URIs that contain the destination hostname::
-A forward proxy is can be used as a central tool in your infrastructure
-to access the web. In combination with a cache that means overall
-reduced bandwidth usage.
+ GET http://example.com/index.php?id=123 HTTP/1.1
-If your forward proxy is not also configured as :ref:`transparent-proxy`
-your clients will have to be configured to actually use it.
+Transparent Proxy
+ The use of a transparent proxy is typically done in concert with network
+ routing rules which redirect all outbound HTTP traffic through your proxy.
+ Clients will behave, and form their HTTP requests, as if they are contacting
+ the remote site directly, and will not be aware of the existence of a proxy
+ server in between themselves and the remote servers. HTTP requests will be
+ generated per their usual form, with only paths in the command and a
+ separate Host request header::
-The main difference between a forward and a transparent proxy is that
-User Agents *know* that they are accessing a proxy, thus forming their
-requests like so: ::
+ GET /index?id=123 HTTP/1.1
+ Host: example.com
- GET http://example.com/index.php?id=1337 HTTP/1.1
+Apache Traffic Server may be configured to operate as both a forward and
+a transparent proxy simultaneously.
-This request, then is translated by the proxy to::
+Proxy Configuration
+===================
- GET /index?id=1337 HTTP/1.1
- Host: example.com
+Configuring basic forward proxy operation in Traffic Server is quite simple
+and straightforward.
-Apache Traffic Server offers two ways to User Agents: They can either be
-pointed directly to the default ``8080`` port. Alternatively, they can
-be pointed to the more dynamic :ts:cv:`proxy.config.url_remap.default_to_server_pac`
+1. Permit Traffic Server to process requests for hosts not explicitly configured
+ in the remap rules, by modifying :ts:cv:`proxy.config.url_remap.remap_required`
+ in :file:`records.config`::
-This port will then serve a JavaScript like configuration that User
-Agents can use to determine where to send their requests to.
+ CONFIG proxy.config.url_remap.remap_required INT 0
-Configuration
-=============
+2. *Optional*: If Traffic Server will be operating strictly as a forward proxy,
+ you will want to disable reverse proxy support by modifying
+ :ts:cv:`proxy.config.reverse_proxy.enabled` in :file:`records.config`::
-In order to configure Apache Traffic Server as forward proxy you will
-have to edit :file:`records.config` and set
+ CONFIG proxy.config.reverse_proxy.enabled INT 0
-- :ts:cv:`proxy.config.url_remap.remap_required` to ``0``
+You may also want to consider some of these configuration options:
-If your proxy is serving as *pure* forward proxy, you will also want to
-set
+- Setting :ts:cv:`proxy.config.http.no_dns_just_forward_to_parent` determines which
+ host will be used for DNS resolution.
-- :ts:cv:`proxy.config.reverse_proxy.enabled` to ``0``
+- Proxy Authentication can be enabled or disabled with
+ :ts:cv:`proxy.config.http.forward.proxy_auth_to_parent` should you also be
+ employing a proxy cache.
-Other configuration variables to consider:
+- The client request header X-Forwarded-For may be toggled with
+ :ts:cv:`proxy.config.http.insert_squid_x_forwarded_for`.
-- :ts:cv:`proxy.config.http.no_dns_just_forward_to_parent`
-- :ts:cv:`proxy.config.http.forward.proxy_auth_to_parent`
-- :ts:cv:`proxy.config.http.insert_squid_x_forwarded_for`
+Client Configuration
+====================
+
+If you are operating your proxy in transparent mode, your clients should require
+no special proxy-related configuration.
+
+If you are operating in explicit forward proxy mode, without automatic routing
+rules on your network to direct all outbound traffic through the proxy, your
+client browsers will need to be directed to the proxy. This may be accomplished
+in two different ways.
+
+Clients may be configured to use the default ``8080`` port on your Traffic Server
+host as a proxy. This will result in all requests from that client browser being
+issued through the single forward proxy as configured.
+
+Alternatively, you may configure clients to use the more dynamic
+:ts:cv:`proxy.config.url_remap.default_to_server_pac` port, which will deliver a
+Javascript based PAC configuration to the client. This permits you to configure
+rules on which proxy servers are used for various types of requests, or to allow
+some requests to bypass proxies all together.
Security Considerations
=======================
-It's important to note that once your Apache Traffic Server is
-configured as forward proxy it will indiscriminately accept proxy
-requests from anyone. That means, if it's reachable on the internet, you
-have configured an *Open Proxy*. Most of the time, this is *not* what
-you want, so you'll have to make sure it's either only reachable within
-your NAT or is secured by firewall rules that permit only those clients
-to access it which you want to it to access.
+It's important to note that once your Apache Traffic Server is configured as a
+forward proxy it will indiscriminately accept proxy requests from anyone. If it
+is reachable from the Internet, then you have configured an *Open Proxy*.
+
+This is generally not desirable, as it will permit anyone to potentially use
+your network as the source of traffic to sites of their choosing. To avoid
+this, you'll have to make sure your proxy server is either only reachable from
+within your private network or is secured by firewall rules that permit only
+those you wish to have access to the proxy.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/getting-started.en.rst b/doc/admin/getting-started.en.rst
index bdb68d8..c03c756 100644
--- a/doc/admin/getting-started.en.rst
+++ b/doc/admin/getting-started.en.rst
@@ -1,4 +1,3 @@
-
.. _getting-started:
Getting Started
@@ -6,46 +5,47 @@ Getting Started
.. 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.
+ 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.
.. toctree::
:maxdepth: 2
-Before you start
+Before You Start
================
Before you get started with Traffic Server you may have to decide which
version you want to use. Traffic Server follows the `Semantic Versioning
-<http://semver.org>`_ guidelines, in summary
+<http://semver.org>`_ guidelines.
-A version is made of a version-triplet: ``MAJOR.MINOR.PATCH``
+A complete version number is made of a version-triplet: ``MAJOR.MINOR.PATCH``.
As of v4.0.0, there are no longer any development (or unstable) releases.
-All releases are considered stable and ready for production use, releases
+All releases are considered stable and ready for production use. Releases
within a major version are always upgrade compatible. More details are
-available on the `Wiki page
-<https://cwiki.apache.org/confluence/display/TS/New+Release+Processes>`_.
-
-Sometimes we speak of trunk, master or HEAD, all of which are used
-interchangeably: trunk or master or sometimes TIP or HEAD, refer to the
-latest code in a Git Version Control System. Master is always kept releasable,
-and compatible with the current major release version. Incompatible changes
-are sometimes committed on a next-major release branch, for example we have
-the ``5.0.x`` branch where changes incompatible with 4.x are managed.
+available on the `New Release Processes
+<https://cwiki.apache.org/confluence/display/TS/New+Release+Processes>`_ wiki
+page.
+
+Sometimes we speak of *trunk*, *master* or *HEAD*, all of which are used
+interchangeably. Trunk and master, or sometimes TIP or HEAD, refer to the
+latest code in a Git version control system (also referred to as a *repository*
+or *Git repo*). Master is always kept releasable, and compatible with the
+current major release version. Incompatible changes are sometimes committed on
+a next-major release branch; for example, we have the ``5.0.x`` branch where
+changes incompatible with 4.x are managed.
If your distribution does not come with a prepackaged Traffic Server,
please go to `downloads </downloads>`_ to choose the version that you
@@ -53,20 +53,23 @@ consider most appropriate for yourself. If you want to really be on the
bleeding edge you can clone our `git
repository <https://git-wip-us.apache.org/repos/asf/trafficserver.git>`_.
-Please note that while we do have a `GitHub
-Mirror <https://github.com/apache/trafficserver>`_ that you can also use
-to submit pull requests, it may not be entirely up-to-date.
+.. note::
+
+ We do also have a `GitHub Mirror <https://github.com/apache/trafficserver>`_
+ that you may use to submit pull requests. However, it may not be
+ entirely up-to-date, and you should always refer to our official project
+ Git repository for the very latest state of the source code.
Building Traffic Server
=======================
In order to build Traffic Server from source you will need the following
-(development) packages:
+development tools and libraries installed:
- pkgconfig
- libtool
- gcc (>= 4.3 or clang > 3.0)
-- make (GNU Make!)
+- GNU make
- openssl
- tcl
- expat
@@ -75,64 +78,67 @@ In order to build Traffic Server from source you will need the following
- flex (for TPROXY)
- hwloc
- lua
-- curses
-- curl (both for :program:`traffic_top`)
+- curses (for :program:`traffic_top`)
+- curl (for :program:`traffic_top`)
-if you're building from a git clone, you'll also need
+If you're building from a git clone, you'll also need:
- git
- autoconf
- automake
-We will show-case a build from git::
+The following instructions demonstrate building a fresh Traffic Server from
+Git sources.
- git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
+#. Clone the official Git repository for Traffic Server. ::
-Next, we ``cd trafficserver`` and run::
+ git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
- autoreconf -if
+#. Change your work directory to the newly-cloned local repository and run autoreconf. ::
-This will generate a ``configure`` file from ``configure.ac``, so now we
-can run that::
+ cd trafficserver/
+ autoreconf -if
- ./configure --prefix=/opt/ats
+#. A ``configure`` script will be generated from ``configure.ac`` which may now
+ be used to configure the source tree for your build. ::
-Note well, that by default Traffic Server uses the user ``nobody``, as
-well as user's primary group as Traffic Server user. If you want to
-change that, you can override it here::
+ ./configure --prefix=/opt/ats
- ./configure --prefix=/opt/ats --with-user=tserver
+ By default, Traffic Server will be built to use the ``nobody`` user and group.
+ You may change this with the ``--with-user`` argument to ``configure``::
-If dependencies are not in standard paths (``/usr/local`` or ``/usr``),
-you need to pass options to ``configure`` to account for that::
+ ./configure --prefix=/opt/ats --with-user=tserver
- ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw
+ If dependencies are not in standard paths (``/usr/local`` or ``/usr``),
+ you may need to pass options to ``configure`` to account for that::
-Most ``configure`` path-options accept a format of
-``"INCLUDE_PATH:LIBRARY_PATH"``::
+ ./configure --prefix=/opt/ats --with-lua=/opt/csw
- ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw \
- --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
+ Most ``configure`` path-options accept a format of "*INCLUDE_PATH*:*LIBRARY_PATH*"::
-We can run ``make`` to build the project. We highly recommend to run
-``make check`` to verify the build's general sanity::
+ ./configure --prefix=/opt/ats --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
- make
- make check
+#. Once the source tree has been configured, you may proceed on to building with
+ the generated Makefiles. The ``make check`` command may be used to perform
+ sanity checks on the resulting build, prior to installation, and it is
+ recommended that you use this. ::
-We can finally run ``make install`` to install (you may have to switch
-to root to do this)::
+ make
+ make check
- sudo make install
+#. With the source built and checked, you may now install all of the binaries,
+ header files, documentation, and other artifacts to their final locations on
+ your system. ::
-We also recommend to run a regression test. Please note that this will
-only work successfully with the default ``layout``::
+ sudo make install
- cd /opt/ats
- sudo bin/traffic_server -R 1
+#. Finally, it is recommended that you run the regression test suite. Please note
+ that the regression tests will only be successful with the default layout. ::
-After you have installed Traffic Server on your system, you can do any
-of the following:
+ cd /opt/ats
+ sudo bin/traffic_server -R 1
+
+You are now ready to configure and run your Traffic Server installation.
.. _start-traffic-server:
@@ -140,24 +146,19 @@ Start Traffic Server
====================
To start Traffic Server manually, issue the ``trafficserver`` command,
-passing in the attribute ``start``. This command starts all the
+passing in the subcommand ``start``. This command starts all the
processes that work together to process Traffic Server requests as well
-as manage, control, and monitor the health of the Traffic Server system.
-
-To run the ``trafficserver start`` command, e.g.::
+as manage, control, and monitor the health of the Traffic Server system. ::
bin/trafficserver start
-At this point your server is up and running in the default configuration
-of a :ref:`reverse-proxy-and-http-redirects`.
-
.. _start-straffic-line:
Start Traffic Line
==================
Traffic Line provides a quick way of viewing Traffic Server statistics
-and configuring the Traffic Server system via command-line interface. To
+and configuring the Traffic Server system via a command-line interface. To
execute individual commands or script multiple commands, refer to
:program:`traffic_line`.
@@ -172,7 +173,7 @@ For a list of :program:`traffic_line` commands, enter::
Please note that :program:`traffic_line`, while a fine tool for an
administrator, is a poor choice for automation, especially that of
monitoring. See our chapter on :ref:`monitoring-traffic`
-for how to do that better.
+for how to do that more efficiently and effectively.
.. _stop-traffic-server:
@@ -183,7 +184,7 @@ To stop Traffic Server, always use the :program:`trafficserver` command,
passing in the attribute ``stop``. This command stops all the Traffic
Server processes (:program:`traffic_manager`, :program:`traffic_server`, and
:program:`traffic_cop`). Do not manually stop processes, as this can lead to
-unpredictable results.::
+unpredictable results. ::
bin/trafficserver stop
[2/4] Documentation editorial update
Posted by jp...@apache.org.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/reverse-proxy-http-redirects.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/reverse-proxy-http-redirects.en.rst b/doc/admin/reverse-proxy-http-redirects.en.rst
index 683e423..73ebcd2 100644
--- a/doc/admin/reverse-proxy-http-redirects.en.rst
+++ b/doc/admin/reverse-proxy-http-redirects.en.rst
@@ -1,4 +1,3 @@
-
.. _reverse-proxy-and-http-redirects:
Reverse Proxy and HTTP Redirects
@@ -6,21 +5,20 @@ Reverse Proxy and HTTP Redirects
.. 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
-
+ 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.
+ 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.
Reverse Proxy and HTTP Redirects
================================
@@ -32,19 +30,17 @@ appears to clients like a normal origin server.
.. toctree::
:maxdepth: 2
-
Understanding Reverse Proxy Caching
===================================
-With **forward proxy caching**, Traffic Server handles web requests to
-distant origin servers on behalf of the clients requesting the content.
-**Reverse proxy caching** (also known as **server acceleration** or
-**virtual web hosting**) is different because Traffic Server acts as a
-proxy cache on behalf of the origin servers that store the content.
-Traffic Server is configured to be *the* origin server which the client
-is trying to connect to. In a typical scenario the advertised hostname
-of the origin server resolves to Traffic Server, which acts as the real
-origin server.
+With *forward proxy caching*, Traffic Server handles web requests to origin
+servers on behalf of the clients requesting the content. *Reverse proxy
+caching* (also known as *server acceleration*) is different because Traffic
+Server acts as a proxy cache on behalf of the origin servers that store the
+content. Traffic Server is configured to behave outwardly as origin server
+which the client is trying to connect to. In a typical scenario the advertised
+hostname of the origin server resolves to Traffic Server, which serves client
+requests directly, fetching content from the true origin server when necessary.
Reverse Proxy Solutions
-----------------------
@@ -52,20 +48,19 @@ Reverse Proxy Solutions
There are many ways to use Traffic Server as a reverse proxy. Below are
a few example scenarios.
-You can use Traffic Server in reverse proxy mode to:
+- Offload heavily-used origin servers.
-- Offload heavily-used origin servers
-- Deliver content efficiently in geographically distant areas
-- Provide security for origin servers that contain sensitive
- information
+- Deliver content efficiently in geographically distant areas.
+
+- Provide security for origin servers that contain sensitive information.
Offloading Heavily-Used Origin Servers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Traffic Server can absorb requests to the main origin server and improve
-the speed & quality of web serving by reducing load and hot spots on
+Traffic Server can accept requests on behalf of the origin server and improve
+the speed and quality of web serving by reducing load and hot spots on
backup origin servers. For example, a web hoster can maintain a scalable
-Traffic Server serving engine with a set of low-cost, low-performance,
+Traffic Server system with a set of low-cost, low-performance,
less-reliable PC origin servers as backup servers. In fact, a single
Traffic Server can act as the virtual origin server for multiple backup
origin servers, as shown in the figure below.
@@ -85,8 +80,8 @@ geographical proximity. Caches are typically easier to manage and are
more cost-effective than replicating data. For example, Traffic Server
can be used as a mirror site on the far side of a trans-Atlantic link to
serve users without having to fetch the request and content across
-expensive international connections. Unlike replication, for which
-hardware must be configured to replicate all data and to handle peak
+expensive, or higher latency, international connections. Unlike replication,
+for which hardware must be configured to replicate all data and to handle peak
capacity, Traffic Server dynamically adjusts to optimally use the
serving and storing capacity of the hardware. Traffic Server is also
designed to keep content fresh automatically, thereby eliminating the
@@ -100,7 +95,7 @@ an origin server. If an origin server contains sensitive information
that you want to keep secure inside your firewall, then you can use a
Traffic Server outside the firewall as a reverse proxy for that origin
server. When outside clients try to access the origin server, the
-requests instead go to Traffic Server. If the desired content is *not*
+requests instead go to Traffic Server. If the desired content is not
sensitive, then it can be served from the cache. If the content is
sensitive and not cacheable, then Traffic Server obtains the content
from the origin server (the firewall allows only Traffic Server access
@@ -114,12 +109,15 @@ When a browser makes a request, it normally sends that request directly
to the origin server. When Traffic Server is in reverse proxy mode, it
intercepts the request before it reaches the origin server. Typically,
this is done by setting up the DNS entry for the origin server (i.e.,
-the origin server's 'advertised' hostname) so it resolves to the Traffic
+the origin server's advertised hostname) so it resolves to the Traffic
Server IP address. When Traffic Server is configured as the origin
server, the browser connects to Traffic Server rather than the origin
server. For additional information, see `HTTP Reverse Proxy`_.
-.. note:: To avoid a DNS conflict, the origin server’s hostname and its advertised hostname must not be the same.
+.. note::
+
+ To avoid a DNS conflict, the origin server’s hostname and its advertised
+ hostname must not be the same.
HTTP Reverse Proxy
==================
@@ -136,25 +134,39 @@ proxy mode serves an HTTP request from a client browser.
The figure above demonstrates the following steps:
+.. List below should remain manually numbered, as the entries correspond to numbers in the figure above.
+
1. A client browser sends an HTTP request addressed to a host called
``www.host.com`` on port 80. Traffic Server receives the request
because it is acting as the origin server (the origin server’s
advertised hostname resolves to Traffic Server).
-2. Traffic Server locates a map rule in the ``remap.config`` file and
+
+2. Traffic Server locates a map rule in the :file:`remap.config` file and
remaps the request to the specified origin server (``realhost.com``).
-3. Traffic Server opens an HTTP connection to the origin server. (If the request is not able to be served from cache)
-4. If the request is a cache hit and the content is fresh, then Traffic
- Server sends the requested object to the client from the cache.
- Otherwise, Traffic Server obtains the requested object from the
- origin server, sends the object to the client, and saves a copy in
- its cache.
+
+3. If the request cannot be served from cache, Traffic Server opens a
+ connection to the origin server (or more likely, uses an existing
+ connection it has pre-established), retrieves the content, and optionally
+ caches it for future use.
+
+4. If the request was a cache hit and the content is still fresh in the cache,
+ or the content is now available through Traffic Server because of step 3,
+ Traffic Server sends the requested object to the client from the cache
+ directly.
+
+.. note::
+
+ Traffic Server, when updating its own cache from the origin server, will
+ simultaneously deliver that content to the client while updating its
+ cache database. The response to the client containing the requested object
+ will begin as soon as Traffic Server has received and processed the full
+ response headers from the origin server.
To configure HTTP reverse proxy, you must perform the following tasks:
- Create mapping rules in the :file:`remap.config` file (refer to `Creating
Mapping Rules for HTTP Requests`_). ::
- # remap.config
map http://www.host.com http://realhost.com
- Enable the reverse proxy option (refer to `Enabling HTTP Reverse Proxy`_).
@@ -167,10 +179,10 @@ Handling Origin Server Redirect Responses
Origin servers often send redirect responses back to browsers
redirecting them to different pages. For example, if an origin server is
overloaded, then it might redirect browsers to a less loaded server.
-Origin servers also redirect when web pages that have moved to different
+Origin servers also redirect when web pages have moved to different
locations. When Traffic Server is configured as a reverse proxy, it must
readdress redirects from origin servers so that browsers are redirected
-to Traffic Server and *not* to another origin server.
+to Traffic Server and not to another origin server.
To readdress redirects, Traffic Server uses reverse-map rules. Unless
you have :ts:cv:`proxy.config.url_remap.pristine_host_hdr` enabled
@@ -186,23 +198,25 @@ Traffic Server uses two types of mapping rules for HTTP reverse proxy.
map rule
~~~~~~~~
-A **map rule** translates the URL in client requests into the URL where
+A *map rule* translates the URL in client requests into the URL where
the content is located. When Traffic Server is in reverse proxy mode and
receives an HTTP client request, it first constructs a complete request
URL from the relative URL and its headers. Traffic Server then looks for
a match by comparing the complete request URL with its list of target
-URLs in the :file:`remap.config` file.
-For the request URL to match a target URL, the following
-conditions must be true:
+URLs in :file:`remap.config`. For the request URL to match a target URL, the
+following conditions must be true:
+
+- The scheme of both URLs must be the same.
-- The scheme of both URLs must be the same
- The host in both URLs must be the same. If the request URL contains
an unqualified hostname, then it will never match a target URL with a
fully-qualified hostname.
+
- The ports in both URLs must be the same. If no port is specified in a
URL, then the default port for the scheme of the URL is used.
+
- The path portion of the target URL must match a prefix of the request
- URL path
+ URL path.
If Traffic Server finds a match, then it translates the request URL into
the replacement URL listed in the map rule: it sets the host and path of
@@ -210,18 +224,18 @@ the request URL to match the replacement URL. If the URL contains path
prefixes, then Traffic Server removes the prefix of the path that
matches the target URL path and substitutes it with the path from the
replacement URL. If two mappings match a request URL, then Traffic
-Server applies the first mapping listed in the :file:`remap.config` file.
+Server applies the first mapping listed in :file:`remap.config`.
reverse-map rule
~~~~~~~~~~~~~~~~
-A **reverse-map rule** translates the URL in origin server redirect
-responses to point to Traffic Server so that clients are **redirected**
+A *reverse-map rule* translates the URL in origin server redirect
+responses to point to Traffic Server so that clients are redirected
to Traffic Server instead of accessing an origin server directly. For
example, if there is a directory ``/pub`` on an origin server at
``www.molasses.com`` and a client sends a request to that origin server
for ``/pub``, then the origin server might reply with a redirect by
-sending the Header ``Location: http://www.test.com/pub/`` to let the
+sending the Header ``Location: http://realhost.com/pub/`` to let the
client know that it was a directory it had requested, not a document (a
common use of redirects is to normalize URLs so that clients can
bookmark documents properly).
@@ -233,35 +247,33 @@ hitting a wall because ``realhost.com`` actually does not resolve for
the client. (E.g.: Because it's running on a port shielded by a
firewall, or because it's running on a non-routable LAN IP)
-Both map and reverse-map rules consist of a **target** (origin) URL and
-a **replacement** (destination) URL. In a **map rule**, the target URL
+Both map and reverse-map rules consist of a *target* (origin) URL and
+a *replacement* (destination) URL. In a *map rule*, the target URL
points to Traffic Server and the replacement URL specifies where the
-original content is located. In a **reverse-map rule**, the target URL
+original content is located. In a *reverse-map rule*, the target URL
specifies where the original content is located and the replacement URL
-points to Traffic Server. Traffic Server stores mapping rules in the
-``remap.config`` file located in the Traffic Server ``config``
-directory.
+points to Traffic Server. Traffic Server stores mapping rules in
+:file:`remap.config` located in the Traffic Server ``config`` directory.
Creating Mapping Rules for HTTP Requests
----------------------------------------
-To create mapping rules
+To create mapping rules:
+
+#. Enter the map and reverse-map rules into :file:`remap.config`.
-1. Enter the map and reverse-map rules into the :file:`remap.config` file
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Enabling HTTP Reverse Proxy
---------------------------
-To enable HTTP reverse proxy, follow the steps below.
+To enable HTTP reverse proxy:
-1. Edit the following variable in :file:`records.config`
+#. Edit :ts:cv:`proxy.config.reverse_proxy.enabled` in :file:`records.config`. ::
- - :ts:cv:`proxy.config.reverse_proxy.enabled`
+ CONFIG proxy.config.reverse_proxy.enabled INT 1
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Setting Optional HTTP Reverse Proxy Options
-------------------------------------------
@@ -270,17 +282,20 @@ Traffic Server provides several reverse proxy configuration options in
:file:`records.config` that enable you to:
- Configure Traffic Server to retain the client host header information
- in a request during translation (:ts:cv:`proxy.config.url_remap.pristine_host_hdr`)
+ in a request during translation.
+ See :ts:cv:`proxy.config.url_remap.pristine_host_hdr`.
- Configure Traffic Server to serve requests only to the origin servers
listed in the mapping rules. As a result, requests to origin servers
- not listed in the mapping rules are not served. (:ts:cv:`proxy.config.url_remap.remap_required`)
-- Specify an alternate URL to which incoming requests from older
- clients (i.e., ones that do not provide ``Host`` headers) are
- directed (:ts:cv:`proxy.config.header.parse.no_host_url_redirect`)
+ not listed in the mapping rules are not served.
+ See :ts:cv:`proxy.config.url_remap.remap_required`.
-Don't forget to run the command :option:`traffic_line -x` to apply the
-configuration changes.
+- Specify an alternate URL to which incoming requests from older clients ,such
+ as ones that do not provide ``Host`` headers, are directed.
+ See :ts:cv:`proxy.config.header.parse.no_host_url_redirect`.
+
+Run the command :option:`traffic_line -x` to apply any of these configuration
+changes.
Redirecting HTTP Requests
=========================
@@ -293,18 +308,17 @@ requests for ``www.ultraseek.com`` go directly to
``www.server1.com/products/portal/search``.
You can configure Traffic Server to perform permanent or temporary
-redirects. **Permanent redirects** notify the browser of the URL change
-(by returning the HTTP status code **``301``**) so that the browser can
-update bookmarks. **Temporary redirects** notify the browser of the URL
+redirects. *Permanent redirects* notify the browser of the URL change
+(by returning the HTTP status code ``301``) so that the browser can
+update bookmarks. *Temporary redirects* notify the browser of the URL
change for the current request only (by returning the HTTP status code
-**``307``** ).
+``307`` ).
+
+To set redirect rules:
-To set redirect rules
+#. For each redirect you want to set enter a mapping rule in :file:`remap.config`.
-1. For each redirect you want to set enter a mapping rule in the
- :file:`remap.config` file
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Example
-------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/security-options.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/security-options.en.rst b/doc/admin/security-options.en.rst
index 3806d4f..9fc612a 100644
--- a/doc/admin/security-options.en.rst
+++ b/doc/admin/security-options.en.rst
@@ -11,7 +11,7 @@ Security Options
"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
+ 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
@@ -20,18 +20,17 @@ Security Options
specific language governing permissions and limitations
under the License.
-Traffic Server provides a number of security features.
-
.. _controlling-client-access-to-cache:
Controlling Client Access to the Proxy Cache
============================================
-You can configure Traffic Server to allow only certain clients to use
-the proxy cache by editing a configuration file.
+Traffic Server can be confgiured to allow only certain clients to use
+the proxy cache.
-#. Add a line in :file:`ip_allow.config` for each IP address or
+#. Add a line to :file:`ip_allow.config` for each IP address or
range of IP addresses allowed to access Traffic Server.
+
#. Run the command :option:`traffic_line -x` to apply the configuration
changes.
@@ -40,7 +39,7 @@ the proxy cache by editing a configuration file.
Configuring DNS Server Selection (Split DNS)
============================================
-The **Split DNS** option enables you to configure Traffic Server to use
+The *Split DNS* option enables you to configure Traffic Server to use
multiple DNS servers, as dictated by your security requirements. For
example, you might configure Traffic Server to use one set of DNS
servers to resolve hostnames on your internal network, while allowing
@@ -48,27 +47,25 @@ DNS servers outside the firewall to resolve hosts on the Internet. This
maintains the security of your intranet, while continuing to provide
direct access to sites outside your organization.
-To configure Split DNS, you must do the following:
+To configure Split DNS:
-- Specify the rules for performing DNS server selection based on the
- destination domain, the destination host, or a URL regular
- expression.
-- Enable the **Split DNS** option.
+#. Specify the rules for performing DNS server selection based on the
+ destination domain, the destination host, or a URL regular expression.
+ These rules are located in :file:`splitdns.config`.
-To do this, we
+#. Enable the *Split DNS* option by adjusting :ts:cv:`proxy.config.dns.splitDNS.enabled`
+ in :file:`records.config`. ::
-#. Add rules to :file:`splitdns.config`.
-#. In :file:`records.config` set the variable
- :ts:cv:`proxy.config.dns.splitDNS.enabled` to ``1`` to enable split DNS.
-#. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+ CONFIG proxy.config.dns.splitDNS.enabled INT 1
+
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
.. _configuring-ssl-termination:
Using SSL Termination
=====================
-The Traffic Server **SSL termination** option enables you to secure
+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.
@@ -76,22 +73,22 @@ The following sections describe how to enable and configure the SSL
termination option.
- Enable and configure SSL termination for client/Traffic Server
- connections: :ref:`client-and-traffic-server-connections`
+ connections: :ref:`admin-client-and-traffic-server-connections`
+
- Enable and configure SSL termination for Traffic Server/origin server
- connections: :ref:`traffic-server-and-origin-server-connections`
-- Enable and configure SSL termination for both client/Traffic Server
- and Traffic Server/origin server connections: :ref:`client-and-traffic-server-connections`
- :ref:`traffic-server-and-origin-server-connections`, respectively.
+ connections: :ref:`admin-traffic-server-and-origin-server-connections`
.. _client-and-traffic-server-connections:
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
-termination option is enabled & configured for **client/Traffic
-Server connections only**.
+termination option is enabled and configured for Client/Traffic
+Server connections only.
.. figure:: ../static/images/admin/ssl_c.jpg
:align: center
@@ -99,64 +96,93 @@ Server connections only**.
Client and Traffic Server 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 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.
+1. The client sends an HTTPS request for content. Traffic Server 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 encrypts the content and sends it to the client. The client decrypts the content (using the method determined during the handshake) and displays it.
+2. If the request is a cache hit and the content is fresh, then Traffic Server
+ 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 content in its cache, encrypts the content, and sends it to the client. The client decrypts and displays the content.
+3. 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
+ 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:
+Client/Traffic Server connections, you must do the following:
-- Obtain and install an SSL server certificate from a recognized
+#. 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
and exchange encryption keys.
-- Configure SSL termination options:
-
- - Set the port number used for SSL communication using :ts:cv:`proxy.config.http.server_ports`.
- - Edit :file:`ssl_multicert.config` to specify the filename and location of the
- SSL certificates and private keys.
- - (Optional) Configure the use of client certificates: Client
- certificates are located on the client. If you configure Traffic
- Server 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 client certificates, then access to Traffic Server is
- managed through other Traffic Server options that have been set
- (such as rules in :file:`ip_allow.config`).
- - (Optional) Configure the use of Certification Authorities (CAs).
- CAs add security by verifying the identity of the person
- requesting a certificate.
-
-In order to accomplish this, we
-
-#. Edit the following variables in the :ref:`records-config-ssl-termination` section of
- :file:`records.config`
-
- - :ts:cv:`proxy.config.http.server_ports`
- - :ts:cv:`proxy.config.ssl.client.certification_level`
- - :ts:cv:`proxy.config.ssl.server.cert.path`
- - :ts:cv:`proxy.config.ssl.server.private_key.path`
- - :ts:cv:`proxy.config.ssl.CA.cert.path`
+
+#. Set the port number used for SSL communication using
+ :ts:cv:`proxy.config.http.server_ports` in :file:`records.config`.
+
+#. Set the appropriate base path for your SSL certificates and private keys
+ in :file:`records.config`. ::
+
+ CONFIG proxy.config.ssl.server.cert.path STRING "/opt/ts/etc/ssl/certs/"
+ 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
+ with clients. ::
+
+ ip_dest=1.2.3.4 ssl_cert_name=example.com.pem
+ ip_dest=* 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
+ Server verifies the client certificate during the SSL handshake that
+ authenticates the client. If you configure Traffic Server 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
+ rules in :file:`ip_allow.config`). ::
+
+ CONFIG proxy.config.ssl.client.certification_level INT 0
+
+ This variable permits one of the following values to be set:
+
+ ===== =======================================================================
+ Value Description
+ ===== =======================================================================
+ ``0`` Client certificates not required.
+ ``1`` Client certificates optional. If present, will be used to validate.
+ ``2`` Client certficates required, and must validate based on configured CAs.
+ ===== =======================================================================
+
+#. *Optional*: Configure the use of Certification Authorities (CAs). CAs add
+ security by verifying the identity of the person requesting a certificate.
+ The list of acceptable CA signers is configured with
+ :ts:cv:`proxy.config.ssl.CA.cert.path` in :file:`records.config`. ::
+
+ CONFIG proxy.config.ssl.CA.cert.path STRING "/opt/CA/certs/private-ca.pem"
#. Run the command :option:`traffic_line -L` to restart Traffic Server on the
local node or :option:`traffic_line -M` to restart Traffic Server on all
the nodes in a cluster.
-
-.. This numbering is ridiculous.
-
.. _traffic-server-and-origin-server-connections:
Traffic Server 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
-origin server when the SSL termination option is enabled for **Traffic
-Server/origin server connections**.
+origin server when the SSL termination option is enabled for Traffic
+Server/origin server connections.
.. figure:: ../static/images/admin/ssl_os.jpg
:align: center
@@ -164,65 +190,73 @@ Server/origin server connections**.
Traffic Server and origin server communication using SSL termination
+.. Manual list numbering below corresponds to figure markings above.
+
The figure above depicts the following:
-**Step 1:** If a client request is a cache miss or is stale, then
-Traffic Server 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.
+1. If a client request is a cache miss or is stale, then Traffic Server 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.
-**Step 2:** 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 method determined during the handshake). A plain
-text version of the content is saved in the cache.
+2. 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
+ method determined during the handshake). A plain text version of the content
+ is saved in the cache, if Traffic Server deems the content cacheable.
-**Step 3:** 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, where it is decrypted and displayed. If SSL
-termination is not enabled for client/Traffic Server connections, then
-Traffic Server sends the plain text version of the content to the client
-via HTTP.
+3. 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,
+ where it is decrypted and displayed. If SSL termination is not enabled for
+ Client/Traffic Server connections, then Traffic Server 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 and origin server connections, you must do the following:
-
-- Obtain and install an SSL client certificate from a recognized
- certificate authority. The SSL client certificate contains
- information that allows the origin server to authenticate Traffic
- Server (the client certificate is optional).
-- Configure SSL termination options:
-- Enable the SSL termination option.
-
- - Set the port number used for SSL communication.
- - Specify the filename and location of the SSL client certificate
- (if you choose to use a client certificate).
- - Specify the filename and location of the Traffic Server private
- key (if the private key is not located in the client certificate
- file). Traffic Server uses its private key during the SSL
- handshake to decrypt the session encryption keys. The private key
- must be stored and protected against theft.
- - Configure the use of CAs. CAs allow the Traffic Server that's
- acting as a client to verify the identity of the server with which
- it is communicating, thereby enabling exchange of encryption keys.
-
-In order to accomplish this, we:
-
-.. This numbering is ridiculous. I need to re-read this doc with a fresh mind and re(number|order) it.
-
-1. Edit the following variables in the :ref:`records-config-ssl-termination` section of
- :file:`records.config`:
-
- - :ts:cv:`proxy.config.http.server_ports`
- - :ts:cv:`proxy.config.ssl.client.verify.server`
- - :ts:cv:`proxy.config.ssl.client.cert.filename`
- - :ts:cv:`proxy.config.ssl.client.cert.path`
- - :ts:cv:`proxy.config.ssl.client.private_key.filename`
- - :ts:cv:`proxy.config.ssl.client.private_key.path`
- - :ts:cv:`proxy.config.ssl.client.CA.cert.filename`
- - :ts:cv:`proxy.config.ssl.client.CA.cert.path`
-
-2. Run the command :option:`traffic_line -L` to restart Traffic Server on the
+To configure Traffic Server to use the SSL termination option for Traffic Server
+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
+ outlined in `Client and Traffic Server Connections`_ for configuring the
+ origin server to validate client certificates.
+
+#. *Optional*: Obtain and install an SSL client certificate from a recognized
+ certificate authority, if your origin server requires client certificate
+ validation for access control. Your client certificate must be signed by a
+ Certificate Authority recognized by your origin server.
+
+ If you are using a client certificate, you must add its location to
+ :file:`records.config` in the setting :ts:cv:`proxy.config.ssl.client.cert.path`
+ and :ts:cv:`proxy.config.ssl.client.cert.filename`. ::
+
+ CONFIG proxy.config.ssl.client.cert.path STRING "/opt/ts/etc/ssl/certs/"
+ CONFIG proxy.config.ssl.client.cert.filename STRING "client.pem"
+
+ You must also provide the paths to the private key for this certificate,
+ unless the key is contained within the same file as the certificate, using
+ :ts:cv:`proxy.config.ssl.client.private_key.path` and
+ :ts:cv:`proxy.config.ssl.client.private_key.filename`. ::
+
+ CONFIG proxy.config.ssl.client.private_key.path STRING "/opt/ts/etc/ssl/keys/"
+ CONFIG proxy.config.ssl.client.private_key.filename STRING "client.pem"
+
+#. Enable or disable, per your security policy, server SSL certificate
+ verification using :ts:cv:`proxy.config.ssl.client.verify.server` in
+ :file:`records.config`. ::
+
+ CONFIG proxy.config.ssl.client.verify.server INT 1
+
+#. Add the collection of authorized Certificate Authorities to the Traffic
+ Server configuration in :file:`records.config` using the settings
+ :ts:cv:`proxy.config.ssl.client.CA.cert.path` and
+ :ts:cv:`proxy.config.ssl.client.CA.cert.filename`. ::
+
+ 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_line -L` to restart Traffic Server on the
local node or :option:`traffic_line -M` to restart Traffic Server on all
the nodes in a cluster.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/session-protocol.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/session-protocol.en.rst b/doc/admin/session-protocol.en.rst
index 84d7040..25d00b0 100644
--- a/doc/admin/session-protocol.en.rst
+++ b/doc/admin/session-protocol.en.rst
@@ -1,3 +1,8 @@
+.. _session-protocol:
+
+Session Protocol
+****************
+
.. 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
@@ -5,9 +10,9 @@
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
@@ -15,19 +20,15 @@
specific language governing permissions and limitations
under the License.
-.. _session-protocol:
-
-Session Protocol
-****************
-
-Traffic Server supports some session level protocols in place or on
-top of HTTP. These can be provided by a plugin
-(:ref:`see <new-protocol-plugins>`) or be one that is supported
-directly by Traffic Server. Currently the
-`SPDY <http://www.chromium.org/spdy>`_ protocol is the only one current
-supported but it is planned to support HTTP 2 when that is finalized.
+Traffic Server supports some session level protocols in place of, or on top of.
+ HTTP. These can be provided by a plugin (see :ref:`new-protocol-plugins`) or
+be one that is supported directly by Traffic Server. The
+`SPDY <http://www.chromium.org/spdy>`_ protocol is the only one currently
+supported, but it is planned to support HTTP 2 when that is finalized.
-Session protocols are specified by explicit names, based on the `NPN <https://technotes.googlecode.com/git/nextprotoneg.html>`_ names. The core supported names are
+Session protocols are specified by explicit names, based on the
+`NPN <https://technotes.googlecode.com/git/nextprotoneg.html>`_ names. The
+core supported names are:
* ``http/0.9``
* ``http/1.0``
@@ -38,18 +39,21 @@ Session protocols are specified by explicit names, based on the `NPN <https://te
* ``spdy/3``
* ``spdy/3.1``
-The ``http/2`` value is currently not functional but included for future use. ``spdy/1`` and ``spdy/2`` are obsolete but are include for completeness.
+The ``http/2`` value is not currently functional, but is included for future
+use. Both ``spdy/1`` and ``spdy/2`` are obsolete, but are include for
+completeness.
-The session protocols supported on a proxy port are a subset of these values. For convenience some psuedo-values are defined in terms of these fundamental protocols.
+The session protocols supported on a proxy port are a subset of these values.
+For convenience some pseudo-values are defined in terms of these fundamental
+protocols:
* ``http`` means ``http/0.9``, ``http/1.0``, and ``http/1.1``
* ``spdy`` means ``spdy/3`` and ``spdy/3.1``.
* ``http2`` means ``http/2``
-Each proxy port can be
-configured in :ts:cv:`proxy.config.http.server_ports` to support a subset of
-these session protocols. For TLS enabled connections this
-configuration controls which protocols are offered by NPN. For non-TLS
-proxy ports protocol sniffing is used to determine which protocol is
-being used by the client. If the detected protocol is not supported
-for that proxy port the connection is dropped.
+Each proxy port can be configured in :ts:cv:`proxy.config.http.server_ports`
+to support a subset of these session protocols. For TLS enabled connections this
+configuration controls which protocols are offered by NPN. Protocol sniffing is
+use for non-TLS proxy ports to determine which protocol is being used by the
+client. If the detected protocol is not supported for that proxy port the
+connection is dropped.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/traffic-server-error-messages.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/traffic-server-error-messages.en.rst b/doc/admin/traffic-server-error-messages.en.rst
index 01586c2..d26b85e 100644
--- a/doc/admin/traffic-server-error-messages.en.rst
+++ b/doc/admin/traffic-server-error-messages.en.rst
@@ -34,7 +34,7 @@ Traffic Server Process Fatal
============================
``Accept port is not between 1 and 65535. Please check configuration``
- The port specified in the :file:`records.config` file that accepts
+ The port specified in :file:`records.config` that accepts
incoming HTTP requests is not valid.
``Self loop is detected in parent proxy configuration``
@@ -66,7 +66,7 @@ Traffic Server Warnings
``Log format symbol <symbol name> not found``
Custom log format references a field symbol that does not exist.
- Refer to :ref:`event-logging-formats`.
+ Refer to :ref:`admin-event-logging-formats`.
``Missing field for field marker``
Error reading a log buffer.
@@ -84,7 +84,7 @@ Traffic Server Warnings
replaced.
``No cache disks specified in storage.config file: cache disabled``
- The Traffic Server ``storage.config`` file does not list any cache
+ The Traffic Server :file:`storage.config` file does not list any cache
disks; Traffic Server is running in proxy-only mode. You must add
the disks you want to use for the cache to :file:`storage.config`.
@@ -143,9 +143,9 @@ Traffic Server returns detailed error messages to browser clients when
there are problems with the HTTP transactions requested by the browser.
These Traffic Server response messages correspond to standard HTTP
response codes, but provide more information. A list of the more
-frequently-encountered HTTP response codes is provided in :ref:`standard-http-response-messages`.
-You can customize the Traffic Server response messages (typically in
-proxy/config/body_factory/default/, but set by
+frequently encountered HTTP response codes is provided in :ref:`standard-http-response-messages`.
+You can customize the Traffic Server response messages (typically in
+``proxy/config/body_factory/default/``, but set by
:ts:cv:`proxy.config.body_factory.template_sets_dir`).
The following table lists the hard-coded Traffic Server HTTP messages,
@@ -311,63 +311,30 @@ Standard HTTP Response Messages
The following standard HTTP response messages are provided for your
information.
-``200``
- OK
-
-``202``
- Accepted
-
-``204``
- No Content
-
-``206``
- Partial Content
-
-``300``
- Multiple Choices
-
-``301``
- Moved Permanently
-
-``302``
- Found
-
-``303``
- See Other
-
-``304``
- Not Modified
-
-``400``
- Bad Request
-
-``401``
- Unauthorized; retry
-
-``403``
- Forbidden
-
-``404``
- Not Found
-
-``405``
- Method Not Allowed
-
-``406``
- Not acceptable
-
-``408``
- Request Timeout
-
-``500``
- Internal server error
-
-``501``
- Not Implemented
-
-``502``
- Bad Gateway
-
-``504``
- Gateway Timeout
-
+======== ===================================
+Code Description
+======== ===================================
+``200`` OK
+``202`` Accepted
+``204`` No Content
+``206`` Partial Content
+``300`` Multiple Choices
+``301`` Moved Permanently
+``302`` Found
+``303`` See Other
+``304`` Not Modified
+``400`` Bad Request
+``401`` Unauthorized; retry
+``403`` Forbidden
+``404`` Not Found
+``405`` Method Not Allowed
+``406`` Not Acceptable
+``408`` Request Timeout
+``500`` Internal Server Error
+``501`` Not Implemented
+``502`` Bad Gateway
+``504`` Gateway Timeout
+======== ===================================
+
+More detail can be found in `RFC2616 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_
+which defines the full range of standardized HTTP/1.1 response codes.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/transparent-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/transparent-proxy.en.rst b/doc/admin/transparent-proxy.en.rst
index 2a2eb5c..74ae56f 100644
--- a/doc/admin/transparent-proxy.en.rst
+++ b/doc/admin/transparent-proxy.en.rst
@@ -5,21 +5,20 @@ Transparent Proxying
.. 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
-
+ 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.
+ 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.
.. toctree::
:maxdepth: 2
@@ -32,8 +31,8 @@ Transparent Proxying
Transparent Proxying is the ability of a proxy (such as ATS) to
intercept connections between clients and servers without being visible.
-The general network structure that will be used in this documentation
-looks like this --
+The general network structure that will be used in this documentation is
+shown in the following figure.
.. figure:: ../static/images/admin/ats-basic-traffic.png
:align: center
@@ -41,16 +40,16 @@ looks like this --
ATS basic traffic flow of Transparent Proxy
-There must be a gateway device through which passes all network traffic
+There must be a gateway device through which all network traffic passes
from the client to the Internet (or external cloud). The gateway is
responsible for effectively splicing ATS in to selected streams of that
-traffic. Each traffic stream is split in to two, with ATS terminating
+traffic. Each traffic stream is split in two, with ATS terminating
both sides. That is, stream green-1, red-2, is split in to the green
connection and the red connection. Note that ATS may or may not be on
the gateway system, the redirected traffic can flow over other network
infrastructure.
-Because ATS uses two connections transparency can be set independently
+Because ATS uses two connections, transparency can be set independently
on the client and origin server (Internet / external cloud) side. We
will define what is generally called "transparent proxy" as two aspects,
*inbound transparency* and *outbound transparency*.
@@ -62,31 +61,37 @@ proxy that is transparent to connections that are outbound from the
proxy, i.e. a connection initiated by the proxy to an origin server
(red-2).
-In most treatments these two types of transparency are treated as
-unitarily but that is not required. This implementation supports
-transparency independently on the two (client, origin server) sides
-(`use cases <half-transparency-use-cases>`_.
+In most situations these two types of transparency are combined, but that is
+not required. Traffic Server supports transparency independently on the two
+sides. `Half-Transparency Use Cases <half-transparency-use-cases>`_ provides
+additional detail.
+
+.. important::
-It is critical to note that any transparency requires specialized
-routing and cannot be done solely by configuring ATS. ATS transparency
-also requires support from the Linux kernel and therefore currently only
-works on sufficiently recent Linux kernels that support the following
-features --
+ It is critical to note that any transparency requires specialized
+ routing and cannot be done solely by configuring ATS. ATS transparency
+ also requires support from the Linux kernel and therefore currently only
+ works on sufficiently recent Linux kernels that support the following
+ features:
-- TPROXY
-- POSIX capabilities
+ - TPROXY
+ - POSIX capabilities
-In addition the specialized routing will require using ``iptables`` and
-in some cases ``ebtables``.
+ In addition the specialized routing will require using ``iptables`` and
+ in some cases ``ebtables``.
Standard build procedures should work for transparency support but if
not consult these :ref:`more detailed instructions <building-ats-for-transparency>`
-Transparency is configured per server port not globally. This is done
+Transparency is configured per server port, not globally. This is done
via the configuration values :ts:cv:`proxy.config.http.server_ports`.
In addition, :ts:cv:`proxy.config.reverse_proxy.enabled` must be enabled if the
client side is transparent. That should be fixed in a future patch.
+.. XXX has that been fixed?
+
+.. XXX revisit section below
+
In the first case use the attribute character (replacing the default
'X')
[3/4] Documentation editorial update
Posted by jp...@apache.org.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/hierachical-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/hierachical-caching.en.rst b/doc/admin/hierachical-caching.en.rst
index 66a1a5e..69ba2cc 100644
--- a/doc/admin/hierachical-caching.en.rst
+++ b/doc/admin/hierachical-caching.en.rst
@@ -5,21 +5,20 @@ Hierarchical Caching
.. 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.
+ 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.
.. toctree::
:maxdepth: 2
@@ -29,7 +28,7 @@ Understanding Cache Hierarchies
A cache hierarchy consists of cache levels that communicate with each
other. Traffic Server supports several types of cache hierarchies. All
-cache hierarchies recognize the concept of **parent** and **child**. A
+cache hierarchies recognize the concept of *parent* and *child*. A
parent cache is a cache higher up in the hierarchy, to which Traffic
Server can forward requests. A child cache is a cache for which Traffic
Server is a parent.
@@ -42,22 +41,23 @@ Parent Caching
If a Traffic Server node cannot find a requested object in its cache,
then it searches a parent cache (which itself can search other caches)
before finally retrieving the object from the origin server. You can
-configure a Traffic Server node to use one or more parent caches so that
-if one parent is unavailable, then another parent is availale to service
-requests. This is called `Parent Failover`_. Traffic
-Server will support parent caching for HTTP and HTTPS requests.
+configure a Traffic Server node to use multiple parent caches so that
+if one parent is unavailable, the other parent caches will be checked in turn
+until either the request is serviced properly or no further parent caches are
+available and the origin server is contacted. This is called `Parent Failover`_.
+Traffic Server supports parent caching for both HTTP and HTTPS requests.
-**Note:** If you do not want all requests to go to the parent cache,
-then simply configure Traffic Server to route certain requests (such as
-requests containing specific URLs) directly to the origin server. Simply
-set parent proxy rules in :file:`parent.config`
+If you do not want all requests to go to the parent cache, then simply configure
+Traffic Server to route certain requests (such as requests containing specific
+URLs) directly to the origin server. This may be achieved by setting parent
+proxy rules in :file:`parent.config`.
The figure below illustrates a simple cache hierarchy with a Traffic
Server node configured to use a parent cache. In the following scenario,
a client sends a request to a Traffic Server node that is a child in the
cache hierarchy (because it's configured to forward missed requests to a
parent cache). The request is a cache miss, so Traffic Server then
-forwards the request to the parent cache, where it is a cache hit. The
+forwards the request to the parent cache where it is a cache hit. The
parent sends a copy of the content to the Traffic Server, where it is
cached and then served to the client. Future requests for this content
can now be served directly from the Traffic Server cache (until the data
@@ -69,11 +69,10 @@ is stale or expired).
Parent caching
-**Note:** If the request is a cache miss on the parent, then the parent
-retrieves the content from the origin server (or from another cache,
-depending on the parent’s configuration). The parent caches the content
-and then sends a copy to Traffic Server (its child), where it is cached
-and served to the client.
+If the request is a cache miss on the parent, then the parent retrieves the
+content from the origin server (or from another cache, depending on the parent’s
+configuration). The parent caches the content and then sends a copy to Traffic
+Server (its child), where it is cached and served to the client.
Parent Failover
---------------
@@ -95,23 +94,27 @@ order they are listed in the configuration file.
Configuring Traffic Server to Use a Parent Cache
------------------------------------------------
-To configure Traffic Server to use one or more parent caches, you must
-complete the following steps:
+To configure Traffic Server to use one or more parent caches, you must perform
+the configuration adjustments detailed below.
+
+.. note::
+
+ You need to configure the child cache only. No additional configuration is
+ needed for the nodes acting as Traffic Server parent caches.
-- Enable the parent caching option.
-- Identify the parent cache you want to use to service missed requests.
- To use **parent failover**, you must identify more than one parent
- cache so that when a parent cache is unavailable, requests are sent
- to another parent cache.
+#. Enable the parent caching option by adjusting
+ :ts:cv:`proxy.config.http.parent_proxy_routing_enable` in
+ :file:`records.config`. ::
-.. note:: You need to configure the child cache only. No additional configuration is needed for the Traffic Server parent cache.
+ CONFIG proxy.config.http.parent_proxy_routing_enable INT 1
-Configure Traffic Server to use a parent cache by editing the following
-variable :ts:cv:`proxy.config.http.parent_proxy_routing_enable` in :file:`records.config` file.
+#. Identify the parent cache you want to use to service missed requests. To
+ use parent failover, you must identify more than one parent cache so that
+ when a parent cache is unavailable, requests are sent to another parent
+ cache.
-Edit the :file:`parent.config` file located in the Traffic Server ``config`` directory to set parent
-proxy rules to specify the parent cache to which you want missed
-requests to be forwarded;
+#. Edit :file:`parent.config` to set parent proxy rules which will specify the
+ parent cache to which you want missed requests to be forwarded.
The following example configures Traffic Server to route all requests
containing the regular expression ``politics`` and the path
@@ -135,35 +138,35 @@ Run the command :option:`traffic_line -x` to apply the configuration changes.
.. # ICP Peering # {#ICPPeering}
-.. The Internet Cache Protocol (ICP) is used by proxy caches to exchange information
+.. The Internet Cache Protocol (ICP) is used by proxy caches to exchange information
about their content. ICP query messages ask other caches if they are storing
- a particular URL; ICP response messages reply with a hit or miss answer. A
- cache exchanges ICP messages only with specific **ICP peers**, which are neighboring
- caches that can receive ICP messages. An ICP peer can be a **sibling cache
+ a particular URL; ICP response messages reply with a hit or miss answer. A
+ cache exchanges ICP messages only with specific **ICP peers**, which are neighboring
+ caches that can receive ICP messages. An ICP peer can be a **sibling cache
**(which is at the same level in the hierarchy) or a **parent cache** (which
- is one level up in the hierarchy).
-
-.. If Traffic Server has ICP caching enabled, then it sends ICP queries to its
- ICP peers when the HTTP request is a cache miss. If there are no hits but parents
- exist, then a parent is selected using a round-robin policy. If no ICP parents
- exist, then Traffic Server forwards the request to its HTTP parents. If there
- are no HTTP parent caches established, then Traffic Server forwards the request
- to the origin server.
-
-.. If Traffic Server receives a hit message from an ICP peer, then Traffic Server
- sends the HTTP request to that peer. However, it might turn out to be a cache
- miss because the original HTTP request contains header information that is
- not communicated by the ICP query. For example, the hit might not be the requested
- alternate. If an ICP hit turns out to be a miss, then Traffic Server forwards
- the request to either its HTTP parent caches or to the origin server.
+ is one level up in the hierarchy).
+
+.. If Traffic Server has ICP caching enabled, then it sends ICP queries to its
+ ICP peers when the HTTP request is a cache miss. If there are no hits but parents
+ exist, then a parent is selected using a round-robin policy. If no ICP parents
+ exist, then Traffic Server forwards the request to its HTTP parents. If there
+ are no HTTP parent caches established, then Traffic Server forwards the request
+ to the origin server.
+
+.. If Traffic Server receives a hit message from an ICP peer, then Traffic Server
+ sends the HTTP request to that peer. However, it might turn out to be a cache
+ miss because the original HTTP request contains header information that is
+ not communicated by the ICP query. For example, the hit might not be the requested
+ alternate. If an ICP hit turns out to be a miss, then Traffic Server forwards
+ the request to either its HTTP parent caches or to the origin server.
.. To configure a Traffic Server node to be part of an ICP cache hierarchy, you
- must perform the following tasks:
+ must perform the following tasks:
-.. * Determine if the Traffic Server can receive ICP messages only, or if it can send _and_ receive ICP messages.
- * Determine if Traffic Server can send messages directly to each ICP peer or send a single message on a specified multicast channel.
- * Specify the port used for ICP messages.
- * Set the ICP query timeout.
+.. * Determine if the Traffic Server can receive ICP messages only, or if it can send _and_ receive ICP messages.
+ * Determine if Traffic Server can send messages directly to each ICP peer or send a single message on a specified multicast channel.
+ * Specify the port used for ICP messages.
+ * Set the ICP query timeout.
* Identify the ICP peers (siblings and parents) with which Traffic Server can communicate.
.. To configure Traffic Server to use an ICP cache hierarchy edit the following variables in :file:`records.config` file:
@@ -173,7 +176,7 @@ Run the command :option:`traffic_line -x` to apply the configuration changes.
* :ts:cv:`proxy.config.icp.multicast_enabled`
* :ts:cv:`proxy.config.icp.query_timeout`
-.. Edit :file:`icp.config` file located in the Traffic Server `config` directory:
+.. Edit :file:`icp.config` file located in the Traffic Server `config` directory:
For each ICP peer you want to identify, enter a separate rule in the :file:`icp.config` file.
.. Run the command :option:`traffic_line -x` to apply the configuration changes.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/http-proxy-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/http-proxy-caching.en.rst b/doc/admin/http-proxy-caching.en.rst
index e305007..c29c824 100644
--- a/doc/admin/http-proxy-caching.en.rst
+++ b/doc/admin/http-proxy-caching.en.rst
@@ -20,7 +20,7 @@ HTTP Proxy Caching
specific language governing permissions and limitations
under the License.
-Web proxy caching enables you to store copies of frequently-accessed web
+HTTP proxy caching enables you to store copies of frequently-accessed web
objects (such as documents, images, and articles) and then serve this
information to users on demand. It improves performance and frees up
Internet bandwidth for other tasks.
@@ -32,23 +32,23 @@ Understanding HTTP Web Proxy Caching
====================================
Internet users direct their requests to web servers all over the
-Internet. A caching server must act as a **web proxy server** so it can
+Internet. A caching server must act as a *web proxy server* so it can
serve those requests. After a web proxy server receives requests for web
-objects, it either serves the requests or forwards them to the **origin
-server** (the web server that contains the original copy of the
-requested information). The Traffic Server proxy supports **explicit
-proxy caching**, in which the user's client software must be configured
+objects, it either serves the requests or forwards them to the *origin
+server* (the web server that contains the original copy of the
+requested information). The Traffic Server proxy supports *explicit
+proxy caching*, in which the user's client software must be configured
to send requests directly to the Traffic Server proxy. The following
overview illustrates how Traffic Server serves a request.
-1. Traffic Server receives a client request for a web object.
+#. Traffic Server receives a client request for a web object.
-2. Using the object address, Traffic Server tries to locate the
- requested object in its object database (**cache**).
+#. Using the object address, Traffic Server tries to locate the
+ requested object in its object database (*cache*).
-3. If the object is in the cache, then Traffic Server checks to see if
+#. If the object is in the cache, then Traffic Server checks to see if
the object is fresh enough to serve. If it is fresh, then Traffic
- Server serves it to the client as a **cache hit** (see the figure
+ Server serves it to the client as a *cache hit* (see the figure
below).
.. figure:: ../static/images/admin/cache_hit.jpg
@@ -57,12 +57,12 @@ overview illustrates how Traffic Server serves a request.
A cache hit
-4. If the data in the cache is stale, then Traffic Server connects to
+#. If the data in the cache is stale, then Traffic Server connects to
the origin server and checks if the object is still fresh (a
:term:`revalidation`). If it is, then Traffic Server immediately sends
the cached copy to the client.
-5. If the object is not in the cache (a **cache miss**) or if the server
+#. If the object is not in the cache (a *cache miss*) or if the server
indicates the cached copy is no longer valid, then Traffic Server
obtains the object from the origin server. The object is then
simultaneously streamed to the client and the Traffic Server local
@@ -78,9 +78,11 @@ overview illustrates how Traffic Server serves a request.
Caching is typically more complex than the preceding overview suggests.
In particular, the overview does not discuss how Traffic Server ensures
freshness, serves correct HTTP alternates, and treats requests for
-objects that cannot/should not be cached. The following sections discuss
+objects that cannot or should not be cached. The following sections discuss
these issues in greater detail.
+.. _ensuring-cached-object-freshness:
+
Ensuring Cached Object Freshness
================================
@@ -98,7 +100,7 @@ HTTP Object Freshness
---------------------
Traffic Server determines whether an HTTP object in the cache is fresh
-by:
+by checking the following conditions in order:
- **Checking the** ``Expires`` **or** ``max-age`` **header**
@@ -119,25 +121,26 @@ by:
and *last_modified* is the date in the ``Last-Modified`` header.
If there is no ``Last-Modified`` header, then Traffic Server uses the
date the object was written to cache. The value ``0.10`` (10 percent)
- can be increased or reduced to better suit your needs (refer to
- `Modifying Aging Factor for Freshness Computations`_).
+ can be increased or reduced to better suit your needs. Refer to
+ `Modifying Aging Factor for Freshness Computations`_.
- The computed freshness limit is bound by a minimum and maximum value
- - refer to `Setting Absolute Freshness Limits`_ for more information.
+ The computed freshness limit is bound by a minimum and maximum value.
+ Refer to `Setting Absolute Freshness Limits`_ for more information.
- **Checking the absolute freshness limit**
For HTTP objects that do not have ``Expires`` headers or do not have
both ``Last-Modified`` and ``Date`` headers, Traffic Server uses a
- maximum and minimum freshness limit (refer to `Setting Absolute Freshness Limits`_).
+ maximum and minimum freshness limit. Refer to
+ `Setting Absolute Freshness Limits`_.
-- **Checking revalidate rules in the** :file:`cache.config` **file**
+- **Checking revalidate rules in** :file:`cache.config`
Revalidate rules apply freshness limits to specific HTTP objects. You
can set freshness limits for objects originating from particular
domains or IP addresses, objects with URLs that contain specified
regular expressions, objects requested by particular clients, and so
- on (refer to :file:`cache.config`).
+ on. Refer to :file:`cache.config`.
Modifying Aging Factor for Freshness Computations
-------------------------------------------------
@@ -148,30 +151,27 @@ Server can estimate its freshness from the ``Last-Modified`` and
the time that elapsed since it last changed. You can increase or reduce
the percentage according to your needs.
-To modify the aging factor for freshness computations
+To modify the aging factor for freshness computations:
-1. Change the value for :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`.
+#. Change the value for :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`.
-2. Run the :option:`traffic_line -x` command to apply the configuration
- changes.
+#. Run the :option:`traffic_line -x` command to apply the configuration changes.
-Setting absolute Freshness Limits
+Setting Absolute Freshness Limits
---------------------------------
Some objects do not have ``Expires`` headers or do not have both
``Last-Modified`` and ``Date`` headers. To control how long these
-objects are considered fresh in the cache, specify an **absolute
-freshness limit**.
-
-To specify an absolute freshness limit
+objects are considered fresh in the cache, specify an *absolute
+freshness limit*.
-1. Edit the variables
+To specify an absolute freshness limit:
- - :ts:cv:`proxy.config.http.cache.heuristic_min_lifetime`
- - :ts:cv:`proxy.config.http.cache.heuristic_max_lifetime`
+#. Edit the variables :ts:cv:`proxy.config.http.cache.heuristic_min_lifetime`
+ and :ts:cv:`proxy.config.http.cache.heuristic_max_lifetime` in
+ :file:`records.config`.
-2. Run the :option:`traffic_line -x` command to apply the configuration
- changes.
+#. Run the :option:`traffic_line -x` command to apply the configuration changes.
Specifying Header Requirements
------------------------------
@@ -185,40 +185,39 @@ with ``Expires`` or ``max-age`` headers, then the cache hit rate will be
noticeably reduced (since very few objects will have explicit expiration
information).
-To configure Traffic Server to cache objects with specific headers
+To configure Traffic Server to cache objects with specific headers:
-1. Change the value for :ts:cv:`proxy.config.http.cache.required_headers`.
+#. Change the value for :ts:cv:`proxy.config.http.cache.required_headers`
+ in :file:`records.config`.
-2. Run the :option:`traffic_line -x` command to apply the configuration
- changes.
-
-.. _cache-control-headers:
+#. Run the :option:`traffic_line -x` command to apply the configuration changes.
Cache-Control Headers
---------------------
Even though an object might be fresh in the cache, clients or servers
often impose their own constraints that preclude retrieval of the object
-from the cache. For example, a client might request that a object *not*
-be retrieved from a cache, or if it does, then it cannot have been
-cached for more than 10 minutes. Traffic Server bases the servability of
-a cached object on ``Cache-Control`` headers that appear in both client
-requests and server responses. The following ``Cache-Control`` headers
-affect whether objects are served from cache:
+from the cache. For example, a client might request that a object not
+be retrieved from a cache, or if it does allow cache retrieval, then it
+cannot have been cached for more than 10 minutes.
+
+Traffic Server bases the servability of a cached object on ``Cache-Control``
+headers that appear in both client requests and server responses. The following
+``Cache-Control`` headers affect whether objects are served from cache:
- The ``no-cache`` header, sent by clients, tells Traffic Server that
- it should not serve any objects directly from the cache;
- therefore, Traffic Server will always obtain the object from the
+ it should not serve any objects directly from the cache. When present in a
+ client request, Traffic Server will always obtain the object from the
origin server. You can configure Traffic Server to ignore client
- ``no-cache`` headers - refer to `Configuring Traffic Server to Ignore Client no-cache Headers`_
+ ``no-cache`` headers. Refer to `Configuring Traffic Server to Ignore Client no-cache Headers`_
for more information.
- The ``max-age`` header, sent by servers, is compared to the object
age. If the age is less than ``max-age``, then the object is fresh
- and can be served.
+ and can be served from the Traffic Server cache.
-- The ``min-fresh`` header, sent by clients, is an **acceptable
- freshness tolerance**. This means that the client wants the object to
+- The ``min-fresh`` header, sent by clients, is an *acceptable
+ freshness tolerance*. This means that the client wants the object to
be at least this fresh. Unless a cached object remains fresh at least
this long in the future, it is revalidated.
@@ -228,16 +227,15 @@ affect whether objects are served from cache:
improved performance, especially during periods of poor Internet
availability.
-Traffic Server applies ``Cache-Control`` servability criteria
-***after*** HTTP freshness criteria. For example, an object might be
-considered fresh but will not be served if its age is greater than its
-``max-age``.
+Traffic Server applies ``Cache-Control`` servability criteria after HTTP
+freshness criteria. For example, an object might be considered fresh but will
+not be served if its age is greater than its ``max-age``.
Revalidating HTTP Objects
-------------------------
When a client requests an HTTP object that is stale in the cache,
-Traffic Server revalidates the object. A **revalidation** is a query to
+Traffic Server revalidates the object. A *revalidation* is a query to
the origin server to check if the object is unchanged. The result of a
revalidation is one of the following:
@@ -261,47 +259,53 @@ object freshness as described in `HTTP Object Freshness`_.
You can reconfigure how Traffic Server evaluates freshness by selecting
one of the following options:
-- Traffic Server considers all HTTP objects in the cache to be stale:
- always revalidate HTTP objects in the cache with the origin server.
-- Traffic Server considers all HTTP objects in the cache to be fresh:
- never revalidate HTTP objects in the cache with the origin server.
-- Traffic Server considers all HTTP objects without ``Expires`` or
- ``Cache-control`` headers to be stale: revalidate all HTTP objects
- without ``Expires`` or ``Cache-Control`` headers.
+*Traffic Server considers all HTTP objects in the cache to be stale:*
+ Always revalidate HTTP objects in the cache with the origin server.
+
+*Traffic Server considers all HTTP objects in the cache to be fresh:*
+ Never revalidate HTTP objects in the cache with the origin server.
+
+*Traffic Server considers all HTTP objects without* ``Expires`` *or*
+``Cache-control`` *headers to be stale:*
+ Revalidate all HTTP objects without ``Expires`` or
+ ``Cache-Control`` headers.
To configure how Traffic Server revalidates objects in the cache, you
can set specific revalidation rules in :file:`cache.config`.
To configure revalidation options
-1. Edit the following variable in :file:`records.config`
+#. Edit the variable :ts:cv:`proxy.config.http.cache.when_to_revalidate`
+ in :file:`records.config`.
- - :ts:cv:`proxy.config.http.cache.when_to_revalidate`
+#. Run the :option:`traffic_line -x` command to apply the configuration changes.
-2. Run the :option:`traffic_line -x` command to apply the configuration
- changes.
+.. _scheduling-updates-to-local-cache-content:
Scheduling Updates to Local Cache Content
=========================================
To further increase performance and to ensure that HTTP objects are
-fresh in the cache, you can use the **Scheduled Update** option. This
+fresh in the cache, you can use the *Scheduled Update* option. This
configures Traffic Server to load specific objects into the cache at
-scheduled times. You might find this especially beneficial in a reverse
-proxy setup, where you can *preload* content you anticipate will be in
-demand.
+scheduled times, regardless of whether there is an active client request
+for those objects at the scheduled time. You might find this especially
+beneficial in a reverse proxy setup, where you can preload content you
+anticipate will be in demand.
+
+To use the scheduled update option, you must:
-To use the Scheduled Update option, you must perform the following
-tasks.
+- Specify the list of URLs that contain the objects you want to schedule
+ for update.
+
+- Specify the time the update should take place.
+
+- Specify the recursion depth for the URL.
-- Specify the list of URLs that contain the objects you want to
- schedule for update,
-- the time the update should take place,
-- and the recursion depth for the URL.
- Enable the scheduled update option and configure optional retry
settings.
-Traffic Server uses the information you specify to determine URLs for
+Traffic Server uses the information you provide to determine URLs for
which it is responsible. For each URL, Traffic Server derives all
recursive URLs (if applicable) and then generates a unique URL list.
Using this list, Traffic Server initiates an HTTP ``GET`` for each
@@ -310,53 +314,59 @@ limits for HTTP concurrency at any given time. The system logs the
completion of all HTTP ``GET`` operations so you can monitor the
performance of this feature.
-Traffic Server also provides a **Force Immediate Update** option that
+Traffic Server also provides a *Force Immediate Update* option that
enables you to update URLs immediately without waiting for the specified
update time to occur. You can use this option to test your scheduled
-update configuration (refer to `Forcing an Immediate Update`_).
+update configuration. Refer to `Forcing an Immediate Update`_.
Configuring the Scheduled Update Option
---------------------------------------
To configure the scheduled update option
-1. Edit :file:`update.config` to
- enter a line in the file for each URL you want to update.
-2. Edit the following variables
+#. Edit :file:`update.config` to enter a line in the file for each URL you
+ want to update.
+
+#. Adjust the following variables in :file:`records.config`:
- :ts:cv:`proxy.config.update.enabled`
- :ts:cv:`proxy.config.update.retry_count`
- :ts:cv:`proxy.config.update.retry_interval`
- :ts:cv:`proxy.config.update.concurrent_updates`
-3. Run the :option:`traffic_line -x` command to apply the configuration
- changes.
+#. Run the :option:`traffic_line -x` command to apply the configuration changes.
-Forcing an Immediate Update
----------------------------
+Forcing Immediate Updates
+-------------------------
-Traffic Server provides a **Force Immediate Update** option that enables
+Traffic Server provides a *Force Immediate Update* option that enables
you to immediately verify the URLs listed in :file:`update.config`.
-The Force Immediate Update option disregards the offset hour and
-interval set in :file:`update.config` and immediately updates the
-URLs listed.
+This option disregards the offset hour and interval set in :file:`update.config`
+and immediately updates the URLs listed.
+
+To configure the Force Immediate Update option:
+
+#. Enable :ts:cv:`proxy.config.update.enabled` in :file:`records.config`::
-To configure the Force Immediate Update option
+ CONFIG proxy.config.update.enabled INT 1
-1. Edit the following variables
+#. Enable :ts:cv:`proxy.config.update.force` in :file:`records.config`::
- - :ts:cv:`proxy.config.update.force`
- - Make sure :ts:cv:`proxy.config.update.enabled` is set to 1.
+ CONFIG proxy.config.update.force INT 1
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+ While enabled, this overrides all normal scheduling intervals.
+
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
.. important::
- When you enable the Force Immediate Update option, Traffic Server continually updates the URLs specified in
- :file:`update.config` until you disable the option. To disable the Force Immediate Update option, set
+ When you enable the Force Immediate Update option, Traffic Server
+ continually updates the URLs specified in :file:`update.config` until you
+ disable the option. To disable the Force Immediate Update option, set
:ts:cv:`proxy.config.update.force` to ``0`` (zero).
+.. _pushing-content-into-the-cache:
+
Pushing Content into the Cache
==============================
@@ -370,17 +380,14 @@ Configuring Traffic Server for PUSH Requests
Before you can deliver content into your cache using HTTP ``PUSH``, you
must configure Traffic Server to accept ``PUSH`` requests.
-To configure Traffic Server to accept ``PUSH`` requests
-
-1. Edit :file:`ip_allow.config` to allow ``PUSH``.
+#. Edit :file:`ip_allow.config` to allow ``PUSH`` from the appropriate addresses.
-2. Edit the following variable in :file:`records.config`, enable
- the push_method.
+#. Update :ts:cv:`proxy.config.http.push_method_enabled` in
+ :file:`records.config`::
- - :ts:cv:`proxy.config.http.push_method_enabled`
+ CONFIG proxy.config.http.push_method_enabled INT 1
-3. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Understanding HTTP PUSH
-----------------------
@@ -402,51 +409,49 @@ place in the cache. The following is an example of a ``PUSH`` request::
.. important::
- Your header must include ``Content-length`` - ``Content-length`` must include both ``header`` and ``body byte
- count``.
+ Your ``PUSH`` headers must include ``Content-length``, the value for which
+ must include both headers and body byte counts. The value is not optional,
+ and an improper (too large or too small) value will result in undesirable
+ behavior.
Tools that will help manage pushing
-----------------------------------
-There is a perl script for pushing, :program:`tspush`,
-which can help you understanding how to write scripts for pushing
+Traffic Server comes with a Perl script for pushing, :program:`tspush`,
+which can assist with understanding how to write scripts for pushing
content yourself.
Pinning Content in the Cache
============================
-The **Cache Pinning Option** configures Traffic Server to keep certain
+The *Cache Pinning Option* configures Traffic Server to keep certain
HTTP objects in the cache for a specified time. You can use this option
to ensure that the most popular objects are in cache when needed and to
prevent Traffic Server from deleting important objects. Traffic Server
observes ``Cache-Control`` headers and pins an object in the cache only
if it is indeed cacheable.
-To set cache pinning rules
+To set cache pinning rules:
-1. Make sure the following variable in :file:`records.config` is set
+#. Enable :ts:cv:`proxy.config.cache.permit.pinning` in :file:`records.config`::
- - :ts:cv:`proxy.config.cache.permit.pinning`
+ CONFIG proxy.config.cache.permit.pinning INT 1
-2. Add a rule in :file:`cache.config` for each
- URL you want Traffic Server to pin in the cache. For example::
+#. Add a rule in :file:`cache.config` for each URL you want Traffic Server to
+ pin in the cache. For example::
url_regex=^https?://(www.)?apache.org/dev/ pin-in-cache=12h
-3. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
-To Cache or Not to Cache?
-=========================
+Caching HTTP Objects
+====================
When Traffic Server receives a request for a web object that is not in
the cache, it retrieves the object from the origin server and serves it
to the client. At the same time, Traffic Server checks if the object is
cacheable before storing it in its cache to serve future requests.
-Caching HTTP Objects
-====================
-
Traffic Server responds to caching directives from clients and origin
servers, as well as directives you specify through configuration options
and files.
@@ -454,19 +459,19 @@ and files.
Client Directives
-----------------
-By default, Traffic Server does *not* cache objects with the following
-**request headers**:
+By default, Traffic Server does not cache objects with the following
+request headers:
-- ``Authorization``: header
+- ``Authorization``
-- ``Cache-Control: no-store`` header
+- ``Cache-Control: no-store``
-- ``Cache-Control: no-cache`` header
+- ``Cache-Control: no-cache``
- To configure Traffic Server to ignore the ``Cache-Control: no-cache``
- header, refer to `Configuring Traffic Server to Ignore Client no-cache Headers`_
+ To configure Traffic Server to ignore this request header, refer to
+ `Configuring Traffic Server to Ignore Client no-cache Headers`_.
-- ``Cookie``: header (for text objects)
+- ``Cookie`` (for text objects)
By default, Traffic Server caches objects served in response to
requests that contain cookies (unless the object is text). You can
@@ -485,35 +490,36 @@ Traffic Server to ignore client ``no-cache`` directives such that it
ignores ``no-cache`` headers from client requests and serves the object
from its cache.
-To configure Traffic Server to ignore client ``no-cache`` headers
-
-1. Edit the following variable in :file:`records.config`
+#. Edit :ts:cv:`proxy.config.http.cache.ignore_client_no_cache` in
+ :file:`records.config`. ::
- - :ts:cv:`proxy.config.http.cache.ignore_client_no_cache`
+ CONFIG proxy.config.http.cache.ignore_client_no_cache INT 1
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Origin Server Directives
------------------------
-By default, Traffic Server does *not* cache objects with the following
-**response headers**:
+By default, Traffic Server does not cache objects with the following response
+headers:
-- ``Cache-Control: no-store`` header
-- ``Cache-Control: private`` header
-- ``WWW-Authenticate``: header
+- ``Cache-Control: no-store``
+
+- ``Cache-Control: private``
+
+- ``WWW-Authenticate``
To configure Traffic Server to ignore ``WWW-Authenticate`` headers,
refer to `Configuring Traffic Server to Ignore WWW-Authenticate Headers`_.
-- ``Set-Cookie``: header
-- ``Cache-Control: no-cache`` headers
+- ``Set-Cookie``
+
+- ``Cache-Control: no-cache``
To configure Traffic Server to ignore ``no-cache`` headers, refer to
`Configuring Traffic Server to Ignore Server no-cache Headers`_.
-- ``Expires``: header with value of 0 (zero) or a past date
+- ``Expires`` header with a value of 0 (zero) or a past date.
Configuring Traffic Server to Ignore Server no-cache Headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -526,12 +532,14 @@ headers, then Traffic Server also ignores ``no-store`` headers. The
default behavior of observing ``no-cache`` directives is appropriate
in most cases.
-To configure Traffic Server to ignore server ``no-cache`` headers
+To configure Traffic Server to ignore server ``no-cache`` headers:
-#. Edit the variable :ts:cv:`proxy.config.http.cache.ignore_server_no_cache`
+#. Edit :ts:cv:`proxy.config.http.cache.ignore_server_no_cache` in
+ :file:`records.config`. ::
-#. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+ CONFIG proxy.config.http.cache.ignore_server_no_cache INT 1
+
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Configuring Traffic Server to Ignore WWW-Authenticate Headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -550,12 +558,14 @@ ignore server ``WWW-Authenticate`` headers if you are knowledgeable
about HTTP 1.1.
To configure Traffic Server to ignore server ``WWW-Authenticate``
-headers
+headers:
+
+#. Edit :ts:cv:`proxy.config.http.cache.ignore_authentication` in
+ :file:`records.config`. ::
-#. Edit the variable :ts:cv:`proxy.config.http.cache.ignore_authentication`
+ CONFIG proxy.config.http.cache.ignore_authentication INT 1
-#. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Configuration Directives
------------------------
@@ -566,49 +576,54 @@ files.
You can configure Traffic Server to do the following:
-- *Not* cache any HTTP objects (refer to `Disabling HTTP Object Caching`_).
-- Cache **dynamic content** - that is, objects with URLs that end in
- ``.asp`` or contain a question mark (``?``), semicolon
- (**``;``**), or **``cgi``**. For more information, refer to `Caching Dynamic Content`_.
-- Cache objects served in response to the ``Cookie:`` header (refer to
+- Not cache any HTTP objects. Refer to `Disabling HTTP Object Caching`_.
+
+- Cache *dynamic content*. That is, objects with URLs that end in ``.asp`` or
+ contain a question mark (``?``), semicolon (``;``), or ``cgi``. For more
+ information, refer to `Caching Dynamic Content`_.
+
+- Cache objects served in response to the ``Cookie:`` header. Refer to
`Caching Cookied Objects`_.
-- Observe ``never-cache`` rules in the :file:`cache.config` file.
+
+- Observe ``never-cache`` rules in :file:`cache.config`.
Disabling HTTP Object Caching
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, Traffic Server caches all HTTP objects except those for
which you have set ``never-cache`` as :ref:`action rules <cache-config-format-action>`
-in the :file:`cache.config` file. You can disable HTTP object
-caching so that all HTTP objects are served directly from the origin
-server and never cached, as detailed below.
+in :file:`cache.config`. You can disable HTTP object caching so that all HTTP
+objects are served directly from the origin server and never cached, as
+detailed below.
+
+To disable HTTP object caching manually:
-To disable HTTP object caching manually
+#. Set :ts:cv:`proxy.config.http.enabled` to ``0`` in :file:`records.config`. ::
-1. Set the variable :ts:cv:`proxy.config.http.enabled` to ``0``.
+ CONFIG proxy.config.http.enabled INT 0
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Caching Dynamic Content
~~~~~~~~~~~~~~~~~~~~~~~
-A URL is considered **dynamic** if it ends in **``.asp``** or contains a
+A URL is considered dynamic if it ends in ``.asp`` or contains a
question mark (``?``), a semicolon (``;``), or ``cgi``. By
default, Traffic Server caches dynamic content. You can configure the
-system to ignore dyanamic looking content, although this is recommended
-only if the content is *truely* dyanamic, but fails to advertise so with
+system to ignore dynamic looking content, although this is recommended
+only if the content is truly dynamic, but fails to advertise so with
appropriate ``Cache-Control`` headers.
To configure Traffic Server's cache behaviour in regard to dynamic
-content
+content:
-1. Edit the following variable in :file:`records.config`
+#. Edit :ts:cv:`proxy.config.http.cache.cache_urls_that_look_dynamic` in
+ :file:`records.config`. To disable caching, set the variable to ``0``,
+ and to explicitly permit caching use ``1``. ::
- - :ts:cv:`proxy.config.http.cache.cache_urls_that_look_dynamic`
+ CONFIG proxy.config.http.cache.cache_urls_that_look_dynamic INT 0
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Caching Cookied Objects
~~~~~~~~~~~~~~~~~~~~~~~
@@ -624,16 +639,18 @@ unlikely that personalized headers are delivered or used.
You can reconfigure Traffic Server to:
-- *Not* cache cookied content of any type.
+- Not cache cookied content of any type.
+
- Cache cookied content that is of image type only.
+
- Cache all cookied content regardless of type.
-To configure how Traffic Server caches cookied content
+To configure how Traffic Server caches cookied content:
-1. Edit the variable :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies`
+#. Edit :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies` in
+ :file:`records.config`.
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Forcing Object Caching
======================
@@ -642,15 +659,14 @@ You can force Traffic Server to cache specific URLs (including dynamic
URLs) for a specified duration, regardless of ``Cache-Control`` response
headers.
-To force document caching
+To force document caching:
-1. Add a rule for each URL you want Traffic Server to pin to the cache
+#. Add a rule for each URL you want Traffic Server to pin to the cache
:file:`cache.config`::
url_regex=^https?://(www.)?apache.org/dev/ ttl-in-cache=6h
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Caching HTTP Alternates
=======================
@@ -660,27 +676,25 @@ objects. The content of these objects can vary widely, according to
whether a server delivers content for different languages, targets
different browsers with different presentation styles, or provides
different document formats (HTML, XML). Different versions of the same
-object are termed **alternates** and are cached by Traffic Server based
+object are termed *alternates* and are cached by Traffic Server based
on ``Vary`` response headers. You can specify additional request and
-response headers for specific ``Content-Type``\s that Traffic Server
+response headers for specific ``Content-Type`` values that Traffic Server
will identify as alternates for caching. You can also limit the number
of alternate versions of an object allowed in the cache.
Configuring How Traffic Server Caches Alternates
------------------------------------------------
-To configure how Traffic Server caches alternates, follow the steps
-below
+To configure how Traffic Server caches alternates::
-1. Edit the following variables
+1. Edit the following variables in :file:`records.config`:
- :ts:cv:`proxy.config.http.cache.enable_default_vary_headers`
- :ts:cv:`proxy.config.http.cache.vary_default_text`
- :ts:cv:`proxy.config.http.cache.vary_default_images`
- :ts:cv:`proxy.config.http.cache.vary_default_other`
-2. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+2. Run the command :option:`traffic_line -x` to apply the configuration changes.
.. note::
@@ -702,66 +716,82 @@ object (the default is 3).
Traffic Server can look up the URL in the index very quickly, it must
scan sequentially through available alternates in the object store.
- To limit the number of alternates
+To alter the limit on the number of alternates:
+
+#. Edit :ts:cv:`proxy.config.cache.limits.http.max_alts` in :file:`records.config`. ::
- #. Edit the variable :ts:cv:`proxy.config.cache.limits.http.max_alts`
- #. Run the command :option:`traffic_line -x` to apply the configuration changes.
+ CONFIG proxy.config.cache.limits.http.max_alts INT 5
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
.. _using-congestion-control:
Using Congestion Control
========================
-The **Congestion Control** option enables you to configure Traffic
+The *Congestion Control* option enables you to configure Traffic
Server to stop forwarding HTTP requests to origin servers when they
become congested. Traffic Server then sends the client a message to
retry the congested origin server later.
-To use the **Congestion Control** option, you must perform the following
-tasks:
+To enable this option:
-#. Set the variable :ts:cv:`proxy.config.http.congestion_control.enabled` to ``1``
+#. Set :ts:cv:`proxy.config.http.congestion_control.enabled` to ``1`` in
+ :file:`records.config`. ::
- - Create rules in the :file:`congestion.config` file to specify:
- - which origin servers Traffic Server tracks for congestion
- - the timeouts Traffic Server uses, depending on whether a server is
- congested
- - the page Traffic Server sends to the client when a server becomes
- congested
- - if Traffic Server tracks the origin servers per IP address or per
- hostname
+ CONFIG proxy.config.http.congestion_control.enabled INT 1
-#. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Create rules in :file:`congestion.config` to specify:
-.. _transaction-buffering-control:
+ - Which origin servers Traffic Server tracks for congestion.
-Using Transaction Buffering Control
-===================================
+ - The timeouts Traffic Server uses, depending on whether a server is
+ congested.
-By default I/O operations are run at full speed, as fast as either Traffic Server, the network, or the cache can go.
-This can be problematic for large objects if the client side connection is significantly slower. In such cases the
-content will be buffered in ram while waiting to be sent to the client. This could potentially also happen for ``POST``
-requests if the client connection is fast and the origin server connection slow. If very large objects are being used
-this can cause the memory usage of Traffic Server to become `very large
-<https://issues.apache.org/jira/browse/TS-1496>`_.
+ - The page Traffic Server sends to the client when a server becomes
+ congested.
-This problem can be ameloriated by controlling the amount of buffer space used by a transaction. A high water and low
-water mark are set in terms of bytes used by the transaction. If the buffer space in use exceeds the high water mark,
-the connection is throttled to prevent additional external data from arriving. Internal operations continue to proceed
-at full speed until the buffer space in use drops below the low water mark and external data I/O is re-enabled.
+ - Whether Traffic Server tracks the origin servers by IP address or by
+ hostname.
-Although this is intended primarily to limit the memory usage of Traffic Server it can also serve as a crude rate
-limiter by setting a buffer limit and then throttling the client side connection either externally or via a transform.
-This will cause the connection to the origin server to be limited to roughly the client side connection speed.
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
-Traffic Server does network I/O in large chunks (32K or so) and therefore the granularity of transaction buffering
-control is limited to a similar precision.
+.. _transaction-buffering-control:
-The buffer size calculations include all elements in the transaction, including any buffers associated with :ref:`transform plugins <transform-plugin>`.
+Using Transaction Buffering Control
+===================================
-Transaction buffering control can be enabled globally by using configuration variables or by :c:func:`TSHttpTxnConfigIntSet` in a plugin.
+By default, I/O operations are run at full speed, as fast as either Traffic
+Server, the network, or the cache can support. This can be problematic for
+large objects if the client side connection is significantly slower. In such
+cases the content will be buffered in ram while waiting to be sent to the
+client. This could potentially also happen for ``POST`` requests if the client
+connection is fast and the origin server connection slow. If very large objects
+are being used this can cause the memory usage of Traffic Server to become
+`very large <https://issues.apache.org/jira/browse/TS-1496>`_.
+
+This problem can be ameloriated by controlling the amount of buffer space used
+by a transaction. A high water and low water mark are set in terms of bytes
+used by the transaction. If the buffer space in use exceeds the high water
+mark, the connection is throttled to prevent additional external data from
+arriving. Internal operations continue to proceed at full speed until the
+buffer space in use drops below the low water mark and external data I/O is
+re-enabled.
+
+Although this is intended primarily to limit the memory usage of Traffic Server
+it can also serve as a crude rate limiter by setting a buffer limit and then
+throttling the client side connection either externally or via a transform.
+This will cause the connection to the origin server to be limited to roughly
+the client side connection speed.
+
+Traffic Server does network I/O in large chunks (32K or so) and therefore the
+granularity of transaction buffering control is limited to a similar precision.
+
+The buffer size calculations include all elements in the transaction, including
+any buffers associated with :ref:`transform plugins <transform-plugin>`.
+
+Transaction buffering control can be enabled globally by using configuration
+variables or by :c:func:`TSHttpTxnConfigIntSet` in a plugin.
================= ================================================== ================================================
Value Variable :c:func:`TSHttpTxnConfigIntSet` key
@@ -771,76 +801,169 @@ Set high water :ts:cv:`proxy.config.http.flow_control.high_water` :c:data:`TS
Set low water :ts:cv:`proxy.config.http.flow_control.low_water` :c:data:`TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER`
================= ================================================== ================================================
-Be careful to always have the low water mark equal or less than the high water mark. If you set only one, the other will
-be set to the same value.
+Be careful to always have the low water mark equal or less than the high water
+mark. If you set only one, the other will be set to the same value.
-If using :c:func:`TSHttpTxnConfigIntSet`, it must be called no later than :c:data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`.
+If using :c:func:`TSHttpTxnConfigIntSet`, it must be called no later than
+:c:data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`.
-.. _reducing-origin-server-requests-avoiding-the-thundering-herd:
+.. _reducing-origin-server-requests:
Reducing Origin Server Requests (Avoiding the Thundering Herd)
==============================================================
-When an object can not be served from cache, the request will be proxied to the origin server. For a popular object,
-this can result in many near simultaneous requests to the origin server, potentially overwhelming it or associated
-resources. There are several features in Traffic Server that can be used to avoid this scenario.
+When an object can not be served from cache, the request will be proxied to the
+origin server. For a popular object, this can result in many near simultaneous
+requests to the origin server, potentially overwhelming it or associated
+resources. There are several features in Traffic Server that can be used to
+avoid this scenario.
Read While Writer
-----------------
-When Traffic Server goes to fetch something from origin, and upon receiving the response, any number of clients can be allowed to start serving the partially filled cache object once background_fill_completed_threshold % of the object has been received. The difference is that Squid allows this as soon as it goes to origin, whereas ATS can not do it until we get the complete response header. The reason for this is that we make no distinction between cache refresh, and cold cache, so we have no way to know if a response is going to be cacheable, and therefore allow read-while-writer functionality.
-The configurations necessary to enable this in ATS are:
+When Traffic Server goes to fetch something from origin, and upon receiving
+the response, any number of clients can be allowed to start serving the
+partially filled cache object once background_fill_completed_threshold % of the
+object has been received.
+
+While some other HTTP proxies permit clients to begin reading the response
+immediately upon the proxy receiving data from the origin server, ATS does not
+begin allowing clients to read until after the complete HTTP response headers
+have been read and processed. This is a side-effect of ATS making no
+distinction between a cache refresh and a cold cache, which prevents knowing
+whether a response is going to be cacheable.
+
+As non-cacheable responses from an origin server are generally due to that
+content being unique to different client requests, ATS will not enable
+read-while-writer functionality until it has determined that it will be able
+to cache the object.
+
+The following settings must be made in :file:`records.config` to enable
+read-while-writer functionality in ATS::
-| CONFIG :ts:cv:`proxy.config.cache.enable_read_while_writer` ``INT 1``
-| CONFIG :ts:cv:`proxy.config.http.background_fill_active_timeout` ``INT 0``
-| CONFIG :ts:cv:`proxy.config.http.background_fill_completed_threshold` ``FLOAT 0.000000``
-| CONFIG :ts:cv:`proxy.config.cache.max_doc_size` ``INT 0``
+ CONFIG proxy.config.cache.enable_read_while_writer INT 1
+ CONFIG proxy.config.http.background_fill_active_timeout INT 0
+ CONFIG proxy.config.http.background_fill_completed_threshold FLOAT 0.000000
+ CONFIG proxy.config.cache.max_doc_size INT 0
All four configurations are required, for the following reasons:
-- enable_read_while_writer turns the feature on. It's off (0) by default
-- The background fill feature should be allowed to kick in for every possible request. This is necessary, in case the writer ("first client session") goes away, someone needs to take over the session. Hence, you should set the background fill timeouts and threshold to zero; this assures they never times out and always is allowed to kick in.
-- The proxy.config.cache.max_doc_size should be unlimited (set to 0), since the object size may be unknown, and going over this limit would cause a disconnect on the objects being served.
+- :ts:cv:`proxy.config.cache.enable_read_while_writer` being set to ``1`` turns
+ the feature on, as it is off (``0``) by default.
-Once all this enabled, you have something that is very close, but not quite the same, as Squid's Collapsed Forwarding.
+- The background fill feature (both
+ :ts:cv:`proxy.config.http.background_fill_active_timeout` and
+ :ts:cv:`proxy.config.http.background_fill_completed_threshold`) should be
+ allowed to kick in for every possible request. This is necessary in the event
+ the writer (the first client session to request the object, which triggered
+ ATS to contact the origin server) goes away. Another client session needs to
+ take over the writer.
+ As such, you should set the background fill timeouts and threshold to zero;
+ this assures they never time out and are always allowed to kick in.
+- The :ts:cv:`proxy.config.cache.max_doc_size` should be unlimited (set to 0),
+ since the object size may be unknown, and going over this limit would cause
+ a disconnect on the objects being served.
+
+Once these are enabled, you have something that is very close, but not quite
+the same, to Squid's Collapsed Forwarding.
.. _fuzzy-revalidation:
Fuzzy Revalidation
------------------
-Traffic Server can be set to attempt to revalidate an object before it becomes stale in cache. :file:`records.config` contains the settings:
-
-| CONFIG :ts:cv:`proxy.config.http.cache.fuzz.time` ``INT 240``
-| CONFIG :ts:cv:`proxy.config.http.cache.fuzz.min_time` ``INT 0``
-| CONFIG :ts:cv:`proxy.config.http.cache.fuzz.probability` ``FLOAT 0.005``
-For every request for an object that occurs "fuzz.time" before (in the example above, 240 seconds) the object is set to become stale, there is a small
-chance (fuzz.probability == 0.5%) that the request will trigger a revalidation request to the origin. For objects getting a few requests per second, this would likely not trigger, but then this feature is not necessary anyways since odds are only 1 or a small number of connections would hit origin upon objects going stale. The defaults are a good compromise, for objects getting roughly 4 requests / second or more, it's virtually guaranteed to trigger a revalidate event within the 240s. These configs are also overridable per remap rule or via a plugin, so can be adjusted per request if necessary.
+Traffic Server can be set to attempt to revalidate an object before it becomes
+stale in cache. :file:`records.config` contains the settings::
-Note that if the revalidation occurs, the requested object is no longer available to be served from cache. Subsequent
-requests for that object will be proxied to the origin.
+ CONFIG proxy.config.http.cache.fuzz.time INT 240
+ CONFIG proxy.config.http.cache.fuzz.min_time INT 0
+ CONFIG proxy.config.http.cache.fuzz.probability FLOAT 0.005
-Finally, the fuzz.min_time is there to be able to handle requests with a TTL less than fuzz.time – it allows for different times to evaluate the probability of revalidation for small TTLs and big TTLs. Objects with small TTLs will start "rolling the revalidation dice" near the fuzz.min_time, while objects with large TTLs would start at fuzz.time. A logarithmic like function between determines the revalidation evaluation start time (which will be between fuzz.min_time and fuzz.time). As the object gets closer to expiring, the window start becomes more likely. By default this setting is not enabled, but should be enabled anytime you have objects with small TTLs. Note that this option predates overridable configurations, so you can achieve something similar with a plugin or remap.config conf_remap.so configs.
+For every request for an object that occurs
+:ts:cv:`proxy.config.http.cache.fuzz.time` before (in the example above, 240
+seconds) the object is set to become stale, there is a small
+chance (:ts:cv:`proxy.config.http.cache.fuzz.probability` == 0.5%) that the
+request will trigger a revalidation request to the origin.
-These configurations are similar to Squid's refresh_stale_hit configuration option.
+.. note::
+ When revalidation occurs, the requested object is no longer available to be
+ served from cache. Subsequent requests for that object will be proxied to
+ the origin.
+
+For objects getting a few requests per second, these settings would offer a
+fairly low probability of revalidating the cached object before it becomes
+stale. This feature is not typically necessary at those rates, though, since
+odds are only one or a small number of connections would hit origin upon the
+objects going stale.
+
+Once request raise rise, the same ``fuzz.probability`` leads to a greater
+chance the object may be revalidated before becoming stale. This can prevent
+multiple clients simultaneously triggering contact with the origin server
+under higher loads, as they would do if no fuzziness was employed for
+revalidations.
+
+These settings are also overridable by remap rules and via plugins, so can be
+adjusted per request if necessary.
+
+Finally, :ts:cv:`proxy.config.http.cache.fuzz.min_time` allows for
+different time periods to evaluate the probability of revalidation for small
+TTLs and large TTLs. Objects with small TTLs will start "rolling the
+revalidation dice" near the ``fuzz.min_time``, while objects with large TTLs
+would start at ``fuzz.time``.
+
+A logarithmic like function between determines the revalidation evaluation
+start time (which will be between ``fuzz.min_time`` and ``fuzz.time``). As the
+object gets closer to expiring, the window start becomes more likely. By
+default this setting is not enabled, but should be enabled anytime you have
+objects with small TTLs. Note that this option predates overridable
+configurations, so you can achieve something similar with a plugin or
+:file:`remap.config` settings.
+
+These configuration options are similar to Squid's refresh_stale_hit
+configuration option.
Open Read Retry Timeout
-----------------------
-The open read retry configurations attempt to reduce the number of concurrent requests to the origin for a given object. While an object is being fetched from the origin server, subsequent requests would wait open_read_retry_time milliseconds before checking if the object can be served from cache. If the object is still being fetched, the subsequent requests will retry max_open_read_retries times. Thus, subsequent requests may wait a total of (max_open_read_retries x open_read_retry_time) milliseconds before establishing an origin connection of its own. For instance, if they are set to 5 and 10 respectively, connections will wait up to 50ms for a response to come back from origin from a previous request, until this request is allowed through.
+The open read retry configurations attempt to reduce the number of concurrent
+requests to the origin for a given object. While an object is being fetched
+from the origin server, subsequent requests would wait
+:ts:cv:`proxy.config.http.cache.open_read_retry_time` milliseconds before
+checking if the object can be served from cache. If the object is still being
+fetched, the subsequent requests will retry
+:ts:cv:`proxy.config.http.cache.max_open_read_retries` times. Thus, subsequent
+requests may wait a total of (``max_open_read_retries`` x ``open_read_retry_time``)
+milliseconds before establishing an origin connection of its own. For instance,
+if they are set to ``5`` and ``10`` respectively, connections will wait up to
+50ms for a response to come back from origin from a previous request, until
+this request is allowed through.
+
+.. important::
+
+ These settings are inappropriate when objects are uncacheable. In those
+ cases, requests for an object effectively become serialized. The subsequent
+ requests would await at least ``open_read_retry_time`` milliseconds before
+ being proxied to the origin.
-These settings are inappropriate when objects are uncacheable. In those cases, requests for an object effectively become serialized. The subsequent requests would await at least open_read_retry_time milliseconds before being proxies to the origin.
+It is advisable that this setting be used in conjunction with `Read While Writer`_
+for big (those that take longer than (``max_open_read_retries`` x
+``open_read_retry_time``) milliseconds to transfer) cacheable objects. Without
+the read-while-writer settings enabled, while the initial fetch is ongoing, not
+only would subsequent requests be delayed by the maximum time, but also, those
+requests would result in unnecessary requests to the origin server.
-Similarly, this setting should be used in conjunction with Read While Writer for big (those that take longer than (max_open_read_retries x open_read_retry_time) milliseconds to transfer) cacheable objects. Without the read-while-writer settings enabled, while the initial fetch is ongoing, not only would subsequent requests be delayed by the maximum time, but also, those requests would result in another request to the origin server.
+Since ATS now supports setting these settings per-request or remap rule, you
+can configure this to be suitable for your setup much more easily.
-Since ATS now supports setting these settings per-request or remap rule, you can configure this to be suitable for your setup much more easily.
+The configurations are (with defaults)::
-The configurations are (with defaults):
+ CONFIG proxy.config.http.cache.max_open_read_retries INT -1
+ CONFIG proxy.config.http.cache.open_read_retry_time INT 10
-| CONFIG :ts:cv:`proxy.config.http.cache.max_open_read_retries` ``INT -1``
-| CONFIG :ts:cv:`proxy.config.http.cache.open_read_retry_time` ``INT 10``
+The defaults are such that the feature is disabled and every connection is
+allowed to go to origin without artificial delay. When enabled, you will try
+``max_open_read_retries`` times, each with an ``open_read_retry_time`` timeout.
-The default means that the feature is disabled, and every connection is allowed to go to origin instantly. When enabled, you will try max_open_read_retries times, each with a open_read_retry_time timeout.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/index.en.rst b/doc/admin/index.en.rst
index 3b1229b..b4b7490 100644
--- a/doc/admin/index.en.rst
+++ b/doc/admin/index.en.rst
@@ -5,28 +5,25 @@ Administrators' Guide
.. 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.
+ 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.
Apache Traffic Server™ speeds Internet access, enhances website
performance, and delivers unprecedented web hosting capabilities.
-This chapter discusses how:
-
-Contents:
+Table of Contents:
.. toctree::
:maxdepth: 2
@@ -50,12 +47,11 @@ Contents:
performance-tuning.en
faqs.en
-
What Is Apache Traffic Server?
==============================
Global data networking has become part of everyday life: Internet users
-request billions of documents and terabytes of data, on a daily basis,
+request billions of documents and petabytes of data, on a daily basis,
to and from all parts of the world. Information is free, abundant, and
accessible. Unfortunately, global data networking can also be a
nightmare for IT professionals as they struggle with overloaded servers
@@ -80,9 +76,8 @@ To best suit your needs, Traffic Server can be deployed in several ways:
- In a cache hierarchy
The following sections provide a summary of these Traffic Server
-deployment options. Please keep in mind that with every of these options
-Traffic Server can be run as a *single instance*, or as a *multi-node
-cluster*.
+deployment options. Please keep in mind that with every one of these options
+Traffic Server can be run as a *single instance*, or as a *multi-node cluster*.
Traffic Server as a Web Proxy Cache
-----------------------------------
@@ -100,6 +95,10 @@ client software must be configured to send requests directly to Traffic
Server. Explicit proxy caching is described in the :ref:`explicit-proxy-caching`
chapter.
+Traffic Server can also be employed as a transparent caching proxy server, in
+which the client software needs no special configuration or even knowledge of
+the proxy's existence. This setup is described in the :ref:`transparent-proxy`
+section.
Traffic Server as a Reverse Proxy
---------------------------------
@@ -108,7 +107,8 @@ As a reverse proxy, Traffic Server is configured to be the origin server
to which the user is trying to connect (typically, the origin server’s
advertised hostname resolves to Traffic Server, which acts as the real
origin server). The reverse proxy feature is also called server
-acceleration. Reverse proxy is described in more detail in :ref:`reverse-proxy-and-http-redirects`.
+acceleration. Reverse proxy is described in more detail in
+:ref:`reverse-proxy-and-http-redirects`.
Traffic Server in a Cache Hierarchy
-----------------------------------
@@ -121,29 +121,31 @@ as a parent or a child cache to other Traffic Server systems or to
similar caching products.
Traffic Server supports ICP (Internet Cache Protocol) peering.
-Hierarchical caching is described in more detail in :ref:`hierarchical-caching`.
+Hierarchical caching is described in more detail in :ref:`admin-hierarchical-caching`.
Deployment Limitations
----------------------
-There's a number of deployment options that Traffic Server does not support right out
-of the box. Such funcionality may be implemented in a plugin, but in some cases
-Traffic Server's internal APIs or architectural restrictions won't make it easy:
+There are a number of deployment options that Traffic Server does not support
+right out of the box. Such functionality may be implemented in a plugin, but
+in some cases Traffic Server's internal APIs or architectural restrictions
+won't make it easy:
* Load Balancing - note that there is an experimental plugin for this: :ref:`balancer-plugin`.
+.. XXX needs re-work: the leadin states there's "a number" of scenarios, and then only lists one -- one's a number, but not much of a list
+
Traffic Server Components
=========================
Traffic Server consists of several components that work together to form
-a web proxy cache you can easily monitor and configure. These main
-components are described below.
+a web proxy cache you can easily monitor and configure.
The Traffic Server Cache
------------------------
The Traffic Server cache consists of a high-speed object database called
-the object store. The object store indexes objects according to URLs and
+the *object store*. The object store indexes objects according to URLs and
associated headers. Using sophisticated object management, the object
store can cache alternate versions of the same object (perhaps in a
different language or encoding type). It can also efficiently store very
@@ -157,7 +159,7 @@ entire disk as corrupt and continues to use remaining disks. If all of
the cache disks fail, then Traffic Server switches to proxy-only mode.
You can partition the cache to reserve a certain amount of disk space
for storing data for specific protocols and origin servers. For more
-information about the cache, see :ref:`configuring-the-cache`.
+information about the cache, see :ref:`admin-configuring-the-cache`.
The RAM Cache
-------------
@@ -165,8 +167,8 @@ The RAM Cache
Traffic Server maintains a small RAM cache that contains extremely
popular objects. This RAM cache serves the most popular objects as fast
as possible and reduces load on disks, especially during temporary
-traffic peaks. You can configure the RAM cache size to suit your needs;
-for detailed information, refer to :ref:`changing-the-size-of-the-ram-cache`.
+traffic peaks. You can configure the RAM cache size to suit your needs.
+For detailed information, refer to :ref:`changing-the-size-of-the-ram-cache`.
The Host Database
-----------------
@@ -177,11 +179,13 @@ user requests. This information is used to adapt future protocol
interactions and optimize performance. Along with other information, the
host database tracks:
-- DNS information (for fast conversion of hostnames to IP addresses)
+- DNS information (for fast conversion of hostnames to IP addresses).
+
- The HTTP version of each host (so advanced protocol features can be
- used with hosts running modern servers)
+ used with hosts running modern servers).
+
- Host reliability and availability information (so users will not wait
- for servers that are not running)
+ for servers that are not running).
The DNS Resolver
----------------
@@ -197,8 +201,7 @@ Traffic Server Processes
------------------------
Traffic Server contains three processes that work together to serve
-requests and manage/control/monitor the health of the system. The three
-processes are described below:
+requests and manage, control, and monitor the health of the system.
- The :program:`traffic_server` process is the transaction processing engine
of Traffic Server. It is responsible for accepting connections,
@@ -223,9 +226,9 @@ processes are described below:
- The :program:`traffic_cop` process monitors the health of both the
:program:`traffic_server` and :program:`traffic_manager` processes. The
:program:`traffic_cop` process periodically (several times each minute)
- queries the :program:`traffic_server` and :program:`traffic_manager` process by
- issuing heartbeat requests to fetch synthetic web pages. In the event
- of failure (if no response is received within a timeout interval or
+ queries the :program:`traffic_server` and :program:`traffic_manager`
+ processes by issuing heartbeat requests to fetch synthetic web pages. In the
+ event of failure (if no response is received within a timeout interval or
if an incorrect response is received), :program:`traffic_cop` restarts the
:program:`traffic_manager` and :program:`traffic_server` processes.
@@ -242,19 +245,22 @@ Administration Tools
Traffic Server offers the following administration options:
-- The Traffic Line command-line interface is a text-based interface
- from which you can monitor Traffic Server performance and network
- traffic, as well as configure the Traffic Server system. From Traffic
- Line, you can execute individual commands or script a series of
+- The Traffic Line (:program:`traffic_line`) command-line interface is a
+ text-based interface from which you can monitor Traffic Server performance
+ and network traffic, as well as configure the Traffic Server system. From
+ Traffic Line, you can execute individual commands or script a series of
commands in a shell.
-- The Traffic Shell command-line interface is an additional
- command-line tool that enables you to execute individual commands
+
+- The Traffic Shell (:program:`traffic_shell`) command-line interface is an
+ additional command-line tool that enables you to execute individual commands
that monitor and configure the Traffic Server system.
+
- Various configuration files enable you to configure Traffic Server
through a simple file-editing and signal-handling interface. Any
changes you make through Traffic Line or Traffic Shell are
automatically made to the configuration files as well.
-- Finally there is a clean C API which can be put to good use from a
+
+- Finally, there is a clean C API which can be put to good use from a
multitude of languages. The Traffic Server Admin Client demonstrates
this for Perl.
@@ -273,7 +279,7 @@ monitoring:
clients used the Traffic Server cache, how much information each of
them requested, and what pages were most popular. You can also see
why a particular transaction was in error and what state the Traffic
- Server was in at a particular time; for example, you can see that
+ Server was in at a particular time. For example, you can see that
Traffic Server was restarted or that cluster communication timed out.
Traffic Server supports several standard log file formats, such as
@@ -295,17 +301,21 @@ computers on the network. Using the security options, you can do the
following:
- Control client access to the Traffic Server proxy cache.
+
- Configure Traffic Server to use multiple DNS servers to match your
site's security configuration. For example, Traffic Server can use
different DNS servers, depending on whether it needs to resolve
hostnames located inside or outside a firewall. This enables you to
keep your internal network configuration secure while continuing to
provide transparent access to external sites on the Internet.
+
- Configure Traffic Server to verify that clients are authenticated
before they can access content from the Traffic Server cache.
+
- Secure connections in reverse proxy mode between a client and Traffic
Server, and Traffic Server and the origin server, using the SSL
termination option.
+
- Control access via SSL (Secure Sockets Layer).
Traffic Server security options are described in more detail in
@@ -314,6 +324,6 @@ Traffic Server security options are described in more detail in
Tuning Traffic Server
=====================
-Finally this last chapter on :ref:`performance-tuning` discusses the vast
-number of options that allow to optimally tune Apache Traffic Server for
-maximum performance.
+Finally, this last chapter on :ref:`performance-tuning` discusses the vast
+number of options that allow administrators to optimally tune Apache Traffic
+Server for maximum performance.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/monitoring-traffic.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/monitoring-traffic.en.rst b/doc/admin/monitoring-traffic.en.rst
index c77548b..30e04ad 100644
--- a/doc/admin/monitoring-traffic.en.rst
+++ b/doc/admin/monitoring-traffic.en.rst
@@ -1,4 +1,3 @@
-
.. _monitoring-traffic:
Monitoring Traffic
@@ -6,20 +5,20 @@ Monitoring Traffic
.. 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
-
+ 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.
+
+ 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 provides several options for monitoring system
performance and analyzing network traffic.
@@ -35,9 +34,11 @@ performance and analyze network traffic:
- Traffic Server can send email that's triggered by alarms that signal
any detected failure conditions; refer to `Working with Traffic Manager Alarms`_.
+
- The Traffic Line command-line interface provides an alternative
method of viewing Traffic Server performance and network traffic
information; refer to `Viewing Statistics from Traffic Line`_.
+
- The Traffic Shell command-line tool provides yet another alternative
method of viewing Traffic Server performance and network traffic
information; refer to `Starting Traffic Shell <../getting-started#StartTrafficShell>`_.
@@ -56,19 +57,21 @@ Configuring Traffic Server to Email Alarms
To configure Traffic Server to send an email to a specific address
whenever an alarm occurs, follow the steps below:
-1. In the :file:`records.config` file
-2. Set the :ts:cv:`proxy.config.alarm_email` variable to the email address alarms will be routed to.
-3. Run the command :option:`traffic_line -x` to apply the configuration
- changes.
+#. Set :ts:cv:`proxy.config.alarm_email` in :file:`records.config` to the email
+ address you want to receive alarm notifications. ::
+
+ CONFIG proxy.config.alarm_email STRING "alerts@example.com"
+
+#. Run the command :option:`traffic_line -x` to apply the configuration changes.
Using a Script File for Alarms
------------------------------
-Alarm messages are built into Traffic Server - you cannot change them.
+Alarm messages are built into Traffic Server and cannot be changed.
However, you can write a script file to execute certain actions when an
alarm is signaled. Traffic Server provides a sample script file named
-``example_alarm_bin.sh`` in the ``bin`` directory; simply modify the
-file to suit your needs.
+``example_alarm_bin.sh`` in the ``bin`` directory which can serve as the
+basis for your custom alarm scripts.
Viewing Statistics from Traffic Line
====================================
@@ -82,7 +85,7 @@ specific information about a Traffic Server node or cluster by
specifying the variable that corresponds to the statistic you want to
see.
-**To view a statistic**, enter the following command:::
+To view a statistic, enter the following command:::
traffic_line -r variable
@@ -100,4 +103,11 @@ prepend the Traffic Line command with ``./`` (for example:
:option:`traffic_line -r` ``variable``).
+Viewing Statistics with Traffic Top
+===================================
+
+The Traffic Top program (see :program:`traffic_top`) offers a *top-like* view of
+common statistics for your Traffic Server system. You must be running
+:ref:`plugin-stats-over-httpd` for Traffic Top to function.
+
.. XXX: We're missing docs on how to use traffic_top here.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/performance-tuning.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/performance-tuning.en.rst b/doc/admin/performance-tuning.en.rst
index 1d9efc0..5486e90 100644
--- a/doc/admin/performance-tuning.en.rst
+++ b/doc/admin/performance-tuning.en.rst
@@ -1,4 +1,3 @@
-
.. _performance-tuning:
Performance Tuning
@@ -6,21 +5,20 @@ Performance Tuning
.. 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
-
+ 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.
+ 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.
.. toctree::
:maxdepth: 2
@@ -29,9 +27,9 @@ Before you start
================
There is no single option to that will guarantee maximum performance of
-Apache Traffic Server in every use-case. There are however numerous options
+Apache Traffic Server in every use case. There are however numerous options
that help tune its performance under different loads and in its - often
-vastly different - use-cases.
+vastly different - use cases.
Building Traffic Server
=======================