trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From andrew...@apache.org
Subject svn commit: r831152 [6/37] - in /incubator/trafficserver/site/trunk/docs: ./ admin/ admin/images/ sdk/ sdk/css/ sdk/images/ sdk/images/docbook/ sdk/js/
Date Thu, 29 Oct 2009 23:23:36 GMT
Added: incubator/trafficserver/site/trunk/docs/admin/logfmts.htm
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/logfmts.htm?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/admin/logfmts.htm (added)
+++ incubator/trafficserver/site/trunk/docs/admin/logfmts.htm Thu Oct 29 23:23:25 2009
@@ -0,0 +1,463 @@
+<html>
+  <head>
+    <title>Event Logging Formats</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="31386">Appendix D - Event Logging Formats</a>
+  </h1>
+
+     <p>       This appendix contains the following sections:      </p>
+<ul>
+<li><a href="#66912"><em>Custom Logging Fields</em></a> provides descriptions of  logging fields.</li>
+<li><a href="#63460"><em>Logging Format Cross-Reference</em></a> provides cross-references between Trafic Server logging fields and Netscape &amp; Squid logging fields (including Netscape Extended and Extended-2 fields).</li>
+</ul>            
+        
+     <h2>
+     <a name="66912"> Custom Logging Fields</a>     </h2>
+     <p>       The following table describes Traffic Server custom logging fields.  </p>
+     <table border="1">
+       <tr>
+         <th> <p> %&lt;field symbol&gt;</p></th>
+         <th> <p> Description</p></th>
+       </tr>
+       <tr>
+         <td><p> {HTTP header field name}cqh</p></td>
+         <td><p> Logs the information in the requested field of the client request HTTP header; for example, <code> %&lt;{Accept-Language}cqh&gt;</code> logs the Accept-Language: field in client request headers. </p></td>
+       </tr>
+       <tr>
+         <td><p> {HTTP header field name}pqh</p></td>
+         <td><p> Logs the information in the requested field of the proxy request HTTP header; for example, <code> %&lt;{Authorization}pqh&gt;</code> logs the Authorization: field in proxy request headers. </p></td>
+       </tr>
+       <tr>
+         <td><p> {HTTP header field name}psh</p></td>
+         <td><p> Logs the information in the requested field of the proxy response HTTP header; for example, <code> %&lt;{Retry-After}psh&gt;</code> logs the Retry-After: field in proxy response headers. </p></td>
+       </tr>
+       <tr>
+         <td><p> {HTTP header field name}ssh</p></td>
+         <td><p> Logs the information in the requested field of the server response HTTP header; for example, <code> %&lt;{Age}ssh&gt;</code> logs the Age: field in server response headers. </p></td>
+       </tr>
+       <tr>
+         <td><p> band</p></td>
+         <td><p> The bandwidth of data sent to the client player.</p></td>
+       </tr>
+       <tr>
+         <td><p> caun</p></td>
+         <td><p> The client authenticated username; result of the RFC931/ident lookup of the client username.</p></td>
+       </tr>
+       <tr>
+         <td><p> cfsc</p></td>
+         <td><p> The client finish status code; specifies whether the client request to Traffic Server was successfully completed (FIN) or interrupted (INTR).</p></td>
+       </tr>
+       <tr>
+         <td><p> chi</p></td>
+         <td><p> The IP address of the client's host machine.</p></td>
+       </tr>
+       <tr>
+         <td><p> cqbl</p></td>
+         <td><p> The client request transfer length; the body length in the client request to Traffic Server in bytes.</p></td>
+       </tr>
+       <tr>
+         <td><p> cqhl</p></td>
+         <td><p> The client request header length; the header length in the client request to Traffic Server.</p></td>
+       </tr>
+       <tr>
+         <td><p> cqhm</p></td>
+         <td><p> The HTTP method in the client request to Traffic Server: GET, POST, and so on (subset of cqtx).</p></td>
+       </tr>
+       <tr>
+         <td><p> cqhv</p></td>
+         <td><p> The client request HTTP version.</p></td>
+       </tr>
+       <tr>
+         <td><p> cqtd</p></td>
+         <td><p> The client request timestamp; specifies the date of the client request in the format yyyy-mm-dd, where yyyy is the 4-digit year, mm is the 2-digit month, and dd is the 2-digit day.</p></td>
+       </tr>
+       <tr>
+         <td><p> cqtn</p></td>
+         <td><p> The client request timestamp; date and time of the client's request (in the Netscape timestamp format).</p></td>
+       </tr>
+       <tr>
+         <td><p> cqtq</p></td>
+         <td><p> The client request timestamp with millisecond resolution.</p></td>
+       </tr>
+       <tr>
+         <td><p> cqts</p></td>
+         <td><p> The client-request timestamp in Squid format; the time of the client request in seconds since January 1, 1970 UTC (with millisecond resolution).</p></td>
+       </tr>
+       <tr>
+         <td><p> cqtt</p></td>
+         <td><p> The client request timestamp; the time of the client request in the format hh:mm:ss, where hh is the two-digit hour in 24-hour format, mm is the two-digit minutes, and ss is the 2-digit seconds; for example, 16:01:19.</p></td>
+       </tr>
+       <tr>
+         <td><p> cqtx</p></td>
+         <td><p> The full HTTP client request text, minus headers; for example, </p>
+             <p> <code> GET http://www.company.com HTTP/1.0</code> </p>
+           <p> In reverse proxy mode, Traffic Server logs the rewritten (mapped) URL (according to the rules in the <code> remap.config</code> file), <em CLASS="Emphasis"> not</em> the pristine (unmapped) URL. To configure Traffic Server to log the original, unmapped URL, set the variable <code> proxy.config.url_remap.pristine_host_hdr</code> in the <code> records.config</code> file to <code> 1</code> .</p></td>
+       </tr>
+       <tr>
+         <td><p> cqu</p></td>
+         <td><p> The universal resource identifier (URI) of the request from client to Traffic Server (subset of <code> cqtx</code> ).</p>
+             <p> In reverse proxy mode, Traffic Server logs the rewritten (mapped) URL (according to the rules in the <code> remap.config</code> file), <em CLASS="Emphasis"> not</em> the pristine (unmapped) URL. To configure Traffic Server to log the original, unmapped URL, set the variable <code> proxy.config.url_remap.pristine_host_hdr</code> in the <code> records.config</code> file to <code> 1</code> .</p></td>
+       </tr>
+       <tr>
+         <td><p> cquc</p></td>
+         <td><p> The client request canonical URL; differs from cqu in that blanks (and other characters that might not be parsed by log analysis tools) are replaced by escape sequences. The escape sequence is a percentage sign followed by the ASCII code number in hex.</p>
+             <p> In reverse proxy mode, Traffic Server logs the rewritten (mapped) URL (according to the rules in the <code> remap.config</code> file), <em CLASS="Emphasis"> not</em> the pristine (unmapped) URL. To configure Traffic Server to log the original, unmapped URL, set the variable <code> proxy.config.url_remap.pristine_host_hdr</code> in the <code> records.config</code> file to <code> 1</code> .</p></td>
+       </tr>
+       <tr>
+         <td><p> cqup</p></td>
+         <td><p> The client request URL path; specifies the argument portion of the URL (everything after the host); for example, if the URL is <br />
+                 <code> http://www.company.com/images/x.gif</code> , then this field displays <code> /images/x.gif</code> .</p></td>
+       </tr>
+       <tr>
+         <td><p> cqus</p></td>
+         <td><p> The client request URL scheme.</p></td>
+       </tr>
+       <tr>
+         <td><p> cquuc</p></td>
+         <td><p> The client request unmapped URL canonical. This field records a URL before it is remapped (reverse proxy mode).</p></td>
+       </tr>
+       <tr>
+         <td><p> crc</p></td>
+         <td><p> The cache result code; specifies how the cache responded to the request (HIT, MISS, and so on).</p></td>
+       </tr>
+       <tr>
+         <td><p> fsiz</p></td>
+         <td><p> The size of the file, in bytes, as seen by the origin server. </p>
+             <p> Windows Media Player sees a smaller size in the case of multibitrate clips.</p></td>
+       </tr>
+       <tr>
+         <td><p> pfsc</p></td>
+         <td><p> The proxy finish status code; specifies whether the Traffic Server request to the origin server was successfully completed (FIN) or interrupted (INTR).</p></td>
+       </tr>
+       <tr>
+         <td><p> phn</p></td>
+         <td><p> The hostname of the Traffic Server that generated the log entry in collated log files.</p></td>
+       </tr>
+       <tr>
+         <td><p> phr</p></td>
+         <td><p> The proxy hierarchy route; the route that Traffic Server used to retrieve the object.</p></td>
+       </tr>
+       <tr>
+         <td><p> pqbl</p></td>
+         <td><p> The proxy request transfer length; the body length in the Traffic Server request to the origin server.</p></td>
+       </tr>
+       <tr>
+         <td><p> pqhl</p></td>
+         <td><p> The proxy request header length; the header length in the Traffic Server request to the origin server.</p></td>
+       </tr>
+       <tr>
+         <td><p> pqsi</p></td>
+         <td><p> The proxy request server IP address (0 on cache hits and parent-ip for requests to parent proxies).</p></td>
+       </tr>
+       <tr>
+         <td><p> pqsn</p></td>
+         <td><p> The proxy request server name; the name of the server that fulfilled the request. </p></td>
+       </tr>
+       <tr>
+         <td><p> prcb</p></td>
+         <td><p> The number of proxy response bytes to the client from the cache.</p></td>
+       </tr>
+       <tr>
+         <td><p> prob</p></td>
+         <td><p> The number of proxy response bytes to the client from the origin server.</p></td>
+       </tr>
+       <tr>
+         <td><p> pscl</p></td>
+         <td><p> The length of the Traffic Server response to the client in bytes.</p></td>
+       </tr>
+       <tr>
+         <td><p> psct</p></td>
+         <td><p> The content type of the document from server response header: for example, <code> img</code> /<code> gif</code> .</p></td>
+       </tr>
+       <tr>
+         <td><p> pshl</p></td>
+         <td><p> The header length in the Traffic Server response to the client.</p></td>
+       </tr>
+       <tr>
+         <td><p> psql</p></td>
+         <td><p> The proxy response transfer length in Squid format (includes header and content length).</p></td>
+       </tr>
+       <tr>
+         <td><p> pssc</p></td>
+         <td><p> The HTTP response status code from Traffic Server to the client.</p></td>
+       </tr>
+       <tr>
+         <td><p> shi</p></td>
+         <td><p> The IP address resolved from the DNS name lookup of the host in the request. For hosts with multiple IP addresses, this field records the IP address resolved from that particular DNS lookup. This can be misleading for cached documents; for example, if the first request was a cache miss and came from IP1 for server S and the second request for server S resolved to IP2 but came from the cache, the log entry for the second request will show IP2.</p></td>
+       </tr>
+       <tr>
+         <td><p> shn</p></td>
+         <td><p> The hostname of the origin server.</p></td>
+       </tr>
+       <tr>
+         <td><p> sscl</p></td>
+         <td><p> The response length, in bytes, from origin server to Traffic Server.</p></td>
+       </tr>
+       <tr>
+         <td><p> sshl </p></td>
+         <td><p> The header length in the origin server response to Traffic Server, in bytes.</p></td>
+       </tr>
+       <tr>
+         <td><p> sshv</p></td>
+         <td><p> The server response HTTP version (1.0, 1.1, and so on).</p></td>
+       </tr>
+       <tr>
+         <td><p> sssc</p></td>
+         <td><p> The HTTP response status code from origin server to Traffic Server.</p></td>
+       </tr>
+       <tr>
+         <td><p> ttms</p></td>
+         <td><p> The time Traffic Server spends processing the client request; the number of milliseconds between the time that the client establishes the connection with Traffic Server and the time that Traffic Server sends the last byte of the response back to the client.</p></td>
+       </tr>
+       <tr>
+         <td><p> ttmsf</p></td>
+         <td><p> The time Traffic Server spends processing the client request as a fractional number of seconds; specifies the time in millisecond resolution, but instead of formatting the output as an integer (as with ttms), the display is formatted as a floating-point number representing a fractional number of seconds; for example, if the time is 1500 milliseconds, this field displays 1.5 while the ttms field displays 1500 and the tts field displays 1.</p></td>
+       </tr>
+       <tr>
+         <td><p> tts</p></td>
+         <td><p> The time Traffic Server spends processing the client request; the number of seconds between the time that the client establishes the connection with Traffic Server and the time that Traffic Server sends the last byte of the response back to the client.</p></td>
+       </tr>
+     </table>
+  <h2><a name="63460">Logging Format Cross-Reference</a> </h2>
+  <p>        The following sections illustrate the correspondence between Traffic Server logging fields and standard logging fields for the Squid and Netscape formats. </p>
+     <h3>
+        <a name="67310">Squid Logging Formats</a>     </h3>
+  <p>       The following table lists the Squid logging fields and the corresponding  logging field symbols. </p>
+  <table border="1">
+        <tr>
+          <TH ROWSPAN="1" colspan="1"> <p> Squid</P></TH>
+          <TH ROWSPAN="1" colspan="1"> <p>  Field Symbols</P></TH>
+        </tr>
+        <tr>
+          <td><p> time</P></td>
+          <td><p> cqts</P></td>
+        </tr>
+        <tr>
+          <td><p> elapsed</P></td>
+          <td><p> ttms</P></td>
+        </tr>
+        <tr>
+          <td><p> client</P></td>
+          <td><p> chi</P></td>
+        </tr>
+        <tr>
+          <td><p> action/code </P></td>
+          <td><p> crc/pssc</P></td>
+        </tr>
+        <tr>
+          <td><p> size</P></td>
+          <td><p> psql</P></td>
+        </tr>
+        <tr>
+          <td><p> method</P></td>
+          <td><p> cqhm</P></td>
+        </tr>
+        <tr>
+          <td><p> url</P></td>
+          <td><p> cquc</P></td>
+        </tr>
+        <tr>
+          <td><p> ident</P></td>
+          <td><p> caun</P></td>
+        </tr>
+        <tr>
+          <td><p> hierarchy/from</P></td>
+          <td><p> phr/pqsn</P></td>
+        </tr>
+        <tr>
+          <td><p> content</P></td>
+          <td><p> psct</P></td>
+        </tr>
+      </table>
+     <h3>
+        <a name="68220">Netscape Common Logging Formats</a>      </h3>
+  <p>       The following table lists the Netscape Common logging fields and the corresponding Traffic Server logging field symbols. </p>
+      <table border="1">
+        <tr>
+          <TH ROWSPAN="1" colspan="1"> <p> Netscape Common</P></TH>
+          <TH ROWSPAN="1" colspan="1"> <p>  Field Symbols</P></TH>
+        </tr>
+        <tr>
+          <td><p> host</P></td>
+          <td><p> chi</P></td>
+        </tr>
+        <tr>
+          <td><p> usr</P></td>
+          <td><p> caun</P></td>
+        </tr>
+        <tr>
+          <td><p> [time]</P></td>
+          <td><p> [cqtn]</P></td>
+        </tr>
+        <tr>
+          <td><p> &quot;req&quot;</P></td>
+          <td><p> &quot;cqtx&quot;</P></td>
+        </tr>
+        <tr>
+          <td><p> s1</P></td>
+          <td><p> pssc</P></td>
+        </tr>
+        <tr>
+          <td><p> c1</P></td>
+          <td><p> pscl</P></td>
+        </tr>
+      </table>
+      <h3>
+        <a name="67697">Netscape Extended Logging Formats</a>      </h3>
+  <p>       The following table lists the Netscape Extended logging fields and the corresponding  Traffic Server logging field symbols. </p>
+      <table border="1">
+        <tr>
+          <TH ROWSPAN="1" colspan="1"> <p> Netscape Extended</P></TH>
+          <TH ROWSPAN="1" colspan="1"> <p>  Field Symbols </P></TH>
+        </tr>
+        <tr>
+          <td><p> host</P></td>
+          <td><p> chi</P></td>
+        </tr>
+        <tr>
+          <td><p> usr</P></td>
+          <td><p> caun</P></td>
+        </tr>
+        <tr>
+          <td><p> [time]</P></td>
+          <td><p> [cqtn]</P></td>
+        </tr>
+        <tr>
+          <td><p> &quot;req&quot;</P></td>
+          <td><p> &quot;cqtx&quot;</P></td>
+        </tr>
+        <tr>
+          <td><p> s1</P></td>
+          <td><p> pssc</P></td>
+        </tr>
+        <tr>
+          <td><p> c1</P></td>
+          <td><p> pscl</P></td>
+        </tr>
+        <tr>
+          <td><p> s2</P></td>
+          <td><p> sssc</P></td>
+        </tr>
+        <tr>
+          <td><p> c2</P></td>
+          <td><p> sscl</P></td>
+        </tr>
+        <tr>
+          <td><p> b1</P></td>
+          <td><p> cqbl</P></td>
+        </tr>
+        <tr>
+          <td><p> b2</P></td>
+          <td><p> pqbl</P></td>
+        </tr>
+        <tr>
+          <td><p> h1</P></td>
+          <td><p> cqhl</P></td>
+        </tr>
+        <tr>
+          <td><p> h2</P></td>
+          <td><p> pshl</P></td>
+        </tr>
+        <tr>
+          <td><p> h3</P></td>
+          <td><p> pqhl</P></td>
+        </tr>
+        <tr>
+          <td><p> h4</P></td>
+          <td><p> sshl</P></td>
+        </tr>
+        <tr>
+          <td><p> xt</P></td>
+          <td><p> tts</P></td>
+        </tr>
+      </table>
+      <h3>
+        <a name="63658">Netscape Extended-2 Logging Formats</a>      </h3>
+  <p>       The following table lists the Netscape Extended-2 logging fields and the corresponding  Traffic Server logging field symbols.</p>
+  <table border="1">
+    <tr>
+      <TH ROWSPAN="1" colspan="1"> <p> Netscape Extended-2</P></TH>
+      <TH ROWSPAN="1" colspan="1"> <p>  Field Symbols</P></TH>
+    </tr>
+    <tr>
+      <td><p> host</P></td>
+      <td><p> chi</P></td>
+    </tr>
+    <tr>
+      <td><p> usr</P></td>
+      <td><p> caun</P></td>
+    </tr>
+    <tr>
+      <td><p> [time]</P></td>
+      <td><p> [cqtn]</P></td>
+    </tr>
+    <tr>
+      <td><p> &quot;req&quot;</P></td>
+      <td><p> &quot;cqtx&quot;</P></td>
+    </tr>
+    <tr>
+      <td><p> s1</P></td>
+      <td><p> pssc</P></td>
+    </tr>
+    <tr>
+      <td><p> c1</P></td>
+      <td><p> pscl</P></td>
+    </tr>
+    <tr>
+      <td><p> s2</P></td>
+      <td><p> sssc</P></td>
+    </tr>
+    <tr>
+      <td><p> c2</P></td>
+      <td><p> sscl</P></td>
+    </tr>
+    <tr>
+      <td><p> b1</P></td>
+      <td><p> cqbl</P></td>
+    </tr>
+    <tr>
+      <td><p> b2</P></td>
+      <td><p> pqbl</P></td>
+    </tr>
+    <tr>
+      <td><p> h1</P></td>
+      <td><p> cqhl</P></td>
+    </tr>
+    <tr>
+      <td><p> h2</P></td>
+      <td><p> pshl</P></td>
+    </tr>
+    <tr>
+      <td><p> h3</P></td>
+      <td><p> pqhl</P></td>
+    </tr>
+    <tr>
+      <td><p> h4</P></td>
+      <td><p> sshl</P></td>
+    </tr>
+    <tr>
+      <td><p> xt</P></td>
+      <td><p> tts</P></td>
+    </tr>
+    <tr>
+      <td><p> route</P></td>
+      <td><p> phr</P></td>
+    </tr>
+    <tr>
+      <td><p> pfs</P></td>
+      <td><p> cfsc</P></td>
+    </tr>
+    <tr>
+      <td><p> ss</P></td>
+      <td><p> pfsc</P></td>
+    </tr>
+    <tr>
+      <td><p> crc</P></td>
+      <td><p> crc</P></td>
+    </tr>
+  </table>
+  <p>&nbsp; </p>
+</body>
+</html>
\ No newline at end of file

