trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [15/51] trafficserver git commit: Documentation reorganization
Date Tue, 03 Nov 2015 06:09:51 GMT
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/testing-with-vagrant/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/testing-with-vagrant/index.en.rst b/doc/developer-guide/testing-with-vagrant/index.en.rst
new file mode 100644
index 0000000..c92c061
--- /dev/null
+++ b/doc/developer-guide/testing-with-vagrant/index.en.rst
@@ -0,0 +1,258 @@
+.. 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.
+
+.. include:: ../../common.defs
+
+.. _developer-testing-with-vagrant:
+
+Using Vagrant to Test |TS|
+**************************
+
+The |ATS| project's official repository includes a Vagrantfile, intended to ease
+the process of creating environments suitable for building and testing |TS|,
+where all the necessary dependencies are installed automatically for a variety
+of operating systems and common distribution releases.
+
+.. epigraph::
+
+   Vagrant is a tool for building complete development environments. With an
+   easy-to-use workflow and focus on automation, Vagrant lowers development
+   environment setup time, increases development/production parity, and makes
+   the "works on my machine" excuse a relic of the past.
+
+   -- `VagrantUp website <https://www.vagrantup.com/about.html>`_
+
+Vagrant can be used in combination with any of the popular configurtion
+management and automation tools, such as `Chef <https://www.chef.io/chef/>`_,
+`Puppet <https://puppetlabs.com/>`_, `Ansible <http://www.ansible.com/home>`_,
+and more. The Vagrantfile included in the |TS| repository happens to make use
+of Puppet.
+
+Installing Vagrant and Dependencies
+===================================
+
+VirtualBox
+----------
+
+The virtualization software `VirtualBox <https://www.virtualbox.org/>`_ is
+required to create and run the virtual machines created by the included project
+Vagrantfile.
+
+VirtualBox can be obtained by free from the official website, and many
+distributions provide their own packages as well. No special configuration of
+the software is required.
+
+Vagrant
+-------
+
+A fairly recent version of `Vagrant <https://www.vagrantup.com/downloads.html>`_
+is necessary to use the included Vagrantfile. While older versions of Vagrant
+could be installed through the Ruby Gems facility, modern versions are only
+provided as distribution specific packages.
+
+NFS Server
+----------
+
+The project Vagrantfile uses the NFS shared folders support of VirtualBox to
+mount the same directory in which the Vagrantfile is located on your host
+machine as a network directory inside the virtual machine. For this to work,
+your host machine must have an NFS server installed and running, and the user
+under which you run the vagrant commands must have sudo permissions to modify
+the NFS exports configuration and restart the NFS service.
+
+The virtual machine created by Vagrant will still function without a working
+NFS server on your host machine, but you will not be able to access the shared
+folder which includes the entire |TS| source tree. You may opt to modify the
+Vagrantfile to use a method other than NFS, as per the `Vagrant documentation
+<https://docs.vagrantup.com/v2/synced-folders/basic_usage.html>`_.
+
+Managing Virtual Machines
+=========================
+
+Listing Available Machines
+--------------------------
+
+The included Vagrantfile defines many variations of operating systems,
+releases, and architectures. To see a complete list of the virtual machine
+options available to you, run the command ``vagrant status`` from within the
+same directory as the Vagrantfile. The command may take a few moments to run as
+the configurations defined in the Vagrantfile are evaluated, and calls are made
+to the underlying VirtualBox utilities to check for the existence and
+operational state of each possibility.  You should expect to see output along
+the lines of::
+
+    $ vagrant status
+    Current machine states:
+
+    saucy32                   not created (virtualbox)
+    raring32                  not created (virtualbox)
+    quantal32                 not created (virtualbox)
+    precise32                 not created (virtualbox)
+    trusty32                  not created (virtualbox)
+    saucy64                   not created (virtualbox)
+    raring64                  not created (virtualbox)
+    quantal64                 not created (virtualbox)
+    precise64                 not created (virtualbox)
+    trusty64                  running (virtualbox)
+    freebsd                   not created (virtualbox)
+    omnios                    not created (virtualbox)
+    lucid64                   not created (virtualbox)
+    fedora18                  not created (virtualbox)
+    centos63                  not created (virtualbox)
+    centos59                  not created (virtualbox)
+    centos64                  not created (virtualbox)
+    debian7                   not created (virtualbox)
+    sles11                    not created (virtualbox)
+    oel63                     not created (virtualbox)
+
+    This environment represents multiple VMs. The VMs are all listed
+    above with their current state. For more information about a specific
+    VM, run `vagrant status NAME`.
+
+Creating and Destroying
+-----------------------
+
+Creation and destruction of virtual machines with Vagrant is very simple. To
+bring a new virtual machine into existence, run the following command from the
+same directory in which the Vagrantfile is located::
+
+    vagrant up <name>
+
+Where ``<name>`` should be the specific operating system release you wish to
+use for the virtual machine. For example, to test |TS| in a CentOS 6.4
+environment, you would run::
+
+    vagrant up centos64
+
+Running the ``vagrant up`` command for a virtual machine which does not exist
+yet (or has previously been deleted) will create a brand new virtual machine,
+using the appropriate image (called a *basebox* in Vagrant parlance), as well as
+provision the machine according to any configuration management rules specified
+in the Vagrantfile.
+
+Similarly, you may destroy the virtual machine when you are finished by running
+the command::
+
+    vagrant destroy <name>
+
+Or if you wish to only stop the virtual machine temporarily without deleting it,
+you may run::
+
+    vagrant halt <name>
+
+A halted virtual machine is started back up with the same ``vagrant up`` command
+shown earlier. The difference is that Vagrant will recognize the box already
+exists and do nothing more than start the vm process and configure the virtual
+networking interfaces on your host. Any configuration management hooks in the
+Vagrantfile will be skipped.
+
+Logging In
+----------
+
+Logging into a virtual machine created with Vagrant may be accomplished in a
+couple different ways. The easiest is to let Vagrant itself figure out where the
+machine is and how to properly authenticate you to it::
+
+    vagrant ssh <name>
+
+Using that command from within the same directory as the Vagrantfile allows you
+to skip figuring out what virtual network interface has been attached to the
+machine, what local port may be assigned to handle SSH forwarding, and so on.
+As long as the virtual machine was already running, you will be quickly dropped
+into a local shell in the virtual machine as the ``vagrant`` user.
+
+.. important::
+
+   Vagrant by default uses a widely-shared private RSA key on newly created
+   virtual machines (that are built on public basebox images). The default user
+   on these baseboxes is also configured for password-less sudo permissions.
+   This is very clearly insecure, but Vagrant is designed for local testing and
+   development, not production (or other public) uses, so the project has made
+   the philosophical trade-off in favor of ease of use.
+
+Alternatively, you may SSH directly to the virtual machine. Because the virtual
+machines are configured to use only the private virtual network layer provided
+by VirtualBox, you cannot directly. Instead, VirtualBox has created a local port
+mapping automatically which should be used. There is no fixed, pre-determined
+port mapping that will be universally valid, as Vagrant and VirtualBox may be
+used together to run an arbitrary number of virtual machines simultaneously,
+each provisioned in any order, and defined by any number and variety of
+Vagrantfiles.
+
+The correct way to determine what port Vagrant and VirtualBox have used to map
+to a given virtual machine is to run the following command from within the same
+directory as your Vagrantfile::
+
+    vagrant ssh-config <name>
+
+That will output a configuration block, suitable for inclusion in your local
+``~/.ssh/config`` file. Note specifically, in addition to the port, the path to
+the private key you will need to use as your identity when attempting to log
+into the virtual machine.
+
+Shared Host Folders
+-------------------
+
+VirtualBox provides a facility for mounting directories from your host machine
+as filesystems inside the virtual machines. The |TS| Vagrantfile makes use of
+this feature to mount its own source tree in a predictable location in the
+virtual environment.
+
+Multiple methods are available for this, including NFS, CIFS, and simulated
+block devices. The |TS| project opts to use NFS for its simplicity, speed,
+support for features such as symlinks, and wide interoperability across the
+various guest operating systems included in the Vagrantfile. Within the included
+Vagrantfile, you can see the following line::
+
+    config.vm.synced_folder ".", "/opt/src/trafficserver.git", :nfs => true
+
+This directs VirtualBox to mount the directory in which the |TS| Vagrantfile
+resides as an NFS mount inside the virtual machine at the path
+``/opt/src/trafficserver.git``. Additional host directories may be mounted in
+the same manner should the need arise.
+
+Forwarding Custom Ports
+-----------------------
+
+.. TODO::
+
+    This is trickier to do than it may seem at first. The easiest method is to
+    just rely on the VirtualBox GUI or underlying vboxmanage commands and set
+    up custom port mappings by hand. To do it dynamically brings up the problem
+    of port conflict resolution, especially with the |TS| Vagrantfile which
+    defines so many different virtual machines, any number of which may be run
+    simultaneously.
+
+Building |TS| Inside Vagrant
+============================
+
+Producing |TS| builds from within the Vagrant managed virtual machines is
+effectively no different than in any other environment. The same directory in
+which the Vagrantfile exists will be mounted via NFS inside the virtual machine
+at the path ``/opt/src/trafficserver.git``.
+
+.. note::
+
+   If you have run ``autoconf`` or ``configure`` from outside the virtual
+   machine environment against the same Git working copy as is mounted inside
+   the virtual machine, you will encounter failures should you attempt to run
+   any of the Make targets inside the VM. Any build related commands should be
+   run inside of the virtual machine. Additionally, if you are running more
+   than one virtual machine simultaneously, remember that they are each using
+   the same NFS export on your host machine.
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/troubleshooting-tips.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/troubleshooting-tips.en.rst b/doc/developer-guide/troubleshooting-tips.en.rst
new file mode 100644
index 0000000..3a312bf
--- /dev/null
+++ b/doc/developer-guide/troubleshooting-tips.en.rst
@@ -0,0 +1,55 @@
+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.
+
+This appendix lists the following troubleshooting tips.
+
+.. toctree::
+   :maxdepth: 2
+
+   troubleshooting-tips/unable-to-load-plugins.en
+   troubleshooting-tips/unable-to-debug-tags.en
+   troubleshooting-tips/using-a-debugger.en
+   troubleshooting-tips/debugging-memory-leaks.en
+
+
+Unable to Compile Plugins
+-------------------------
+
+The process for compiling a shared library varies with the platform
+used, so the Traffic Server API includes the :program:`tsxs` script you can use
+to create shared libraries on all supported Traffic Server platforms.
+
+Example
+~~~~~~~
+
+Assuming the sample program is stored in the file ``hello-world.c``, you
+could use the following commands to building a shared library:
+
+::
+
+        tsxs -c hello-world.c -o hello-world.so
+
+To install this plugin in your ``plugindir`` use the equivalent of sudo
+on your platform to execute:
+
+::
+
+        sudo tsxs -o hello-world.so -i
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst b/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst
new file mode 100644
index 0000000..6d360b4
--- /dev/null
+++ b/doc/developer-guide/troubleshooting-tips/unable-to-load-plugins.en.rst
@@ -0,0 +1,40 @@
+.. 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.
+
+.. include:: ../../common.defs
+
+.. _developer-troubleshooting-unable-to-load-plugins:
+
+Unable to Load Plugins
+**********************
+
+To load plugins, follow the steps below.
+
+#. Make sure that your plugin source code contains an ``TSPluginInit``
+   initialization function.
+
+#. Compile your plugin source code, creating a shared library.
+
+#. Add an entry to the ``plugin.config`` file for your plugin.
+
+#. Add the path to your plugin shared library to the :file:`records.config`
+   file.
+
+#. Restart Traffic Server.
+
+For detailed information about each step above, refer to
+:ref:`developer-plugins-getting-started-simple-plugin`.

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/ext/traffic-server.py
----------------------------------------------------------------------
diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py
index 67b401c..975efc4 100644
--- a/doc/ext/traffic-server.py
+++ b/doc/ext/traffic-server.py
@@ -28,6 +28,7 @@
 
 from docutils import nodes
 from docutils.parsers import rst
