trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [22/26] Separate the Admin and SDK guides.
Date Sun, 02 Jun 2013 05:02:19 GMT
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/faqs.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/faqs.en.rst b/doc/admin/faqs.en.rst
new file mode 100644
index 0000000..8755306
--- /dev/null
+++ b/doc/admin/faqs.en.rst
@@ -0,0 +1,408 @@
+FAQ and Troubleshooting Tips
+****************************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+.. toctree::
+   :maxdepth: 2
+
+FAQs
+====
+
+How do you create a raw disk for the cache if all your disks have mounted file systems?
+---------------------------------------------------------------------------------------
+
+Create a large file on filesystem (with ``dd``) and mount it as loopback device.
+This is accomplished with ``loosetup(8)`` on Linux, ``lofiadm(1m)`` on Solaris
+and Illumos, and ``mdconfig(8)`` on FreeBSD.
+
+How do disk I/O errors affect the cache and what does Traffic Server do when a cache disk fails?
+------------------------------------------------------------------------------------------------
+
+If a disk drive fails five successive I/O operations, then Traffic
+Server considers the drive inaccessible and removes the entire disk from
+the cache. Normal cache operations continue for all other Traffic Server
+disk drives.
+
+If a client disconnects during the time that Traffic Server is downloading a large object, is any of the object saved in the cache?
+-----------------------------------------------------------------------------------------------------------------------------------
+
+When a client disconnects during an HTTP operation, Traffic Server
+continues to download the object from the origin server for up to 10
+seconds. If the transfer from the origin server completes successfully
+within 10 seconds after the client disconnect, then Traffic Server
+stores the object in cache. If the origin server download does *not*
+complete successfully within 10 seconds, then Traffic Server disconnects
+from the origin server and deletes the object from cache. Traffic Server
+does not store partial documents in the cache.
+
+Can Traffic Server cache Java applets, JavaScript programs, or other application files like VBScript?
+-----------------------------------------------------------------------------------------------------
+
+Yes, Traffic Server can store and serve Java applets, JavaScript
+programs, VBScripts, and other executable objects from its cache
+according to the freshness and cacheability rules for HTTP objects.
+Traffic Server does not execute the applets, scripts, or programs,
+however - these objects run only when the client system (ie, the one
+that sent the request) loads them.
+
+How do you apply changes to the ``logs_xml.config`` file to all nodes in a cluster?
+-----------------------------------------------------------------------------------
+
+Link to documentation
+
+In Squid- and Netscape-format log files, what do the cache result codes mean?
+-----------------------------------------------------------------------------
+
+This is described in detail in the `Squid log format
+documentation <../working-log-files/squid-format>`_
+
+What is recorded by the ``cqtx`` field in a custom log file?
+------------------------------------------------------------
+
+-  In **forward proxy mode**, the cqtx field records the complete client
+   request in the log file (for example, GET http://www.company.com
+   HTTP/1.0 ).
+-  In **reverse proxy mode**, the cqtx field records the hostname or IP
+   address of the origin server because Traffic Server first remaps the
+   request as per map rules in the
+   `remap.config <../configuration-files/remap.config>`_ file.
+
+Does Traffic Server refresh entries in its host database after a certain period of time if they have not been used?
+-------------------------------------------------------------------------------------------------------------------
+
+By default, the Traffic Server host database observes the time-to-live
+(``ttl``) values set by name servers. You can reconfigure Traffic Server
+to ignore the ``ttl`` set by name servers and use a specific Traffic
+Server setting instead. Alternatively, you can configure Traffic Server
+to compare the ``ttl`` value set by the name server with the ``ttl``
+value set by Traffic Server, and then use either the lower or the higher
+value.
+
+see
+`proxy.config.hostdb.ttl_mode <../configuration-files/records.config#proxy.config.hostdb.ttl_mode>`_
+for more info
+
+Can you improve the look of your custom response pages by using images, animated .gifs, and Java applets?
+---------------------------------------------------------------------------------------------------------
+
+No, because Traffic Server can only respond to clients with a single
+text or HTML document. As a workaround, however, you can provide
+references on your custom response pages to images, animated .gifs, Java
+applets, or objects other than text which are located on a web server.
+Add links in the body_factory template files in the same way you would
+for any image in an HTML document (i.e., with the full URL in the
+``SRC`` attribute).
+
+Can Traffic Server run in forward proxy and reverse proxy modes at the same time?
+---------------------------------------------------------------------------------
+
+Yes. When you enable reverse proxy mode, Traffic Server remaps incoming
+requests according to the map rules in the
+```remap.config`` <../configuration-files/remap.config>`_ file. All
+other requests that do not match a map rule are simply served in forward
+proxy mode.
+
+If you want to run in reverse proxy only mode (wherein Traffic Server
+does *not* serve requests that fail to match a map rule), then you must
+set the configuration variable
+`proxy.config.url_remap.remap_required <../configuration-files/records.config#proxy.config.url_remap.remap_required>`_
+to ``1`` in the
+```records.config`` <../configuration-files/records.config>`_ file.
+
+How do I enable forward proxy mode
+----------------------------------
+
+Please refer to the `Forward Proxy <../forward-proxy>`_ documentation
+
+How do I interpret the Via: header code?
+----------------------------------------
+
+Take a look at our `Via decoder Ring </tools/via>`_
+
+Support for HTTP Expect: Header
+-------------------------------
+
+Traffic Server currently does not handle request Expect: headers
+according to the HTTP/1.1 spec.
+
+Note that clients such as cURL automatically send Expect: for POST
+requests with large POST bodies, with a 1 second timeout if a 100
+Continue response is not received. To avoid the timeout when using cURL
+as a client to Traffic Server, you can turn off the Expect: header as
+follows:
+
+command line:
+
+::
+    curl -H"Expect:" http://www.example.com/
+
+C (libcurl):
+
+::
+    struct curl_slist *header_list=NULL;
+    header_list = curl_slist_append(header_list, "Expect:");
+    curl_easy_setopt(my_curlp, CURLOPT_HTTPHEADER, header_list);
+
+php:
+
+::
+    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));
+
+Troubleshooting Tips
+====================
+
+The throughput statistic is inaccurate
+--------------------------------------
+
+Traffic Server updates the throughput statistic after it has transferred
+an entire object. For larger files, the byte count increases sharply at
+the end of a transfer. The complete number of bytes transferred is
+attributed to the last 10-second interval, although it can take several
+minutes to transfer the object. This inaccuracy is more noticeable with
+a light load. A heavier load yields a more accurate statistic.
+
+You are unable to execute Traffic Line commands
+-----------------------------------------------
+
+Traffic Line commands do not execute under the following conditions:
+
+-  **When the ``traffic_manager`` process is not running** Check to see
+   if the ``**traffic_manager**`` process is running by entering the
+   following command: ``ps aux | grep traffic_manager``
+
+If the ``traffic_manager`` process is not running, then enter the
+following command from the Traffic Server ``bin`` directory to start it:
+``./traffic_manager``
+
+You should always start and stop Traffic Server with the
+``start_traffic_server``\ and ``stop_traffic_server`` commands to ensure
+that all the processes start and stop correctly. For more information,
+refer to `Getting Started <getstart.htm>`_. \* \* **When you are not
+executing the command from ``$TSHome/bin``** If the Traffic Server
+``bin`` directory is not in your path, then prepend the Traffic Line
+commands with ``./`` (for example, ``./traffic_line -h``). \* \* *\*
+When multiple Traffic Server installations are present and you are not
+executing the Traffic Line command from the active Traffic Server path
+specified in ``/etc/trafficserver``*\ \*
+
+You observe inconsistent behavior when one node obtains an object from another node in the cluster
+--------------------------------------------------------------------------------------------------
+
+As part of the initial system preparation, you must synchronize the
+clocks on all nodes in your cluster. Minor time differences do not cause
+problems, but differences of more than a few minutes can affect Traffic
+Server operation.
+
+You should run a clock synchronization daemon such as xntpd. To obtain
+the latest version of xntpd, go to ``http://www.eecis.udel.edu/~ntp/``
+
+Web browsers display an error document with a 'data missing' message
+--------------------------------------------------------------------
+
+A message similar to the following might display in web browsers:
+
+::
+      Data Missing
+
+      This document resulted from a POST operation and has expired from the cache. You can repost the form data to recreate the document by pressing the Reload button.
+
+This is a Web browser issue and not a problem specific to (or caused by)
+Traffic Server. Because Web browsers maintain a separate local cache in
+memory and/or disk on the client system, messages about documents that
+have expired from cache refer to the browser's local cache and _not _
+to the Traffic Server cache. There is no Traffic Server message or
+condition that can cause such messages to appear in a web browser.
+
+Traffic Server does not resolve any websites
+--------------------------------------------
+
+The browser indicates that it is contacting the host and then times out
+with the following message:
+
+::
+        The document contains no data; Try again later, or contact the server's Administrator...
+
+Make sure the system is configured correctly and that Traffic Server can
+read the name resolution file:
+
+-  Check if the server can resolve DNS lookups by issuing the nslookup
+   command (for example, ``nslookup www.myhost.com``).
+-  Check if the ``/etc/resolv.conf`` file contains valid IP addresses
+   for your DNS servers.
+-  On some systems, if the ``/etc/resolv.conf`` file is unreadable or
+   has no name server entry, then the operating system uses
+   ``localhost`` as a name server. Traffic Server, however, does not use
+   this convention. If you want to use ``localhost`` as a name server,
+   then you must add a name server entry for ``127.0.0.1`` or
+   ``0.0.0.0`` in the ``/etc/resolv.conf`` file.
+-  Check that the Traffic Server user account has permission to read the
+   /etc/resolv.conf file. If it does not, then change the file
+   permissions to ``rw-r--r--`` (``644``)
+
+'Maximum document size exceeded' message in the system log file
+---------------------------------------------------------------
+
+The following message appears in the system log file:
+
+::
+         WARNING: Maximum document size exceeded
+
+A requested object was larger than the maximum size allowed in the
+Traffic Server cache, so Traffic Server provided proxy service for the
+oversized object but did not cache it. To set the object size limit for
+the cache, modify the proxy.config.cache.limits.http.max_doc_size
+variable in the records.config file. If you do not want to limit the
+size of objects in the cache, then set the document size
+to\ ``**0**``\ (zero).
+
+'DrainIncomingChannel' message in the system log file
+-----------------------------------------------------
+
+The following messages may appear in the system log file:
+
+::
+     Feb 20 23:53:40 louis traffic_manager[4414]: ERROR ==> [drainIncomingChannel] Unknown message: 'GET http://www.telechamada.pt/ HTTP/1.0'
+     Feb 20 23:53:46 louis last message repeated 1 time 
+     Feb 20 23:53:58 louis traffic_manager[4414]: ERROR ==> [drainIncomingChannel] Unknown message: 'GET http://www.ip.pt/ HTTP/1.0'
+
+These error messages indicate that a browser is sending HTTP requests to
+one of the Traffic Server cluster ports - either ``rsport`` (default
+port 8088) or ``mcport`` (default port 8089). Traffic Server discards
+the request; this error does not cause any Traffic Server problems. The
+misconfigured browser must be reconfigured to use the correct proxy
+port. Traffic Server clusters work best when configured to use a
+separate network interface and cluster on a private subnet, so that
+client machines have no access to the cluster ports.
+
+'No cop file' message in the system log file
+--------------------------------------------
+
+The following message appears repeatedly in the system log file:
+
+::
+     traffic_cop[16056]: encountered "config/internal/no_cop" file...exiting
+
+The file ``config/internal/no_cop`` acts as an administrative control
+that instructs the ``traffic_cop`` process to exit immediately without
+starting ``traffic_manager`` or performing any health checks. The
+``no_cop`` file prevents Traffic Server from starting automatically when
+it has been stopped with the ``stop_traffic_server`` command. Without
+this static control, Traffic Server would restart automatically upon
+system reboot. The ``no_cop`` control keeps Traffic Server off until it
+is explicitly restarted with the
+
+::
+    trafficserver start
+
+command.
+
+
+Warning in the system log file when manually editing vaddrs.config
+------------------------------------------------------------------
+
+If you manually edit the vaddrs.config file as a non-root user, then
+Traffic Server issues a warning message in the system log file similar
+to the following:
+
+::
+         WARNING: interface is ignored: Operation not permitted
+
+You can safely ignore this message; Traffic Server *does* apply your
+configuration edits.
+
+Traffic Server is running but no log files are created
+------------------------------------------------------
+
+Traffic Server only writes event log files when there is information to
+record. If Traffic Server is idle, then it's possible/probable that no
+log files exist. In addition:
+
+Make sure you're looking in the correct directory. By default, Traffic
+Server creates log files in the logs directory. Check the location of
+log files by checking the value of the variable
+proxy.config.log.logfile_dir in the records.config file. Check that the
+log directory has read/write permissions for the Traffic Server user
+account. If the log directory does not have the correct permissions,
+then the traffic_server process is unable to open or create log files.
+Check that logging is enabled by checking the value of the
+proxy.config.log.logging_enabled variable in the records.config file.
+Check that a log format is enabled. In the records.config file, select
+the standard or custom format by editing variables in the Logging Config
+section.
+
+Traffic Server shows an error indicating too many network connections
+---------------------------------------------------------------------
+
+By default, Traffic Server supports 8000 network connections: half of
+this number is allocated for client connections and the remaining half
+is for origin server connections. A **connection throttle event** occurs
+when client or origin server connections reach 90% of half the
+configured limit (3600 by default). When a connection throttle event
+occurs, Traffic Server continues processing all existing connections but
+will not accept new client connection requests until the connection
+count falls below the limit.
+
+Connection throttle events can occur under the following conditions:
+
+-  If there is a **connection spike** (e.g., if thousands of client
+   requests all reach Traffic Server at the same time). Such events are
+   typically transient and require no corrective action.
+-  If there is a **service overload** (e.g., if client requests
+   continuously arrive faster than Traffic Server can service them).
+   Service overloads often indicate network problems between Traffic
+   Server and origin servers. Conversely, it may indicate that Traffic
+   Server needs more memory, CPU, cache disks, or other resources to
+   handle the client load.
+
+If necessary, you can reset the maximum number of connections supported
+by Traffic Server by editing the value of the
+``_proxy.config.net.connections_throttle _`` configuration variable in
+the records.config file. Do not increase the connection throttle limit
+unless the system has adequate memory to handle the client connections
+required. A system with limited RAM might need a throttle limit lower
+than the default value. Do not set this variable below the minimum value
+of 100.
+
+Low memory symptoms
+-------------------
+
+Under heavy load, the Linux kernel can run out of RAM. This low memory
+condition can cause slow performance and a variety of other system
+problems. In fact, RAM exhaustion can occur even if the system has
+plenty of free swap space.
+
+Symptoms of extreme memory exhaustion include the following messages in
+the system log files (``/var/log/messages``):
+
+::
+     WARNING: errno 105 is ENOBUFS (low on kernel memory), consider a memory upgrade `kernel: eth0: can't fill rx buffer (force 0)!
+     kernel: recvmsg bug: copied E01BA916 seq E01BAB22
+
+To avoid memory exhaustion, add more RAM to the system or reduce the
+load on Traffic Server.
+
+Connection timeouts with the origin server
+------------------------------------------
+
+Certain origin servers take longer than 30 seconds to post HTTP
+requests, which results in connection timeouts with Traffic Server. To
+prevent such connection timeouts, you must change the value of the
+configuration variable proxy.config.http.connect_attempts_timeout in
+the records.config file to 60 seconds or more.
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/forward-proxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/forward-proxy.en.rst b/doc/admin/forward-proxy.en.rst
new file mode 100644
index 0000000..00b4e91
--- /dev/null
+++ b/doc/admin/forward-proxy.en.rst
@@ -0,0 +1,90 @@
+Forward Proxy
+*************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+The Apache Traffic Server is a general purpose *proxy*. As such it can
+also be used as forward proxy.
+
+A forward proxy is can be used as a central tool in your infrastructure
+to access the web. In combination with a cache that means overall
+reduced bandwidth usage.
+
+If your forward proxy is not also configured as `transparent
+proxy <../transparent-proxy>`_ your clients will have to be configured
+to actually use it.
+
+The main difference between a forward and a transparent proxy is that
+User Agents *know* that they are accessing a proxy, thus forming their
+requests like so:
+
+::
+    GET http://example.com/index.php?id=1337 HTTP/1.1
+
+This request, then is translated by the proxy to
+
+::
+    GET /index?id=1337 HTTP/1.1
+    Host: example.com
+
+Apache Traffic Server offers two ways to User Agents: They can either be
+pointed directly to the default ``8080`` port. Alternatively, they can
+be pointed to the more dynamic
+```proxy.config.url_remap.default_to_server_pac`` <../configuration-files/records.config#proxy.config.url_remap.default_to_server_pac>`_
+
+This port will then serve a JavaScript like configuration that User
+Agents can use to determine where to send their requests to.
+
+Configuration
+=============
+
+In order to configure Apache Traffic Server as forward proxy you will
+have to edit
+```records.config`` <../configuration-files/records.config>`_ and set
+
+-  ``CONFIG``
+   ```proxy.config.url_remap.remap_required`` <../configuration-files/records.config#proxy.config.url_remap.remap_required>`_
+   ``0``
+
+If your proxy is serving as *pure* forward proxy, you will also want to
+set
+
+-  ``CONFIG``
+   ```proxy.config.reverse_proxy.enabled`` <../configuration-files/records.config#proxy.config.reverse_proxy.enabled>`_
+   ``0``
+
+Other configuration variables to consider:
+
+-  ``CONFIG``
+   ```proxy.config.http.no_dns_just_forward_to_parent`` <../configuration-files/records.config#proxy.config.http.no_dns_just_forward_to_parent>`_
+-  ``CONFIG``
+   ```proxy.config.http.forward.proxy_auth_to_parent`` <../configuration-files/records.config#proxy.config.http.forward.proxy_auth_to_parent>`_
+-  ``CONFIG``
+   ```proxy.config.http.insert_squid_x_forwarded_for`` <../configuration-files/records.config#proxy.config.http.insert_squid_x_forwarded_for>`_
+
+Security Considerations
+=======================
+
+It's important to note that once your Apache Traffic Server is
+configured as forward proxy it will indiscriminately accept proxy
+requests from anyone. That means, if it's reachable on the internet, you
+have configured an *Open Proxy*. Most of the time, this is *not* what
+you want, so you'll have to make sure it's either only reachable within
+your NAT or is secured by firewall rules that permit only those clients
+to access it which you want to it to access.
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/getting-started.en.rst b/doc/admin/getting-started.en.rst
new file mode 100644
index 0000000..a3e743e
--- /dev/null
+++ b/doc/admin/getting-started.en.rst
@@ -0,0 +1,206 @@
+Getting Started
+***************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+
+.. toctree::
+   :maxdepth: 2
+
+Before you start
+================
+
+Before you get started with Traffic Server you may have to decide which
+version you want to use. Traffic Server uses the same "semantic
+versioning" to denote "stability" as Apache
+`apr <http://apr.apache.org/versioning.html>`_ and
+`httpd <http://httpd.apache.org/dev/release.html>`_ do:
+
+A version is made of a version-triplet: *``MAJOR.MINOR.PATCH``*
+
+The most important thing that you need to know is that an *even
+``MINOR``* marks a production stable release (such as 3.0.3 and 3.2.5),
+while an *odd ``MINOR``* number marks a targeted at developers.
+
+Sometimes we speak of trunk, master, or when talking about actual
+releases, we will say "-unstable", or "-dev". All of these are
+interchangable: trunk or master or sometimes TIP or HEAD, refer to the
+latest code in a Version Control System. While "-dev" (or the
+unfortunately named "-unstable") qualifies that a certain release
+"3.3.1-dev" is has not had seen enough testing to be seen as production
+ready.
+
+If your distribution does not come with a prepackaged Traffic Server,
+please go to `downloads </downloads>`_ to choose the version that you
+consider most appropriate for yourself. If you want to really be on the
+bleeding edge you can clone our `git
+repository <https://git-wip-us.apache.org/repos/asf/trafficserver.git>`_.
+
+Please note that while we do have a `GitHub
+Mirror <https://github.com/apache/trafficserver>`_ that you can also use
+to submit pull requests, it may not be entirely up-to-date.
+
+Building Traffic Server
+=======================
+
+In order to build Traffic Server from source you will need the following
+(development) packages:
+
+-  pkgconfig
+-  libtool
+-  gcc (>= 4.3 or clang > 3.0)
+-  make (GNU Make!)
+-  openssl
+-  tcl
+-  expat
+-  pcre
+-  pcre
+-  libcap
+-  flex (for TPROXY)
+-  hwloc
+-  lua
+
+if you're building from a git clone, you'll also need
+
+-  git
+-  autoconf
+-  automake
+
+We will show-case a build from git:
+
+::
+
+     git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
+
+Next, we ``cd trafficserver`` and run:
+
+::
+
+     autoreconf -if
+
+This will generate a ``configure`` file from ``configure.ac``, so now we
+can run that:
+
+::
+
+     ./configure --prefix=/opt/ats
+
+Note well, that by default Traffic Server uses the user ``nobody``, as
+well as user's primary group as Traffic Server user. If you want to
+change that, you can override it here:
+
+::
+
+     ./configure --prefix=/opt/ats --with-user=tserver
+
+If dependencies are not in standard paths (``/usr/local`` or ``/usr``),
+you need to pass options to ``configure`` to account for that:
+
+::
+
+     ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw
+
+Most ``configure`` path-options accept a format of
+``"INCLUDE_PATH:LIBRARY_PATH"``:
+
+::
+
+     ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw \
+        --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
+
+We can run ``make`` to build the project. We highly recommend to run
+``make check`` to verify the build's general sanity:
+
+::
+
+     make
+     make check
+
+We can finally run ``make install`` to install (you may have to switch
+to root to do this):
+
+::
+
+     sudo make install
+
+We also recommend to run a regression test. Please note that this will
+only work successfully with the default ``layout``:
+
+::
+
+     cd /opt/ats
+     sudo bin/traffic_server -R 1
+
+After you have installed Traffic Server on your system, you can do any
+of the following:
+
+Start Traffic Server
+====================
+
+To start Traffic Server manually, issue the ``trafficserver`` command,
+passing in the attribute ``start``. This command starts all the
+processes that work together to process Traffic Server requests as well
+as manage, control, and monitor the health of the Traffic Server system.
+
+To run the ``trafficserver start`` command, e.g.:
+
+::
+
+        bin/trafficserver start
+
+At this point your server is up and running in the default configuration
+of a `reverse proxy <../reverse-proxy-http-redirects>`_.
+
+Start Traffic Line
+==================
+
+Traffic Line provides a quick way of viewing Traffic Server statistics
+and configuring the Traffic Server system via command-line interface. To
+execute individual commands or script multiple commands, refer to
+`Traffic Line Commands <../traffic-line-commands>`_.
+
+Traffic Line commands take the following form:
+
+::
+
+     bin/traffic_line -command argument
+
+For a list of ``traffic_line`` commands, enter:
+
+::
+
+     bin/traffic_line -h
+
+Please note that ``traffic_line``, while a fine tool for an
+administrator, is a poor choice for automation, especially that of
+monitoring. See our chapter on `Monitoring
+Traffic <../monitoring-traffic>`_ for how to get that righter.
+
+Stop Traffic Server
+===================
+
+To stop Traffic Server, always use the ``trafficserver`` command,
+passing in the attribute ``stop``. This command stops all the Traffic
+Server processes (``traffic_manager``, ``traffic_server``, and
+``traffic_cop``). Do not manually stop processes, as this can lead to
+unpredictable results.
+
+::
+
+    bin/trafficserver stop
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/hierachical-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/hierachical-caching.en.rst b/doc/admin/hierachical-caching.en.rst
new file mode 100644
index 0000000..fc0236a
--- /dev/null
+++ b/doc/admin/hierachical-caching.en.rst
@@ -0,0 +1,188 @@
+Hierarchical Caching
+********************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+
+.. toctree::
+   :maxdepth: 2
+
+Understanding Cache Hierarchies
+===============================
+
+A cache hierarchy consists of cache levels that communicate with each
+other. Traffic Server supports several types of cache hierarchies. All
+cache hierarchies recognize the concept of **parent** and **child**. A
+parent cache is a cache higher up in the hierarchy, to which Traffic
+Server can forward requests. A child cache is a cache for which Traffic
+Server is a parent.
+
+Traffic Server supports the following hierarchical caching options:
+
+-  `Parent Caching <#ParentCaching>`_
+
+Parent Caching
+==============
+
+If a Traffic Server node cannot find a requested object in its cache,
+then it searches a parent cache (which itself can search other caches)
+before finally retrieving the object from the origin server. You can
+configure a Traffic Server node to use one or more parent caches so that
+if one parent is unavailable, then another parent is availale to service
+requests. This is called `Parent Failover <#ParentFailover>`_. Traffic
+Server will support parent caching for HTTP and HTTPS requests.
+
+**Note:** If you do not want all requests to go to the parent cache,
+then simply configure Traffic Server to route certain requests (such as
+requests containing specific URLs) directly to the origin server. SImply
+set parent proxy rules in
+`parent.config <configuration-files/parent.config>`_
+
+The figure below illustrates a simple cache hierarchy with a Traffic
+Server node configured to use a parent cache. In the following scenario,
+a client sends a request to a Traffic Server node that is a child in the
+cache hierarchy (because it's configured to forward missed requests to a
+parent cache). The request is a cache miss, so Traffic Server then
+forwards the request to the parent cache, where it is a cache hit. The
+parent sends a copy of the content to the Traffic Server, where it is
+cached and then served to the client. Future requests for this content
+can now be served directly from the Traffic Server cache (until the data
+is stale or expired).
+
+.. figure:: ../_static/images/admin/cachehrc.jpg
+   :align: center
+   :alt: Parent caching
+
+   Parent caching
+
+**Note:** If the request is a cache miss on the parent, then the parent
+retrieves the content from the origin server (or from another cache,
+depending on the parent’s configuration). The parent caches the content
+and then sends a copy to Traffic Server (its child), where it is cached
+and served to the client.
+
+Parent Failover
+---------------
+
+Traffic Server supports use of several parent caches. This ensures that
+if one parent cache is not available, another parent cache can service
+client requests.
+
+When you configure your Traffic Server to use more than one parent
+cache, Traffic Server detects when a parent is not available and sends
+missed requests to another parent cache. If you specify more than two
+parent caches, then the order in which the parent caches are queried
+depends upon the parent proxy rules configured in the
+`parent.config <configuration-files/parent.config>`_ configuration
+file. By default, the parent caches are queried in the order they are
+listed in the configuration file.
+
+Configuring Traffic Server to Use a Parent Cache
+------------------------------------------------
+
+To configure Traffic Server to use one or more parent caches, you must
+complete the following steps:
+
+-  Enable the parent caching option.
+-  Identify the parent cache you want to use to service missed requests.
+   To use **parent failover**, you must identify more than one parent
+   cache so that when a parent cache is unavailable, requests are sent
+   to another parent cache.
+
+**Note:** You need to configure the child cache only. No additional
+configuration is needed for the Traffic Server parent cache.
+
+Configure Traffic Server to use a parent cache by editing the following
+variable
+`*``proxy.config.http.parent_proxy_routing_enable``* <configuration-files/records.config#proxy.config.http.parent_proxy_routing_enable>`_
+in ``records.config`` file.
+
+Edit the ```parent.config`` <../configuration-files/parent.config>`_
+file located in the Traffic Server ``config`` directory to set parent
+proxy rules to specify the parent cache to which you want missed
+requests to be forwarded;
+
+The following example configures Traffic Server to route all requests
+containing the regular expression ``politics`` and the path
+``/viewpoint`` directly to the origin server (bypassing any parent
+hierarchies):
+
+::
+
+    url_regex=politics prefix=/viewpoint go_direct=true
+
+The following example configures Traffic Server to direct all missed
+requests with URLs beginning with ``http://host1`` to the parent cache
+``parent1``. If ``parent1`` cannot serve the requests, then requests are
+forwarded to ``parent2``. Because ``round-robin=true``, Traffic Server
+goes through the parent cache list in a round-robin based on client IP
+address.
+
+::
+
+    dest_host=host1 scheme=http parent="parent1;parent2" round-robin=strict
+
+Run the command ``traffic_line -x`` to apply the configuration changes.
+
+.. XXX As of yet, this is unsupported.
+
+.. # ICP Peering # {#ICPPeering}
+
+.. The Internet Cache Protocol (ICP) is used by proxy caches to exchange information 
+   about their content. ICP query messages ask other caches if they are storing 
+   a particular URL; ICP response messages reply with a hit or miss answer. A 
+   cache exchanges ICP messages only with specific **ICP peers**, which are neighboring 
+   caches that can receive ICP messages. An ICP peer can be a **sibling cache 
+   **(which is at the same level in the hierarchy) or a **parent cache** (which 
+   is one level up in the hierarchy). 
+
+.. If Traffic Server has ICP caching enabled, then it sends ICP queries to its 
+   ICP peers when the HTTP request is a cache miss. If there are no hits but parents 
+   exist, then a parent is selected using a round-robin policy. If no ICP parents 
+   exist, then Traffic Server forwards the request to its HTTP parents. If there 
+   are no HTTP parent caches established, then Traffic Server forwards the request 
+   to the origin server. 
+
+.. If Traffic Server receives a hit message from an ICP peer, then Traffic Server 
+   sends the HTTP request to that peer. However, it might turn out to be a cache 
+   miss because the original HTTP request contains header information that is 
+   not communicated by the ICP query. For example, the hit might not be the requested 
+   alternate. If an ICP hit turns out to be a miss, then Traffic Server forwards 
+   the request to either its HTTP parent caches or to the origin server. 
+
+.. To configure a Traffic Server node to be part of an ICP cache hierarchy, you 
+   must perform the following tasks: 
+
+.. * Determine if the Traffic Server can receive ICP messages only, or if it can send _and_ receive ICP messages. 
+   * Determine if Traffic Server can send messages directly to each ICP peer or send a single message on a specified multicast channel. 
+   * Specify the port used for ICP messages. 
+   * Set the ICP query timeout. 
+   * Identify the ICP peers (siblings and parents) with which Traffic Server can communicate.
+
+.. To configure Traffic Server to use an ICP cache hierarchy edit the following variables in [`records.config`](../configuration-files/records.config) file:
+
+.. * [_`proxy.config.icp.enabled`_](../configuration-files/records.config#proxy.config.icp.enabled)
+   * [_`proxy.config.icp.icp_port`_](../configuration-files/records.config#proxy.config.icp.port)
+   * [_`proxy.config.icp.multicast_enabled`_](../configuration-files/records.config#proxy.config.icp.multicast_enabled)
+   * [_`proxy.config.icp.query_timeout`_](../configuration-files/records.config#proxy.config.icp.query_timeout)
+
+.. Edit `icp.config` file located in the Traffic Server `config` directory: 
+   For each ICP peer you want to identify, enter a separate rule in the [icp.config](../configuration-files/icp.config) file.
+
+.. Run the command `traffic_line -x` to apply the configuration changes.
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/http-proxy-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/http-proxy-caching.en.rst b/doc/admin/http-proxy-caching.en.rst
new file mode 100644
index 0000000..c602742
--- /dev/null
+++ b/doc/admin/http-proxy-caching.en.rst
@@ -0,0 +1,793 @@
+HTTP Proxy Caching
+******************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+Web proxy caching enables you to store copies of frequently-accessed web
+objects (such as documents, images, and articles) and then serve this
+information to users on demand. It improves performance and frees up
+Internet bandwidth for other tasks.
+
+This chapter discusses the following topics:
+
+.. toctree::
+   :maxdepth: 2
+
+Understanding HTTP Web Proxy Caching
+====================================
+
+Internet users direct their requests to web servers all over the
+Internet. A caching server must act as a **web proxy server** so it can
+serve those requests. After a web proxy server receives requests for web
+objects, it either serves the requests or forwards them to the **origin
+server** (the web server that contains the original copy of the
+requested information). The Traffic Server proxy supports **explicit
+proxy caching**, in which the user's client software must be configured
+to send requests directly to the Traffic Server proxy. The following
+overview illustrates how Traffic Server serves a request.
+
+1. Traffic Server receives a client request for a web object.
+
+2. Using the object address, Traffic Server tries to locate the
+   requested object in its object database (**cache**).
+
+3. If the object is in the cache, then Traffic Server checks to see if
+   the object is fresh enough to serve. If it is fresh, then Traffic
+   Server serves it to the client as a **cache hit** (see the figure
+   below).
+
+   .. figure:: ../_static/images/admin/cache_hit.jpg
+      :align: center
+      :alt: A cache hit
+
+      A cache hit
+4. If the data in the cache is stale, then Traffic Server connects to
+   the origin server and checks if the object is still fresh (a
+   **revalidation**). If it is, then Traffic Server immediately sends
+   the cached copy to the client.
+
+5. If the object is not in the cache (a **cache miss**) or if the server
+   indicates the cached copy is no longer valid, then Traffic Server
+   obtains the object from the origin server. The object is then
+   simultaneously streamed to the client and the Traffic Server local
+   cache (see the figure below). Subsequent requests for the object can
+   be served faster because the object is retrieved directly from cache.
+
+   .. figure:: ../_static/images/admin/cache_miss.jpg
+      :align: center
+      :alt: A cache miss
+
+      A cache miss
+
+Caching is typically more complex than the preceding overview suggests.
+In particular, the overview does not discuss how Traffic Server ensures
+freshness, serves correct HTTP alternates, and treats requests for
+objects that cannot/should not be cached. The following sections discuss
+these issues in greater detail.
+
+Ensuring Cached Object Freshness
+================================
+
+When Traffic Server receives a request for a web object, it first tries
+to locate the requested object in its cache. If the object is in cache,
+then Traffic Server checks to see if the object is fresh enough to
+serve. For HTTP objects, Traffic Server supports optional
+author-specified expiration dates. Traffic Server adheres to these
+expiration dates; otherwise, it picks an expiration date based on how
+frequently the object is changing and on administrator-chosen freshness
+guidelines. Objects can also be revalidated by checking with the origin
+server to see if an object is still fresh.
+
+HTTP Object Freshness
+---------------------
+
+Traffic Server determines whether an HTTP object in the cache is fresh
+by:
+
+-  **Checking the ``Expires`` or ``max-age`` header**
+
+   Some HTTP objects contain ``Expires`` headers or ``max-age`` headers
+   that explicitly define how long the object can be cached. Traffic
+   Server compares the current time with the expiration time to
+   determine if the object is still fresh.
+
+-  **Checking the ``Last-Modified`` / ``Date`` header**
+
+   If an HTTP object has no ``Expires`` header or ``max-age`` header,
+   then Traffic Server can calculate a freshness limit using the
+   following formula:
+
+   ::
+       freshness_limit = ( date - last_modified ) * 0.10   
+
+   where *``date``* is the date in the object's server response header
+   and *``last_modified``* is the date in the ``Last-Modified`` header.
+   If there is no ``Last-Modified`` header, then Traffic Server uses the
+   date the object was written to cache. The value ``0.10`` (10 percent)
+   can be increased or reduced to better suit your needs (refer to
+   `Modifying the Aging Factor for Freshness
+   Computations <#ModifyingAgingFactorFreshnessComputations>`_).
+
+   The computed freshness limit is bound by a minimum and maximum value
+   - refer to `Setting an Absolute Freshness
+   Limit <#SettingAbsoluteFreshnessLimit>`_ for more information.
+
+-  **Checking the absolute freshness limit**
+
+   For HTTP objects that do not have ``Expires`` headers or do not have
+   both ``Last-Modified`` and ``Date`` headers, Traffic Server uses a
+   maximum and minimum freshness limit (refer to `Setting an Absolute
+   Freshness Limit <#SettingAbsoluteFreshnessLimit>`_).
+
+-  **Checking revalidate rules in the ``cache.config`` file**
+
+   Revalidate rules apply freshness limits to specific HTTP objects. You
+   can set freshness limits for objects originating from particular
+   domains or IP addresses, objects with URLs that contain specified
+   regular expressions, objects requested by particular clients, and so
+   on (refer to
+   ```cache.config`` <../configuration-files/cache.config>`_).
+
+Modifying Aging Factor for Freshness Computations
+-------------------------------------------------
+
+If an object does not contain any expiration information, then Traffic
+Server can estimate its freshness from the ``Last-Modified`` and
+``Date`` headers. By default, Traffic Server stores an object for 10% of
+the time that elapsed since it last changed. You can increase or reduce
+the percentage according to your needs.
+
+To modify the aging factor for freshness computations
+
+1. Edit the following variables in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.http.cache.heuristic_lm_factor``* <configuration-files/records.config#proxy.config.http.cache.heuristic_lm_factor>`_
+
+2. Run the ``traffic_line -x`` command to apply the configuration
+   changes.
+
+Setting absolute Freshness Limits
+---------------------------------
+
+Some objects do not have ``Expires`` headers or do not have both
+``Last-Modified`` and ``Date`` headers. To control how long these
+objects are considered fresh in the cache, specify an **absolute
+freshness limit**.
+
+To specify an absolute freshness limit
+
+1. Edit the following variables in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.http.cache.heuristic_min_lifetime``* <configuration-files/records.config#proxy.config.http.cache.heuristic_min_lifetime>`_
+   -  `*``proxy.config.http.cache.heuristic_max_lifetime``* <configuration-files/records.config#proxy.config.http.cache.heuristic_max_lifetime>`_
+
+2. Run the ``traffic_line -x`` command to apply the configuration
+   changes.
+
+Specifying Header Requirements
+------------------------------
+
+To further ensure freshness of the objects in the cache, configure
+Traffic Server to cache only objects with specific headers. By default,
+Traffic Server caches all objects (including objects with no headers);
+you should change the default setting only for specialized proxy
+situations. If you configure Traffic Server to cache only HTTP objects
+with ``Expires`` or ``max-age`` headers, then the cache hit rate will be
+noticeably reduced (since very few objects will have explicit expiration
+information).
+
+To configure Traffic Server to cache objects with specific headers
+
+1. Edit the following variable in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.http.cache.required_headers``* <configuration-files/records.config#proxy.config.http.cache.required_headers>`_
+
+2. Run the ``traffic_line -x`` command to apply the configuration
+   changes.
+
+Cache-Control Headers
+---------------------
+
+Even though an object might be fresh in the cache, clients or servers
+often impose their own constraints that preclude retrieval of the object
+from the cache. For example, a client might request that a object *not*
+be retrieved from a cache, or if it does, then it cannot have been
+cached for more than 10 minutes. Traffic Server bases the servability of
+a cached object on ``Cache-Control`` headers that appear in both client
+requests and server responses. The following ``Cache-Control`` headers
+affect whether objects are served from cache:
+
+-  The ``no-cache`` header, sent by clients, tells Traffic Server that
+   it should not to serve any objects directly from the cache;
+   therefore, Traffic Server will always obtain the object from the
+   origin server. You can configure Traffic Server to ignore client
+   ``no-cache`` headers - refer to `Configuring Traffic Server to Ignore
+   Client no-cache Headers <#ConfiguringTSIgnoreClientnocacheHeaders>`_
+   for more information.
+
+-  The ``max-age`` header, sent by servers, is compared to the object
+   age. If the age is less than ``max-age``, then the object is fresh
+   and can be served.
+
+-  The ``min-fresh`` header, sent by clients, is an **acceptable
+   freshness tolerance**. This means that the client wants the object to
+   be at least this fresh. Unless a cached object remains fresh at least
+   this long in the future, it is revalidated.
+
+-  The ``max-stale`` header, sent by clients, permits Traffic Server to
+   serve stale objects provided they are not too old. Some browsers
+   might be willing to take slightly stale objects in exchange for
+   improved performance, especially during periods of poor Internet
+   availability.
+
+Traffic Server applies ``Cache-Control`` servability criteria
+***after*** HTTP freshness criteria. For example, an object might be
+considered fresh but will not be served if its age is greater than its
+``max-age``.
+
+Revalidating HTTP Objects
+-------------------------
+
+When a client requests an HTTP object that is stale in the cache,
+Traffic Server revalidates the object. A **revalidation** is a query to
+the origin server to check if the object is unchanged. The result of a
+revalidation is one of the following:
+
+-  If the object is still fresh, then Traffic Server resets its
+   freshness limit and serves the object.
+
+-  If a new copy of the object is available, then Traffic Server caches
+   the new object (thereby replacing the stale copy) and simultaneously
+   serves the object to the client.
+
+-  If the object no longer exists on the origin server, then Traffic
+   Server does not serve the cached copy.
+
+-  If the origin server does not respond to the revalidation query, then
+   Traffic Server serves the stale object along with a
+   ``111 Revalidation Failed`` warning.
+
+By default, Traffic Server revalidates a requested HTTP object in the
+cache if it considers the object to be stale. Traffic Server evaluates
+object freshness as described in `HTTP Object
+Freshness <#HTTPObjectFreshness>`_. You can reconfigure how Traffic
+Server evaluates freshness by selecting one of the following options:
+
+-  Traffic Server considers all HTTP objects in the cache to be stale:
+   always revalidate HTTP objects in the cache with the origin server.
+-  Traffic Server considers all HTTP objects in the cache to be fresh:
+   never revalidate HTTP objects in the cache with the origin server.
+-  Traffic Server considers all HTTP objects without ``Expires`` or
+   ``Cache-control`` headers to be stale: revalidate all HTTP objects
+   without ``Expires`` or ``Cache-Control`` headers.
+
+To configure how Traffic Server revalidates objects in the cache, you
+can set specific revalidation rules in
+```cache.config`` <../configuration-files/records.config>`_.
+
+To configure revalidation options
+
+1. Edit the following variable in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.http.cache.when_to_revalidate``* <configuration-files/records.config#proxy.config.http.cache.when_to_revalidate>`_
+
+2. Run the ``traffic_line -x`` command to apply the configuration
+   changes.
+
+Scheduling Updates to Local Cache Content
+=========================================
+
+To further increase performance and to ensure that HTTP objects are
+fresh in the cache, you can use the **Scheduled Update** option. This
+configures Traffic Server to load specific objects into the cache at
+scheduled times. You might find this especially beneficial in a reverse
+proxy setup, where you can *preload* content you anticipate will be in
+demand.
+
+To use the Scheduled Update option, you must perform the following
+tasks.
+
+-  Specify the list of URLs that contain the objects you want to
+   schedule for update,
+-  the time the update should take place,
+-  and the recursion depth for the URL.
+-  Enable the scheduled update option and configure optional retry
+   settings.
+
+Traffic Server uses the information you specify to determine URLs for
+which it is responsible. For each URL, Traffic Server derives all
+recursive URLs (if applicable) and then generates a unique URL list.
+Using this list, Traffic Server initiates an HTTP ``GET`` for each
+unaccessed URL. It ensures that it remains within the user-defined
+limits for HTTP concurrency at any given time. The system logs the
+completion of all HTTP ``GET`` operations so you can monitor the
+performance of this feature.
+
+Traffic Server also provides a **Force Immediate Update** option that
+enables you to update URLs immediately without waiting for the specified
+update time to occur. You can use this option to test your scheduled
+update configuration (refer to `Forcing an Immediate
+Update <#ForcingImmediateUpdate>`_).
+
+Configuring the Scheduled Update Option
+---------------------------------------
+
+To configure the scheduled update option
+
+1. Edit ```update.config`` <../configuration-files/update.config>`_ to
+   enter a line in the file for each URL you want to update.
+2. Edit the following variables in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.update.enabled``* <configuration-files/records.config#proxy.config.http.update.enabled>`_
+   -  `*``proxy.config.update.retry_count``* <configuration-files/records.config#proxy.config.http.update.retry_count>`_
+   -  `*``proxy.config.update.retry_interval``* <configuration-files/records.config#proxy.config.http.update.retry_interval>`_
+   -  `*``proxy.config.update.concurrent_updates``* <configuration-files/records.config#proxy.config.http.update.concurrent_updates>`_
+
+3. Run the ``traffic_line -x`` command to apply the configuration
+   changes.
+
+Forcing an Immediate Update
+---------------------------
+
+Traffic Server provides a **Force Immediate Update** option that enables
+you to immediately verify the URLs listed in the ``update.config`` file.
+The Force Immediate Update option disregards the offset hour and
+interval set in the ``update.config`` file and immediately updates the
+URLs listed.
+
+To configure the Force Immediate Update option
+
+1. Edit the following variables in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.update.force``* <configuration-files/records.config#proxy.config.http.update.force>`_
+   -  Make sure the variable
+      `*``proxy.config.update.enabled``* <configuration-files/records.config#proxy.config.http.update.enabled>`_
+      is set to 1.
+
+2. Run the ``command traffic_line -x`` to apply the configuration
+   changes.
+
+**IMPORTANT:** When you enable the Force Immediate Update option,
+Traffic Server continually updates the URLs specified in the
+``update.config`` file until you disable the option. To disable the
+Force Immediate Update option, set the variable
+`*``proxy.config.update.force``* <configuration-files/records.config#proxy.config.http.update.force>`_
+to ``0`` (zero).
+
+Pushing Content into the Cache
+==============================
+
+Traffic Server supports the HTTP ``PUSH`` method of content delivery.
+Using HTTP ``PUSH``, you can deliver content directly into the cache
+without client requests.
+
+Configuring Traffic Server for PUSH Requests
+--------------------------------------------
+
+Before you can deliver content into your cache using HTTP ``PUSH``, you
+must configure Traffic Server to accept ``PUSH`` requests.
+
+To configure Traffic Server to accept ``PUSH`` requests
+
+1. Edit ```records.config`` <../configuration-files/records.config>`_,
+   modify the super mask to allow ``PUSH`` request.
+
+   -  `*``proxy.config.http.quick_filter.mask``* <configuration-files/records.config#proxy.config.http.quick_filter.mask>`_
+
+2. Edit the following variable in
+   ```records.config`` <../configuration-files/records.config>`_, enable
+   the push_method.
+
+   -  `*``proxy.config.http.push_method_enabled``* <configuration-files/records.config#proxy.config.http.push_method_enabled>`_
+
+3. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Understanding HTTP PUSH
+-----------------------
+
+``PUSH`` uses the HTTP 1.1 message format. The body of a ``PUSH``
+request contains the response header and response body that you want to
+place in the cache. The following is an example of a ``PUSH`` request:
+
+::
+
+    PUSH http://www.company.com HTTP/1.0
+    Content-length: 84
+
+    HTTP/1.0 200 OK
+    Content-type: text/html
+    Content-length: 17
+
+    <HTML>
+    a
+    </HTML>
+
+**IMPORTANT:** Your header must include ``Content-length`` -
+``Content-length`` must include both ``header`` and ``body byte count``.
+
+Tools that will help manage pushing
+-----------------------------------
+
+There is a perl script for pushing,
+```tools/push.pl`` <http://git-wip-us.apache.org/repos/asf?p=trafficserver.git;a=blob;f=tools/push.pl>`_,
+which can help you understanding how to write some script for pushing
+content.
+
+Pinning Content in the Cache
+============================
+
+The **Cache Pinning Option** configures Traffic Server to keep certain
+HTTP objects in the cache for a specified time. You can use this option
+to ensure that the most popular objects are in cache when needed and to
+prevent Traffic Server from deleting important objects. Traffic Server
+observes ``Cache-Control`` headers and pins an object in the cache only
+if it is indeed cacheable.
+
+To set cache pinning rules
+
+3. Make sure the following variable in
+   ```records.config`` <../configuration-files/records.config>`_ is set
+
+   -  `*``proxy.config.cache.permit.pinning``* <configuration-files/records.config#proxy.config.cache.permit.pinning>`_
+
+4. Add a rule in
+   ```cache.config`` <../configuration-files/cache.config>`_ for each
+   URL you want Traffic Server to pin in the cache. For example:
+
+   ::
+
+       :::text
+       url_regex=^https?://(www.)?apache.org/dev/ pin-in-cache=12h
+
+5. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+To Cache or Not to Cache?
+=========================
+
+When Traffic Server receives a request for a web object that is not in
+the cache, it retrieves the object from the origin server and serves it
+to the client. At the same time, Traffic Server checks if the object is
+cacheable before storing it in its cache to serve future requests.
+
+Caching HTTP Objects
+====================
+
+Traffic Server responds to caching directives from clients and origin
+servers, as well as directives you specify through configuration options
+and files.
+
+Client Directives
+-----------------
+
+By default, Traffic Server does *not* cache objects with the following
+**request headers**:
+
+-  ``Authorization``: header
+
+-  ``Cache-Control: no-store`` header
+
+-  ``Cache-Control: no-cache`` header
+
+   To configure Traffic Server to ignore the ``Cache-Control: no-cache``
+   header, refer to `Configuring Traffic Server to Ignore Client
+   no-cache Headers <#ConfiguringTSIgnoreClientnocacheHeaders>`_.
+
+-  ``Cookie``: header (for text objects)
+
+   By default, Traffic Server caches objects served in response to
+   requests that contain cookies (unless the object is text). You can
+   configure Traffic Server to not cache cookied content of any type,
+   cache all cookied content, or cache cookied content that is of image
+   type only. For more information, refer to `Caching Cookied
+   Objects <#CachingCookiedObjects>`_.
+
+Configuring Traffic Server to Ignore Client no-cache Headers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, Traffic Server strictly observes client
+``Cache-Control: no-cache`` directives. If a requested object contains a
+``no-cache`` header, then Traffic Server forwards the request to the
+origin server even if it has a fresh copy in cache. You can configure
+Traffic Server to ignore client ``no-cache`` directives such that it
+ignores ``no-cache`` headers from client requests and serves the object
+from its cache.
+
+To configure Traffic Server to ignore client ``no-cache`` headers
+
+3. Edit the following variable in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.cache.ignore_client_no_cache``* <configuration-files/records.config#proxy.config.cache.ignore_client_no_cache>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Origin Server Directives
+------------------------
+
+By default, Traffic Server does *not* cache objects with the following
+**response** **headers**:
+
+-  ``Cache-Control: no-store`` header
+-  ``Cache-Control: private`` header
+-  ``WWW-Authenticate``: header
+
+   To configure Traffic Server to ignore\ ``WWW-Authenticate`` headers,
+   refer to `Configuring Traffic Server to Ignore WWW-Authenticate
+   Headers <#ConfiguringTrafficEdgeIgnoreWWWAuthenticateHeaders>`_.
+
+-  ``Set-Cookie``: header
+-  ``Cache-Control: no-cache`` headers
+
+   To configure Traffic Server to ignore ``no-cache`` headers, refer to
+   `Configuring Traffic Server to Ignore Server no-cache
+   Headers <#ConfiguringTrafficEdgeIgnoreServerNoCacheHeaders>`_.
+
+-  ``Expires``: header with value of 0 (zero) or a past date
+
+Configuring Traffic Server to Ignore Server no-cache Headers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, Traffic Server strictly observes ``Cache-Control: no-cache``
+directives. A response from an origin server with a ``no-cache`` header
+is not stored in the cache and any previous copy of the object in the
+cache is removed. If you configure Traffic Server to ignore ``no-cache``
+headers, then Traffic Server also ignores ``no-``\ **``store``**
+headers. The default behavior of observing ``no-cache`` directives is
+appropriate in most cases.
+
+To configure Traffic Server to ignore server ``no-cache`` headers
+
+3. Edit the following variable in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.cache.ignore_server_no_cache``* <configuration-files/records.config#proxy.config.cache.ignore_server_no_cache>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Configuring Traffic Server to Ignore WWW-Authenticate Headers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, Traffic Server does not cache objects that contain
+``WWW-Authenticate`` response headers. The ``WWW-Authenticate`` header
+contains authentication parameters the client uses when preparing the
+authentication challenge response to an origin server.
+
+When you configure Traffic Server to ignore origin server
+``WWW-Authenticate`` headers, all objects with ``WWW-Authenticate``
+headers are stored in the cache for future requests. However, the
+default behavior of not caching objects with ``WWW-Authenticate``
+headers is appropriate in most cases. Only configure Traffic Server to
+ignore server ``WWW-Authenticate`` headers if you are knowledgeable
+about HTTP 1.1.
+
+To configure Traffic Server to ignore server ``WWW-Authenticate``
+headers
+
+3. Edit the following variable in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.cache.ignore_authentication``* <configuration-files/records.config#proxy.config.cache.ignore_authentication>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Configuration Directives
+------------------------
+
+In addition to client and origin server directives, Traffic Server
+responds to directives you specify through configuration options and
+files.
+
+You can configure Traffic Server to do the following:
+
+-  *Not* cache any HTTP objects (refer to `Disabling HTTP Object
+   Caching <#DisablingHTTPObjectCaching>`_).
+-  Cache **dynamic content** - that is, objects with URLs that end in
+   **``.asp``** or contain a question mark (**``?``**), semicolon
+   (**``;``**), or **``cgi``**. For more information, refer to `Caching
+   Dynamic Content <#CachingDynamicContent>`_.
+-  Cache objects served in response to the ``Cookie:`` header (refer to
+   `Caching Cookied Objects) <#CachingCookiedObjects>`_.
+-  Observe ``never-cache`` rules in the
+   ```cache.config`` <../configuration-files/cache.config>`_ file.
+
+Disabling HTTP Object Caching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, Traffic Server caches all HTTP objects except those for
+which you have set
+```never-cache`` <configuration-files/cache.config#action>`_ rules in
+the ```cache.config`` <../configuration-files/cache.config>`_ file. You
+can disable HTTP object caching so that all HTTP objects are served
+directly from the origin server and never cached, as detailed below.
+
+To disable HTTP object caching manually
+
+3. Edit the following variable in
+   ```records.config`` <configuration-files/records.config>`_
+
+   -  `*``proxy.config.cache.http``* <configuration-files/records.config#proxy.config.cache.http>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Caching Dynamic Content
+~~~~~~~~~~~~~~~~~~~~~~~
+
+A URL is considered **dynamic** if it ends in **``.asp``** or contains a
+question mark (**``?``**), a semicolon (**``;``**), or **``cgi``**. By
+default, Traffic Server caches dynamic content. You can configure the
+system to ignore dyanamic looking content, although this is recommended
+only if the content is *truely* dyanamic, but fails to advertise so with
+appropriate ``Cache-Control`` headers.
+
+To configure Traffic Server's cache behaviour in regard to dynamic
+content
+
+3. Edit the following variable in
+   ```records.config`` <configuration-files/records.config>`_
+
+   -  `*``proxy.config.http.cache.cache_urls_that_look_dynamic``* <configuration-files/records.config#proxy.config.http.cache.cache_urls_that_look_dynamic>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Caching Cookied Objects
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. XXX This should be extended to xml as well!
+
+By default, Traffic Server caches objects served in response to requests
+that contain cookies. This is true for all types of objects except for
+text. Traffic Server does not cache cookied text content because object
+headers are stored along with the object, and personalized cookie header
+values could be saved with the object. With non-text objects, it is
+unlikely that personalized headers are delivered or used.
+
+You can reconfigure Traffic Server to:
+
+-  *Not* cache cookied content of any type.
+-  Cache cookied content that is of image type only.
+-  Cache all cookied content regardless of type.
+
+To configure how Traffic Server caches cookied content
+
+3. Edit the following variable in
+   ```records.config`` <configuration-files/records.config>`_
+
+   -  `*``proxy.config.cache_responses_to_cookies``* <configuration-files/records.config#proxy.config.cache_responses_to_cookies>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Forcing Object Caching
+======================
+
+You can force Traffic Server to cache specific URLs (including dynamic
+URLs) for a specified duration, regardless of ``Cache-Control`` response
+headers.
+
+To force document caching
+
+1. Add a rule for each URL you want Traffic Server to pin to the cache
+   ```cache.config`` <../configuration-files/cache.config>`_:
+
+   ::
+       url_regex=^https?://(www.)?apache.org/dev/ ttl-in-cache=6h
+
+2. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Caching HTTP Alternates
+=======================
+
+Some origin servers answer requests to the same URL with a variety of
+objects. The content of these objects can vary widely, according to
+whether a server delivers content for different languages, targets
+different browsers with different presentation styles, or provides
+different document formats (HTML, XML). Different versions of the same
+object are termed **alternates** and are cached by Traffic Server based
+on ``Vary`` response headers. You can specify additional request and
+response headers for specific ``Content-Type``\ s that Traffic Server
+will identify as alternates for caching. You can also limit the number
+of alternate versions of an object allowed in the cache.
+
+Configuring How Traffic Server Caches Alternates
+------------------------------------------------
+
+To configure how Traffic Server caches alternates, follow the steps
+below
+
+3. Edit the following variables in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.http.cache.enable_default_vary_headers``* <configuration-files/records.config#proxy.config.http.cache.enable_default_vary_headers>`_
+   -  `*``proxy.config.http.cache.vary_default_text``* <configuration-files/records.config#proxy.config.http.cache.vary_default_text>`_
+   -  `*``proxy.config.http.cache.vary_default_images``* <configuration-files/records.config#proxy.config.cache.vary_default_images>`_
+   -  `*``proxy.config.http.cache.vary_default_other``* <configuration-files/records.config#proxy.config.http.cache.vary_default_other>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+**Note:** If you specify ``Cookie`` as the header field on which to vary
+in the above variables, make sure that the variable
+`*``proxy.config.cache.cache_responses_to_cookies``* <configuration-files/records.config#proxy.config.cache.cache_responses_to_cookies>`_
+is set appropriately.
+
+Limiting the Number of Alternates for an Object
+-----------------------------------------------
+
+You can limit the number of alternates Traffic Server can cache per
+object (the default is 3).
+
+**IMPORTANT:** Large numbers of alternates can affect Traffic Server
+cache performance because all alternates have the same URL. Although
+Traffic Server can look up the URL in the index very quickly, it must
+scan sequentially through available alternates in the object store.
+
+To limit the number of alternates
+
+3. Edit the following variable in
+   ```records.config`` <../configuration-files/records.config>`_
+
+   -  `*``proxy.config.cache.limits.http.max_alts``* <configuration-files/records.config#proxy.config.cache.limits.http.max_alts>`_
+
+4. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+
+Using Congestion Control
+========================
+
+The **Congestion Control** option enables you to configure Traffic
+Server to stop forwarding HTTP requests to origin servers when they
+become congested. Traffic Server then sends the client a message to
+retry the congested origin server later.
+
+To use the **Congestion Control** option, you must perform the following
+tasks:
+
+3. Set the following variable in
+   ```records.config`` <configuration-files/records.config>`_
+
+   -  `*``proxy.config.http.congestion_control.enabled``* <configuration-files/records.config#proxy.config.http.congestion_control.enabled>`_
+      to ``1``
+
+-  Create rules in the
+   ```congestion.config`` <configuration-files/congestion.config>`_
+   file to specify:
+-  which origin servers Traffic Server tracks for congestion
+-  the timeouts Traffic Server uses, depending on whether a server is
+   congested
+-  the page Traffic Server sends to the client when a server becomes
+   congested
+-  if Traffic Server tracks the origin servers per IP address or per
+   hostname
+
+9. Run the command ``traffic_line -x`` to apply the configuration
+   changes.
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/index.en.rst b/doc/admin/index.en.rst
new file mode 100644
index 0000000..d959287
--- /dev/null
+++ b/doc/admin/index.en.rst
@@ -0,0 +1,314 @@
+Apache Traffic Server Title: Administrators's Guide - Overview
+**************************************************************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+ 
+   http://www.apache.org/licenses/LICENSE-2.0
+ 
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+
+
+Apache Traffic Server™ speeds Internet access, enhances website
+performance, and delivers unprecedented web hosting capabilities.
+
+This chapter discusses the following topics:
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   getting-started.en
+   http-proxy-caching.en
+   reverse-proxy-http-redirects.en
+   forward-proxy.en
+   transparent-proxy.en
+   explicit-proxy-caching.en
+   hierachical-caching.en
+   configuring-cache.en
+   monitoring-traffic.en
+   configuring-traffic-server.en
+   cluster-howto.en
+   security-options.en
+   working-log-files.en
+   event-logging-formats.en
+   configuration-files.en
+   traffic-line-commands.en
+   traffic-server-error-messages.en
+   faqs.en
+   plugins.en
+
+
+What Is Apache Traffic Server?
+==============================
+
+Global data networking has become part of everyday life: Internet users
+request billions of documents and terabytes of data, on a daily basis,
+to and from all parts of the world. Information is free, abundant, and
+accessible. Unfortunately, global data networking can also be a
+nightmare for IT professionals as they struggle with overloaded servers
+and congested networks. It can be challenging to consistently and
+reliably accommodate society’s growing data demands.
+
+Traffic Server is a high-performance web proxy cache that improves
+network efficiency and performance by caching frequently-accessed
+information at the edge of the network. This brings content physically
+closer to end users, while enabling faster delivery and reduced
+bandwidth use. Traffic Server is designed to improve content delivery
+for enterprises, Internet service providers (ISPs), backbone providers,
+and large intranets by maximizing existing and available bandwidth.
+
+Traffic Server Deployment Options
+=================================
+
+To best suit your needs, Traffic Server can be deployed in several ways:
+
+-  As a web proxy cache
+-  As a reverse proxy
+-  In a cache hierarchy
+
+The following sections provide a summary of these Traffic Server
+deployment options. Please keep in mind that with every of these options
+Traffic Server can be run as a *single instance*, or as a *multi-node
+cluster*.
+
+Traffic Server as a Web Proxy Cache
+-----------------------------------
+
+As a web proxy cache, Traffic Server receives user requests for web
+content as those requests travel to the destined web server (origin
+server). If Traffic Server contains the requested content, then it
+serves the content directly. If the requested content is not available
+from cache, then Traffic Server acts as a proxy: it obtains the content
+from the origin server on the user’s behalf and also keeps a copy to
+satisfy future requests.
+
+Traffic Server provides explicit proxy caching, in which the user’s
+client software must be configured to send requests directly to Traffic
+Server. Explicit proxy caching is described in the `Explicit Proxy
+Caching <explicit-proxy-caching>`_ chapter.
+
+Traffic Server as a Reverse Proxy
+---------------------------------
+
+As a reverse proxy, Traffic Server is configured to be the origin server
+to which the user is trying to connect (typically, the origin server’s
+advertised hostname resolves to Traffic Server, which acts as the real
+origin server). The reverse proxy feature is also called server
+acceleration. Reverse proxy is described in more detail in `Reverse
+Proxy and HTTP Redirects <reverse-proxy-http-redirects>`_.
+
+Traffic Server in a Cache Hierarchy
+-----------------------------------
+
+Traffic Server can participate in flexible cache hierarchies, in which
+Internet requests not fulfilled from one cache are routed to other
+regional caches, thereby leveraging the contents and proximity of nearby
+caches. In a hierarchy of proxy servers, Traffic Server can act either
+as a parent or a child cache to other Traffic Server systems or to
+similar caching products.
+
+Traffic Server supports ICP (Internet Cache Protocol) peering.
+Hierarchical caching is described in more detail in `Hierarchical
+Caching <hierachical-caching>`_.
+
+Traffic Server Components
+=========================
+
+Traffic Server consists of several components that work together to form
+a web proxy cache you can easily monitor and configure. These main
+components are described below.
+
+The Traffic Server Cache
+------------------------
+
+The Traffic Server cache consists of a high-speed object database called
+the object store. The object store indexes objects according to URLs and
+associated headers. Using sophisticated object management, the object
+store can cache alternate versions of the same object (perhaps in a
+different language or encoding type). It can also efficiently store very
+small and very large objects, thereby minimizing wasted space. When the
+cache is full, Traffic Server removes stale data to ensure that the most
+requested objects are readily available and fresh.
+
+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 to use remaining disks. If all of
+the cache disks fail, then Traffic Server switches to proxy-only mode.
+You can partition the cache to reserve a certain amount of disk space
+for storing data for specific protocols and origin servers. For more
+information about the cache, see `Configuring the
+Cache <configuring-cache>`_.
+
+The RAM Cache
+-------------
+
+Traffic Server maintains a small RAM cache that contains extremely
+popular objects. This RAM cache serves the most popular objects as fast
+as possible and reduces load on disks, especially during temporary
+traffic peaks. You can configure the RAM cache size to suit your needs;
+for detailed information, refer to `Changing the Size of the RAM
+Cache <configuring-cache#ChangingSizeofRAMCache>`_.
+
+The Host Database
+-----------------
+
+The Traffic Server host database stores the domain name server (DNS)
+entries of origin servers to which Traffic Server connects to fulfill
+user requests. This information is used to adapt future protocol
+interactions and optimize performance. Along with other information, the
+host database tracks:
+
+-  DNS information (for fast conversion of hostnames to IP addresses)
+-  The HTTP version of each host (so advanced protocol features can be
+   used with hosts running modern servers)
+-  Host reliability and availability information (so users will not wait
+   for servers that are not running)
+
+The DNS Resolver
+----------------
+
+Traffic Server includes a fast, asynchronous DNS resolver to streamline
+conversion of hostnames to IP addresses. Traffic Server implements the
+DNS resolver natively by directly issuing DNS command packets rather
+than relying on slower, conventional resolver libraries. Since many DNS
+queries can be issued in parallel and a fast DNS cache maintains popular
+bindings in memory, DNS traffic is reduced.
+
+Traffic Server Processes
+------------------------
+
+Traffic Server contains three processes that work together to serve
+requests and manage/control/monitor the health of the system. The three
+processes are described below:
+
+-  The ``traffic_server`` process is the transaction processing engine
+   of Traffic Server. It is responsible for accepting connections,
+   processing protocol requests, and serving documents from the cache or
+   origin server.
+
+-  The ``traffic_manager`` process is the command and control facility
+   of the Traffic Server, responsible for launching, monitoring, and
+   reconfiguring the ``traffic_server`` process. The ``traffic_manager``
+   process is also responsible for the proxy autoconfiguration port, the
+   statistics interface, cluster administration, and virtual IP
+   failover.
+
+   If the ``traffic_manager`` process detects a ``traffic_server``
+   process failure, it instantly restarts the process but also maintains
+   a connection queue of all incoming requests. All incoming connections
+   that arrive in the several seconds before full server restart are
+   saved in the connection queue and processed in first-come,
+   first-served order. This connection queueing shields users from any
+   server restart downtime.
+
+-  The ``traffic_cop`` process monitors the health of both the
+   ``traffic_server`` and ``traffic_manager`` processes. The
+   ``traffic_cop`` process periodically (several times each minute)
+   queries the ``traffic_server`` and ``traffic_manager`` process by
+   issuing heartbeat requests to fetch synthetic web pages. In the event
+   of failure (if no response is received within a timeout interval or
+   if an incorrect response is received), ``traffic_cop`` restarts the
+   ``traffic_manager`` and ``traffic_server`` processes.
+
+The figure below illustrates the three Traffic Server processes.
+
+.. figure:: ../_static/images/admin/process.jpg
+   :align: center
+   :alt: Illustration of the three Traffic Server Processes
+
+   Illustration of the three Traffic Server Processes
+
+Administration Tools
+--------------------
+
+Traffic Server offers the following administration options:
+
+-  The Traffic Line command-line interface is a text-based interface
+   from which you can monitor Traffic Server performance and network
+   traffic, as well as configure the Traffic Server system. From Traffic
+   Line, you can execute individual commands or script a series of
+   commands in a shell.
+-  The Traffic Shell command-line interface is an additional
+   command-line tool that enables you to execute individual commands
+   that monitor and configure the Traffic Server system.
+-  Various configuration files enable you to configure Traffic Server
+   through a simple file-editing and signal-handling interface. Any
+   changes you make through Traffic Line or Traffic Shell are
+   automatically made to the configuration files as well.
+-  Finally there is a clean C API which can be put to good use from a
+   multitude of languages. The Traffic Server Admin Client demonstrates
+   this for Perl.
+
+Traffic Analysis Options
+========================
+
+Traffic Server provides several options for network traffic analysis and
+monitoring:
+
+-  Traffic Line and Traffic Shell enable you to collect and process
+   statistics obtained from network traffic information.
+
+-  Transaction logging enables you to record information (in a log file)
+   about every request Traffic Server receives and every error it
+   detects. By analyzing the log files, you can determine how many
+   clients used the Traffic Server cache, how much information each of
+   them requested, and what pages were most popular. You can also see
+   why a particular transaction was in error and what state the Traffic
+   Server was in at a particular time; for example, you can see that
+   Traffic Server was restarted or that cluster communication timed out.
+
+   Traffic Server supports several standard log file formats, such as
+   Squid and Netscape, and its own custom format. You can analyze the
+   standard format log files with off-the-shelf analysis packages. To
+   help with log file analysis, you can separate log files so that they
+   contain information specific to protocol or hosts.
+
+Traffic analysis options are described in more detail in `Monitoring
+Traffic <monitoring-traffic>`_.
+
+Traffic Server logging options are described in `Working with Log
+Files <working-log-files>`_.
+
+Traffic Server Security Options
+===============================
+
+Traffic Server provides numerous options that enable you to establish
+secure communication between the Traffic Server system and other
+computers on the network. Using the security options, you can do the
+following:
+
+-  Control client access to the Traffic Server proxy cache.
+-  Configure Traffic Server to use multiple DNS servers to match your
+   site's security configuration. For example, Traffic Server can use
+   different DNS servers, depending on whether it needs to resolve
+   hostnames located inside or outside a firewall. This enables you to
+   keep your internal network configuration secure while continuing to
+   provide transparent access to external sites on the Internet.
+-  Configure Traffic Server to verify that clients are authenticated
+   before they can access content from the Traffic Server cache.
+-  Secure connections in reverse proxy mode between a client and Traffic
+   Server, and Traffic Server and the origin server, using the SSL
+   termination option.
+-  Control access via SSL (Secure Sockets Layer).
+
+Traffic Server security options are described in more detail in
+`Security Options <security-options>`_.
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`


Mime
View raw message