Propchange: incubator/trafficserver/site/trunk/docs/admin/logfmts.htm
------------------------------------------------------------------------------
    svn:executable = *

Added: incubator/trafficserver/site/trunk/docs/admin/monitor.htm
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/monitor.htm?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/admin/monitor.htm (added)
+++ incubator/trafficserver/site/trunk/docs/admin/monitor.htm Thu Oct 29 23:23:25 2009
@@ -0,0 +1,56 @@
+<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>Monitoring Traffic</h1>
+<p>Traffic Server provides several options for monitoring system performance and analyzing network traffic.</p>
+<p>This chapter discusses the following topics:</p>
+<ul>
+<li><a href="#TrafficEdgeMonitoringTools"><em>Traffic Server Monitoring Tools</em></a></li>
+<li><a href="#WorkingTrafficManagerAlarms"><em>Working with Traffic Manager Alarms</em></a></li>
+<li><a href="#ViewingStatisticsTrafficLine"><em>Viewing Statistics from Traffic Line</em></a></li> 
+</ul>
+<h2 id="TrafficEdgeMonitoringTools">Traffic Server Monitoring Tools</h2>
+<p> Traffic Server provides the following tools to monitor system performance and analyze network traffic:</p>
+<ul>
+ <li>Traffic Server  can send email that's triggered by alarms that signal any detected failure conditions; refer to <a href="#WorkingTrafficManagerAlarms"><em>Working with Traffic Manager Alarms</em></a>.</li>
+ <li>The Traffic Line command-line interface provides an alternative method of viewing Traffic Server performance and network traffic information; refer to <a href="#ViewingStatisticsTrafficLine"><em>Viewing Statistics from Traffic Line</em></a>.</li>
+ <li>The Traffic Shell command-line tool provides yet another alternative method of viewing Traffic Server performance and network traffic information; refer to <a href="getstart.htm#StartingTrafficShell"><em>Starting Traffic Shell</em></a>. </li>
+</ul>
+<h2 id="WorkingTrafficManagerAlarms">Working with Traffic Manager Alarms</h2>
+<p>Traffic Server signals an alarm when it detects a problem; for example, the space allocated to event logs could be full or Traffic Server may not be able to write to a configuration file.</p>
+<h3>Configuring Traffic Server to Email Alarms</h3>
+<p>To configure Traffic Server to send an email to a specific address whenever an alarm occurs, 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>Set the  <code><i>proxy.config.alarm_email</i></code> variable to the email address alarms will be routed to.</li>
+  <li>Save and close the <code>records.config</code> file.</li>
+  <li>Navigate to the Traffic Server <code>bin</code> directory. <br />
+  </li>
+  <li>Run the command <code>traffic_line -x</code> to apply the configuration changes.</li>
+</ol>
+<h3>Using a Script File for Alarms</h3>
+<p>Alarm messages are built into Traffic Server - you cannot change them. However, you can write a script file to execute certain actions when an alarm is signaled. Traffic Server provides a sample script file named <code>example_alarm_bin.sh</code> in the <code>bin</code> directory; simply modify the file to suit your needs.</p>
+<h2 id="ViewingStatisticsTrafficLine">Viewing Statistics from Traffic Line</h2>
+<p>As an alternative to using Traffic Manager, you can use the Traffic Line command-line interface to view statistics about Traffic Server performance and web traffic. Traffic Line provides a quick way of viewing Traffic Server statistics via command-line interface. In addition to viewing statistics, you can also configure, stop, and restart the Traffic Server system. For additional information, refer to <a href="configure.htm#ConfiguringTrafficEdgeUsingTrafficLine"><em>Configuring Traffic Server Using Traffic Line</em></a> and <em><a href="cli.htm">Traffic Line Commands</a></em>.  You can view specific information about a Traffic Server node or cluster by specifying the variable that corresponds to the statistic you want to see.
+</p>
+<h5>To view a statistic:</h5>
+<ol>
+ <li>Log on to a Traffic Server node as the Traffic Server administrator;   navigate to the Traffic Server <code>bin</code> directory. <br />
+ </li>
+ <li>Enter the following command: <br />
+ <code>traffic_line -r <em>variable</em></code><br />
+ where <em><code>variable</code></em> is the variable  representing the information you want to view. For a list of  variables you can specify, refer to <a href="cli.htm#1025718"><em>Traffic Line Variables</em></a>. <br /> <br />
+ For example, the following command displays the document hit rate for the Traffic Server node: <br />
+ <code>traffic_line -r proxy.node.http.cache_hit_ratio</code><br />
+ <br />
+ If the Traffic Server <code>bin</code> directory is not in your path, then prepend the Traffic Line command with <code>./</code> (for example: <code>./traffic_line -r <em>variable</em></code>).</li>
+</ol>
+
+
+</body>
+</html>
\ No newline at end of file

