You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by di...@apache.org on 2010/01/07 22:18:47 UTC
svn commit: r897017 - in /incubator/trafficserver/site/trunk/docs/admin:
cache.htm reverse.htm
Author: dianes
Date: Thu Jan 7 21:18:22 2010
New Revision: 897017
URL: http://svn.apache.org/viewvc?rev=897017&view=rev
Log: (empty)
Modified:
incubator/trafficserver/site/trunk/docs/admin/cache.htm
incubator/trafficserver/site/trunk/docs/admin/reverse.htm
Modified: incubator/trafficserver/site/trunk/docs/admin/cache.htm
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/cache.htm?rev=897017&r1=897016&r2=897017&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/admin/cache.htm (original)
+++ incubator/trafficserver/site/trunk/docs/admin/cache.htm Thu Jan 7 21:18:22 2010
@@ -1,175 +1,174 @@
-<html>
-<head>
-<title>Traffic Edge Administratorâs Guide</title>
-<meta content="text/html; charset=UTF-8" http-equiv="content-type"/>
-
-<link rel="stylesheet" href="doc.css" type="text/css" media="all" />
-</head>
-
-<body>
-<h1>Configuring the Cache</h1>
-<p>The Traffic Server cache consists of a high-speed object database called the <i>object store</i> that indexes objects according to URLs and associated headers.</p>
-<p>This chapter discusses the following topics: </p>
-<ul>
-<li><a href="#TrafficEdgeCache"><em>The Traffic Server Cache</em></a></li>
-<li><a href="#RAMCache"><em>The RAM Cache</em></a></li>
-<li><a href="#ChangingSizeRAMCache"><em>Changing the Size of the RAM Cache</em></a></li>
-<li><a href="#ChangingCacheCapacity"><em>Changing Cache Capacity</em></a></li>
-<li><a href="#PartitioningCache"><em>Partitioning the Cache</em></a></li>
-<li><a href="#ConfiguringCacheObjectSizeLimit"><em>Configuring the Cache Object Size Limit</em></a></li>
-<li><a href="#ClearingCache"><em>Clearing the Cache</em></a></li>
-<li><a href="#InspectingCache"><em>Inspecting the Cache</em></a></li>
-</ul>
-<h2 id="TrafficEdgeCache">The Traffic Server Cache</h2>
-<p>The Traffic Server cache consists of a high-speed object database called the <em>object store</em>. 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, providing optimum bandwidth savings. Using sophisticated object management, the object store can cache alternate versions of the same object (perhaps due to dissimilar language or encoding type). It can also efficiently store very small and very large documents, thereby minimizing wasted space. When the cache is full, Traffic Server removes stale data, ensuring that the most requested objects are kept on-hand and fresh. </p>
-<p>Traffic Server is designed to tolerate total disk failures on any of the cache disks. If the disk fails completely, then Traffic Server marks the entire disk as corrupt and continues using the remaining disks. An alarm is created, indicating which disk failed. If all of the cache disks fail, then Traffic Server goes into proxy-only mode. </p>
-<p>You can perform the following cache configuration tasks: </p>
-<ul>
- <li>Change the total amount of disk space allocated to the cache; refer to <a href="#ChangingCacheCapacity"><em>Changing Cache Capacity</em></a>. </li>
- <li>Partition the cache by reserving cache disk space for specific protocols and origin servers/domains; refer to <a href="#PartitioningCache"><em>Partitioning the Cache</em></a>. </li>
- <li>Delete all data in the cache; refer to <a href="#ClearingCache"><em>Clearing the Cache</em></a>.</li>
-</ul>
-<h2 id="RAMCache">The RAM Cache</h2>
-<p>Traffic Server maintains a small RAM cache of 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, as described in the next section, <a href="#ChangingSizeRAMCache"><em>Changing the Size of the RAM Cache</em></a>. </p>
-<h2 id="ChangingSizeRAMCache">Changing the Size of the RAM Cache</h2>
-<p>Traffic Server provides a dedicated RAM cache for fast retrieval of popular small objects. The default RAM cache size is automatically calculated based on the number and size of the cache partitions you have configured. If you have partitioned your cache according to protocol and/or hosts, then the size of the RAM cache for each partition is proportional to the size of that partition. </p>
-<p>You can increase the RAM cache size for better cache hit performance. However, if you increase the size of the RAM cache and observe a decrease in performance (such as increased latencies), then the operating system might require more memory for network resources. In such instances, you should return the RAM cache size to its previous value.</p>
-<h5>To change RAM cache size: </h5>
-<ol>
- <li>Stop Traffic Server. </li>
- <li>In a text editor, open the <code>records.config</code> file located in the Traffic Server <code>config</code> directory. </li>
- <li>Edit the following variable:</li>
-</ol>
-<br />
-<table width="1232" border="1">
- <tr>
- <th width="322" scope="col">Variable</th>
- <th width="894" scope="col">Description</th>
- </tr>
- <tr>
- <td><i><code>proxy.config.cache.ram_cache.size</code></i></td>
- <td>Set this variable to specify the size of the RAM cache.<br />
- The default value of -1 means that the RAM cache is automatically sized at approximately one MB per gigabyte of disk.</td>
- </tr>
-</table>
-<br />
-<ol>
- <li>Save and close the <code>records.config</code> file. </li>
- <li>Restart Traffic Server. If you increase the RAM cache to a size or 1GB or more, then restart with the <code>start_traffic_server</code> command; refer to <a href="getstart.htm#StartingTrafficEdge"><em>Starting Traffic Server</em></a>. </li>
-</ol>
-<p> </p>
-<h2 id="ChangingCacheCapacity">Changing Cache Capacity</h2>
-<p>You can increase or reduce the total amount of disk space allocated to the cache without clearing the content. <br /> To check the size of the cache (in bytes), enter the command <code>traffic_line -r proxy.process.cache.bytes_total</code>. </p>
-<h3>Increasing Cache Capacity </h3>
-<p>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:</p>
-<ol>
- <li>Stop Traffic Server. </li>
- <li>Add hardware, if necessary. </li>
- <li>Edit the Traffic Server <code>storage.config</code> file: increase the amount of disk space allocated to the cache on existing disks or describe the new hardware you are adding; refer to <a href="files.htm#151089"><em>storage.config</em></a>.</li>
- <li>If you add a new disk, then you must edit the <code>/etc/rc.d/init.d/traffic_server</code> file to add a raw disk binding. Instructions for adding a raw disk binding are located in the Traffic Server <code>storage.config</code> file. </li>
- <li>Restart Traffic Server. </li>
-</ol>
-<h3>Reducing Cache Capacity </h3>
-<p>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:</p>
-<ol>
- <li>Stop Traffic Server. </li>
- <li>Remove hardware, if necessary. </li>
- <li>Edit the Traffic Server <code>storage.config</code> file: reduce the amount of disk space allocated to the cache on existing disks or delete the reference to the hardware you're removing; refer to <a href="files.htm#151089"><em>storage.config</em></a>. </li>
- <li>If you remove a disk, then you must edit the <code>/etc/rc.d/init.d/traffic_server</code> file to remove the raw disk binding for the disk. </li>
- <li>Restart Traffic Server. </li>
-</ol>
-<p><strong>IMPORTANT:</strong> In the <code>storage.config</code> file, a formatted or raw disk must be at least 128 MB. </p>
-<h2 id="PartitioningCache">Partitioning the Cache</h2>
-<p>You can manage your cache space more efficiently and restrict disk usage by creating cache partitions with different sizes for specific protocols. You can further configure these partitions to store data from specific origin servers and/or domains. The partition configuration must be the same on all nodes in a cluster. </p>
-<h3 id="CreatingCachePartitionsSpecificProtocols">Creating Cache Partitions for Specific Protocols</h3>
-<p>You can create separate partitions 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 supports the <b>http</b> partition type for HTTP objects.</p>
-<h5>To partition the cache according to protocol: </h5>
-<ol>
- <li>In a text editor, open the <code>partition.config</code> file located in the Traffic Server <code>config</code> directory. </li>
- <li>Enter a line in the file for each partition you want to create; refer to <a href="files.htm#50072"><em>partition.config</em></a>. </li>
- <li>Save and close the <code>partition.config</code> file. </li>
- <li>Restart Traffic Server. </li>
-</ol>
-<h4>Making Changes to Partition Sizes and Protocols </h4>
-<p>After you've configured your cache partitions based on protocol, you can make changes to the configuration at any time. Before making changes, note the following: </p>
-<ul>
- <li>You must stop Traffic Server before you change the cache partition size and protocol assignment. </li>
- <li>When you increase the size of a partition, the contents of the partition are <em>not</em> deleted However, when you reduce the size of a partition, the contents of the partition <em>are</em> deleted. </li>
- <li>When you change the partition number, the partition is deleted and then re-created, even if the size and protocol type remain the same. </li>
- <li>When you add new disks to your Traffic Server node, the partition sizes specified in percentages increase proportionately. </li>
- <li>A lot of changes to the partition sizes might result in disk fragmentation, which affects performance and hit rate. You should clear the cache before making many changes to cache partition sizes (refer to <a href="#ClearingCache"><em>Clearing the Cache</em></a>).</li>
-</ul>
-<h3>Partitioning the Cache According to Origin Server or Domain</h3>
-<p>After you have partitioned the cache according to size and protocol, you can assign the partitions you created to specific origin servers and/or domains. You can assign a partition to a single origin server or multiple origin servers. However, if a partition is assigned to multiple origin servers, then there is no guarantee on the space available in the partition for each origin server. Content is stored in the partition according to popularity. In addition to assigning partitions to specific origin servers and domains, you must assign a generic partition to store content from all origin servers and domains that are not listed. This generic partition is also used if the partitions for a particular origin server or domain become corrupt. If you do not assign a generic partition, then Traffic Server will run in proxy-only mode. </p>
-<p><strong>Note: </strong>You do <em>not</em> need to stop Traffic Server before you assign partitions 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 low traffic. </p>
-<h5>To partition the cache according to hostname and domain: </h5>
-<ol>
- <li>Configure the cache partitions according to size and protocol, as described in <a href="#CreatingCachePartitionsSpecificProtocols"><em>Creating Cache Partitions for Specific Protocols</em></a>. </li>
- <li>Create a separate partition 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 partitions do not need to be the same size. </li>
- <li>In a text editor, open the <code>hosting.config</code> file located in the Traffic Server <code>config</code> directory. </li>
- <li>Enter a line in the file to allocate the partition(s) used for each origin server and/or domain; refer to <a href="files.htm#139053"><em>hosting.config</em></a>. </li>
- <li>Assign a generic partition to use for content that does not belong to any of the origin servers or domains listed in the file. If all partitions for a particular origin server become corrupt, then Traffic Server will also use the generic partition to store content for that origin server; refer to <a href="files.htm#139053"><em>hosting.config</em></a>. </li>
- <li>Save and close the <code>hosting.config</code> file. </li>
- <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
- <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
-</ol>
-<h2 id="ConfiguringCacheObjectSizeLimit">Configuring the Cache Object Size Limit</h2>
-<p>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:</p>
-<ol>
- <li>In a text editor, open the <code>records.config</code> file located in the Traffic Server <code>config</code> directory. </li>
- <li>Edit the following variable:</li>
- <br />
-<table width="1232" border="1">
- <tr>
- <th width="322" scope="col">Variable</th>
- <th width="894" scope="col">Description</th>
- </tr>
- <tr>
- <td><code><i>proxy.config.cache.max_doc_size</i></code></td>
- <td>Set this variable to specify the maximum size allowed for objects in the cache in bytes.<br /> Enter <code>0</code> (zero) if you do not want a size limit.</td>
- </tr>
-</table>
-<br />
- <li>Save and close the <code>records.config</code> file. </li>
- <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
- <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
-</ol>
-<h2 id="ClearingCache">Clearing the Cache</h2>
-<p>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 cannot clear the cache when Traffic Server is running. </p>
-<h5>To clear the cache: </h5>
-<ol>
- <li>Stop Traffic Server; refer to <a href="getstart.htm#StoppingTrafficEdge"><em>Stopping Traffic Server</em></a>. </li>
- <li>Enter the following command to clear the cache:<br /><code>traffic_server -Cclear</code><br />The <code>clear</code> command deletes all data in the object store and the host database. Traffic Server does not prompt you to confirm the deletion. </li>
- <li>Restart Traffic Server; refer to <a href="getstart.htm#StartingTrafficEdge"><em>Starting Traffic Server</em></a>.</li>
-</ol>
-<h2 id="InspectingCache">Inspecting the Cache</h2>
-<p>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 <i>all</i> the objects in your cache. Make sure that only authorized administrators are allowed to access this utility. To control which hosts have access via the <code>mgmt_allow.config</code> file, refer to <a href="secure.htm#ControllingHostAccessTrafficManager"><em>Controlling Host Access to Traffic Manager</em></a>. </p>
-<h3>Accessing the Cache Inspector Utility </h3>
-<p>To access the Cache Inspector utility, follow the steps below:</p>
-<ol>
- <li>In a text editor, open the <code>records.config</code> file located in the Traffic Server <code>config</code> directory. </li>
- <li>Add the following variable at the end of the file:<br /><code><i>CONFIG proxy.config.http_ui_enabled INT 1</i></code></li>
- <li>To access the cache inspector in reverse proxy mode, you must add a remap rule to <code>remap.config</code> to expose the URL. <br />
- For example: <br />
- <code>map http://yourhost.com/myCI http://{cache} @action=allow @src_ip=corp_internal_address</code></li>
- <li>From the Traffic Server <code>bin</code> directory, enter the following command to re-read the configuration file:<br />
- <code>traffic_line -x</code></li>
- <li>Open your web browser and configure it to use your Traffic Server as a proxy server. Type the following URL:
-<br /><code>http://{cache}</code></li>
- <li>The Cache page opens; refer to <a href="#UsingCachePage"><em>Using the Cache Page</em></a> below.</li>
-</ol>
-<h3 id="UsingCachePage">Using the Cache Page </h3>
-<p>The <b>Cache page</b> provides several options that enable you to view and delete the contents of your cache: </p>
-<ul>
- <li>Click <strong>Lookup url</strong> 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. </li>
- <li>Click <strong>Delete url</strong> to delete a particular URL or list of URLs from the cache. Traffic Server indicates if a delete is successful. </li>
- <li>Click <strong>Regex lookup</strong> to search for URLs that match one or more regular expressions. From the display page, you can delete the URLs listed.<br />
- For example, enter the following to search for all URLs that end in html and are prefixed with <code>http://www.dianes.com: <br />
- http://www.dianes.com/.*\.html$</code></li>
- <li>Click <strong>Regex delete</strong> to delete all URLs that match a specified regular expression.<br /> For example, enter the following to delete all HTTP URLs that end in <code>html</code>: <br /><code>http://.*\.html$</code> </li>
- <li>Click <strong>Regex invalidate</strong> 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. </li>
-</ul>
-<p><strong>Note:</strong> Only one administrator should delete and invalidate cache entries from the Cache page at any point in time. Changes made by multiple administrators at the same time can lead to unpredictable results.</p>
-
-</body>
+<html>
+<head>
+<title>Traffic Edge Administratorâs Guide</title>
+<meta content="text/html; charset=UTF-8" http-equiv="content-type"/>
+
+<link rel="stylesheet" href="doc.css" type="text/css" media="all" />
+</head>
+
+<body>
+<h1>Configuring the Cache</h1>
+<p>The Traffic Server cache consists of a high-speed object database called the <b>object store </b>that indexes objects according to URLs and their associated headers.</p>
+<p>This chapter discusses the following topics: </p>
+<ul>
+<li><a href="#TrafficEdgeCache">The Traffic Server Cache</a></li>
+<li><a href="#RAMCache">The RAM Cache</a></li>
+<li><a href="#ChangingSizeRAMCache">Changing the Size of the RAM Cache</a></li>
+<li><a href="#ChangingCacheCapacity">Changing Cache Capacity</a></li>
+<li><a href="#PartitioningCache">Partitioning the Cache</a></li>
+<li><a href="#ConfiguringCacheObjectSizeLimit">Configuring the Cache Object Size Limit</a></li>
+<li><a href="#ClearingCache">Clearing the Cache</a></li>
+<li><a href="#InspectingCache">Inspecting the Cache</a></li>
+</ul>
+<h2 id="TrafficEdgeCache">The Traffic Server Cache</h2>
+<p>The Traffic Server cache consists of a high-speed object database called the <b>object store</b>. 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 management, the object store can cache alternate versions of the same object (versions may differ because of dissimilar language or encoding types). It can also efficiently store very small and very large documents, thereby minimizing wasted space. When the cache is full, Traffic Server removes stale data to ensure the most requested objects are kept readily available and fresh. </p>
+<p>Traffic Server is designed to tolerate total disk failures on any of the cache disks. If the disk fails completely, then Traffic Server marks the entire disk as corrupt and continues using the remaining disks. An alarm is then created to indicate which disk failed. If all of the cache disks fail, then Traffic Server goes into proxy-only mode. </p>
+<p>You can perform the following cache configuration tasks: </p>
+<ul>
+ <li>Change the total amount of disk space allocated to the cache: refer to <a href="#ChangingCacheCapacity">Changing Cache Capacity</a>. </li>
+ <li>Partition the cache by reserving cache disk space for specific protocols and origin servers/domains: refer to <a href="#PartitioningCache">Partitioning the Cache</a>. </li>
+ <li>Delete all data in the cache: refer to <a href="#ClearingCache">Clearing the Cache</a>.</li>
+</ul>
+<h2 id="RAMCache">The RAM Cache</h2>
+<p>Traffic Server maintains a small RAM cache of extremely popular objects. This RAM cache serves the most popular objects as quickly as possible and reduces load on disks, especially during temporary traffic peaks. You can configure the RAM cache size to suit your needs, as described in <a href="#ChangingSizeRAMCache">Changing the Size of the RAM Cache</a> below. </p>
+<h2 id="ChangingSizeRAMCache">Changing the Size of the RAM Cache</h2>
+<p>Traffic Server provides a dedicated RAM cache for fast retrieval of popular small objects. The default RAM cache size is automatically calculated based on the number and size of the cache partitions you have configured. If you've partitioned your cache according to protocol and/or hosts, then the size of the RAM cache for each partition is proportional to the size of that partition. </p>
+<p>You can increase the RAM cache size for better cache hit performance. However, if you increase the size of the RAM cache and observe a decrease in performance (such as increased latencies), then it's possible that the operating system requires more memory for network resources. In such instances, you should return the RAM cache size to its previous value.</p>
+<h5>To change the RAM cache size: </h5>
+<ol>
+ <li>Stop Traffic Server. </li>
+ <li>In a text editor, open the <code>records.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+ <li>Edit the following variable:</li>
+
+
+<table width="1232" border="1">
+ <tr>
+ <th width="322" scope="col">Variable</th>
+ <th width="894" scope="col">Description</th>
+ </tr>
+ <tr>
+ <td><i><code>proxy.config.cache.ram_cache.size</code></i></td>
+ <td>Set this variable to specify the size of the RAM cache.<br />
+ The default value of -1 means that the RAM cache is automatically sized at approximately 1MB per gigabyte of disk.</td>
+ </tr>
+</table>
+
+
+ <li>Save and close the <code>records.config</code> file. </li>
+ <li>Restart Traffic Server. If you increase the RAM cache to a size or 1GB or more, then restart with the <code>start_traffic_server</code> command (refer to <a href="getstart.htm#StartingTrafficEdge">Starting Traffic Server</a>). </li>
+</ol>
+<p> </p>
+<h2 id="ChangingCacheCapacity">Changing Cache Capacity</h2>
+<p>You can increase or reduce the total amount of disk space allocated to the cache without clearing the content. To check the size of the cache (in bytes), enter the command <code>traffic_line -r proxy.process.cache.bytes_total</code>. </p>
+<h3>Increasing Cache Capacity </h3>
+<p>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:</p>
+<ol>
+ <li>Stop Traffic Server. </li>
+ <li>Add hardware, if necessary. </li>
+ <li>Edit the Traffic Server <code>storage.config</code> file: increase the amount of disk space allocated to the cache on existing disks or describe the new hardware you are adding (refer to <a href="files.htm#151089">storage.config</a>).</li>
+ <li>If you add a new disk, then you must edit the <code>/etc/rc.d/init.d/traffic_server</code> file to add a raw disk binding. Instructions for adding a raw disk binding are located in the Traffic Server <code>storage.config</code> file. </li>
+ <li>Restart Traffic Server. </li>
+</ol>
+<h3>Reducing Cache Capacity </h3>
+<p>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:</p>
+<ol>
+ <li>Stop Traffic Server. </li>
+ <li>Remove hardware, if necessary. </li>
+ <li>Edit the Traffic Server <code>storage.config</code> file: reduce the amount of disk space allocated to the cache on existing disks or delete the reference to the hardware you're removing (refer to <a href="files.htm#151089">storage.config</a>). </li>
+ <li>If you remove a disk, then you must edit the <code>/etc/rc.d/init.d/traffic_server</code> file to remove the raw disk binding for the disk. </li>
+ <li>Restart Traffic Server. </li>
+</ol>
+<p><strong>IMPORTANT:</strong> In the <code>storage.config</code> file, a formatted or raw disk must be at least 128 MB. </p>
+<h2 id="PartitioningCache">Partitioning the Cache</h2>
+<p>You can manage your cache space more efficiently and restrict disk usage by creating cache partitions with different sizes for specific protocols. You can further configure these partitions to store data from specific origin servers and/or domains. The partition configuration must be the same on all nodes in a cluster. </p>
+<h3 id="CreatingCachePartitionsSpecificProtocols">Creating Cache Partitions for Specific Protocols</h3>
+<p>You can create separate partitions 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 <b>http</b> partition type for HTTP objects.</p>
+<h5>To partition the cache according to protocol: </h5>
+<ol>
+ <li>In a text editor, open the <code>partition.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+ <li>Enter a line in the file for each partition you want to create (refer to <a href="files.htm#50072">partition.config</a>). </li>
+ <li>Save and close the <code>partition.config</code> file. </li>
+ <li>Restart Traffic Server. </li>
+</ol>
+<h4>Making Changes to Partition Sizes and Protocols </h4>
+<p>After you've configured your cache partitions based on protocol, you can make changes to the configuration at any time. Before making changes, note the following: </p>
+<ul>
+ <li>You must stop Traffic Server before you change the cache partition size and protocol assignment. </li>
+ <li>When you increase the size of a partition, the contents of the partition are <em>not</em> deleted However, when you reduce the size of a partition, the contents of the partition <em>are</em> deleted. </li>
+ <li>When you change the partition number, the partition is deleted and then recreated, even if the size and protocol type remain the same. </li>
+ <li>When you add new disks to your Traffic Server node, partition sizes specified in percentages will increase proportionately. </li>
+ <li>A lot of changes to partition sizes might result in disk fragmentation, which affects performance and hit rate. You should clear the cache before making many changes to cache partition sizes (refer to <a href="#ClearingCache">Clearing the Cache</a>).</li>
+</ul>
+<h3>Partitioning the Cache According to Origin Server or Domain</h3>
+<p>After you have partitioned the cache according to size and protocol, you can assign the partitions you created to specific origin servers and/or domains. You can assign a partition to a single origin server or to multiple origin servers. However, if a partition is assigned to multiple origin servers, then there is no guarantee on the space available in the partition for each origin server. Content is stored in the partition according to popularity. In addition to assigning partitions to specific origin servers and domains, you must assign a generic partition to store content from all origin servers and domains that are not listed. This generic partition is also used if the partitions for a particular origin server or domain become corrupt. If you do not assign a generic partition, then Traffic Server will run in proxy-only mode. </p>
+<p><strong>Note: </strong>You do <em>not</em> need to stop Traffic Server before you assign partitions 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 low traffic. </p>
+<h5>To partition the cache according to hostname and domain: </h5>
+<ol>
+ <li>Configure the cache partitions according to size and protocol, as described in <a href="#CreatingCachePartitionsSpecificProtocols">Creating Cache Partitions for Specific Protocols</a>. </li>
+ <li>Create a separate partition 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 partitions do not need to be the same size. </li>
+ <li>In a text editor, open the <code>hosting.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+ <li>Enter a line in the file to allocate the partition(s) used for each origin server and/or domain (refer to <a href="files.htm#139053">hosting.config</a>). </li>
+ <li>Assign a generic partition to use for content that does not belong to any of the origin servers or domains listed in the file. If all partitions for a particular origin server become corrupt, then Traffic Server will also use the generic partition to store content for that origin server (see <a href="files.htm#139053">hosting.config</a>). </li>
+ <li>Save and close the <code>hosting.config</code> file. </li>
+ <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
+ <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
+</ol>
+<h2 id="ConfiguringCacheObjectSizeLimit">Configuring the Cache Object Size Limit</h2>
+<p>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:</p>
+<ol>
+ <li>In a text editor, open the <code>records.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+ <li>Edit the following variable:<br />
+ <table width="1232" border="1">
+ <tr>
+ <th width="322" scope="col">Variable</th>
+ <th width="894" scope="col">Description</th>
+ </tr>
+ <tr>
+ <td><code><i>proxy.config.cache.max_doc_size</i></code></td>
+ <td>Set this variable to specify the maximum size allowed for objects in the cache in bytes.<br /> Enter <code>0</code> (zero) if you do not want a size limit.</td>
+ </tr>
+ </table>
+ </li>
+ <li>Save and close the <code>records.config</code> file. </li>
+ <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
+ <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
+</ol>
+<h2 id="ClearingCache">Clearing the Cache</h2>
+<p>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 cannot clear the cache when Traffic Server is running. </p>
+<h5>To clear the cache: </h5>
+<ol>
+ <li>Stop Traffic Server (refer to <a href="getstart.htm#StoppingTrafficEdge">Stopping Traffic Server</a>). </li>
+ <li>Enter the following command to clear the cache:<br /><code>traffic_server -Cclear</code><br />The <code>clear</code> command deletes all data in the object store and the host database. Traffic Server does not prompt you to confirm the deletion. </li>
+ <li>Restart Traffic Server (refer to <a href="getstart.htm#StartingTrafficEdge">Starting Traffic Server</a>).</li>
+</ol>
+<h2 id="InspectingCache">Inspecting the Cache</h2>
+<p>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 <i>all</i> the objects in your cache; therefore, make sure that only authorized administrators are allowed to access this utility. To control which hosts have access via the <code>mgmt_allow.config</code> file, see <a href="secure.htm#ControllingHostAccessTrafficManager">Controlling Host Access to Traffic Manager</a>. </p>
+<h3>Accessing the Cache Inspector Utility </h3>
+<p>To access the Cache Inspector utility, follow the steps below:</p>
+<ol>
+ <li>In a text editor, open the <code>records.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+ <li>Add the following variable at the end of the file:<br /><code><i>CONFIG proxy.config.http_ui_enabled INT 1</i></code></li>
+ <li>To access the cache inspector in reverse proxy mode, you must add a remap rule to <code>remap.config</code> to expose the URL. <br />
+ For example: <br />
+ <code>map http://yourhost.com/myCI http://{cache} @action=allow @src_ip=corp_internal_address</code></li>
+ <li>From the Traffic Server <code>bin</code> directory, enter the following command to re-read the configuration file:<br />
+ <code>traffic_line -x</code></li>
+ <li>Open your web browser and configure it to use your Traffic Server as a proxy server. Type the following URL:
+<br /><code>http://{cache}</code></li>
+ <li>The Cache page opens (see <a href="#UsingCachePage">Using the Cache Page</a> below).</li>
+</ol>
+<h3 id="UsingCachePage">Using the Cache Page </h3>
+<p>The <b>Cache page</b> provides several options that enable you to view and delete the contents of your cache: </p>
+<ul>
+ <li>Click <strong>Lookup url</strong> 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. </li>
+ <li>Click <strong>Delete url</strong> to delete a particular URL or list of URLs from the cache. Traffic Server indicates if a delete is successful. </li>
+ <li>Click <strong>Regex lookup</strong> to search for URLs that match one or more regular expressions. From the display page, you can delete the URLs listed.<br />
+ For example, enter the following to search for all URLs that end in html and are prefixed with <code>http://www.dianes.com: <br />
+ http://www.dianes.com/.*\.html$</code></li>
+ <li>Click <strong>Regex delete</strong> to delete all URLs that match a specified regular expression.<br /> For example, enter the following to delete all HTTP URLs that end in <code>html</code>: <br /><code>http://.*\.html$</code> </li>
+ <li>Click <strong>Regex invalidate</strong> 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. </li>
+</ul>
+<p><strong>Note:</strong> Only one administrator should delete and invalidate cache entries from the Cache page at any point in time. Changes made by multiple administrators at the same time can lead to unpredictable results.</p>
+
+</body>
</html>
\ No newline at end of file
Modified: incubator/trafficserver/site/trunk/docs/admin/reverse.htm
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/reverse.htm?rev=897017&r1=897016&r2=897017&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/admin/reverse.htm (original)
+++ incubator/trafficserver/site/trunk/docs/admin/reverse.htm Thu Jan 7 21:18:22 2010
@@ -1,193 +1,188 @@
-<html>
-<head>
-<title>Traffic Edge Administratorâs Guide</title>
-<meta content="text/html; charset=UTF-8" http-equiv="content-type"/>
-
-<link rel="stylesheet" href="doc.css" type="text/css" media="all" /></head>
-
-<body>
-<h1><a name="ReverseProxyHTTPRedirects"></a>Reverse Proxy and HTTP Redirects</h1>
-<p>As a reverse proxy cache, Traffic Server serves requests on behalf of origin servers. Traffic Server is configured in such a way that it appears to clients like a normal origin server.</p>
-<p>This chapter discusses the following topics: </p>
-<ul>
-<li><a href="#UnderstandingReverseProxyCaching"><em>Understanding Reverse Proxy Caching</em></a></li>
-<li><a href="#HTTPReverseProxy"><em>HTTP Reverse Proxy</em></a></li>
-<li><a href="#RedirectingHTTPRequests"><em>Redirecting HTTP Requests</em></a></li>
-</ul>
-<h2 id="UnderstandingReverseProxyCaching">Understanding Reverse Proxy Caching</h2>
-<p>With <i>forward proxy caching</i>, Traffic Server handles web requests to distant origin servers on behalf of the clients requesting the content. <em><b>Reverse proxy caching</b></em> (also known as <em>server acceleration</em> or <em>virtual web hosting</em>) 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 <em>the</em> origin server that the user is trying to connect to (in contrast to a typical scenario inwhich the advertised hostname of the origin server resolves to Traffic Server, which acts as the real origin server). </p>
-<h3>Reverse Proxy Solutions </h3>
-<p>There are many ways to use Traffic Server as a reverse proxy. Here are a few example scenarios. </p>
-<p>You can use Traffic Server in reverse proxy mode to: </p>
-<ul>
- <li>Offload heavily-used origin servers</li>
- <li>Deliver content efficiently in geographically-dispersed areas</li>
- <li>Provide security for origin servers that contain sensitive information </li>
-</ul>
-<h4>Offloading Heavily-Used Origin Servers </h4>
-<p>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 backup origin servers. For example, a web hoster can maintain a scalable Traffic Server serving engine and 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. </p>
-<p id="FigureTEReverseProxy"><img src="images/revproxy.jpg" width="852" height="508" /></p>
-<blockquote>
- <p><em><b>Traffic Server as reverse proxy for a pair of origin servers </b></em></p>
-</blockquote>
-<h4>Delivering Content in Geographically-Dispersed Areas </h4>
-<p>Traffic Server can be used in reverse proxy mode to accelerate origin servers that provide content to areas not located within close geographical proximity. Caches can be easier to manage and 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, where hardware must be configured to replicate all data and to handle peak capacity, Traffic Server dynamically adjusts to best utilize the serving and storing capacity of the hardware. Traffic Server is also designed to keep content fresh automatically, which eliminates the complexity of updating remote origin servers. </p>
-<h4>Providing Security for an Origin Server </h4>
-<p>Traffic Server can be used in reverse proxy mode to provide security for 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 <em>not</em> 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 to the origin server). The sensitive content resides on the origin server, safely inside the firewall. </p>
-<h3>How Does Reverse Proxy Work? </h3>
-<p>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 (ie, the origin serverâs <em>advertised</em> 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 <a href="#HTTPReverseProxy"><em>HTTP Reverse Proxy</em></a>.</p>
-<p><strong>Note:</strong> The origin serverâs hostname and its advertised hostname cannot be the same or there will be a DNS conflict. </p>
-<h2 id="HTTPReverseProxy">HTTP Reverse Proxy</h2>
-<p>In reverse proxy mode, Traffic Server serves HTTP requests on behalf of a web server. The figure below illustrates how Traffic Server in reverse proxy mode serves an HTTP request from a client browser. </p>
-<p><img src="images/httprvs.jpg" width="1035" height="403" /></p>
-<blockquote>
- <p><em><b>HTTP reverse proxy </b></em></p>
-</blockquote>
-<p>The figure above demonstrates the following steps: </p>
-<ol>
- <li>A client browser sends an HTTP request addressed to a host called <code>www.host.com</code> 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). </li>
- <li>Traffic Server locates a map rule in the <code>remap.config</code> file and remaps the request to the specified origin server (<code>realhost.com</code>). </li>
- <li>Traffic Server opens an HTTP connection to the origin server. </li>
- <li>If the request is a cache hit and the content is fresh, Traffic Server sends the requested object to the client from the cache; if not, Traffic Server obtains the requested object from the origin server, sends the object to the client and saves a copy in its cache. </li>
-</ol>
-<p>To configure HTTP reverse proxy, you must perform the following tasks: </p>
-<ul>
- <li>Create mapping rules in the remap.config file; refer to <a href="#CreatingMappingRulesHTTPRequests"><em>Creating Mapping Rules for HTTP Requests</em></a>. </li>
- <li>Enable the reverse proxy option; refer to <a href="#EnablingHTTPReverseProxy"><em>Enabling HTTP Reverse Proxy</em></a>. </li>
-</ul>
-<p>In addition to the tasks above, you can <a href="#SettingOptionalHTTPReverseProxyOptions"><em>Set Optional HTTP Reverse Proxy Options</em></a>. </p>
-<h3 id="CreatingMappingRulesHTTPRequests">Creating Mapping Rules for HTTP Requests </h3>
-<p>In forward proxy caching, Traffic Server acts as a proxy server and receives proxy requests. In reverse proxy caching, Traffic Server needs to act as an origin server rather than a proxy server - this means that it receives server requests and not proxy requests. Therefore, to satisfy proxy requests, Traffic Server must construct a proxy request from the server request. </p>
-<p>In HTTP, proxy requests specify the entire URL whereas server requests specify only the path. A server request might look like this:<br /><code>GET /index.html HTTP/1.0 Host: real.janes_books.com</code><br /><br />However, the corresponding proxy request would look like this: <br />
-<code>GET http://real.janes_books.com/index.html HTTP/1.0 Host: real.janes_books.com</code></p>
-<p>Traffic Server can construct a proxy request from a server request by using the server information in the host header. However, the correct proxy request must contain the hostname of the origin server, not the advertised hostname that the name servers associate to Traffic Server. The advertised hostname is the name that appears in the host header; for example, for the origin server <code>real.janes_books.com</code> in <a href="#FigureTEReverseProxy"><em>this figure</em></a>, the server request and host header would be:<br />
-<code>GET /index.html HTTP/1.0 Host: www.janes_books.com</code></p>
-And the correct proxy request should be <br /><code>GET http://real.janes_books.com/index.html HTTP/1.0 Host: real.janes_books.co</code> <br />
-<p>To translate <code>www.janes_books.com</code> to <code>real.janes_books.com</code>, Traffic Server needs a set of URL rewriting rules (mapping rules). Mapping rules are described in <a href="#UsingMappingRulesHTTPRequests"><em>Using Mapping Rules for HTTP Requests</em></a>.</p>
-<p>In general, use reverse proxy mode to support more than one origin server. In this case, all of the advertised hostnames resolve to the IP address or virtual IP address of Traffic Server. Using host headers, Traffic Server is able to translate server requests for any number of servers into proxy requests for those servers. If Traffic Server receives requests from older browsers that do not support host headers, then Traffic Server can either route these requests directly to a specific server or send the browser to a URL containing information about the problem; refer to <a href="#SettingOptionalHTTPReverseProxyOptions"><em>Setting Optional HTTP Reverse Proxy Options</em></a>. </p>
-<h4>Handling Origin Server Redirect Responses </h4>
-<p>Origin servers often send redirect responses (redirects) back to browsers, redirecting them to different pages; for example, if an origin server is overloaded, it might redirect browsers to a less loaded server. 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, not to another origin server. </p>
-<p>To readdress redirects, Traffic Server uses reverse-map rules. In general, you should set up a reverse-map rule for each map rule. To create reverse-map rules, refer to <a href="#UsingMappingRulesHTTPRequests"><em>Using Mapping Rules for HTTP Requests</em></a>. </p>
-<h4 id="UsingMappingRulesHTTPRequests">Using Mapping Rules for HTTP Requests </h4>
-<p>Traffic Server uses two types of mapping rules for HTTP reverse proxy: </p>
-<ul>
- <li>A <em><b>map rule</b></em> translates the URL in client requests into the URL where the content is located. When Traffic Server in reverse proxy mode receives an HTTP client request, it first constructs a complete request URL from the relative URL and its headers. Traffic Server then compares the complete request URL with its list of target URLs in the remap.config file, looking for a match. For the request URL to match a target URL, the following conditions must be true:
-<ul>
- <li>The scheme of both URLs must be the same</li>
- <li>The host in both URLs must be the same (if the request URL contains an unqualified hostname, it will never match a target URL with a fully qualified hostname).</li>
- <li>The ports in both URLs must be the same (if no port is specified in a URL, the default port for the scheme of the URL is used)</li>
- <li>The path portion of the target URL must match a prefix of the request URL path</li>
- </ul>
- If Traffic Server finds a match, it translates the request URL into the replacement URL listed in the map rule. It sets the host and path of the request URL to match the replacement URL. If the URL contains path prefixes, Traffic Server removes the prefix of the path that matches the target URL path and substitutes it with the path from the replacement URL. <br />
- If two mappings match a request URL, Traffic Server applies the first mapping listed in the <code>remap.config</code> file. </li>
- <li>A <em><b>reverse-map rule</b></em> translates the URL in origin server redirect responses to point to the Traffic Server so that clients are redirected to Traffic Server instead of accessing an origin server directly; for example, if there is a directory <code>/pub</code> on an origin server at <code>www.molasses.com</code> and a client sends a request to that origin server for <code>/pub</code>, the origin server might reply with a redirect to <code>http://www.test.com/pub/</code> 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.) <br />
- Traffic Server uses reverse-map rules to prevent redirects from origin servers from causing clients to bypass Traffic Server in favor of direct access to the origin servers. </li>
-</ul>
-<p>Both map and reverse-map rules consist of a <em>target</em> (origin) URL and a <em>replacement</em> (destination) URL. In a <em>map</em> rule, the target URL points to Traffic Server and the replacement URL specifies where the original content is located. In a <em>reverse-map</em> 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 <code>remap.config</code> file located in the Traffic Server <code>config</code> directory.</p>
-<h5>To create mapping rules: </h5>
-<ol>
- <li>In a text editor, open the <code>remap.config</code> file located in the Traffic Server <code>config</code> directory. </li>
- <li>Enter your map and reverse-map rules; refer to <a href="files.htm#232990"><em>remap.config</em></a>. </li>
- <li>Save and close the <code>remap.config</code> file. </li>
- <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
- <li>Run the command <code>traffic_line -x</code> to apply the configuration changes.</li>
-</ol>
-<h3 id="EnablingHTTPReverseProxy">Enabling HTTP Reverse Proxy </h3>
-<p>To enable HTTP reverse proxy, follow the steps below.</p>
-<ol>
- <li>In a text editor, open the <code>records.config</code> file located in the <code>config</code> directory. </li>
- <li>Edit the following variable:</li>
-<br />
-<table width="1232" border="1">
- <tr>
- <th width="322" scope="col">Variable</th>
- <th width="894" scope="col">Description</th>
- </tr>
- <tr>
- <td><code><i>proxy.config.reverse_proxy.enabled</i></code></td>
- <td>Set this variable to 1 to enable HTTP reverse proxy mode. </td>
- </tr>
-</table>
-<br />
- <li>Save and close the <code>records.config</code> file. </li>
- <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
- <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
-</ol>
-<h3 id="SettingOptionalHTTPReverseProxyOptions">Setting Optional HTTP Reverse Proxy Options </h3>
-<p>Traffic Server provides several configuration options for reverse proxy that enable you to: </p>
-<ul>
- <li>Configure Traffic Server to retain the client host header information in a request during translation</li>
- <li>Configure Traffic Server to serve requests only to the origin servers listed in the mapping rules; requests to origin servers not listed in the mapping rules are not served</li>
- <li>Specify an alternate URL, to which incoming requests from older clients that do not provide Host headers are directed</li>
-</ul>
-<h5>To set optional HTTP reverse proxy options: </h5>
-<ol>
- <li>In a text editor, open the <code>records.config</code> file located in the <code>config</code> directory. </li>
- <li>Edit the following variables:</li>
-<br />
-<table width="1232" border="1">
- <tr>
- <th width="322" scope="col">Variable</th>
- <th width="894" scope="col">Description</th>
- </tr>
- <tr>
- <td><code><i>proxy.config.url_remap.pristine_host_hdr</i></code></td>
- <td>Set this variable to 1 to retain the client host header in the request. <br />
- Set this variable to 0 (zero) if you want Traffic Server to translate the client host header.</td>
- </tr>
- <tr>
- <td><code><i>proxy.config.url_remap.remap_required</i></code></td>
- <td>Set this variable to 1 if you want Traffic Server to serve requests only to the origin servers listed in the mapping rules of the <code>remap.config</code> file. <br />
- Set this variable to 0 (zero) if you want Traffic Server to serve requests to all origin servers.</td>
- </tr>
- <tr>
- <td><code><i>proxy.config.header.parse.no_host_url_redirect</i></code></td>
- <td>Enter the URL to which to redirect requests with no host headers.</td>
- </tr>
-</table>
-<br />
- <li>Save and close the <code>records.config</code> file. </li>
- <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
- <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
-</ol>
-<h2 id="RedirectingHTTPRequests">Redirecting HTTP Requests</h2>
-<p>You can configure Traffic Server to redirect HTTP requests without having to contact any origin servers; for example, if you redirect all requests for <code>http://www.ultraseek.com</code> to <code>http://www.server1.com/products/portal/search/</code>, all HTTP requests for <code>www.ultraseek.com</code> go directly to <code>www.server1.com/products/portal/search</code>. </p>
-<p>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 <code><b>301</b></code>) 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 <b><code>307</code></b>).</p>
-<h5>To set redirect rules: </h5>
-<ol>
- <li>In a text editor, open the <code>remap.config</code> file located in the Traffic Server <code>config</code> directory. </li>
- <li>Enter a mapping rule for each redirect you want to set. Each mapping rule must be on a separate line and must consist of three space-delimited fields: <code>type</code>, <code>target</code>, and <code>replacement</code>. The following table describes the format for each field.<br />
-<br />
-<table width="1232" border="1">
- <tr>
- <th width="168" scope="col">Field</th>
- <th width="1048" scope="col">Description</th>
- </tr>
- <tr>
- <td><code>type</code></td>
- <td>Enter either one of the following: <br />
- <code>redirect</code>âredirects HTTP requests permanently without having to contact the origin server. <br />
- <code>redirect_temporary</code>âredirects HTTP requests temporarily without having to contact the origin server.</td>
- </tr>
- <tr>
- <td><code>target</code></td>
- <td>Enter the origin or from URL. You can enter up to four components: <br />
- <em><code>scheme://host:port/path_prefix</code></em></td>
- </tr>
- <tr>
- <td><code>replacement</code></td>
- <td>Enter the destination or to URL. You can enter up to four components: <br />
- <em><code>scheme://host:port/path_prefix</code></em></td>
- </tr>
-</table>
-<br />
-The following permanently redirects all HTTP requests for <code>www.server1.com</code> to <code>www.server2.com</code> <br />
-<code>redirect http://www.server1.com http://www.server2.com </code><br />
-<br />
- </li>
- <li>Save and close the <code>remap.config</code> file. </li>
- <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
- <li>Run the command <code>traffic_line -x</code> to apply the configuration changes.</li>
-</ol>
-</body>
+<html>
+<head>
+<title>Traffic Edge Administratorâs Guide</title>
+<meta content="text/html; charset=UTF-8" http-equiv="content-type"/>
+
+<link rel="stylesheet" href="doc.css" type="text/css" media="all" /></head>
+
+<body>
+<h1><a name="ReverseProxyHTTPRedirects"></a>Reverse Proxy and HTTP Redirects</h1>
+<p>As a reverse proxy cache, Traffic Server serves requests on behalf of origin servers. Traffic Server is configured in such a way that it appears to clients like a normal origin server.</p>
+<p>This chapter discusses the following topics: </p>
+<ul>
+<li><a href="#UnderstandingReverseProxyCaching">Understanding Reverse Proxy Caching</a></li>
+<li><a href="#HTTPReverseProxy">HTTP Reverse Proxy</a></li>
+<li><a href="#RedirectingHTTPRequests">Redirecting HTTP Requests</a></li>
+</ul>
+<h2 id="UnderstandingReverseProxyCaching">Understanding Reverse Proxy Caching</h2>
+<p>With <b>forward proxy caching</b>, Traffic Server handles web requests to distant origin servers on behalf of the clients requesting the content. <b>Reverse proxy caching</b> (also known as <b>server acceleration </b>or <b>virtual web hosting</b>) 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 <em>the</em> origin server that the user is trying to connect to (in contrast to a typical scenario inwhich the advertised hostname of the origin server resolves to Traffic Server, which acts as the real origin server). </p>
+<h3>Reverse Proxy Solutions </h3>
+<p>There are many ways to use Traffic Server as a reverse proxy. Below are a few example scenarios. </p>
+<p>You can use Traffic Server in reverse proxy mode to: </p>
+<ul>
+ <li>Offload heavily-used origin servers</li>
+ <li>Deliver content efficiently in geographically distant areas</li>
+ <li>Provide security for origin servers that contain sensitive information </li>
+</ul>
+<h4>Offloading Heavily-Used Origin Servers </h4>
+<p>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 backup origin servers. For example, a web hoster can maintain a scalable Traffic Server serving engine 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. </p>
+<p id="FigureTEReverseProxy"><img src="images/revproxy.jpg" width="852" height="508" /></p>
+<blockquote>
+ <p><em><b>Traffic Server as reverse proxy for a pair of origin servers </b></em></p>
+</blockquote>
+<h4>Delivering Content in Geographically-Dispersed Areas </h4>
+<p>Traffic Server can be used in reverse proxy mode to accelerate origin servers that provide content to areas not located within close 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 capacity, Traffic Server dynamically adjusts to best utilize the serving and storing capacity of the hardware. Traffic Server is also designed to keep content fresh automatically, thereby eliminating the complexity of updating remote origin servers. </p>
+<h4>Providing Security for an Origin Server </h4>
+<p>Traffic Server can be used in reverse proxy mode to provide security for 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 <em>not</em> 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 to the origin server). The sensitive content resides on the origin server, safely inside the firewall. </p>
+<h3>How Does Reverse Proxy Work? </h3>
+<p>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 (ie, 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 <a href="#HTTPReverseProxy">HTTP Reverse Proxy</a>.</p>
+<p><strong>Note:</strong> To avoid a DNS conflict, the origin serverâs hostname and its advertised hostname must not be the same. </p>
+<h2 id="HTTPReverseProxy">HTTP Reverse Proxy</h2>
+<p>In reverse proxy mode, Traffic Server serves HTTP requests on behalf of a web server. The figure below illustrates how Traffic Server in reverse proxy mode serves an HTTP request from a client browser. </p>
+<p><img src="images/httprvs.jpg" width="1035" height="403" /></p>
+<blockquote>
+ <p><em><b>HTTP reverse proxy </b></em></p>
+</blockquote>
+<p>The figure above demonstrates the following steps: </p>
+<ol>
+ <li>A client browser sends an HTTP request addressed to a host called <code>www.host.com</code> 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). </li>
+ <li>Traffic Server locates a map rule in the <code>remap.config</code> file and remaps the request to the specified origin server (<code>realhost.com</code>). </li>
+ <li>Traffic Server opens an HTTP connection to the origin server. </li>
+ <li>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. </li>
+</ol>
+<p>To configure HTTP reverse proxy, you must perform the following tasks: </p>
+<ul>
+ <li>Create mapping rules in the <code>remap.config</code> file (refer to <a href="#CreatingMappingRulesHTTPRequests">Creating Mapping Rules for HTTP Requests</a>). </li>
+ <li>Enable the reverse proxy option (refer to <a href="#EnablingHTTPReverseProxy">Enabling HTTP Reverse Proxy</a>). </li>
+</ul>
+<p>In addition to the tasks above, you can also <a href="#SettingOptionalHTTPReverseProxyOptions">Set Optional HTTP Reverse Proxy Options</a>. </p>
+<h3 id="CreatingMappingRulesHTTPRequests">Creating Mapping Rules for HTTP Requests </h3>
+<p>In forward proxy caching, Traffic Server acts as a proxy server and receives proxy requests. In reverse proxy caching, however, Traffic Server must act as an origin server rather than a proxy server - this means that it receives server requests and not proxy requests. Therefore, to satisfy proxy requests, Traffic Server must construct a proxy request from the server request. </p>
+<p>In HTTP, proxy requests specify the entire URL whereas server requests specify only the path. A server request might look like this:<br />
+<code>GET /index.html HTTP/1.0 Host: real.dianes_books.com</code><br /><br />However, the corresponding proxy request would look like this: <br />
+<code>GET http://real.dianes_books.com/index.html HTTP/1.0 Host: real.dianes_books.com</code></p>
+<p>Traffic Server can construct a proxy request from a server request by using the server information in the host header. However, the correct proxy request must contain the hostname of the origin server, not the advertised hostname that name servers associate to Traffic Server. The advertised hostname is the name that appears in the host header; for the origin server <code>real.dianes_books.com</code>, the server request and host header would be:<br />
+<code>GET /index.html HTTP/1.0 Host: www.dianes_books.com</code></p>
+And the correct proxy request should be <br />
+<code>GET http://real.dianes_books.com/index.html HTTP/1.0 Host: real.dianes_books.com</code> <br />
+<p>To translate <code>www.dianes_books.com</code> to <code>real.dianes_books.com</code>, Traffic Server needs a set of URL rewriting rules (mapping rules). Mapping rules are described in <a href="#UsingMappingRulesHTTPRequests">Using Mapping Rules for HTTP Requests</a>.</p>
+<p>In general, use reverse proxy mode to support more than one origin server. In this case, all of the advertised hostnames resolve to the IP address or virtual IP address of Traffic Server. Using host headers, Traffic Server is able to translate server requests for any number of servers into proxy requests for those servers. If Traffic Server receives requests from older browsers that do not support host headers, then Traffic Server can either route these requests directly to a specific server or send the browser to a URL containing information about the problem (refer to <a href="#SettingOptionalHTTPReverseProxyOptions">Setting Optional HTTP Reverse Proxy Options</a>). </p>
+<h4>Handling Origin Server Redirect Responses </h4>
+<p>Origin servers often send redirect responses back to browsers that 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 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 <i>not</i> to another origin server. </p>
+<p>To readdress redirects, Traffic Server uses reverse-map rules. In general, you should set up a reverse-map rule for each map rule. To create reverse-map rules, refer to <a href="#UsingMappingRulesHTTPRequests">Using Mapping Rules for HTTP Requests</a>. </p>
+<h4 id="UsingMappingRulesHTTPRequests">Using Mapping Rules for HTTP Requests </h4>
+<p>Traffic Server uses two types of mapping rules for HTTP reverse proxy: </p>
+<ul>
+ <li>A <b>map rule</b> 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 <code>remap.config </code>file. For the request URL to match a target URL, the following conditions must be true:
+ <ul>
+ <li>The scheme of both URLs must be the same</li>
+ <li>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.</li>
+ <li>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.</li>
+ <li>The path portion of the target URL must match a prefix of the request URL path</li>
+ </ul>
+ 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 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 <code>remap.config</code> file. </li> <br>
+ <li>A <b>reverse-map rule</b> 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 <code>/pub</code> on an origin server at <code>www.molasses.com</code> and a client sends a request to that origin server for <code>/pub</code>, then the origin server might reply with a redirect to <code>http://www.test.com/pub/</code> 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). <br />
+ Traffic Server uses reverse-map rules to prevent clients (that receive redirects from origin servers) from bypassing Traffic Server and directly accessing the origin servers. </li>
+</ul>
+<p>Both map and reverse-map rules consist of a <b>target</b> (origin) URL and a <b>replacement</b> (destination) URL. In a <b>map rule</b>, the target URL points to Traffic Server and the replacement URL specifies where the original content is located. In a <b>reverse-map rule</b>, 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 <code>remap.config</code> file located in the Traffic Server <code>config</code> directory.</p>
+<h5>To create mapping rules: </h5>
+<ol>
+ <li>In a text editor, open the <code>remap.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+ <li>Enter your map and reverse-map rules (refer to <a href="files.htm#232990">remap.config</a>). </li>
+ <li>Save and close the <code>remap.config</code> file. </li>
+ <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
+ <li>Run the command <code>traffic_line -x</code> to apply the configuration changes.</li>
+</ol>
+<h3 id="EnablingHTTPReverseProxy">Enabling HTTP Reverse Proxy </h3>
+<p>To enable HTTP reverse proxy, follow the steps below.</p>
+<ol>
+ <li>In a text editor, open the <code>records.config</code> file located in the <code>config</code> directory. </li>
+ <li>Edit the following variable:</li>
+ <table width="1232" border="1">
+ <tr>
+ <th width="322" scope="col">Variable</th>
+ <th width="894" scope="col">Description</th>
+ </tr>
+ <tr>
+ <td><code><i>proxy.config.reverse_proxy.enabled</i></code></td>
+ <td>Set this variable to 1 to enable HTTP reverse proxy mode. </td>
+ </tr>
+</table>
+ <li>Save and close the <code>records.config</code> file. </li>
+ <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
+ <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
+</ol>
+<h3 id="SettingOptionalHTTPReverseProxyOptions">Setting Optional HTTP Reverse Proxy Options </h3>
+<p>Traffic Server provides several reverse proxy configuration options that enable you to: </p>
+<ul>
+ <li>Configure Traffic Server to retain the client host header information in a request during translation</li>
+ <li>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.</li>
+ <li>Specify an alternate URL to which incoming requests from older clients (i.e., ones that do not provide <code>Host</code> headers) are directed</li>
+</ul>
+<h5>To set optional HTTP reverse proxy options: </h5>
+<ol>
+ <li>In a text editor, open the <code>records.config</code> file located in the <code>config</code> directory. </li>
+ <li>Edit the following variables:</li>
+ <table width="1232" border="1">
+ <tr>
+ <th width="322" scope="col">Variable</th>
+ <th width="894" scope="col">Description</th>
+ </tr>
+ <tr>
+ <td><code><i>proxy.config.url_remap.pristine_host_hdr</i></code></td>
+ <td>Set this variable to 1 to retain the client host header in the request. <br />
+ Set this variable to 0 (zero) if you want Traffic Server to translate the client host header.</td>
+ </tr>
+ <tr>
+ <td><code><i>proxy.config.url_remap.remap_required</i></code></td>
+ <td>Set this variable to 1 if you want Traffic Server to serve requests only to the origin servers listed in the mapping rules of the <code>remap.config</code> file. <br />
+ Set this variable to 0 (zero) if you want Traffic Server to serve requests to all origin servers.</td>
+ </tr>
+ <tr>
+ <td><code><i>proxy.config.header.parse.no_host_url_redirect</i></code></td>
+ <td>Enter the URL to which to redirect requests with no host headers.</td>
+ </tr>
+</table>
+ <li>Save and close the <code>records.config</code> file. </li>
+ <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
+ <li>Run the command <code>traffic_line -x</code> to apply the configuration changes. </li>
+</ol>
+<h2 id="RedirectingHTTPRequests">Redirecting HTTP Requests</h2>
+<p>You can configure Traffic Server to redirect HTTP requests without having to contact any origin servers. For example, if you redirect all requests for <code>http://www.ultraseek.com</code> to <code>http://www.server1.com/products/portal/search/</code>, then all HTTP requests for <code>www.ultraseek.com</code> go directly to <code>www.server1.com/products/portal/search</code>. </p>
+<p>You can configure Traffic Server to perform permanent or temporary redirects. <b>Permanent redirects</b> notify the browser of the URL change (by returning the HTTP status code <code><b>301</b></code>) so that the browser can update bookmarks. <b>Temporary redirects </b>notify the browser of the URL change for the current request only (by returning the HTTP status code <b><code>307</code></b>).</p>
+<h5>To set redirect rules: </h5>
+<ol>
+ <li>In a text editor, open the <code>remap.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+ <li>Enter a mapping rule for each redirect you want to set. Each mapping rule must be on a separate line and must consist of three space-delimited fields: <code>type</code>, <code>target</code>, and <code>replacement</code>. The following table describes the format for each field.<br />
+ <table width="1232" border="1">
+ <tr>
+ <th width="168" scope="col">Field</th>
+ <th width="1048" scope="col">Description</th>
+ </tr>
+ <tr>
+ <td><code>type</code></td>
+ <td>Enter either one of the following: <br />
+ <code>redirect</code>âredirects HTTP requests permanently without having to contact the origin server. <br />
+ <code>redirect_temporary</code>âredirects HTTP requests temporarily without having to contact the origin server.</td>
+ </tr>
+ <tr>
+ <td><code>target</code></td>
+ <td>Enter the origin or from URL. You can enter up to four components: <br />
+ <em><code>scheme://host:port/path_prefix</code></em></td>
+ </tr>
+ <tr>
+ <td><code>replacement</code></td>
+ <td>Enter the destination or to URL. You can enter up to four components: <br />
+ <em><code>scheme://host:port/path_prefix</code></em></td>
+ </tr>
+</table>
+ The following permanently redirects all HTTP requests for <code>www.server1.com</code> to <code>www.server2.com</code> :<br />
+<code>redirect http://www.server1.com http://www.server2.com </code><br />
+<br />
+ </li>
+ <li>Save and close the <code>remap.config</code> file. </li>
+ <li>Navigate to the Traffic Server <code>bin</code> directory. </li>
+ <li>Run the command <code>traffic_line -x</code> to apply the configuration changes.</li>
+</ol>
+</body>
</html>
\ No newline at end of file