fix formatting and links of everything around reverse-proxy-http-redirects
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/5748c846 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/5748c846 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/5748c846 Branch: refs/heads/master Commit: 5748c8469ad5c95005b8f313735542b535a89cdb Parents: 6823479 Author: Igor GaliÄ <[email protected]> Authored: Sun Aug 18 19:44:24 2013 +0200 Committer: Igor GaliÄ <[email protected]> Committed: Sun Aug 18 19:44:24 2013 +0200 ---------------------------------------------------------------------- doc/admin/hierachical-caching.en.rst | 4 +- doc/admin/http-proxy-caching.en.rst | 86 ++++++++++---------- doc/admin/reverse-proxy-http-redirects.en.rst | 8 +- doc/reference/configuration/cache.config.en.rst | 61 ++++++++++---- .../configuration/update.config.en.rst | 26 ++++-- doc/reference/plugins/balancer.en.rst | 2 +- doc/reference/plugins/header_filter.en.rst | 2 +- 7 files changed, 115 insertions(+), 74 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/5748c846/doc/admin/hierachical-caching.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/hierachical-caching.en.rst b/doc/admin/hierachical-caching.en.rst index 481eb73..1dd3459 100644 --- a/doc/admin/hierachical-caching.en.rst +++ b/doc/admin/hierachical-caching.en.rst @@ -1,4 +1,4 @@ -.. _hierachical-caching: +.. _hierarchical-caching: Hierarchical Caching ******************** @@ -139,7 +139,7 @@ address. dest_host=host1 scheme=http parent="parent1;parent2" round-robin=strict -Run the command ``traffic_line -x`` to apply the configuration changes. +Run the command :option:`traffic_line -x` to apply the configuration changes. .. XXX As of yet, this is unsupported. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/5748c846/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 2dd86ef..190d1d2 100644 --- a/doc/admin/http-proxy-caching.en.rst +++ b/doc/admin/http-proxy-caching.en.rst @@ -56,6 +56,7 @@ overview illustrates how Traffic Server serves a request. :alt: A cache hit A cache hit + 4. 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 **revalidation**). If it is, then Traffic Server immediately sends @@ -99,14 +100,14 @@ HTTP Object Freshness Traffic Server determines whether an HTTP object in the cache is fresh by: -- **Checking the ``Expires`` or ``max-age`` header** +- **Checking the** ``Expires`` **or** ``max-age`` **header** Some HTTP objects contain ``Expires`` headers or ``max-age`` headers that explicitly define how long the object can be cached. Traffic Server compares the current time with the expiration time to determine if the object is still fresh. -- **Checking the ``Last-Modified`` / ``Date`` header** +- **Checking the** ``Last-Modified`` **/** ``Date`` **header** If an HTTP object has no ``Expires`` header or ``max-age`` header, then Traffic Server can calculate a freshness limit using the @@ -130,7 +131,7 @@ by: both ``Last-Modified`` and ``Date`` headers, Traffic Server uses a maximum and minimum freshness limit (refer to `Setting Absolute Freshness Limits`_). -- **Checking revalidate rules in the :file:`cache.config` file** +- **Checking revalidate rules in the** :file:`cache.config` **file** Revalidate rules apply freshness limits to specific HTTP objects. You can set freshness limits for objects originating from particular @@ -151,7 +152,7 @@ To modify the aging factor for freshness computations 1. Change the value for :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`. -2. Run the ``traffic_line -x`` command to apply the configuration +2. Run the :option:`traffic_line -x` command to apply the configuration changes. Setting absolute Freshness Limits @@ -169,7 +170,7 @@ To specify an absolute freshness limit - :ts:cv:`proxy.config.http.cache.heuristic_min_lifetime` - :ts:cv:`proxy.config.http.cache.heuristic_max_lifetime` -2. Run the ``traffic_line -x`` command to apply the configuration +2. Run the :option:`traffic_line -x` command to apply the configuration changes. Specifying Header Requirements @@ -188,9 +189,11 @@ To configure Traffic Server to cache objects with specific headers 1. Change the value for :ts:cv:`proxy.config.http.cache.required_headers`. -2. Run the ``traffic_line -x`` command to apply the configuration +2. Run the :option:`traffic_line -x` command to apply the configuration changes. +.. _cache-control-headers: + Cache-Control Headers --------------------- @@ -204,7 +207,7 @@ 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 to serve any objects directly from the cache; + it should not serve any objects directly from the cache; therefore, 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`_ @@ -255,8 +258,8 @@ revalidation is one of the following: By default, Traffic Server revalidates a requested HTTP object in the cache if it considers the object to be stale. Traffic Server evaluates object freshness as described in `HTTP Object Freshness`_. -You can reconfigure how Traffic -Server evaluates freshness by selecting one of the following options: +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. @@ -275,7 +278,7 @@ To configure revalidation options - :ts:cv:`proxy.config.http.cache.when_to_revalidate` -2. Run the ``traffic_line -x`` command to apply the configuration +2. Run the :option:`traffic_line -x` command to apply the configuration changes. Scheduling Updates to Local Cache Content @@ -326,7 +329,7 @@ To configure the scheduled update option - :ts:cv:`proxy.config.update.retry_interval` - :ts:cv:`proxy.config.update.concurrent_updates` -3. Run the ``traffic_line -x`` command to apply the configuration +3. Run the :option:`traffic_line -x` command to apply the configuration changes. Forcing an Immediate Update @@ -345,7 +348,7 @@ To configure the Force Immediate Update option - :ts:cv:`proxy.config.update.force` - Make sure :ts:cv:`proxy.config.update.enabled` is set to 1. -2. Run the ``command traffic_line -x`` to apply the configuration +2. Run the command :option:`traffic_line -x` to apply the configuration changes. .. important:: @@ -376,7 +379,7 @@ To configure Traffic Server to accept ``PUSH`` requests - :ts:cv:`proxy.config.http.push_method_enabled` -3. Run the command ``traffic_line -x`` to apply the configuration +3. Run the command :option:`traffic_line -x` to apply the configuration changes. Understanding HTTP PUSH @@ -404,9 +407,9 @@ place in the cache. The following is an example of a ``PUSH`` request:: Tools that will help manage pushing ----------------------------------- -There is a perl script for pushing, `tools/push.pl`_, -which can help you understanding how to write some script for pushing -content. +There is a perl script for pushing, :program:`tspush`, +which can help you understanding how to write scripts for pushing +content yourself. Pinning Content in the Cache ============================ @@ -429,7 +432,7 @@ To set cache pinning rules url_regex=^https?://(www.)?apache.org/dev/ pin-in-cache=12h -5. Run the command ``traffic_line -x`` to apply the configuration +5. Run the command :option:`traffic_line -x` to apply the configuration changes. To Cache or Not to Cache? @@ -485,16 +488,16 @@ To configure Traffic Server to ignore client ``no-cache`` headers 3. Edit the following variable in :file:`records.config` - - `proxy.config.cache.ignore_client_no_cache` + - :ts:cv:`proxy.config.http.cache.ignore_client_no_cache` -4. Run the command ``traffic_line -x`` to apply the configuration +4. 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**: +**response headers**: - ``Cache-Control: no-store`` header - ``Cache-Control: private`` header @@ -518,15 +521,15 @@ By default, Traffic Server strictly observes ``Cache-Control: no-cache`` directives. A response from an origin server with a ``no-cache`` header is not stored in the cache and any previous copy of the object in the cache is removed. If you configure Traffic Server to ignore ``no-cache`` -headers, then Traffic Server also ignores ``no-``\ **``store``** -headers. The default behavior of observing ``no-cache`` directives is -appropriate in most cases. +headers, then Traffic Server also ignores ``no-store`` headers. The +efault behavior of observing ``no-cache`` directives is appropriate +in most cases. To configure Traffic Server to ignore server ``no-cache`` headers #. Edit the variable :ts:cv:`proxy.config.http.cache.ignore_server_no_cache` -#. Run the command ``traffic_line -x`` to apply the configuration +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Configuring Traffic Server to Ignore WWW-Authenticate Headers @@ -550,7 +553,7 @@ headers #. Edit the variable :ts:cv:`proxy.config.http.cache.ignore_authentication` -#. Run the command ``traffic_line -x`` to apply the configuration +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Configuration Directives @@ -564,7 +567,7 @@ 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 + ``.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`_. @@ -574,17 +577,16 @@ Disabling HTTP Object Caching ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, Traffic Server caches all HTTP objects except those for -which you have set -```never-cache`` <configuration-files/cache.config#action>`_ rules in -the ```cache.config`` <../configuration-files/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. +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. To disable HTTP object caching manually 3. Set the variable :ts:cv:`proxy.config.http.enabled` to ``0``. -4. Run the command ``traffic_line -x`` to apply the configuration +4. Run the command :option:`traffic_line -x` to apply the configuration changes. Caching Dynamic Content @@ -602,9 +604,9 @@ content 3. Edit the following variable in :file:`records.config` - - `proxy.config.http.cache.cache_urls_that_look_dynamic` + - :ts:cv:`proxy.config.http.cache.cache_urls_that_look_dynamic` -4. Run the command ``traffic_line -x`` to apply the configuration +4. Run the command :option:`traffic_line -x` to apply the configuration changes. Caching Cookied Objects @@ -629,7 +631,7 @@ To configure how Traffic Server caches cookied content 3. Edit the variable :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies` -4. Run the command ``traffic_line -x`` to apply the configuration +4. Run the command :option:`traffic_line -x` to apply the configuration changes. Forcing Object Caching @@ -642,12 +644,11 @@ headers. To force document caching 1. Add a rule for each URL you want Traffic Server to pin to the cache - :file:`cache.config`: + :file:`cache.config`:: - :: url_regex=^https?://(www.)?apache.org/dev/ ttl-in-cache=6h -2. Run the command ``traffic_line -x`` to apply the configuration +2. Run the command :option:`traffic_line -x` to apply the configuration changes. Caching HTTP Alternates @@ -660,7 +661,7 @@ 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 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``\s 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. @@ -677,7 +678,7 @@ below - :ts:cv:`proxy.config.http.cache.vary_default_images` - :ts:cv:`proxy.config.http.cache.vary_default_other` -4. Run the command ``traffic_line -x`` to apply the configuration +4. Run the command :option:`traffic_line -x` to apply the configuration changes. .. note:: @@ -703,7 +704,7 @@ object (the default is 3). To limit the number of alternates #. Edit the variable :ts:cv:`proxy.config.cache.limits.http.max_alts` - #. Run the command ``traffic_line -x`` to apply the configuration changes. + #. Run the command :option:`traffic_line -x` to apply the configuration changes. Using Congestion Control ======================== @@ -727,7 +728,6 @@ tasks: - if Traffic Server tracks the origin servers per IP address or per hostname -#. Run the command ``traffic_line -x`` to apply the configuration +#. Run the command :option:`traffic_line -x` to apply the configuration changes. -.. _tools/push.pl: http://git-wip-us.apache.org/repos/asf?p=trafficserver.git;a=blob;f=tools/push.pl http://git-wip-us.apache.org/repos/asf/trafficserver/blob/5748c846/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 fd66ca6..a2c1f55 100644 --- a/doc/admin/reverse-proxy-http-redirects.en.rst +++ b/doc/admin/reverse-proxy-http-redirects.en.rst @@ -258,7 +258,7 @@ To create mapping rules 1. Enter the map and reverse-map rules into the ```remap.config`` <configuration-files/remap.config>`_ file -2. Run the command ``traffic_line -x`` to apply the configuration +2. Run the command :option:`traffic_line -x` to apply the configuration changes. Enabling HTTP Reverse Proxy @@ -271,7 +271,7 @@ To enable HTTP reverse proxy, follow the steps below. - `*``proxy.config.reverse_proxy.enabled``* <configuration-files/records.config#proxy.config.reverse_proxy.enabled>`_ -2. Run the command ``traffic_line -x`` to apply the configuration +2. Run the command :option:`traffic_line -x` to apply the configuration changes. Setting Optional HTTP Reverse Proxy Options @@ -294,7 +294,7 @@ enable you to: directed (`*``proxy.config.header.parse.no_host_url_reedirect``* <configuration-files/records.config#proxy.config.header.parse.no_host_url_redirect>`_) -Don't forget to run the command ``traffic_line -x`` to apply the +Don't forget to run the command :option:`traffic_line -x` to apply the configuration changes. Redirecting HTTP Requests @@ -318,7 +318,7 @@ To set redirect rules 1. For each redirect you want to set enter a mapping rule in the ```remap.config`` <../configuration-files/remap.config>`_ file -2. Run the command ``traffic_line -x`` to apply the configuration +2. Run the command :option:`traffic_line -x` to apply the configuration changes. **Example** http://git-wip-us.apache.org/repos/asf/trafficserver/blob/5748c846/doc/reference/configuration/cache.config.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/configuration/cache.config.en.rst b/doc/reference/configuration/cache.config.en.rst index 6b6e0c9..18f8758 100644 --- a/doc/reference/configuration/cache.config.en.rst +++ b/doc/reference/configuration/cache.config.en.rst @@ -47,48 +47,73 @@ You can use more than one secondary specifier in a rule. However, you cannot repeat a secondary specifier. The following list shows the possible primary destinations with allowed values. -*``dest_domain``* {#dest_domain} +.. _cache-config-format-dest-domain: + +``dest_domain`` A requested domain name. Traffic Server matches the domain name of the destination from the URL in the request. -*``dest_host``* {#dest_host} +.. _cache-config-format-dest-host: + +``dest_host`` A requested hostname. Traffic Server matches the hostname of the destination from the URL in the request. -*``dest_ip``* {#dest_ip} +.. _cache-config-format-dest-ip: + +``dest_ip`` A requested IP address. Traffic Server matches the IP address of the destination in the request. -*``url_regex``* {#url_regex} +.. _cache-config-format-url-regex: + +``url_regex`` A regular expression (regex) to be found in a URL. The secondary specifiers are optional in the :file:`cache.config` file. The following list shows possible secondary specifiers with allowed values. -*``port``* {#port} +.. _cache-config-format-port: + +``port`` A requested URL port. -*``scheme``* {#scheme} +.. _cache-config-format-scheme: + +``scheme`` A request URL protocol: http or https. -*``prefix``* {#prefix} +.. _cache-config-format-prefix: + +``prefix`` A prefix in the path part of a URL. -*``suffix``* {#suffix} +.. _cache-config-format-suffix: + +``suffix`` A file suffix in the URL. -*``method``* {#method} +.. _cache-config-format-method: + +``method`` A request URL method: get, put, post, trace. -*``time``* {#time} +.. _cache-config-format-time: + +``time`` A time range, such as 08:00-14:00. -*``src_ip``* {#src_ip} +.. _cache-config-format-src-ip: + +``src_ip`` A client IP address. The following list shows possible actions and their allowed values. -*``action``* {#action} + +.. _cache-config-format-action: + +``action`` One of the following values: - ``never-cache`` configures Traffic Server to never cache @@ -100,7 +125,9 @@ The following list shows possible actions and their allowed values. - ``ignore-server-no-cache`` configures Traffic Server to ignore ``Cache-Control: no-cache`` headers from origin server responses. -*``pin-in-cache``* {#pin-in-cache} +.. _cache-config-format-pin-in-cache: + +``pin-in-cache`` The amount of time you want to keep the object(s) in the cache. The following time formats are allowed: @@ -110,11 +137,15 @@ The following list shows possible actions and their allowed values. - ``s`` for seconds; for example: 20s - mixed units; for example: 1h15m20s -*``revalidate``* {#revalidate} +.. _cache-config-format-revalidate: + +``revalidate`` The amount of time object(s) are to be considered fresh. Use the same time formats as ``pin-in-cache``. -*``ttl-in-cache``* {#ttl-in-cache} +.. _cache-config-format-ttl-in-cache: + +``ttl-in-cache`` The amount of time object(s) are to be kept in the cache, regardless of Cache-Control response headers. Use the same time formats as pin-in-cache and revalidate . http://git-wip-us.apache.org/repos/asf/trafficserver/blob/5748c846/doc/reference/configuration/update.config.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/configuration/update.config.en.rst b/doc/reference/configuration/update.config.en.rst index 0b7659e..33a7931 100644 --- a/doc/reference/configuration/update.config.en.rst +++ b/doc/reference/configuration/update.config.en.rst @@ -70,31 +70,39 @@ such as those used by Internet crawlers. Format ====== -Each line in the :file:`update.config` file uses the following format: - -:: +Each line in the :file:`update.config` file uses the following format:: URL\request_headers\offset_hour\interval\recursion_depth\ The following list describes each field. -*``URL``* {#URL} +.. _update-config-format-url: + +*URL* HTTP-based URLs. -*``request_headers``* {#request_headers} +.. _update-config-format-request-headers: + +*request_headers* Optional. A list of headers, separated by semicolons, passed in each ``GET`` request. You can define any request header that conforms to the HTTP specification; the default is no request header. -*``offset_hour``* {#offset_hour} +.. _update-config-format-offset-hour: + +*offset_hour* The base hour used to derive the update periods. The range is 00-23 hours. -*``interval``* {#interval} +.. _update-config-format-interval: + +*interval* The interval (in seconds) at which updates should occur, starting at the offset hour. -*``recursion_depth``* {#recursion_depth} +.. _update-config-format-reecursion-depth: + +*recursion_depth* The depth to which referenced URLs are recursively updated, starting at the given URL. This field applies only to HTTP. @@ -113,6 +121,8 @@ result in updates at 13:00, 14:00, 15:00, and so on. To schedule an update that occurs only once a day, use an interval value 86400 (i.e., 24 hours x 60 minutes x 60 seconds = 86400). +.. XXX: The following seems misplaced here, and is probably better off placed in an apendix. + Specifying URL Regular Expressions (``url_regex``) ================================================== http://git-wip-us.apache.org/repos/asf/trafficserver/blob/5748c846/doc/reference/plugins/balancer.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/plugins/balancer.en.rst b/doc/reference/plugins/balancer.en.rst index 3222184..4fba905 100644 --- a/doc/reference/plugins/balancer.en.rst +++ b/doc/reference/plugins/balancer.en.rst @@ -1,4 +1,4 @@ -.. balancer-plugin: +.. _balancer-plugin: Balancer Plugin *************** http://git-wip-us.apache.org/repos/asf/trafficserver/blob/5748c846/doc/reference/plugins/header_filter.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/plugins/header_filter.en.rst b/doc/reference/plugins/header_filter.en.rst index 3885612..aa34717 100644 --- a/doc/reference/plugins/header_filter.en.rst +++ b/doc/reference/plugins/header_filter.en.rst @@ -123,7 +123,7 @@ The configuration that ties everything together is then X-Forwarded-Proto =https= To activate this configuration, we need to restart Traffic Server with -``traffic_line -L``. +:option:`traffic_line -L`. In the backend servers we can now pick this up and do appropriately set server variables that will be picked up by CGI programs for instance. In