Propchange: incubator/trafficserver/site/trunk/docs/admin/monitor.htm
------------------------------------------------------------------------------
    svn:executable = *

Added: incubator/trafficserver/site/trunk/docs/admin/preface.htm
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/preface.htm?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/admin/preface.htm (added)
+++ incubator/trafficserver/site/trunk/docs/admin/preface.htm Thu Oct 29 23:23:25 2009
@@ -0,0 +1,55 @@
+<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>Preface</h1>
+<p>This manual describes how to use and configure Traffic Server<sup><font size="-1"></font></sup>. </p>
+<p>For information about installing Traffic Server, refer to the <em>Traffic Server Installation Guide</em>. For information about unsupported features and last-minute information not available in this manual, refer to the <em>Release Notes</em>.  The <i>Administrator's Guide</i> covers the following topics: </p>
+<ul>
+  <li><a href="intro.htm"><em>Chapter 1</em></a> provides an overview of Traffic Server features and components. </li>
+  <li><a href="getstart.htm"><em>Chapter 2</em></a> through <a href="log.htm"><em>Chapter 11</em></a> provide procedural information about starting, monitoring, configuring, and maintaining Traffic Server. </li>
+  <li><a href="stats.htm"><em>Appendix A</em></a> through <a href="errors.htm"><em>Appendix F</em></a> provide Traffic Server reference information. </li>
+  <li><a href="trouble.htm"><em>Appendix G</em></a> discusses frequently asked questions (FAQs) and provides troubleshooting tips. </li>
+  <li>The <a href="Glossary.htm"><em>Glossary</em></a> defines terminology related to and used throughout this manual.</li>
+</ul>
+<h2>Who Should Read This Manual</h2>
+<p>This manual is intended for Traffic Server system administrators who configure, run, and administer Traffic Server systems. To use this manual, you should understand web proxy caching, TCP/IP network protocols, network administration and management, and the Linux operating system. </p>
+<h2>Conventions Used in This Manual </h2>
+<p>This manual uses the following typographic conventions.</p>
+<table width="993" border="1">
+  <tr>
+    <th width="154" scope="col">Convention</th>
+    <th width="711" scope="col">Purpose</th>
+  </tr>
+  <tr>
+    <td><em>italic</em></td>
+    <td>Represents emphasis and introduces terms: for example, “the <em>reverse proxy</em> option.”   </td>
+  </tr>
+  <tr>
+    <td><strong>bold</strong></td>
+    <td>Represents graphical user interface options and menu names: for example, click the <strong>Protocols</strong> button.</td>
+  </tr>
+  <tr>
+    <td><pre>monospaced face</pre></td>
+    <td>Represents commands, filenames, file content, and computer input and output: for example, “use the <code>reconfigure</code> command.”</td>
+  </tr>
+  <tr>
+    <td><pre><em>monospaced italic</em></pre></td>
+    <td>Represents variables for which you should substitute a value: for example, “enter <code>filename</code>.” </td>
+  </tr>
+  <tr>
+    <td>brackets [ ]</td>
+    <td>Enclose optional command arguments in command syntax: for example, <code>add <em>pathname</em> [<em>size</em>]</code>. </td>
+  </tr>
+  <tr>
+    <td>vertical line |</td>
+    <td>Separates value options in command syntax: for example, <code>open tcp|udp ports <em>o_ports</em></code>.</td>
+  </tr>
+</table>
+
+</body>
+</html>
\ No newline at end of file

