Repository: trafficserver Updated Branches: refs/heads/master cc6233173 -> f65b867bd
TS-3831: Documentation update. Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/f65b867b Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/f65b867b Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/f65b867b Branch: refs/heads/master Commit: f65b867bd0741ec1d370e429ac774e5930a56dfa Parents: cc62331 Author: Alan M. Carroll <[email protected]> Authored: Tue Aug 11 11:00:16 2015 -0500 Committer: Alan M. Carroll <[email protected]> Committed: Tue Aug 11 11:01:58 2015 -0500 ---------------------------------------------------------------------- doc/admin/traffic-server-error-messages.en.rst | 35 +++++++++++++++----- .../configuration/records.config.en.rst | 13 ++++++-- 2 files changed, 38 insertions(+), 10 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/f65b867b/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 d26b85e..b15a491 100644 --- a/doc/admin/traffic-server-error-messages.en.rst +++ b/doc/admin/traffic-server-error-messages.en.rst @@ -136,21 +136,40 @@ Traffic Server Alarm Messages addresses. You must ``setuid root`` for the ``vip_config`` file in the Traffic Server ``bin`` directory. +.. _body-factory: + HTML Messages Sent to Clients ============================= -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 -:ts:cv:`proxy.config.body_factory.template_sets_dir`). +Traffic Server returns detailed error messages to client browsers 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`. + +The error messages can be customized. The actual response is generated from a template. These +templates are stored in files which means the errors responses can be customized by modifying these +files. The default directory for the template files is ``PREFIX/body_factory/default`` +but this can be changed by the configuration variable +:ts:cv:`proxy.config.body_factory.template_sets_dir`. All files in this directory are added to a +lookup table which is consulted when the error message is generated. The name used for lookup is by +default that listed in the :ref:`following table <body-factory-error-table>`. It can be overridden by +:ts:cv:`proxy.config.body_factory.template_base` which, if set, is a string that is prepended to the +search name along with an underscore. For example, if the default lookup name is +``cache#read_error`` then by default the response will be generated from the template in the file +named ``cache#read_error``. If the template base name were set to "apache" then the lookup would +look for a file named ``apache_cache#read_error`` in the template table. This can be used to switch +out error message sets or, because this variable is overridable, to select an error message set +based on data in the transaction. + +The text for an error message is processed as if it were a :ref:`custom logging format <custom-logging-fields>` which +enables customization by values present in the transaction for which the error occurred. The following table lists the hard-coded Traffic Server HTTP messages, with corresponding HTTP response codes and customizable files. +.. _body-factory-error-table: + ``Access Denied`` ``403`` You are not allowed to access the document at location ``URL``. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/f65b867b/doc/reference/configuration/records.config.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst index 257e070..c34a7e8 100644 --- a/doc/reference/configuration/records.config.en.rst +++ b/doc/reference/configuration/records.config.en.rst @@ -379,6 +379,7 @@ Unless explicitly specified in `proxy.config.http.server_ports`_ the server port :reloadable: When we trigger a throttling scenario, this how long our accept() are delayed. + Cluster ======= @@ -1678,7 +1679,7 @@ all the different user-agent versions of documents it encounters. - ``0`` = default, disable cache and goto origin server - ``1`` = return a 502 error on a cache miss - - ``2`` = serve stale if object's age is under :ref:`proxy.config.http.cache.max_stale_age`, else, goto origin server + - ``2`` = serve stale if object's age is under :ts:cv:`proxy.config.http.cache.max_stale_age`, else, goto origin server Customizable User Response Pages ================================ @@ -1703,6 +1704,14 @@ Customizable User Response Pages relative path, Traffic Server resolves it relative to the ``PREFIX`` directory. +.. ts:cv:: CONFIG proxy.config.body_factory.template_base STRING "" + :reloadable: + :overridable: + + A prefix for the file name to use to find an error template file. If set (not the empty string) + this value and an underscore are predended to the file name to find in the template sets + directory. See :ref:`body-factory`. + .. ts:cv:: CONFIG proxy.config.body_factory.response_suppression_mode INT 0 Specifies when Traffic Server suppresses generated response pages: @@ -2062,7 +2071,7 @@ Logging Configuration - ``log_name`` STRING [format] The filename (ex. :ref:`squid log <log-formats-squid-format>`). - - ``log_header_ STRING NULL + - ``log_header`` STRING NULL The file header text (ex. :ref:`squid log <log-formats-squid-format>`). The format can be either ``squid`` (Squid Format), ``common`` (Netscape Common), ``extended`` (Netscape Extended),