+from docutils.parsers.rst import directives
 from sphinx.domains import Domain, ObjType, std
 from sphinx.roles import XRefRole
 from sphinx.locale import l_, _
@@ -142,6 +143,123 @@ class TSConfVarRef(XRefRole):
     def process_link(self, env, ref_node, explicit_title_p, title, target):
         return title, target
 
+def metrictypes(typename):
+    return directives.choice(typename.lower(), ('counter','gauge','derivative','flag','text'))
+
+def metricunits(unitname):
+    return directives.choice(unitname.lower(), ('ratio','percent','kbits','mbits','bytes','kbytes','mbytes','nanoseconds','microseconds','milliseconds','seconds'))
+
+class TSStat(std.Target):
+    """
+    Description of a traffic server statistic.
+
+    Argument is the JSON stat group ("global", etc.) in which the statistic is
+    returned, then the statistic name as used by traffic_line/stats_over_http,
+    followed by the value type of the statistic ('string', 'integer'), and
+    finally an example value.
+
+    Descriptive text should follow, indented.
+
+    Then the bulk description (if any) undented. This should be considered
+    equivalent to the Doxygen short and long description.
+    """
+
+    option_spec = {
+        'type': metrictypes,
+        'unit': metricunits,
+        'introduced' : rst.directives.unchanged,
+        'deprecated' : rst.directives.unchanged,
+        'ungathered' : rst.directives.flag
+    }
+    required_arguments = 3
+    optional_arguments = 1 # example value is optional
+    final_argument_whitespace = True
+    has_content = True
+
+    def make_field(self, tag, value):
+        field = nodes.field();
+        field.append(nodes.field_name(text=tag))
+        body = nodes.field_body()
+        if (isinstance(value, basestring)):
+            body.append(sphinx.addnodes.compact_paragraph(text=value))
+        else:
+            body.append(value)
+        field.append(body)
+        return field
+
+    # External entry point
+    def run(self):
+        env = self.state.document.settings.env
+        stat_example = None
+        stat_group, stat_name, stat_type = self.arguments[0:3]
+        if (len(self.arguments) > 3):
+            stat_example = self.arguments[3]
+
+        # First, make a generic desc() node to be the parent.
+        node = sphinx.addnodes.desc()
+        node.document = self.state.document
+        node['objtype'] = 'stat'
+
+        # Next, make a signature node. This creates a permalink and a
+        # highlighted background when the link is selected.
+        title = sphinx.addnodes.desc_signature(stat_name, '')
+        title['ids'].append(nodes.make_id('stat-'+stat_name))
+        title['names'].append(stat_name)
+        title['first'] = False
+        title['objtype'] = 'stat'
+        self.add_name(title)
+        title.set_class('ts-stat-title')
+
+        # Finally, add a desc_name() node to display the name of the
+        # configuration variable.
+        title += sphinx.addnodes.desc_name(stat_name, stat_name)
+
+        node.append(title)
+
+        # This has to be a distinct node before the title. if nested then
+        # the browser will scroll forward to just past the title.
+        anchor = nodes.target('', '', names=[stat_name])
+        # Second (optional) arg is 'msgNode' - no idea what I should pass for that
+        # or if it even matters, although I now think it should not be used.
+        self.state.document.note_explicit_target(title)
+        env.domaindata['ts']['stat'][stat_name] = env.docname
+
+        fl = nodes.field_list()
+        fl.append(self.make_field('Collection', stat_group))
+        if ('type' in self.options):
+            fl.append(self.make_field('Type', self.options['type']))
+        if ('unit' in self.options):
+            fl.append(self.make_field('Units', self.options['unit']))
+        fl.append(self.make_field('Datatype', stat_type))
+        if ('introduced' in self.options and len(self.options['introduced']) > 0):
+            fl.append(self.make_field('Introduced', self.options['introduced']))
+        if ('deprecated' in self.options):
+            if (len(self.options['deprecated']) > 0):
+                fl.append(self.make_field('Deprecated', self.options['deprecated']))
+            else:
+                fl.append(self.make_field('Deprecated', 'Yes'))
+        if ('ungathered' in self.options):
+            fl.append(self.make_field('Gathered', 'No'))
+        if (stat_example):
+            fl.append(self.make_field('Example', stat_example))
+
+        # Get any contained content
+        nn = nodes.compound();
+        self.state.nested_parse(self.content, self.content_offset, nn)
+
+        # Create an index node so that Sphinx adds this statistic to the
+        # index. nodes.make_id() specifies the link anchor name that is
+        # implicitly generated by the anchor node above.
+        indexnode = sphinx.addnodes.index(entries=[])
+        indexnode['entries'].append(
+            ('single', _('%s') % stat_name, nodes.make_id(stat_name), '')
+        )
+
+        return [ indexnode, node, fl, nn ]
+
+class TSStatRef(XRefRole):
+    def process_link(self, env, ref_node, explicit_title_p, title, target):
+        return title, target
 
 class TrafficServerDomain(Domain):
     """
@@ -153,23 +271,28 @@ class TrafficServerDomain(Domain):
     data_version = 2
 
     object_types = {
-        'cv': ObjType(l_('configuration variable'), 'cv')
+        'cv': ObjType(l_('configuration variable'), 'cv'),
+        'stat': ObjType(l_('statistic'), 'stat')
     }
 
     directives = {
-        'cv' : TSConfVar
+        'cv' : TSConfVar,
+        'stat' : TSStat
     }
 
     roles = {
-        'cv' : TSConfVarRef()
+        'cv' : TSConfVarRef(),
+        'stat' : TSStatRef()
     }
 
     initial_data = {
-        'cv' : {} # full name -> docname
+        'cv' : {}, # full name -> docname
+        'stat' : {}
     }
 
     dangling_warnings = {
-        'cv' : "No definition found for configuration variable '%(target)s'"
+        'cv' : "No definition found for configuration variable '%(target)s'",
+        'stat' : "No definition found for statistic '%(target)s'"
     }
 
     def clear_doc(self, docname):
@@ -177,12 +300,18 @@ class TrafficServerDomain(Domain):
         for var, doc in cv_list.items():
             if doc == docname:
                 del cv_list[var]
+        stat_list = self.data['stat']
+        for var, doc in stat_list.items():
+            if doc == docname:
+                del stat_list[var]
 
     def find_doc(self, key, obj_type):
         zret = None
 
         if obj_type == 'cv' :
             obj_list = self.data['cv']
+        elif obj_type == 'stat' :
+            obj_list = self.data['stat']
         else:
             obj_list = None
 
@@ -199,6 +328,8 @@ class TrafficServerDomain(Domain):
     def get_objects(self):
         for var, doc in self.data['cv'].iteritems():
             yield var, var, 'cv', doc, var, 1
+        for var, doc in self.data['stat'].iteritems():
+            yield var, var, 'stat', doc, var, 1
 
 # These types are ignored as missing references for the C++ domain.
 # We really need to do better with this. Editing this file for each of

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/getting-started.en.rst b/doc/getting-started.en.rst
deleted file mode 100644
index ef4583a..0000000
--- a/doc/getting-started.en.rst
+++ /dev/null
@@ -1,451 +0,0 @@
-.. _getting-started:
-
-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.
-
-.. include:: common.defs
-
-.. toctree::
-   :maxdepth: 2
-
-Introduction
-============
-
-|ATS| provides a high-performance and scalable software solution for both
-forward and reverse proxying of HTTP/HTTPS traffic, and may be configured to
-run in either or both modes simultaneously. This Getting Started guide explains
-the basic steps an administrator new to |TS| will need to perform to get the
-software up and running in a minimal configuration as quickly as possible.
-
-Example Scenario
-----------------
-
-In this guide, we will use the fictional company |AW| as a basis for the
-configuration examples. |AW| has a product brochure website (assumed to reside
-at the domain ``www.acme.com``) that performs very poorly. The content management
-software they chose takes an unbearable amount of time to generate pages on
-every request and their engineering team has chosen |TS| as a caching proxy
-layer to improve site performance.
-
-Separately, |AW| has decided to use |TS| to help improve the performance of
-their office's Internet access, which is hobbled by their reliance on an aging
-leased line and certain employees' predilection for extracurricular web
-browsing.
-
-Terminology
------------
-
-This guide uses some terms which may be unfamiliar to administrators new to
-proxy servers.
-
-Origin Server
-    The server which generates the content you wish to proxy (and optionally
-    cache) with |TS|. In a forward proxy configuration, the origin server may be
-    any remote server to which a proxied client attempts to connect. In a
-    reverse proxy configuration, the origin servers are typically a known set of
-    servers for which you are using |TS| as a performance-enhancing caching
-    layer.
-
-Reverse Proxy
-    A reverse proxy appears to outside users as if it were the origin server,
-    though it does not generate the content itself. Instead, it intercepts the
-    requests and, based on the configured rules and contents of its cache, will
-    either serve a cached copy of the requested content itself, or forward the
-    request to the origin server, possibly caching the content returned for use
-    with future requests.
-
-Forward Proxy
-    A forward proxy brokers access to external resources, intercepting all
-    matching outbound traffic from a network. Forward proxies may be used to
-    speed up external access for locations with slow connections (by caching the
-    external resources and using those cached copies to service requests
-    directly in the future), or may be used to restrict or monitor external
-    access.
-
-Transparent Proxy
-    A transparent proxy may be either a reverse or forward proxy (though nearly
-    all reverse proxies are deployed transparently), the defining feature being
-    the use of network routing to send requests through the proxy without any
-    need for clients to configure themselves to do so, and often without the
-    ability for those clients to bypass the proxy.
-
-For a more complete list of definitions, please see the :ref:`glossary`.
-
-Installation
-============
-
-As with many other software packages, you may have the option of installing
-|ATS| from your operating system disttribution's packages, or compiling and
-installing from the source code yourself. Distribution packages may lag behind
-the current stable release of |TS|, sometimes by a significant amount. While
-we will cover briefly the packages required for common operating system
-distributions, the remainder of this guide will be assuming the latest stable
-release of |TS| when discussing configuration parameters and available features.
-
-.. _gs-install-from-package:
-
-Installing From Distribution Packages
--------------------------------------
-
-It is recommended that you install from source code, as described in the section
-below, rather than rely on your distribution's packages if you wish to have
-access to the latest features and fixes in |TS|.
-
-Ubuntu
-~~~~~~
-
-The Canonical repositories up through, and including, Utopic Unicorn only
-provide |TS| v3.2.x. ::
-
-    sudo apt-get install trafficserver
-
-RHEL / CentOS
-~~~~~~~~~~~~~
-
-|TS| is available through the EPEL repositories. If you do not have those
-configured on your machine yet, you must install them first with the following::
-
-    wget http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-1.noarch.rpm
-    sudo rpm -Uvh epel-release-7*.rpm
-
-Ensuring that you replace the release number with a value that is appropriate
-for your system. Once you have EPEL installed, you may install |TS| itself. ::
-
-    sudo yum install trafficserver
-
-OmniOS (illumos)
-~~~~~~~~~~~~~~~~
-
-OmniOS (an illumos-based distribution) provides the |TS| package in its public
-*OmniTI-MS* publisher. ::
-
-    sudo pkg set-publisher -g http://pkg.omniti.com/omniti-ms/ ms.omniti.com
-    sudo pkg install omniti/server/trafficserver
-
-The latest release published, at the time of this writing, is |TS| v4.2.1.
-
-.. _gs-install-from-source:
-
-Installing From Source Code
----------------------------
-
-To install from source code, you will need to have the following tools and
-libraries on the machine used to build |TS|:
-
-- pkgconfig
-- libtool
-- gcc (>= 4.3 or clang > 3.0)
-- GNU make
-- openssl
-- tcl
-- expat
-- pcre
-- libcap
-- flex (for TPROXY)
-- hwloc
-- lua
-- curses (for traffic_top)
-- curl (for traffic_top)
-
-To build |TS| from a Git clone (the method we will be using in this guide), you
-will also need the following:
-
-- git
-- autoconf
-- automake
-
-In this guide, |TS| will be built to use the default ``nobody`` user and group
-and will be installed to ``/opt/ts``. It is assumed that all of the dependencies
-are located in standard paths. If this is not the case, you may need to use the
-appropriate ``--with-<package>`` options as detailed in the output of
-``./configure --help``.
-
-#. Clone the repository (you may skip this if you have downloaded an archive of
-   the source code to build a specific official release of |TS| instead of the
-   HEAD from source control)::
-
-    git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
-
-#. Change to the cloned (or unarchived) directory::
-
-    cd trafficserver/
-
-#. If you have cloned the repository from Git, you will need to generate the
-   ``configure`` script before proceeding::
-
-    autoreconf -if
-
-#. Configure the source tree::
-
-    ./configure --prefix=/opt/ts
-
-#. Build |TS| with the generated Makefiles, and test the results::
-
-    make
-    make check
-
-#. Install |TS| to the configured location::
-
-    sudo make install
-
-#. Optionally, you may find it prudent to run the regression tests on your newly
-   installed |TS|::
-
-    cd /opt/ts
-    sudo bin/traffic_server -R 1
-
-Configuration
-=============
-
-We will be tackling two separate configuration scenarios in the following
-sections. The first is the most common application of a performance-enhancing
-caching proxy for externally-facing websites, a transparent and caching reverse
-proxy which forwards all requests presented to it to a single origin address
-and caches the responses based on their cache control headers (as well as some
-simple heuristics for specific content types when cache control headers are not
-present).
-
-The second configuration we will review is a very basic transparent forward
-proxy, typically used in situations where you either need to improve the
-performance of a local network's use of external resources, or you wish to have
-the capability of monitoring or filtering the traffic.
-
-Configuring A Reverse Proxy
----------------------------
-
-A minimal reverse proxy configuration requires changes to only a few
-configuration files, which will all be located in the
-``/opt/ts/etc/trafficserver`` directory if you have configured your installation
-per the instructions in :ref:`gs-install-from-source` above.
-
-For these examples, we will be assuming that |TS| is running on the same host
-machine as the origin website. This is not a requirement, and you may choose to
-run |TS| on an entirely different host, even connected to entirely different
-networks, as long as |TS| is able to reach the origin host.
-
-Enable Reverse Proxying
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Within the :file:`records.config` configuration file, ensure that the following
-settings have been configured as shown below::
-
-    CONFIG proxy.config.http.cache.http INT 1
-    CONFIG proxy.config.reverse_proxy.enabled INT 1
-    CONFIG proxy.config.url_remap.remap_required INT 1
-    CONFIG proxy.config.url_remap.pristine_host_hdr INT 1
-    CONFIG proxy.config.http.server_ports STRING 8080
-
-:ts:cv:`proxy.config.http.cache.http`
-    Enables caching of proxied HTTP requests.
-
-:ts:cv:`proxy.config.reverse_proxy.enabled`
-    Enables reverse proxying support.
-
-:ts:cv:`proxy.config.url_remap.remap_required`
-    This setting requires that a remap rule exist before |TS| will proxy the
-    request and ensures that your proxy cannot be used to access the content of
-    arbitrary websites (allowing someone of malicious intent to potentially
-    mask their identity to an unknowning third party).
-
-:ts:cv:`proxy.config.url_remap.pristine_host_hdr`
-    This setting causes |TS| to keep the ``Host:`` client request header intact
-    which is necessary in cases where your origin servers may be performing
-    domain-based virtual hosting, or taking other actions dependent upon the
-    contents of that header.
-
-:ts:cv:`proxy.config.http.server_ports`
-    This configures |TS| to bind itself to the port ``8080`` for HTTP traffic.
-
-Configure Origin Location
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The previous settings enable reverse proxying (and prevent flagrant abuse of
-it), but now |TS| needs to know what to proxy. This is achieved by writing remap
-rules, which make use of the core :ref:`conf-remap-plugin`. For our Geting
-Started guide's |AW| example scenario, we have very simple needs and want little
-more than to proxy all requests to our single origin server. This is
-accomplished with the following rule added to the :file:`remap.config`
-configuration::
-
-    regex_map http://(.*)/ http://localhost:80/
-
-It is worth pausing at this point to note that in a reverse proxying scenario,
-it is |TS| itself which should be responding to HTTP requests made to your
-public domain. While you first configure and evaluate whether |TS| will meet
-your needs, your origin server will continue to reside at the public-facing
-domain name on the default ports, should you move your |TS| configuration into
-production your DNS records for the domain(s) you wish to proxy and cache should
-resolve to the host(s) running |TS| (in the event that you run it on a separate
-host from your origin). Your origin should be accessible at a different address
-(or bind to different ports if you are running both your origin service and |TS|
-on the same host) and should no longer receive requests sent to the primary
-domain on its default ports.
-
-In our |AW| scenario, they ultimately decide to deploy |TS| at which point,
-since they are running both |TS| and their origin web server on the same host,
-they reconfigure their origin service to listen on port ``8080`` instead of the
-default, and change |TS| to bind to ``80`` itself. Updating the remap is thus
-required, and it should now be::
-
-    regex_map http://(.*)/ http://localhost:8080/
-
-Now all requests made to ``www.acme.com`` are received by |TS| which knows to
-proxy those requests to ``localhost:8080`` if it cannot already serve them from
-its cache. Because we enabled pristine host headers earlier, the origin service
-will continue to receive ``Host: www.acme.com`` in the HTTP request.
-
-Adjust Cache Parameters
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The default |TS| configuration will provide a 256 MB disk cache, located in
-``var/trafficserver/`` underneath your install prefix. You may wish to adjust
-either or both of the size and location of this cache. This is done with the
-:file:`storage.config` configuration file. In our example, |AW| has dedicated
-a large storage pool on their cache server which is mounted at ``/cache``. To
-use this, and to disable the default cache storage setting, the following will
-be the sole entry in :file:`storage.config`::
-
-    /cache/trafficserver 500G
-
-.. note:: Changes to the cache configuration require a restart of |TS|.
-
-You may also wish to use raw devices, or partition your cache storage. Details
-on these features may be found in the :ref:`configuring-the-cache` section of
-the Administrator's Guide.
-
-Final Configurations
-~~~~~~~~~~~~~~~~~~~~
-
-Once completed, the following configuration files for |AW| contain the following
-entries:
-
-:file:`records.config`::
-
-    CONFIG proxy.config.http.cache.http INT 1
-    CONFIG proxy.config.reverse_proxy.enabled INT 1
-    CONFIG proxy.config.url_remap.remap_required INT 1
-    CONFIG proxy.config.url_remap.pristine_host_hdr INT 1
-    CONFIG proxy.config.http.server_ports STRING 80
-
-:file:`remap.config`::
-
-    regex_map http://(.*)/ http://localhost:8080/
-
-:file:`storage.config`::
-
-    /cache/trafficserver 500G
-
-Configuring A Forward Proxy
----------------------------
-
-Configuring a forward proxy with |TS| is somewhat more straightforward, though
-there are two main approaches for how to direct client traffic through the
-proxy: explicit or transparent.
-
-More detail on the process is also available in the Administrator's Guide in
-the :ref:`forward-proxy` section. This guide will cover only a minimal
-configuration.
-
-Enable Forward Proxying
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Contrary to a reverse proxy, where you have a defined list of origin servers for
-which you wish to proxy (and optionally cache), a forward proxy is used to
-proxy (and optionally cache) for arbitrary remote hosts. As such, the following
-settings in :file:`records.config` are the base configuration for a minimal
-forward proxy::
-
-    CONFIG proxy.config.url_remap.remap_required INT 0
-    CONFIG proxy.config.http.cache.http INT 1
-
-:ts:cv:`proxy.config.url_remap.remap_required`
-    Disables the requirement for a remap rule to exist and match the incoming
-    request before |TS| will proxy the request to the remote host.
-
-:ts:cv:`proxy.config.http.cache.http`
-    Enables caching of proxied HTTP requests.
-
-If your installation will be strictly a forwarding proxy, then reverse proxying
-should be explicitly disabled::
-
-    CONFIG proxy.config.reverse_proxy.enabled INT 0
-
-Explicit Versus Transparent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-With forward proxying enabled, the next step is deciding how clients will
-connect through the proxy server. Explicit forward proxying requires that every
-client application be configured (manually or through whatever configuration
-management system you may employ) to use the proxy. The presence of the proxy
-will be known to clients, and any clients not configured to use the proxy will
-bypass it entirely unless you otherwise block network access for unproxied
-traffic.
-
-With transparent proxying, clients require no configuration and may be given no
-option to bypass the proxy. This configuration requires your network to route
-all requests automatically to the proxy. The details of how to accomplish this
-routing are entirely dependent upon the layout of your network and the routing
-devices you use.
-
-For a more detailed discussion of the options, and starting points for
-configuring each in your network environment, please refer to the
-:ref:`forward-proxy` section of the Administrator's Guide.
-
-Logging and Monitoring
-======================
-
-Configuring Log Output
-----------------------
-
-The log formats used by |TS| are highly configurable. While this guide will not
-go into full detail of this versatility, it is useful to consider what style of
-logging you would like to perform. If your organization already makes use of
-log monitoring or analysis tools that understand, for example, *Netscape
-Extended-2* format you may wish to enable that logging format in addition to,
-or instead of, the default |TS| logs.
-
-The Administrator's Guide discusses logging options in great detail in
-:ref:`working-with-log-files`.
-
-Using Traffic Top
------------------
-
-Using Stats Over HTTP
----------------------
-
-Using Cache Inspector
----------------------
-
-Further Steps
-=============
-
-By this point, you should have a fully functioning caching proxy, whether to
-help improve the customer facing performance of your website, or to assist in
-speeding up Internet access for your office while allowing for the possibility
-of access control, content filtering, and/or usage monitoring. However, it is
-quite likely that your installation is not yet tuned properly and may not be
-providing the best experience |ATS| has to offer. It is strongly recommended
-that you consult the :ref:`performance-tuning` guide.
-
-You may also want to learn more about :ref:`monitoring-traffic`, or ensuring
-that your installation is properly secured by reading the :ref:`security-options`
-section. Properly sizing your cache, both the on-disk cache and the companion
-memory cache, are important topics covered in :ref:`configuring-the-cache`.
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/getting-started/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/getting-started/index.en.rst b/doc/getting-started/index.en.rst
new file mode 100644
index 0000000..d91d7af
--- /dev/null
+++ b/doc/getting-started/index.en.rst
@@ -0,0 +1,451 @@
+.. 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.
+
+.. include:: ../common.defs
+
+.. _getting-started:
+
+Getting Started
+***************
+
+.. toctree::
+   :maxdepth: 2
+
+Introduction
+============
+
+|ATS| provides a high-performance and scalable software solution for both
+forward and reverse proxying of HTTP/HTTPS traffic, and may be configured to
+run in either or both modes simultaneously. This Getting Started guide explains
+the basic steps an administrator new to |TS| will need to perform to get the
+software up and running in a minimal configuration as quickly as possible.
+
+Example Scenario
+----------------
+
+In this guide, we will use the fictional company |AW| as a basis for the
+configuration examples. |AW| has a product brochure website (assumed to reside
+at the domain ``www.acme.com``) that performs very poorly. The content management
+software they chose takes an unbearable amount of time to generate pages on
+every request and their engineering team has chosen |TS| as a caching proxy
+layer to improve site performance.
+
+Separately, |AW| has decided to use |TS| to help improve the performance of
+their office's Internet access, which is hobbled by their reliance on an aging
+leased line and certain employees' predilection for extracurricular web
+browsing.
+
+Terminology
+-----------
+
+This guide uses some terms which may be unfamiliar to administrators new to
+proxy servers.
+
+Origin Server
+    The server which generates the content you wish to proxy (and optionally
+    cache) with |TS|. In a forward proxy configuration, the origin server may be
+    any remote server to which a proxied client attempts to connect. In a
+    reverse proxy configuration, the origin servers are typically a known set of
+    servers for which you are using |TS| as a performance-enhancing caching
+    layer.
+
+Reverse Proxy
+    A reverse proxy appears to outside users as if it were the origin server,
+    though it does not generate the content itself. Instead, it intercepts the
+    requests and, based on the configured rules and contents of its cache, will
+    either serve a cached copy of the requested content itself, or forward the
+    request to the origin server, possibly caching the content returned for use
+    with future requests.
+
+Forward Proxy
+    A forward proxy brokers access to external resources, intercepting all
+    matching outbound traffic from a network. Forward proxies may be used to
+    speed up external access for locations with slow connections (by caching the
+    external resources and using those cached copies to service requests
+    directly in the future), or may be used to restrict or monitor external
+    access.
+
+Transparent Proxy
+    A transparent proxy may be either a reverse or forward proxy (though nearly
+    all reverse proxies are deployed transparently), the defining feature being
+    the use of network routing to send requests through the proxy without any
+    need for clients to configure themselves to do so, and often without the
+    ability for those clients to bypass the proxy.
+
+For a more complete list of definitions, please see the :ref:`glossary`.
+
+Installation
+============
+
+As with many other software packages, you may have the option of installing
+|ATS| from your operating system disttribution's packages, or compiling and
+installing from the source code yourself. Distribution packages may lag behind
+the current stable release of |TS|, sometimes by a significant amount. While
+we will cover briefly the packages required for common operating system
+distributions, the remainder of this guide will be assuming the latest stable
+release of |TS| when discussing configuration parameters and available features.
+
+.. _gs-install-from-package:
+
+Installing From Distribution Packages
+-------------------------------------
+
+It is recommended that you install from source code, as described in the section
+below, rather than rely on your distribution's packages if you wish to have
+access to the latest features and fixes in |TS|.
+
+Ubuntu
+~~~~~~
+
+The Canonical repositories up through, and including, Utopic Unicorn only
+provide |TS| v3.2.x. ::
+
+    sudo apt-get install trafficserver
+
+RHEL / CentOS
+~~~~~~~~~~~~~
+
+|TS| is available through the EPEL repositories. If you do not have those
+configured on your machine yet, you must install them first with the following::
+
+    wget http://dl.fedoraproject.org/pub/epel/7/x86_64/e/epel-release-7-1.noarch.rpm
+    sudo rpm -Uvh epel-release-7*.rpm
+
+Ensuring that you replace the release number with a value that is appropriate
+for your system. Once you have EPEL installed, you may install |TS| itself. ::
+
+    sudo yum install trafficserver
+
+OmniOS (illumos)
+~~~~~~~~~~~~~~~~
+
+OmniOS (an illumos-based distribution) provides the |TS| package in its public
+*OmniTI-MS* publisher. ::
+
+    sudo pkg set-publisher -g http://pkg.omniti.com/omniti-ms/ ms.omniti.com
+    sudo pkg install omniti/server/trafficserver
+
+The latest release published, at the time of this writing, is |TS| v4.2.1.
+
+.. _gs-install-from-source:
+
+Installing From Source Code
+---------------------------
+
+To install from source code, you will need to have the following tools and
+libraries on the machine used to build |TS|:
+
+- pkgconfig
+- libtool
+- gcc (>= 4.3 or clang > 3.0)
+- GNU make
+- openssl
+- tcl
+- expat
+- pcre
+- libcap
+- flex (for TPROXY)
+- hwloc
+- lua
+- curses (for traffic_top)
+- curl (for traffic_top)
+
+To build |TS| from a Git clone (the method we will be using in this guide), you
+will also need the following:
+
+- git
+- autoconf
+- automake
+
+In this guide, |TS| will be built to use the default ``nobody`` user and group
+and will be installed to ``/opt/ts``. It is assumed that all of the dependencies
+are located in standard paths. If this is not the case, you may need to use the
+appropriate ``--with-<package>`` options as detailed in the output of
+``./configure --help``.
+
+#. Clone the repository (you may skip this if you have downloaded an archive of
+   the source code to build a specific official release of |TS| instead of the
+   HEAD from source control)::
+
+    git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
+
+#. Change to the cloned (or unarchived) directory::
+
+    cd trafficserver/
+
+#. If you have cloned the repository from Git, you will need to generate the
+   ``configure`` script before proceeding::
+
+    autoreconf -if
+
+#. Configure the source tree::
+
+    ./configure --prefix=/opt/ts
+
+#. Build |TS| with the generated Makefiles, and test the results::
+
+    make
+    make check
+
+#. Install |TS| to the configured location::
+
+    sudo make install
+
+#. Optionally, you may find it prudent to run the regression tests on your newly
+   installed |TS|::
+
+    cd /opt/ts
+    sudo bin/traffic_server -R 1
+
+Configuration
+=============
+
+We will be tackling two separate configuration scenarios in the following
+sections. The first is the most common application of a performance-enhancing
+caching proxy for externally-facing websites, a transparent and caching reverse
+proxy which forwards all requests presented to it to a single origin address
+and caches the responses based on their cache control headers (as well as some
+simple heuristics for specific content types when cache control headers are not
+present).
+
+The second configuration we will review is a very basic transparent forward
+proxy, typically used in situations where you either need to improve the
+performance of a local network's use of external resources, or you wish to have
+the capability of monitoring or filtering the traffic.
+
+Configuring A Reverse Proxy
+---------------------------
+
+A minimal reverse proxy configuration requires changes to only a few
+configuration files, which will all be located in the
+``/opt/ts/etc/trafficserver`` directory if you have configured your installation
+per the instructions in :ref:`gs-install-from-source` above.
+
+For these examples, we will be assuming that |TS| is running on the same host
+machine as the origin website. This is not a requirement, and you may choose to
+run |TS| on an entirely different host, even connected to entirely different
+networks, as long as |TS| is able to reach the origin host.
+
+Enable Reverse Proxying
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Within the :file:`records.config` configuration file, ensure that the following
+settings have been configured as shown below::
+
+    CONFIG proxy.config.http.cache.http INT 1
+    CONFIG proxy.config.reverse_proxy.enabled INT 1
+    CONFIG proxy.config.url_remap.remap_required INT 1
+    CONFIG proxy.config.url_remap.pristine_host_hdr INT 1
+    CONFIG proxy.config.http.server_ports STRING 8080
+
+:ts:cv:`proxy.config.http.cache.http`
+    Enables caching of proxied HTTP requests.
+
+:ts:cv:`proxy.config.reverse_proxy.enabled`
+    Enables reverse proxying support.
+
+:ts:cv:`proxy.config.url_remap.remap_required`
+    This setting requires that a remap rule exist before |TS| will proxy the
+    request and ensures that your proxy cannot be used to access the content of
+    arbitrary websites (allowing someone of malicious intent to potentially
+    mask their identity to an unknowning third party).
+
+:ts:cv:`proxy.config.url_remap.pristine_host_hdr`
+    This setting causes |TS| to keep the ``Host:`` client request header intact
+    which is necessary in cases where your origin servers may be performing
+    domain-based virtual hosting, or taking other actions dependent upon the
+    contents of that header.
+
+:ts:cv:`proxy.config.http.server_ports`
+    This configures |TS| to bind itself to the port ``8080`` for HTTP traffic.
+
+Configure Origin Location
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The previous settings enable reverse proxying (and prevent flagrant abuse of
+it), but now |TS| needs to know what to proxy. This is achieved by writing remap
+rules, which make use of the core :ref:`conf-remap-plugin`. For our Geting
+Started guide's |AW| example scenario, we have very simple needs and want little
+more than to proxy all requests to our single origin server. This is
+accomplished with the following rule added to the :file:`remap.config`
+configuration::
+
+    regex_map http://(.*)/ http://localhost:80/
+
+It is worth pausing at this point to note that in a reverse proxying scenario,
+it is |TS| itself which should be responding to HTTP requests made to your
+public domain. While you first configure and evaluate whether |TS| will meet
+your needs, your origin server will continue to reside at the public-facing
+domain name on the default ports, should you move your |TS| configuration into
+production your DNS records for the domain(s) you wish to proxy and cache should
+resolve to the host(s) running |TS| (in the event that you run it on a separate
+host from your origin). Your origin should be accessible at a different address
+(or bind to different ports if you are running both your origin service and |TS|
+on the same host) and should no longer receive requests sent to the primary
+domain on its default ports.
+
+In our |AW| scenario, they ultimately decide to deploy |TS| at which point,
+since they are running both |TS| and their origin web server on the same host,
+they reconfigure their origin service to listen on port ``8080`` instead of the
+default, and change |TS| to bind to ``80`` itself. Updating the remap is thus
+required, and it should now be::
+
+    regex_map http://(.*)/ http://localhost:8080/
+
+Now all requests made to ``www.acme.com`` are received by |TS| which knows to
+proxy those requests to ``localhost:8080`` if it cannot already serve them from
+its cache. Because we enabled pristine host headers earlier, the origin service
+will continue to receive ``Host: www.acme.com`` in the HTTP request.
+
+Adjust Cache Parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The default |TS| configuration will provide a 256 MB disk cache, located in
+``var/trafficserver/`` underneath your install prefix. You may wish to adjust
+either or both of the size and location of this cache. This is done with the
+:file:`storage.config` configuration file. In our example, |AW| has dedicated
+a large storage pool on their cache server which is mounted at ``/cache``. To
+use this, and to disable the default cache storage setting, the following will
+be the sole entry in :file:`storage.config`::
+
+    /cache/trafficserver 500G
+
+.. note:: Changes to the cache configuration require a restart of |TS|.
+
+You may also wish to use raw devices, or partition your cache storage. Details
+on these features may be found in the :ref:`admin-configuration` section of
+the Administrator's Guide.
+
+Final Configurations
+~~~~~~~~~~~~~~~~~~~~
+
+Once completed, the following configuration files for |AW| contain the following
+entries:
+
+:file:`records.config`::
+
+    CONFIG proxy.config.http.cache.http INT 1
+    CONFIG proxy.config.reverse_proxy.enabled INT 1
+    CONFIG proxy.config.url_remap.remap_required INT 1
+    CONFIG proxy.config.url_remap.pristine_host_hdr INT 1
+    CONFIG proxy.config.http.server_ports STRING 80
+
+:file:`remap.config`::
+
+    regex_map http://(.*)/ http://localhost:8080/
+
+:file:`storage.config`::
+
+    /cache/trafficserver 500G
+
+Configuring A Forward Proxy
+---------------------------
+
+Configuring a forward proxy with |TS| is somewhat more straightforward, though
+there are two main approaches for how to direct client traffic through the
+proxy: explicit or transparent.
+
+More detail on the process is also available in the Administrator's Guide in
+the :ref:`forward-proxy` section. This guide will cover only a minimal
+configuration.
+
+Enable Forward Proxying
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Contrary to a reverse proxy, where you have a defined list of origin servers for
+which you wish to proxy (and optionally cache), a forward proxy is used to
+proxy (and optionally cache) for arbitrary remote hosts. As such, the following
+settings in :file:`records.config` are the base configuration for a minimal
+forward proxy::
+
+    CONFIG proxy.config.url_remap.remap_required INT 0
+    CONFIG proxy.config.http.cache.http INT 1
+
+:ts:cv:`proxy.config.url_remap.remap_required`
+    Disables the requirement for a remap rule to exist and match the incoming
+    request before |TS| will proxy the request to the remote host.
+
+:ts:cv:`proxy.config.http.cache.http`
+    Enables caching of proxied HTTP requests.
+
+If your installation will be strictly a forwarding proxy, then reverse proxying
+should be explicitly disabled::
+
+    CONFIG proxy.config.reverse_proxy.enabled INT 0
+
+Explicit Versus Transparent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With forward proxying enabled, the next step is deciding how clients will
+connect through the proxy server. Explicit forward proxying requires that every
+client application be configured (manually or through whatever configuration
+management system you may employ) to use the proxy. The presence of the proxy
+will be known to clients, and any clients not configured to use the proxy will
+bypass it entirely unless you otherwise block network access for unproxied
+traffic.
+
+With transparent proxying, clients require no configuration and may be given no
+option to bypass the proxy. This configuration requires your network to route
+all requests automatically to the proxy. The details of how to accomplish this
+routing are entirely dependent upon the layout of your network and the routing
+devices you use.
+
+For a more detailed discussion of the options, and starting points for
+configuring each in your network environment, please refer to the
+:ref:`forward-proxy` section of the Administrator's Guide.
+
+Logging and Monitoring
+======================
+
+Configuring Log Output
+----------------------
+
+The log formats used by |TS| are highly configurable. While this guide will not
+go into full detail of this versatility, it is useful to consider what style of
+logging you would like to perform. If your organization already makes use of
+log monitoring or analysis tools that understand, for example, *Netscape
+Extended-2* format you may wish to enable that logging format in addition to,
+or instead of, the default |TS| logs.
+
+The Administrator's Guide discusses logging options in great detail in
+:ref:`working-with-log-files`.
+
+Using Traffic Top
+-----------------
+
+Using Stats Over HTTP
+---------------------
+
+Using Cache Inspector
+---------------------
+
+Further Steps
+=============
+
+By this point, you should have a fully functioning caching proxy, whether to
+help improve the customer facing performance of your website, or to assist in
+speeding up Internet access for your office while allowing for the possibility
+of access control, content filtering, and/or usage monitoring. However, it is
+quite likely that your installation is not yet tuned properly and may not be
+providing the best experience |ATS| has to offer. It is strongly recommended
+that you consult the :ref:`performance-tuning` guide.
+
+You may also want to learn more about :ref:`admin-monitoring`, or ensuring
+that your installation is properly secured by reading the :ref:`admin-security`
+section. Properly sizing your cache, both the on-disk cache and the companion
+memory cache, are important topics covered in :ref:`admin-configuration`.
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/glossary.en.rst
----------------------------------------------------------------------
diff --git a/doc/glossary.en.rst b/doc/glossary.en.rst
deleted file mode 100644
index 758523e..0000000
--- a/doc/glossary.en.rst
+++ /dev/null
@@ -1,123 +0,0 @@
-.. 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.
-
-=============
-Glossary
-=============
-
-.. glossary::
-   :sorted:
-
-   continuation
-      A callable object that contains state. These are are mechanism used by Traffic Server to implement callbacks and
-      continued computations. Continued computations are critical to efficient processing of traffic because by avoiding
-      any blocking operations that wait on external events. In any such case a continuation is used so that other
-      processing can continue until the external event occurs. At that point the continuation is invoked to continue the
-      suspended processing. This can be considered similar to co-routines.
-
-   session
-      A single connection from a client to Traffic Server, covering all requests and responses on that connection. A
-      session starts when the client connection opens, and ends when the connection closes.
-
-   transaction
-      A client request and response, either from the origin server or from the cache. A transaction begins when Traffic
-      Server receives a request, and ends when Traffic Server sends the response.
-
-   cache volume
-      A user defined unit of persistent storage for the cache. Cache volumes are defined in :file:`volume.config`. A
-      cache volume is by default spread across :term:`cache span`\ s to increase robustness. Each section of a cache
-      volume on a specific cache span is a :term:`cache stripe`.
-
-   cache stripe
-      A homogenous persistent store for the cache in a single :term:`cache span`. A stripe always resides
-      entirely on a single physical device and is treated as an undifferentiated span of bytes. This is the smallest
-      independent unit of storage.
-
-   cache span
-      The physical storage described by a single line in :file:`storage.config`.
-
-   cache key
-      A byte sequence that is a globally unique identifier for an :term:`object <cache object>` in the cache. By default
-      the URL for the object is used.
-
-   cache ID
-      A 128 bit value used as a fixed sized identifier for an object in the cache. This is computed from the
-      :term:`cache key` using the `MD5 hashing function <http://www.openssl.org/docs/crypto/md5.html>`_.
-
-   cache tag
-      The bottom few bits (12 currently) of the :term:`cache ID`. This is used in the :ref:`cache directory <cache-directory>`
-      for a preliminary identity check before going to disk.
-
-   cache object
-      The minimal self contained unit of data in the cache. Cache objects are the stored version of equivalent content
-      streams from an origin server. A single object can have multiple variants called :term:`alternates <alternate>`.
-
-   alternate
-      A variant of a :term:`cache object`. This was originally created to handle the `VARY mechanism
-      <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44>`_ but has since been used for additional
-      purposes. All alternates of an object must be equivalent in some manner, that is they are alternate forms of the
-      same stream. The most common example is having normal and compressed versions of the stream.
-
-   storage unit
-      Obsolete term for :term:`cache span`.
-
-   revalidation
-      Verifying that a currently cached object is still valid. This is usually done using an `If-Modified-Since
-      <http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25>`_ request which allows the origin server to
-      validate the content without resending the content.
-
-   write cursor
-      The location in a :term:`cache stripe` where new data is written.
-
-   directory segment
-      A contiguous group of :term:`buckets <directory bucket>`. Each :term:`cache stripe` has a set of segments all of
-      which have the same number of buckets, although the number of buckets per segment can vary between cache stripes.
-      Segments are administrative in purpose to minimize the size of free list and hash bucket pointers.
-
-   directory bucket
-      A contiguous fixed sized group of :term:`directory entries <directory entry>`. This is used for hash bucket
-      maintenance optimization.
-
-   directory entry
-      An in memory entry that describes a :term:`cache fragment`.
-
-   cache fragment
-      The unit of storage in the cache. All reads from the cache always read exactly one fragment. Fragments may be
-      written in groups, but every write is always an integral number of fragments. Each fragment has a corresponding
-      :term:`directory entry` which describes its location in the cache storage.
-
-   object store
-      The database of :term:`cache objects <cache object>`.
-
-   fresh
-      The state of a :term:`cache object` which can be served directly from the
-      the cache in response to client requests. Fresh objects have not met or
-      passed their :term:`origin server` defined expiration time, nor have they
-      reached the algorithmically determined :term:`stale` age.
-
-   stale
-      The state of a :term:`cache object` which is not yet expired, but has
-      reached an algorithmically determined age at which the :term:`origin server`
-      will be contacted to :term:`revalidate <revalidation>` the freshness of
-      the object. Contrast with :term:`fresh`.
-
-   origin server
-      An HTTP server which provides the original source of content being cached
-      by Traffic Server.
-
-   cache partition
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/index.rst
----------------------------------------------------------------------
diff --git a/doc/index.rst b/doc/index.rst
index a428a81..36ac32c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,6 +1,3 @@
-Apache Traffic Server
-*********************
-
 .. 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
@@ -18,34 +15,21 @@ Apache Traffic Server
    specific language governing permissions and limitations
    under the License.
 
+.. include:: common.defs
 
-Apache Traffic Serverâ„¢ speeds Internet access, enhances website
-performance, and delivers unprecedented web hosting capabilities.
-
-What Is Apache Traffic Server?
-==============================
+.. _manual-toc:
 
-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.
+Apache Traffic Server Manual
+****************************
 
 .. toctree::
-  :maxdepth: 1
-
-  getting-started.en
-  admin/index.en
-  sdk/index.en
-  reference/configuration/index.en
-  reference/commands/index.en
-  reference/plugins/index.en
-  reference/api/index.en
-  arch/index.en
-  glossary.en
+  :maxdepth: 2
+
+  preface/index.en
+  getting-started/index.en
+  admin-guide/index.en
+  developer-guide/index.en
+  appendices/index.en
 
 Indices and tables
 ==================

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/manpages.py
----------------------------------------------------------------------
diff --git a/doc/manpages.py b/doc/manpages.py
index 4f0b846..162a162 100644
--- a/doc/manpages.py
+++ b/doc/manpages.py
@@ -19,37 +19,38 @@ import sys, os
 man_pages = [
   # Add all files in the reference/api directory to the list of manual
   # pages
-  ('reference/api/' + filename[:-4], filename.split('.', 1)[0], '', None, '3ts') for filename in os.listdir('reference/api') if filename != 'index.en.rst' and filename.endswith('.rst')] + [
+  ('developer-guide/api/' + filename[:-4], filename.split('.', 1)[0], '', None, '3ts') for filename in os.listdir('developer-guide/api') if filename != 'index.en.rst' and filename.endswith('.rst')] + [
 
-  ('reference/commands/traffic_cop.en', 'traffic_cop', u'Traffic Server watchdog', None, '8'),
-  ('reference/commands/traffic_ctl.en', 'traffic_ctl', u'Traffic Server management tool', None, '8'),
-  ('reference/commands/traffic_crashlog.en', 'traffic_crashlog', u'Traffic Server crash log helper', None, '8'),
-  ('reference/commands/traffic_line.en', 'traffic_line', u'Traffic Server command line', None, '8'),
-  ('reference/commands/traffic_logcat.en', 'traffic_logcat', u'Traffic Server log spooler', None, '8'),
-  ('reference/commands/traffic_logstats.en', 'traffic_logstats', u'Traffic Server analyzer', None, '8'),
-  ('reference/commands/traffic_manager.en', 'traffic_manager', u'Traffic Server process manager', None, '8'),
-  ('reference/commands/traffic_server.en', 'traffic_server', u'Traffic Server', None, '8'),
+  ('appendices/command-line/traffic_cop.en', 'traffic_cop', u'Traffic Server watchdog', None, '8'),
+  ('appendices/command-line/traffic_ctl.en', 'traffic_cop', u'Traffic Server watchdog', None, '8'),
+  ('appendices/command-line/traffic_crashlog.en', 'traffic_crashlog', u'Traffic Server crash log helper', None, '8'),
+  ('appendices/command-line/traffic_line.en', 'traffic_line', u'Traffic Server command line', None, '8'),
+  ('appendices/command-line/traffic_logcat.en', 'traffic_logcat', u'Traffic Server log spooler', None, '8'),
+  ('appendices/command-line/traffic_logstats.en', 'traffic_logstats', u'Traffic Server analyzer', None, '8'),
+  ('appendices/command-line/traffic_manager.en', 'traffic_manager', u'Traffic Server process manager', None, '8'),
+  ('appendices/command-line/traffic_server.en', 'traffic_server', u'Traffic Server', None, '8'),
 
-  ('reference/commands/tspush.en', 'tspush', u'Push objects into the Traffic Server cache', None, '1'),
-  ('reference/commands/traffic_top.en','traffic_top', u'Display Traffic Server statistics', None, '1'),
-  ('reference/commands/tsxs.en', 'tsxs', u'Traffic Server plugin tool', None, '1'),
-  ('reference/commands/traffic_via.en', 'traffic_via', u'Traffic Server Via header decoder', None, '1'),
+  ('appendices/command-line/tspush.en', 'tspush', u'Push objects into the Traffic Server cache', None, '1'),
+  ('appendices/command-line/traffic_top.en','traffic_top', u'Display Traffic Server statistics', None, '1'),
+  ('appendices/command-line/tsxs.en', 'tsxs', u'Traffic Server plugin tool', None, '1'),
+  ('appendices/command-line/traffic_via.en', 'traffic_via', u'Traffic Server Via header decoder', None, '1'),
 
-  ('reference/configuration/cache.config.en', 'cache.config', u'Traffic Server cache configuration file', None, '5'),
-  ('reference/configuration/congestion.config.en', 'congestion.config', u'Traffic Server congestion control configuration file', None, '5'),
-  ('reference/configuration/hosting.config.en', 'hosting.config', u'Traffic Server domain hosting configuration file', None, '5'),
-  ('reference/configuration/icp.config.en', 'icp.config', u'Traffic Server ICP configuration file', None, '5'),
-  ('reference/configuration/ip_allow.config.en', 'ip_allow.config', u'Traffic Server IP access control configuration file', None, '5'),
-  ('reference/configuration/log_hosts.config.en', 'log_hosts.config', u'Traffic Server log host configuration file', None, '5'),
-  ('reference/configuration/logs_xml.config.en', 'logs_xml.config', u'Traffic Server log format configuration file', None, '5'),
-  ('reference/configuration/parent.config.en', 'parent.config', u'Traffic Server parent cache configuration file', None, '5'),
-  ('reference/configuration/plugin.config.en', 'plugin.config', u'Traffic Server global plugin configuration file', None, '5'),
-  ('reference/configuration/records.config.en', 'records.config', u'Traffic Server configuration file', None, '5'),
-  ('reference/configuration/remap.config.en', 'remap.config', u'Traffic Server remap rules configuration file', None, '5'),
-  ('reference/configuration/splitdns.config.en', 'splitdns.config', u'Traffic Server split DNS configuration file', None, '5'),
-  ('reference/configuration/ssl_multicert.config.en', 'ssl_multicert.config', u'Traffic Server SSL certificate configuration file', None, '5'),
-  ('reference/configuration/storage.config.en', 'storage.config', u'Traffic Server cache storage configuration file', None, '5'),
-  ('reference/configuration/volume.config.en', 'volume.config', u'Traffic Server cache volume configuration file', None, '5'),
+  ('admin-guide/files/cache.config.en', 'cache.config', u'Traffic Server cache configuration file', None, '5'),
+  ('admin-guide/files/congestion.config.en', 'congestion.config', u'Traffic Server congestion control configuration file', None, '5'),
+  ('admin-guide/files/hosting.config.en', 'hosting.config', u'Traffic Server domain hosting configuration file', None, '5'),
+  ('admin-guide/files/icp.config.en', 'icp.config', u'Traffic Server ICP configuration file', None, '5'),
+  ('admin-guide/files/ip_allow.config.en', 'ip_allow.config', u'Traffic Server IP access control configuration file', None, '5'),
+  ('admin-guide/files/log_hosts.config.en', 'log_hosts.config', u'Traffic Server log host configuration file', None, '5'),
+  ('admin-guide/files/logs_xml.config.en', 'logs_xml.config', u'Traffic Server log format configuration file', None, '5'),
+  ('admin-guide/files/parent.config.en', 'parent.config', u'Traffic Server parent cache configuration file', None, '5'),
+  ('admin-guide/files/plugin.config.en', 'plugin.config', u'Traffic Server global plugin configuration file', None, '5'),
+  ('admin-guide/files/records.config.en', 'records.config', u'Traffic Server configuration file', None, '5'),
+  ('admin-guide/files/remap.config.en', 'remap.config', u'Traffic Server remap rules configuration file', None, '5'),
+  ('admin-guide/files/splitdns.config.en', 'splitdns.config', u'Traffic Server split DNS configuration file', None, '5'),
+  ('admin-guide/files/ssl_multicert.config.en', 'ssl_multicert.config', u'Traffic Server SSL certificate configuration file', None, '5'),
+  ('admin-guide/files/storage.config.en', 'storage.config', u'Traffic Server cache storage configuration file', None, '5'),
+  ('admin-guide/files/update.config.en', 'update.config', u'Traffic Server automated update configuration file', None, '5'),
+  ('admin-guide/files/volume.config.en', 'volume.config', u'Traffic Server cache volume configuration file', None, '5'),
 
 ]
 

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/preface/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/preface/index.en.rst b/doc/preface/index.en.rst
new file mode 100644
index 0000000..27eca8c
--- /dev/null
+++ b/doc/preface/index.en.rst
@@ -0,0 +1,130 @@
+.. 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.
+
+.. include:: ../common.defs
+
+.. _preface:
+
+Preface
+*******
+
+.. toctree::
+  :maxdepth: 2
+
+What is Apache Traffic Server?
+==============================
+
+|ATS| 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. |TS| is designed to improve content
+delivery for enterprises, Internet service providers (ISPs), backbone
+providers, and large intranets by maximizing existing and available bandwidth.
+
+This manual will explore every aspect of installing, managing, extending, and
+troubleshooting |TS|.
+
+Typographic Conventions
+=======================
+
+This documentation uses the following typographic conventions:
+
+Italic
+    Used to introduce new terms on their initial appearance.
+
+    Example:
+        The |ATS| object storage is based on a *cyclone buffer* architecture.
+        Cyclone buffers are a form of storage addressing in which a single
+        writer continually reclaims the oldest allocations for use by new
+        updates.
+
+Monospace
+    Represents C/C++ language statements, commands, file paths, file content,
+    and computer output.
+
+    Example:
+        The default installation prefix for |TS| is ``/usr/local/ts``.
+
+Bracketed Monospace
+    Represents variables for which you should substitute a value in file content
+    or commands.
+
+    Example:
+        Running the command ``traffic_line -r <name>`` will display the current
+        value of a performance statistic, where ``<name>`` is the statistic
+        whose value you wish to view.
+
+Ellipsis
+    Indicates the omission of irrelevant or unimportant information.
+
+.. _intro-other-resources:
+
+Other Resources
+===============
+
+Websites
+--------
+
+Official Website
+    https://trafficserver.apache.org/
+
+    The official |ATS| project website is hosted by the |ASF|. Documentation,
+    software downloads, community resource links, security announcements, and
+    more are located, or linked to, at the site.
+
+Online Documentation
+    https://docs.trafficserver.apache.org/
+
+    The most up to date version of the documentation is hosted at |RTD|, with
+    built-in search functionality. Documentation for past releases is also
+    available.
+
+Jira Bug Tracker
+    https://issues.apache.org/jira/browse/TS
+
+    If you wish to report bugs, or look for open issues on which you may help
+    contribute to the |TS| project, please visit the public Jira bug tracker
+    site.
+
+Mailing Lists
+-------------
+
+User List
+    The user's mailing list offers support and discussions oriented to users
+    and administrators of the |TS| software.
+
+    Send an email to ``users-subscribe@trafficserver.apache.org`` to join the
+    list.
+
+Developer List
+    If you have questions about, or wish to discuss, the development of |TS|,
+    plugins for the server, or other developer-oriented matters, the developer
+    list offers an active list of both core project members and external
+    contributors.
+
+    Send an email to ``dev-subscribe@trafficserver.apache.org`` to join the
+    list.
+
+Internet Relay Chat (IRC)
+-------------------------
+
+The ``#traffic-server`` channel on ``irc.freenode.net`` is the official IRC
+resource for the |TS| project, and boasts active discussions.
+
+Community Forums
+----------------
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/reference/api/TSAPI.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/api/TSAPI.en.rst b/doc/reference/api/TSAPI.en.rst
deleted file mode 100644
index bfc9c5a..0000000
--- a/doc/reference/api/TSAPI.en.rst
+++ /dev/null
@@ -1,145 +0,0 @@
-.. 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.
-
-.. default-domain:: c
-
-=====
-TSAPI
-=====
-
-Introduction to the Apache Traffic Server API.
-
-Synopsis
-========
-| `#include <ts/ts.h>`
-| `#include <ts/remap.h>`
-
-Description
-===========
-The Apache Traffic Server API enables you to create plugins, using
-the C programming language, that customize the behavior of your
-Traffic Server installation.
-
-Traffic Server enables sophisticated caching and processing of
-web-related traffic, such as DNS and HTTP requests and responses.
-Traffic Server itself consists of an event-driven loop that can be
-simplified as follows::
-
-    for (;;) {
-        event = get_next_event();
-        handle_event (event);
-    }
-
-You compile your plugin source code to create a shared library that
-Traffic Server loads when it is started. Your plugin contains
-callback functions that are registered for specific Traffic Server
-events. When Traffic Server needs to process an event, it invokes
-any and all call-back functions you've registered for that event
-type.
-
-Possible uses for plugins include the following:
-
-* HTTP processing plugins can filter, blacklist, authorize users or transform content.
-* Protocol plugins can enable Traffic Server to proxy-cache new protocol content.
-* A blacklisting plugin denies attempts to access web sites that are off-limits.
-* Append transform plugins add data to HTTP response content.
-* An image conversion plugin transforms JPEG images to GIF images.
-* Compression plugins send response content to a compression server
-  that compresses the data (alternatively, a compression library local
-  to the Traffic Server host machine could do the compression).
-* Authorization plugins check a user's permissions to access
-  particular web sites. The plugin could consult a local authorization
-  program or send queries to an authorization server.
-* A plugin that gathers client information from request headers
-  and enters this information in a database.
-* A protocol plugin listen for specific protocol requests on a
-  designated port and then uses Traffic Server's proxy server and
-  cache to serve client requests.
-
-Naming conventions
-==================
-
-The Traffic Server API adheres to the following naming conventions:
-
-* The TS prefix is used for all function and variable names defined
-  in the Traffic Server API. For example, :data:`TS_EVENT_NONE`, :type:`TSMutex`,
-  and :func:`TSContCreate`.
-* Enumerated values are always written in all uppercase letters.
-  For example, :data:`TS_EVENT_NONE` and :data:`TS_VC_CLOSE_ABORT`.
-* Constant values are all uppercase; enumerated values can be seen
-  as a subset of constants. For example, :data:`TS_URL_SCHEME_FILE` and
-  :data:`TS_MIME_FIELD_ACCEPT`.
-* The names of defined types are mixed-case. For example, :type:`TSHttpSsn`
-  and :func:`TSHttpTxn`. :func:`TSDebug`
-* Function names are mixed-case. For example, :func:`TSUrlCreate`
-  and :func:`TSContDestroy`.
-* Function names use the following subject-verb naming style:
-  TS-<subject>-<verb>, where <subject> goes from general to specific.
-  This makes it easier to determine what a function does by reading
-  its name. For example, the function to retrieve the password field
-  (the specific subject) from a URL (the general subject) is
-  :func:`TSUrlPasswordGet`.
-* Common verbs like Create, Destroy, Get, Set, Copy, Find, Retrieve,
-  Insert, Remove, and Delete are used only when appropriate.
-
-Plugin loading and configuration
-================================
-
-When Traffic Server is first started, it consults the plugin.config
-file to determine the names of all shared plugin libraries that
-need to be loaded. The plugin.config file also defines arguments
-that are to be passed to each plugin's initialization function,
-:func:`TSPluginInit`. The :file:`records.config` file defines the path to
-each plugin shared library.
-
-The sample :file:`plugin.config` file below contains a comment line, a blank
-line, and two plugin configurations::
-
-    # This is a comment line.
-    my-plugin.so www.junk.com www.trash.com www.garbage.com
-    some-plugin.so arg1 arg2 $proxy.config.http.cache.on
-
-Each plugin configuration in the :file:`plugin.config` file resembles
-a UNIX or DOS shell command; each line in :file:`plugin.config`
-cannot exceed 1023 characters.
-
-The first plugin configuration is for a plugin named my-plugin.so.
-It contains three arguments that are to be passed to that plugin's
-initialization routine. The second configuration is for a plugin
-named some-plugin.so; it contains three arguments. The last argument,
-$proxy.config.http.cache.on, is actually a configuration variable.
-Traffic Server will look up the specified configuration variable
-and substitute its value.
-
-Plugins are loaded and initialized by Traffic Server in the order
-they appear in the :file:`plugin.config` file.
-
-Plugin initialization
-=====================
-
-Each plugin must define an initialization function named
-:func:`TSPluginInit` that Traffic Server invokes when the
-plugin is loaded. :func:`TSPluginInit` is commonly used to
-read configuration information and register hooks for event
-notification.
-
-Files
-=====
-:file:`{CONFIG_DIR}/plugin.config`, :file:`{CONFIG_DIR}/records.config`
-
-See also
-========
-:manpage:`TSPluginInit(3ts)`

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/reference/api/TSActionCancel.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/api/TSActionCancel.en.rst b/doc/reference/api/TSActionCancel.en.rst
deleted file mode 100644
index cf76213..0000000
--- a/doc/reference/api/TSActionCancel.en.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-.. 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.
-
-
-TSActionCancel
-==============
-
-Synopsis
---------
-
-`#include <ts/ts.h>`
-
-.. c:function:: void TSActionCancel(TSAction actionp)
-
-
-Description
------------


Mime
View raw message