Propchange: incubator/trafficserver/site/trunk/docs/admin/preface.htm
------------------------------------------------------------------------------
    svn:executable = *

Added: incubator/trafficserver/site/trunk/docs/admin/reverse.htm
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/reverse.htm?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/admin/reverse.htm (added)
+++ incubator/trafficserver/site/trunk/docs/admin/reverse.htm Thu Oct 29 23:23:25 2009
@@ -0,0 +1,193 @@
+<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 &amp; 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 />
+       &nbsp;&nbsp;<code>redirect</code>—redirects HTTP requests permanently without having to contact the origin server. <br />
+       &nbsp;&nbsp;<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 />
+       &nbsp;&nbsp;<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 />
+       &nbsp;&nbsp;<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>
\ No newline at end of file

Propchange: incubator/trafficserver/site/trunk/docs/admin/reverse.htm
------------------------------------------------------------------------------
    svn:executable = *

Added: incubator/trafficserver/site/trunk/docs/admin/secure.htm
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/admin/secure.htm?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/admin/secure.htm (added)
+++ incubator/trafficserver/site/trunk/docs/admin/secure.htm Thu Oct 29 23:23:25 2009
@@ -0,0 +1,301 @@
+<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>Security Options</h1>
+<p>Traffic Server provides a number of security features.</p>
+<p>This chapter discusses the following topics: </p>
+<ul>
+<li><a href="#ControllingClientAccessProxyCache"><em>Controlling Client Access to the Proxy Cache</em></a></li> 
+<li><a href="#ControllingAccessTrafficManager"><em>Controlling Access: SSL</em></a></li> 
+<li><a href="#ConfiguringDNSServerSelectionSplit"><em>Configuring DNS Server Selection (Split DNS)</em></a></li> 
+<li><a href="#ConfiguringProxyAuthentication"><em>Configuring Proxy Authentication</em></a></li> 
+<li><a href="#UsingSSLTermination"><em>Using SSL Termination</em></a></li> 
+</ul>
+<h2 id="ControllingClientAccessProxyCache">Controlling Client Access to the Proxy Cache</h2>
+<p>You can configure Traffic Server to allow only certain clients to use the proxy cache by  editing a configuration file.</p>
+<h5>To specify the clients allowed to use the proxy cache: </h5>
+<ol>
+  <li>In a text editor, open the <code>ip_allow.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+  <li>Add a line in the file for each IP address or range of IP addresses allowed to access Traffic Server (refer to <a href="files.htm#53256"><em>ip_allow.config</em></a>). </li>
+  <li>Save and close the <code>ip_allow.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="ControllingAccessTrafficManager">Controlling Access via SSL</h2>
+<p>By restricting access to Traffic Server, you ensure that only authenticated users can change configuration options and view network traffic statistics. </p>
+<h3 id="UsingSSLSecureAdministration">Using SSL for Secure Administration</h3>
+<p>Traffic Server supports the Secure Sockets Layer protocol (SSL) to provide protection for remote administrative monitoring and configuration. SSL security provides authentication for both ends of a network connection via certificates, and provides privacy via encryption. </p>
+<p>To use SSL, you must perform the following procedures:  </p>
+<ul>
+  <li>Obtain an SSL certificate  </li>
+  <li>Enable SSL   </li>
+</ul>
+<h4>Obtain an SSL Certificate </h4>
+<p>The SSL certificate is a text file  you must install in the Traffic Server <code>config</code> directory. You must either rename the certificate to the default filename <code>private_key.pem</code>, or specify the name of the certificate in the configuration file (follow the procedure in <a href="#EnablingSSL"><em>Enabling SSL</em></a>). </p>
+<h4 id="EnablingSSL">Enable SSL</h4>
+<p>After you have obtained an SSL certificate, enable SSL  by manually editing a configuration file. 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>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.admin.use_ssl</i></code></td>
+      <td>Set this variable to 1 to enable SSL.</td>
+  </tr>
+      <tr>
+      <td><code><i>proxy.config.admin.ssl_cert_file</i></code></td>
+      <td>Set this variable to specify the filename of the SSL certificate. You have to change the filename only if the certificate file does not use the default name <code>private_key.pem</code>.</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><a name="ConfiguringDNSServerSelectionSplit"></a>Configuring DNS Server Selection (Split DNS)</h2>
+<p>The Split DNS option enables you to configure Traffic Server to use multiple DNS servers, as dictated by your security requirements. For example, you might configure Traffic Server to use one set of DNS servers to resolve hostnames on your internal network, while allowing DNS servers outside the firewall to resolve hosts on the Internet. This maintains the security of your intranet, while continuing to provide direct access to sites outside your organization. </p>
+<p>To configure Split DNS, you must perform the following tasks: </p>
+<ul>
+  <li>Specify the rules for performing DNS server selection based on the destination domain, the destination host, or a URL regular expression. </li>
+  <li>Enable the <b>Split DNS</b> option.</li>
+</ul>
+<h5>To configure Split DNS: </h5>
+<ol>
+  <li>In a text editor, open the <code>splitdns.config</code> file located in the Traffic Server <code>config</code> directory. </li>
+  <li>Add rules to the <code>splitdns.config</code> file. For information about the format of the <code>splitdns.config</code> file, <a href="files.htm#132448"><em>click here</em></a>. </li>
+  <li>Save and close the <code>splitdns.config</code> file.</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 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.process.dns.splitDNS.enabled</i></code></td>
+      <td>Set this variable to 1 to enable split DNS.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.dns.splitdns.def_domain</i></code></td>
+      <td>Set this variable to specify the default domain for split DNS requests. Traffic Server appends this value automatically to a hostname that does not include a domain before determining which DNS server to use.</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><a name="UsingSSLTermination"></a>Using SSL Termination</h2>
+<p>The Traffic Server SSL termination option enables you to secure connections in reverse proxy mode between a client and a Traffic Server and/or Traffic Server and an origin server.  </p>
+<p>The following sections describe how to enable and configure the SSL termination option.  </p>
+<ul>
+  <li>To enable and configure SSL termination for client/Traffic Server connections: <a href="#ClientTrafficEdgeConnections"><em>Client and Traffic Server Connections</em></a>. </li>
+  <li>To enable and configure SSL termination for Traffic Server/origin server connections:  <a href="#TrafficEdgeOriginServerConnections"><em>Traffic Server and Origin Server Connections</em></a>. </li>
+  <li>To enable and configure SSL termination for both client/Traffic Server and Traffic Server/origin server connections: <a href="#ClientTrafficEdgeConnections"><em>Client and Traffic Server Connections</em></a> and <a href="#TrafficEdgeOriginServerConnections"><em>Traffic Server and Origin Server Connections</em></a>. </li>
+</ul>
+<p>If you install an SSL accelerator card on your Traffic Server system, then you must perform additional configuration steps - refer to <a href="#ConfiguringTrafficEdgeSSLAcceleratorCard"><em>Configuring Traffic Server to Use an SSL Accelerator Card</em></a>. </p>
+<h3 id="ClientTrafficEdgeConnections">Client and Traffic Server Connections </h3>
+<p>The figure below illustrates communication between a client and Traffic Server and between Traffic Server and an origin server, when the SSL termination option is enabled &amp; configured <i>for client/Traffic Server connections only.</i></p>
+<p><img src="images/ssl_c.jpg" width="1017" height="388" /></p>
+<blockquote>
+  <p><em><b>Client and Traffic Server communication using SSL termination</b></em></p>
+</blockquote>
+<p>The figure above demonstrates the following: </p>
+<p><strong>Step 1:</strong> The client sends an HTTPS request for content. Traffic Server receives the request and performs the SSL 'handshake' to authenticate the client (depending on the authentication options configured) and  determine the encryption method to be used. If the client is allowed access, then Traffic Server checks its cache for the requested content. </p>
+<p><strong>Step 2:</strong> If the request is a cache hit and the content is fresh, thenTraffic Server encrypts the content and sends it to the client. The client decrypts the content (using the method determined during the handshake) and displays it. </p>
+<p><strong>Step 3:</strong> If the request is a cache miss or is stale, then Traffic Server communicates with the origin server via HTTP and obtains a plain text version of the content. Traffic Server saves the plain text version of the content in its cache, encrypts the content, and sends it to the client. The client decrypts and displays the content. </p>
+<p>To configure Traffic Server to use the SSL termination option for client/Traffic Server connections, you must perform the following procedures: </p>
+<ul>
+  <li>Obtain and install an SSL server certificate from a recognized certificate authority (such as VeriSign). The SSL server certificate contains information that enables the client to authenticate Traffic Server and exchange  encryption keys. </li>
+  <li>Configure SSL termination options: </li>
+<ul> 
+<li>Enable the SSL termination option. </li>
+  <li>Set the port number used for SSL communication. </li>
+  <li>Specify the filename and location of the server certificate. </li>
+  <li><em>(Optional)</em> Configure the use of client certificates. <br />
+    Client certificates are located on the client. If you configure Traffic Server to require client certificates, then Traffic Server verifies the client certificate during the SSL handshake to authenticate the client. If you configure Traffic Server to <em>not</em> require client certificates, then access to Traffic Server is managed through other Traffic Server options that have been set (such as rules in the <code>ip_allow.config</code> file). </li>
+  <li>Specify the filename and location of the Traffic Server private key (if the private key is not located in the server certificate file) <br />
+    Traffic Server uses its private key during the SSL handshake to decrypt the session encryption keys. The private key must be stored and protected against theft. </li>
+  <li><i>(Optional)</i> Configure the use of certification authorities (CAs). <br />
+    CAs provide added security by verifying the identity of the person requesting a certificate.</li>
+</ul>
+</ul>
+<h5>To configure SSL termination for client/Traffic Server connections: </h5>
+<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 variables in the <code>SSL Termination</code> section of the file: </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.ssl.enabled</i></code></td>
+      <td>Set this variable to 1 to enable the SSL termination option.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.server_port</i></code></td>
+      <td>Set this variable to specify the port used for SSL communication. The default port is 443.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.certification_level</i></code></td>
+      <td>Set this variable to one of the following values:<br />0 specifies that no client certificates are required. Traffic Server does not verify client certificates during the SSL handshake. Access to Traffic Server depends on Traffic Server configuration options (such as access control lists).<br />1 specifies that client certificates are optional. If a client has a certificate, the certificate is validated. If the client does not have a certificate, the client is still allowed access to Traffic Server unless access is denied through other Traffic Server configuration options.<br />2 specifies that client certificates are required. The client must be authenticated during the SSL handshake. Clients without a certificate are not allowed to access Traffic Server.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.server.cert.filename</i></code></td>
+      <td>Set this variable to specify the filename of the Traffic Server SSL server certificate.<br />Traffic Server provides a demo server certificate called <code>server.pem</code>. You can use this certificate to verify that the SSL feature is working.<br />If you are using multiple server certificates, set this variable to specify the default filename.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.server.cert.path</i></code></td>
+      <td>Set this variable to specify the location of the Traffic Server SSL server certificate. The default directory is the Traffic Server <code>config</code> directory.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.server.private_key.filename</i></code></td>
+      <td>Set this variable to specify the filename of the Traffic Server private key. Change this variable only if the private key is not located in the Traffic Server SSL server certificate file.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.server.private_key.path</i></code></td>
+      <td>Set this variable to specify the location of the Traffic Server private key. Change this variable only if the private key is not located in the Traffic Server SSL server certificate file.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.CA.cert.filename</i></code></td>
+      <td>Specify the filename of the certificate authority that client certificates will be verified against. The default value is <code>NULL</code>.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.CA.cert.path</i></code></td>
+      <td>Specify the location of the certificate authority file that client certificates will be verified against. The default value is <code>NULL</code>.</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 -L</code> to restart Traffic Server on the local node or <code>traffic_line -M</code> to restart Traffic Server on all the nodes in a cluster. </li>
+</ol>
+<h3 id="TrafficEdgeOriginServerConnections">Traffic Server and Origin Server Connections</h3>
+<p>The figure below illustrates communication between Traffic Server and an origin server when the SSL termination option is enabled for<i> Traffic Server/origin server connections</i>.</p>
+<p><img src="images/ssl_os.jpg" width="1039" height="313" /></p>
+<blockquote>
+  <p><em><b>Traffic Server and origin server communication using SSL termination</b></em></p>
+</blockquote>
+<p>The figure above demonstrates the following: </p>
+<p><strong>Step 1:</strong> If a client request is a cache miss or is stale, then Traffic Server sends an HTTPS request for the content to the origin server. The origin server receives the request and performs the SSL handshake to authenticate Traffic Server and to determine the encryption method to be used. </p>
+<p><strong>Step 2:</strong> If Traffic Server is allowed access, then the origin server encrypts the content and sends it to Traffic Server, where it is decrypted (using the method determined during the handshake) and the plain text version of the content saved in the cache. </p>
+<p><strong>Step 3:</strong> If SSL termination is enabled for client /Traffic Server connections, then Traffic Server re-encrypts the content and sends it to the client via HTTPS, where it is decrypted and displayed. If SSL termination is not enabled for client/Traffic Server connections, Traffic Server sends the plain text version of the content to the client via HTTP. </p>
+<p>To configure Traffic Server to use the SSL termination option for Traffic Server and origin server connections, you must perform the following steps: </p>
+<ul>
+  <li>Obtain and install an SSL <em>client</em> certificate from a recognized certificate authority (such as VeriSign). The SSL client certificate contains information that allows the origin server to authenticate Traffic Server. <br />
+  The client certificate is optional.  </li>
+  <li>Configure SSL termination options: </li>
+ <ul> <li>Enable the SSL termination option. </li>
+   <li>Set the port number used for SSL communication. </li>
+   <li>Specify the filename and location of the SSL client certificate (if you choose to use a client certificate). </li>
+   <li>Specify the filename and location of the Traffic Server private key (if the private key is not located in the client certificate file). <br />
+    Traffic Server uses its private key during the SSL handshake to decrypt the session encryption keys. The private key must be stored and protected against theft. </li>
+   <li>Configure the use of CAs. <br />
+    CAs allow the Traffic Server that's acting as a client to verify the identity of the server with which it is communicating; this enables exchange  of encryption keys.</li>
+ </ul>
+</ul>
+<h5>To configure SSL termination for Traffic Server/origin server connections: </h5>
+<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 variables in the SSL Termination section of the file: </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.ssl.auth.enabled</i></code></td>
+      <td>Set this variable to 1 to enable the SSL termination option.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.server_port</i></code></td>
+      <td>Set this variable to specify the port used for SSL communication. The default port is 443.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.verify.server</i></code></td>
+      <td>Set this option to 1 to require Traffic Server to verify the origin server certificate with the CA.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.cert.filename</i></code></td>
+      <td>If you have installed an SSL client certificate on Traffic Server, set this variable to specify the filename of client certificate.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.cert.path</i></code></td>
+      <td>If you have installed an SSL client certificate on Traffic Server, set this variable to specify the location of the client certificate. The default directory is the Traffic Server <code>config</code> directory.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.private_key.filename</i></code></td>
+      <td>Set this variable to specify the filename of the Traffic Server private key. Change this variable only if the private key is not located in the Traffic Server SSL client certificate file.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.private_key.path</i></code></td>
+      <td>Set this variable to specify the location of the Traffic Server private key. Change this variable only if the private key is not located in the SSL client certificate file.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.CA.cert.filename</i></code></td>
+      <td>Specify the filename of the certificate authority against which the origin server will be verified.The default value is <code>NULL</code>.</td>
+  </tr>
+   <tr>
+      <td><code><i>proxy.config.ssl.client.CA.cert.path</i></code></td>
+      <td>Specify the location of the certificate authority file against which the origin server will be verified.The default value is <code>NULL</code>.</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 -L</code> to restart Traffic Server on the local node or <code>traffic_line -M</code> to restart Traffic Server on all the nodes in a cluster. </li>
+</ol>
+<h3 id="ConfiguringTrafficEdgeSSLAcceleratorCard">Configuring Traffic Server to Use an SSL Accelerator Card </h3>
+<p>You can install an SSL accelerator card on your Traffic Server machine to accelerate the number of requests Traffic Server can process. Traffic Server supports the Cavium accelerator card. If you opt not to use an SSL accelerator card, then you'll use your normal SSL library; if you install the Cavium card, then you'll use the library supported &amp; provided by the  manufacturer.</p>
+<h5>Configure Traffic Server to use an SSL accelerator card: </h5>
+<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 variables in the <code>SSL Termination</code> section of the file: </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.confg.ssl.accelerator.type</i></code></td>
+      <td>Set this variable to specify the type of SSL accelerator card installed on your Traffic Server machine:<br />0 = none (no SSL accelerator card is installed on the Traffic Server machine. The CPU on the Traffic Server machine determines the number of requests served per second).<br />1 = nCipher nFast accelerator card<br />2 = Rainbow CryptoSwift accelerator card<br />3 = Compaq Atalla accelerator card</td>
+  </tr>
+    <tr>
+      <td><code><i>proxy.config.ssl.atalla.lib.path</i></code></td>
+      <td>Set this variable to specify the library path for the Compaq Atalla accelerator card.<br />You need only change this variable if you did not use the default path when you installed the card.</td>
+  </tr>
+    <tr>
+      <td><code><i>proxy.config.ssl.ncipher.lib.path</i></code></td>
+      <td>Set this variable to specify the library path for the nCipher nFast accelerator card.<br />You need only change this variable if you did not use the default path when you installed the card.</td>
+  </tr>
+    <tr>
+      <td><code><i>proxy.config.ssl.cswift.lib.path</i></code></td>
+      <td>Set this variable to specify the library path for the Rainbow CryptoSwift accelerator card.<br />You need only change this variable if you did not use the default path when you installed the card.</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 -L</code> to restart Traffic Server on the local node or <code>traffic_line -M</code> to restart Traffic Server on all the nodes in a cluster. </li>
+</ol>
+
+
+</body>
+</html>
\ No newline at end of file

Propchange: incubator/trafficserver/site/trunk/docs/admin/secure.htm
------------------------------------------------------------------------------
    svn:executable = *



Mime
View raw message