You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2015/11/03 07:10:16 UTC
[40/51] trafficserver git commit: Documentation reorganization
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/remap.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/remap.config.en.rst b/doc/admin-guide/files/remap.config.en.rst
new file mode 100644
index 0000000..209d7ac
--- /dev/null
+++ b/doc/admin-guide/files/remap.config.en.rst
@@ -0,0 +1,495 @@
+.. 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.
+
+============
+remap.config
+============
+
+.. configfile:: remap.config
+
+.. include:: ../../common.defs
+
+.. toctree::
+ :maxdepth: 2
+
+
+The :file:`remap.config` file (by default, located in
+``/usr/local/etc/trafficserver/``) contains mapping rules that Traffic Server
+uses to perform the following actions:
+
+- Map URL requests for a specific origin server to the appropriate
+ location on Traffic Server when Traffic Server acts as a reverse
+ proxy for that particular origin server
+- Reverse-map server location headers so that when origin servers
+ respond to a request with a location header that redirects the client
+ to another location, the clients do not bypass Traffic Server
+- Redirect HTTP requests permanently or temporarily without Traffic
+ Server having to contact any origin servers
+
+Refer to :ref:`reverse-proxy-and-http-redirects`, for information about
+redirecting HTTP requests and using reverse proxy.
+
+After you modify the :file:`remap.config` run the
+:option:`traffic_ctl config reload` to apply the changes. When you apply the
+changes to one node in a cluster, Traffic Server automatically applies
+the changes to all other nodes in the cluster.
+
+Format
+======
+
+Each line in the :file:`remap.config` file must contain a mapping rule. Empty lines,
+or lines starting with ``#`` are ignored. Each line can be broken up into multiple
+lines for better readability by using ``\`` as continuation marker.
+
+Traffic Server recognizes three space-delimited fields: ``type``,
+``target``, and ``replacement``. The following list describes the format of each field.
+
+.. _remap-config-format-type:
+
+``type``
+ Enter one of the following:
+
+ - ``map`` --translates an incoming request URL to the appropriate
+ origin server URL.
+
+ - ``map_with_recv_port`` --exactly like 'map' except that it uses the port at
+ which the request was received to perform the mapping instead of the port present
+ in the request. The regex qualifier can also be used for this type. When present,
+ 'map_with_recv_port' mappings are checked first. If there is a match, then it is
+ chosen without evaluating the "regular" forward mapping rules.
+
+ - ``map_with_referer`` -- extended version of 'map', which can be used to activate
+ "deep linking protection", where target URLs are only accessible when the Referer
+ header is set to a URL that is allowed to link to the target.
+
+ - ``reverse_map`` --translates the URL in origin server redirect
+ responses to point to the Traffic Server.
+
+ - ``redirect`` --redirects HTTP requests permanently without having
+ to contact the origin server. Permanent redirects notify the
+ browser of the URL change (by returning an HTTP status code 301)
+ so that the browser can update bookmarks.
+
+ - ``redirect_temporary`` --redirects HTTP requests temporarily
+ without having to contact the origin server. Temporary redirects
+ notify the browser of the URL change for the current request only
+ (by returning an HTTP status code 307).
+
+ .. note: use the ``regex_`` prefix to indicate that the line has a regular expression (regex).
+
+.. _remap-config-format-target:
+
+``target``
+ Enter the origin ("from") URL. You can enter up to four components: ::
+
+ scheme://host:port/path_prefix
+
+ where ``scheme`` is ``http``, ``https``, ``ws`` or ``wss``.
+
+.. _remap-config-format-replacement:
+
+``replacement``
+ Enter the origin ("from") URL. You can enter up to four components: ::
+
+ scheme://host:port/path_prefix
+
+ where ``scheme`` is ``http``, ``https``, ``ws`` or ``wss``.
+
+
+.. _remap-config-precedence:
+
+Precedence
+==========
+
+Remap rules are not processed top-down, but based on an internal
+priority. Once these rules are executed we pick the first match
+based on configuration file parse order.
+
+1. ``map_with_recv_port`` and ```regex_map_with_recv_port```
+#. ``map`` and ``regex_map`` and ``reverse_map``
+#. ``redirect`` and ``redirect_temporary``
+#. ``regex_redirect`` and ``regex_redirect_temporary``
+
+
+Match-All
+=========
+
+A map rule with a single ``/`` acts as a wildcard, it will match any
+request. This should be use with care, and certainly only once at the
+end of the remap.config file. E.g.
+
+::
+
+ map / http://all.example.com
+
+Examples
+--------
+
+The following section shows example mapping rules in the
+:file:`remap.config` file.
+
+Reverse Proxy Mapping Rules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example shows a map rule that does not specify a path
+prefix in the target or replacement: ::
+
+ map http://www.x.com/ http://server.hoster.com/
+ reverse_map http://server.hoster.com/ http://www.x.com/
+
+This rule results in the following translations:
+
+================================================ ========================================================
+Client Request Translated Request
+================================================ ========================================================
+``http://www.x.com/Widgets/index.html`` ``http://server.hoster.com/Widgets/index.html``
+``http://www.x.com/cgi/form/submit.sh?arg=true`` ``http://server.hoster.com/cgi/form/submit.sh?arg=true``
+================================================ ========================================================
+
+The following example shows a map rule with path prefixes specified in
+the target: ::
+
+ map http://www.y.com/marketing/ http://marketing.y.com/
+ reverse_map http://marketing.y.com/ http://www.y.com/marketing/
+ map http://www.y.com/sales/ http://sales.y.com/
+ reverse_map http://sales.y.com/ http://www.y.com/sales/
+ map http://www.y.com/engineering/ http://engineering.y.com/
+ reverse_map http://engineering.y.com/ http://www.y.com/engineering/
+ map http://www.y.com/stuff/ http://info.y.com/
+ reverse_map http://info.y.com/ http://www.y.com/stuff/
+
+These rules result in the following translations:
+
+=============================================================== ==========================================================
+Client Request Translated Request
+=============================================================== ==========================================================
+``http://www.y.com/marketing/projects/manhattan/specs.html`` ``http://marketing.y.com/projects/manhattan/specs.html``
+``http://www.y.com/stuff/marketing/projects/boston/specs.html`` ``http://info.y.com/marketing/projects/boston/specs.html``
+``http://www.y.com/engineering/marketing/requirements.html`` ``http://engineering.y.com/marketing/requirements.html``
+=============================================================== ==========================================================
+
+The following example shows that the order of the rules matters: ::
+
+ map http://www.g.com/ http://external.g.com/
+ reverse_map http://external.g.com/ http://www.g.com/
+ map http://www.g.com/stuff/ http://stuff.g.com/
+ reverse_map http://stuff.g.com/ http://www.g.com/stuff/
+
+These rules result in the following translation.
+
+================================ =====================================
+Client Request Translated Request
+================================ =====================================
+``http://www.g.com/stuff/a.gif`` ``http://external.g.com/stuff/a.gif``
+================================ =====================================
+
+In the above examples, the second rule is never applied because all URLs
+that match the second rule also match the first rule. The first rule
+takes precedence because it appears earlier in the :file:`remap.config`
+file.
+
+The following example shows a mapping with a path prefix specified in
+the target and replacement::
+
+ map http://www.h.com/a/b/ http://server.h.com/customers/x/y
+ reverse_map http://server.h.com/customers/x/y/ http://www.h.com/a/b/
+
+This rule results in the following translation.
+
+===================================== ==================================================
+Client Request Translated Request
+===================================== ==================================================
+``http://www.h.com/a/b/c/d/doc.html`` ``http://server.h.com/customers/x/y/c/d/doc.html``
+``http://www.h.com/a/index.html`` ``Translation fails``
+===================================== ==================================================
+
+The following example shows reverse-map rules::
+
+ map http://www.x.com/ http://server.hoster.com/x/
+ reverse_map http://server.hoster.com/x/ http://www.x.com/
+
+These rules result in the following translations.
+
+================================ =====================================
+Client Request Translated Request
+================================ =====================================
+``http://www.x.com/Widgets`` ``http://server.hoster.com/x/Widgets``
+================================ =====================================
+
+
+
+================================ ======================================= =============================
+Client Request Origin Server Header Translated Request
+================================ ======================================= =============================
+``http://www.x.com/Widgets`` ``http://server.hoster.com/x/Widgets/`` ``http://www.x.com/Widgets/``
+================================ ======================================= =============================
+
+When acting as a reverse proxy for multiple servers, Traffic Server is
+unable to route to URLs from older browsers that do not send the
+``Host:`` header. As a solution, set the variable :ts:cv:`proxy.config.header.parse.no_host_url_redirect`
+in the :file:`records.config` file to the URL to which Traffic Server will redirect
+requests without host headers.
+
+Redirect Mapping Rules
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following rule permanently redirects all HTTP requests for
+``www.company.com`` to ``www.company2.com``: ::
+
+ redirect http://www.company.com/ http://www.company2.com/
+
+The following rule *temporarily* redirects all HTTP requests for
+``www.company1.com`` to ``www.company2.com``: ::
+
+ redirect_temporary http://www.company1.com/ http://www.company2.com/
+
+.. _remap-config-regex:
+
+Regular Expression (regex) Remap Support
+========================================
+
+Regular expressions can be specified in remapping rules, with the
+limitations below:
+
+- Only the ``host`` field can contain a regex; the ``scheme``,
+ ``port``, and other fields cannot. For path manipulation via regexes,
+ use the ``regex_remap`` plugin.
+- The number of capturing subpatterns is limited to 9. This means that
+ ``$0`` through ``$9`` can be used as subtraction placeholders (``$0``
+ will be the entire input string).
+- The number of substitutions in the expansion string is limited to 10.
+- There is no ``regex_`` equivalent to ``reverse_remap``, so when using
+ ``regex_remap`` you should make sure the reverse path is clear by
+ setting (:ts:cv:`proxy.config.url_remap.pristine_host_hdr`)
+
+Examples
+--------
+
+::
+
+ regex_map http://x([0-9]+).z.com/ http://real-x$1.z.com/
+ regex_redirect http://old.(.*).z.com http://new.$1.z.com
+
+.. _map_with_referer:
+
+map_with_referer
+================
+
+the format of is the following::
+
+ map_with_referer client-URL origin-server-URL redirect-URL regex1 [regex2 ...]
+
+'redirect-URL' is a redirection URL specified according to RFC 2616 and can
+contain special formatting instructions for run-time modifications of the
+resulting redirection URL. All regexes Perl compatible regular expressions,
+which describes the content of the "Referer" header which must be
+verified. In case an actual request does not have "Referer" header or it
+does not match with referer regular expression, the HTTP request will be
+redirected to 'redirect-URL'.
+
+At least one regular expressions must be specified in order to activate
+'deep linking protection'. There are limitations for the number of referer
+regular expression strings - 2048. In order to enable the 'deep linking
+protection' feature in Traffic Server, configure records.config with::
+
+ CONFIG proxy.config.http.referer_filter INT 1
+
+In order to enable run-time formatting for redirect URL, configure::
+
+ CONFIG proxy.config.http.referer_format_redirect INT 1
+
+When run-time formatting for redirect-URL was enabled the following format
+symbols can be used::
+
+ %r - to substitute original "Referer" header string
+ %f - to substitute client-URL from 'map_with_referer' record
+ %t - to substitute origin-server-URL from 'map_with_referer' record
+ %o - to substitute request URL to origin server, which was created a
+ the result of a mapping operation
+
+Note: There is a special referer type "~*" that can be used in order to
+specify that the Referer header is optional in the request. If "~*" referer
+was used in map_with_referer mapping, only requests with Referer header will
+be verified for validity. If the "~" symbol was specified before referer
+regular expression, it means that the request with a matching referer header
+will be redirected to redirectURL. It can be used to create a so-called
+negative referer list. If "*" was used as a referer regular expression -
+all referers are allowed. Various combinations of "*" and "~" in a referer
+list can be used to create different filtering rules.
+
+map_with_referer Examples
+-------------------------
+
+::
+
+ map_with_referer http://y.foo.bar.com/x/yy/ http://foo.bar.com/x/yy/ http://games.bar.com/new_games .*\.bar\.com www.bar-friends.com
+
+Explanation: Referer header must be in the request, only ".*\.bar\.com" and "www.bar-friends.com" are allowed.
+
+::
+
+ map_with_referer http://y.foo.bar.com/x/yy/ http://foo.bar.com/x/yy/ http://games.bar.com/new_games * ~.*\.evil\.com
+
+Explanation: Referer header must be in the request but all referers are allowed except ".*\.evil\.com".
+
+::
+
+ map_with_referer http://y.foo.bar.com/x/yy/ http://foo.bar.com/x/yy/ http://games.bar.com/error ~* * ~.*\.evil\.com
+
+Explanation: Referer header is optional. However, if Referer header exists, only request from ".*\.evil\.com" will be redirected to redirect-URL.
+
+
+.. _remap-config-plugin-chaining:
+
+Plugin Chaining
+===============
+
+Plugins can be configured to be evaluated in a specific order, passing
+the results from one in to the next (unless a plugin returns 0, then the
+"chain" is broken).
+
+Examples
+--------
+
+::
+
+ map http://url/path http://url/path \
+ @plugin=/etc/traffic_server/config/plugins/plugin1.so @pparam=1 @pparam=2 \
+ @plugin=/etc/traffic_server/config/plugins/plugin2.so @pparam=3
+
+will pass "1" and "2" to plugin1.so and "3" to plugin2.so.
+
+This will pass "1" and "2" to plugin1.so and "3" to plugin2.so
+
+.. _remap-config-named-filters:
+
+Acl Filters
+===========
+
+Acl filters can be created to control access of specific remap lines. The markup
+is very similar to that of :file:`ip_allow.config`, with slight changes to
+accomodate remap markup
+
+Examples
+--------
+
+::
+
+ map http://foo.example.com/neverpost http://foo.example.com/neverpost @action=deny @method=post
+ map http://foo.example.com/onlypost http://foo.example.com/onlypost @action=allow @method=post
+
+ map http://foo.example.com/ http://foo.example.com/ @action=deny @src_ip=1.2.3.4
+ map http://foo.example.com/ http://foo.example.com/ @action=allow @src_ip=127.0.0.1
+
+ map http://foo.example.com/ http://foo.example.com/ @action=allow @src_ip=10.5.2.1 @in_ip=72.209.23.4
+
+ map http://foo.example.com/ http://foo.example.com/ @action=allow @src_ip=127.0.0.1 @method=post @method=get @method=head
+
+Note that these Acl filters will return a 403 response if the resource is restricted.
+
+The difference between ``@src_ip`` and ``@in_ip`` is that the ``@src_ip`` is the client
+ip and the ``in_ip`` is the ip address the client is connecting to (the incoming address).
+
+Named Filters
+=============
+
+Named filters can be created and applied to blocks of mappings using
+the ``.definefilter``, ``.activatefilter``, and ``.deactivatefilter``
+directives. Named filters must be defined using ``.definefilter`` before
+being used. Once defined, ``.activatefilter`` can used to activate a
+filter for all mappings that follow until deactivated with
+``.deactivatefilter``.
+
+The ``@internal`` operator can be used to filter on whether a request
+is generated by |TS| itself, usually by a plugin. This operator
+is helpful for remapping internal requests without allowing access
+to external users. By default both internal and external requests
+are allowed.
+
+
+Examples
+--------
+
+::
+
+ .definefilter disable_delete_purge @action=deny @method=delete @method=purge
+ .definefilter local_only @action=allow @src_ip=192.168.0.1-192.168.0.254 @src_ip=10.0.0.1-10.0.0.254
+
+ .activatefilter disable_delete_purge
+
+ map http://foo.example.com/ http://bar.example.com/
+
+ .activatefilter local_only
+ map http://www.example.com/admin http://internal.example.com/admin
+ .deactivatefilter local_only
+
+ map http://www.example.com/ http://internal.example.com/
+ map http://auth.example.com/ http://auth.internal.example.com/ @action=allow @internal
+
+The filter `disable_delete_purge` will be applied to all of the
+mapping rules. (It is activated before any mappings and is never
+deactivated.) The filter `local_only` will only be applied to the
+second mapping.
+
+Including Additional Remap Files
+================================
+
+The ``.include`` directive allows mapping rules to be spread across
+multiple files. The argument to the ``.include`` directive is a
+list of file names to be parsed for additional mapping rules. Unless
+the names are absolute paths, they are resolved relative to the
+Traffic Server configuration directory.
+
+The effect of the ``.include`` directive is as if the contents of
+the listed files is included in the parent and parsing restarted
+at the point of inclusion. This means that and filters named in the
+included files are global in scope, and that additional ``.include``
+directives are allowed.
+
+.. note::
+
+ Included remap files are not currently tracked by the configuration
+ subsystem. Changes to included remap files will not be noticed
+ by online configuration changes applied by :option:`traffic_ctl config reload`
+ unless :file:`remap.config` has also changed.
+
+Examples
+--------
+
+In this example, a top-level :file:`remap.config` file simply
+references additional mapping rules files ::
+
+ .include filters.config
+ .include one.example.com.config two.example.com.config
+
+The file `filters.config` contains ::
+
+ .definefilter deny_purge @action=deny @method=purge
+ .definefilter allow_purge @action=allow @method=purge
+
+The file `one.example.com.config` contains::
+
+ .activatefilter deny_purge
+ map http://one.example.com http://origin-one.example.com
+ .deactivatefilter deny_purge
+
+The file `two.example.com.config` contains::
+
+ .activatefilter allow_purge
+ map http://two.example.com http://origin-two.example.com
+ .deactivatefilter dallowpurge
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/splitdns.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/splitdns.config.en.rst b/doc/admin-guide/files/splitdns.config.en.rst
new file mode 100644
index 0000000..6697648
--- /dev/null
+++ b/doc/admin-guide/files/splitdns.config.en.rst
@@ -0,0 +1,129 @@
+.. 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.
+
+===============
+splitdns.config
+===============
+
+.. configfile:: splitdns.config
+
+The :file:`splitdns.config` file enables you to specify the DNS server that
+Traffic Server should use for resolving hosts under specific conditions.
+For more information, refer to :ref:`admin-split-dns`.
+
+To specify a DNS server, you must supply the following information in
+each active line within the file:
+
+- A primary destination specifier in the form of a destination domain,
+ a destination host, or a URL regular expression
+- A set of server directives, listing one or more DNS servers with
+ corresponding port numbers
+
+You can also include the following optional information with each DNS
+server specification:
+
+- A default domain for resolving hosts
+- A search list specifying the domain search order when multiple
+ domains are specified
+
+After you modify the :file:`splitdns.config` file,
+run the :option:`traffic_ctl config reload`
+command to apply the changes. When you apply changes to a node in a
+cluster, Traffic Server automatically applies the changes to all other
+nodes in the cluster.
+
+Format
+======
+
+Each line in the :file:`splitdns.config` file uses one of the following
+formats: ::
+
+ dest_domain=dest_domain | dest_host | url_regex named=dns_server def_domain=def_domain search_list=search_list
+
+The following list describes each field.
+
+.. _splitdns-config-format-dest-domain:
+
+``dest_domain``
+ A valid domain name. This specifies that DNS server selection will
+ be based on the destination domain. You can prefix the domain with
+ an exclamation mark (``!``) to indicate the NOT logical operator.
+
+.. _splitdns-config-format-dest-host:
+
+``dest_host``
+ A valid hostname. This specifies that DNS server selection will be
+ based on the destination host. You can prefix the host with an
+ exclamation mark (``!``) to indicate the ``NOT`` logical operator.
+
+.. _splitdns-config-format-url-regex:
+
+``url_regex``
+ A valid URL regular expression. This specifies that DNS server
+ selection will be based on a regular expression.
+
+.. _splitdns-config-format-named:
+
+``named``
+ This is a required directive. It identifies the DNS server that
+ Traffic Server should use with the given destination specifier. You
+ can specify a port using a colon (``:``). If you do not specify a
+ port, then 53 is used. Specify multiple DNS servers with spaces or
+ semicolons (``;``) as separators.
+
+ You must specify the domains with IP addresses in CIDR ("dot")
+ notation.
+
+.. _splitdns-config-format-def-domain:
+
+``def_domain``
+ A valid domain name. This optional directive specifies the default
+ domain name to use for resolving hosts. Only one entry is allowed.
+ If you do not provide the default domain, the system determines its
+ value from ``/etc/resolv.conf``
+
+.. _splitdns-config-format-search-list:
+
+``search_list``
+ A list of domains separated by spaces or semicolons (;). This
+ specifies the domain search order. If you do not provide the search
+ list, the system determines the value from :manpage:`resolv.conf(5)`
+
+Examples
+========
+
+Consider the following DNS server selection specifications: ::
+
+ dest_domain=internal.company.com named=255.255.255.255:212 255.255.255.254 def_domain=company.com search_list=company.com company1.com
+ dest_domain=!internal.company.com named=255.255.255.253
+
+Now consider the following two requests: ::
+
+ http://minstar.internal.company.com
+
+This request matches the first line and therefore selects DNS server
+``255.255.255.255`` on port ``212``. All resolver requests use
+``company.com`` as the default domain, and ``company.com`` and
+``company1.com`` as the set of domains to search first. ::
+
+ http://www.microsoft.com
+
+This request matches the second line. Therefore, Traffic Server selects
+DNS server ``255.255.255.253``. Because no ``def_domain`` or
+``search_list`` was supplied, Traffic Server retrieves this information
+from :manpage:`resolv.conf(5)`
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/ssl_multicert.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/ssl_multicert.config.en.rst b/doc/admin-guide/files/ssl_multicert.config.en.rst
new file mode 100644
index 0000000..0be58e6
--- /dev/null
+++ b/doc/admin-guide/files/ssl_multicert.config.en.rst
@@ -0,0 +1,228 @@
+.. 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.
+
+====================
+ssl_multicert.config
+====================
+
+.. configfile:: ssl_multicert.config
+
+The :file:`ssl_multicert.config` file lets you configure Traffic
+Server to use multiple SSL server certificates to terminate the SSL
+sessions. If you have a Traffic Server system with more than one
+IP address assigned to it, then you can assign a different SSL
+certificate to be served when a client requests a particular IP
+address or host name.
+
+At configuration time, certificates are parsed to extract the
+certificate subject and all the DNS `subject alternative names
+<http://en.wikipedia.org/wiki/SubjectAltName>`_. A certificate
+will be presented for connections requesting any of the hostnames
+found in the certificate. Wildcard names are supported, but only
+of the form `*.domain.com`, ie. where `*` is the leftmost domain
+component.
+
+Changes to :file:`ssl_multicert.config` can be applied to a running
+Traffic Server using :option:`traffic_ctl config reload`.
+
+Format
+======
+
+Each :file:`ssl_multicert.config` line consists of a sequence of
+`key=value` fields that specify how Traffic Server should use a
+particular SSL certificate.
+
+ssl_cert_name=FILENAME[,FILENAME ...]
+ The name of the file containing the TLS certificate. *FILENAME*
+ is located relative to the directory specified by the
+ :ts:cv:`proxy.config.ssl.server.cert.path` configuration variable.
+ It may also include the intermediate CA certificates, sorted from
+ leaf to root. At a minimum, the file must include a leaf
+ certificate.
+
+ When running with OpenSSL 1.0.2 or later, this directive can be
+ used to configure the intermediate CA chain on a per-certificate
+ basis. Multiple chain files are separated by comma character.
+ For example, it is possible able to configure a ECDSA certificate
+ chain and a RSA certificate chain and serve them simultaneously,
+ allowing OpenSSL to determine which certificate would be used
+ when the TLS session cipher suites are negotiated. Note that the
+ leaf certs in `FILENAME1` and `FILENAME2` must have the same
+ subjects and alternate names. The first certificate is used to
+ to match the client's SNI request.
+
+ You can also configure multiple leaf certificates in a same chain
+ with OpenSSL 1.0.1.
+
+ This is the only field that is required to be present.
+
+dest_ip=ADDRESS (optional)
+ The IP (v4 or v6) address that the certificate should be presented
+ on. This is now only used as a fallback in the case that the TLS
+ SubjectNameIndication extension is not supported. If *ADDRESS* is
+ `*`, the corresponding certificate will be used as the global
+ default fallback if no other match can be made. The address may
+ contain a port specifier, in which case the corresponding certificate
+ will only match for connections accepted on the specified port.
+ IPv6 addresses must be enclosed by square brackets if they have
+ a port, eg, [::1]:80. Care should be taken to make each ADDRESS unique.
+
+ssl_key_name=FILENAME (optional)
+ The name of the file containing the private key for this certificate.
+ If the key is contained in the certificate file, this field can
+ be omitted, otherwise *FILENAME* is resolved relative to the
+ :ts:cv:`proxy.config.ssl.server.private_key.path` configuration variable.
+
+ssl_ca_name=FILENAME (optional)
+ If the certificate is issued by an authority that is not in the
+ system CA bundle, additional certificates may be needed to validate
+ the certificate chain. *FILENAME* is resolved relative to the
+ :ts:cv:`proxy.config.ssl.CA.cert.path` configuration variable.
+
+ssl_ticket_enabled=1|0 (optional)
+ Enable RFC 5077 stateless TLS session tickets. To support this,
+ OpenSSL should be upgraded to version 0.9.8f or higher. This
+ option must be set to `0` to disable session ticket support.
+
+ticket_key_name=FILENAME (optional)
+ The name of session ticket key file which contains a secret for
+ encrypting and decrypting TLS session tickets. If *FILENAME* is
+ not an absolute path, it is resolved relative to the
+ :ts:cv:`proxy.config.ssl.server.cert.path` configuration variable.
+ This option has no effect if session tickets are disabled by the
+ ``ssl_ticket_enabled`` option. The contents of the key file should
+ be 48 random bytes.
+
+ Session ticket support is enabled by default. If neither of the
+ ``ssl_ticket_enabled`` and ``ticket_key_name`` options are
+ specified, and internal session ticket key is generated. This
+ key will be different each time Traffic Server is started.
+
+ssl_key_dialog=builtin|"exec:/path/to/program [args]" (optional)
+ Method used to provide a pass phrase for encrypted private keys. If the
+ pass phrase is incorrect, SSL negotiation for this dest_ip will fail for
+ clients who attempt to connect.
+ Two options are supported: builtin and exec:
+
+ ``builtin`` - Requests pass phrase via stdin/stdout. User will be
+ provided the ssl_cert_name and be prompted for the pass phrase.
+ Useful for debugging.
+
+ ``exec:`` - Executes program /path/to/program and passes args, if
+ specified, to the program and reads the output from stdout for
+ the pass phrase. If args are provided then the entire exec: string
+ must be quoted with "" (see examples). Arguments with white space
+ are supported by single quoting ('). The intent is that this
+ program runs a security check to ensure that the system is not
+ compromised by an attacker before providing the pass phrase.
+
+Certificate Selection
+=====================
+
+Traffic Server attempts two certificate selections during SSL
+connection setup. An initial selection is made when a TCP connection
+is accepted. This selection examines the IP address and port that
+the client is connecting to and chooses the best certificate from
+the those that have a ``dest_ip`` specification. If no matching
+certificates are found, a default certificate is chosen. The final
+certificate selection is made during the SSL handshake. At this
+point, the client may use `Server Name Indication
+<http://en.wikipedia.org/wiki/Server_Name_Indication>`_ to request
+a specific hostname. Traffic Server will use this request to select
+a certificate with a matching subject or subject alternative name.
+Failing that, a wildcard certificate match is attempted. If no match
+can be made, the initial certificate selection remains in force.
+
+In all cases, Traffic Server attempts to select the most specific
+match. An address specification that contains a port number will
+take precedence over a specification that does not contain a port
+number. A specific certificate subject will take precedence over a
+wildcard certificate. In the case of multiple matching certificates
+the first match will be returned to non-SNI capable clients.
+
+Examples
+========
+
+The following example configures Traffic Server to use the SSL
+certificate ``server.pem`` for all requests to the IP address
+111.11.11.1 and the SSL certificate ``server1.pem`` for all requests
+to the IP address 11.1.1.1. Connections from all other IP addresses
+are terminated with the ``default.pem`` certificate.
+Since the private key is included in the certificate files, no
+private key name is specified.
+
+::
+
+ dest_ip=111.11.11.1 ssl_cert_name=server.pem
+ dest_ip=11.1.1.1 ssl_cert_name=server1.pem
+ dest_ip=* ssl_cert_name=default.pem
+
+The following example configures Traffic Server to use the ECDSA
+certificate chain ``ecdsa.pem`` or RSA certificate chain ``rsa.pem``
+for all requests.
+
+::
+
+ dest_ip=* ssl_cert_name=ecdsa.pem,rsa.pem
+
+The following example configures Traffic Server to use the ECDSA
+certificate chain ``ecdsa.pem`` or RSA certificate chain ``rsa.pem``
+for all requests, the public key and private key are in separate PEM files.
+Note that the number of files in ssl_key_name must match the files in ssl_cert_name,
+and they should be presented in the same order.
+
+::
+
+ dest_ip=* ssl_cert_name=ecdsa_pub.pem,rsa_pub.pem ssl_key_name=ecdsa_private.pem,rsa_private.pem
+
+The following example configures Traffic Server to use the SSL
+certificate ``server.pem`` and the private key ``serverKey.pem``
+for all requests to port 8443 on IP address 111.11.11.1. The
+``general.pem`` certificate is used for server name matches.
+
+::
+
+ dest_ip=111.11.11.1:8443 ssl_cert_name=server.pem ssl_key_name=serverKey.pem ssl_cert_name=general.pem
+
+The following example configures Traffic Server to use the SSL
+certificate ``server.pem`` for all requests to the IP address
+111.11.11.1. Session tickets are enabled with a persistent ticket
+key.
+
+::
+
+ dest_ip=111.11.11.1 ssl_cert_name=server.pem ssl_ticket_enabled=1 ticket_key_name=ticket.key
+
+The following example configures Traffic Server to use the SSL
+certificate ``server.pem`` and disable session tickets for all
+requests to the IP address 111.11.11.1.
+
+::
+
+ dest_ip=111.11.11.1 ssl_cert_name=server.pem ssl_ticket_enabled=0
+
+The following examples configure Traffic Server to use the SSL
+certificate ``server.pem`` which includes an encrypted private key.
+The external program /usr/bin/mypass will be called on startup with one
+parameter (foo) in the first example, and with two parameters (foo)
+and (ba r) in the second example, the program (mypass) will return the
+pass phrase to decrypt the keys.
+
+::
+
+ ssl_cert_name=server1.pem ssl_key_dialog="exec:/usr/bin/mypass foo"
+ ssl_cert_name=server2.pem ssl_key_dialog="exec:/usr/bin/mypass foo 'ba r'"
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/storage.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/storage.config.en.rst b/doc/admin-guide/files/storage.config.en.rst
new file mode 100644
index 0000000..1c958ba
--- /dev/null
+++ b/doc/admin-guide/files/storage.config.en.rst
@@ -0,0 +1,186 @@
+.. 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.
+
+==============
+storage.config
+==============
+
+.. configfile:: storage.config
+
+The :file:`storage.config` file (by default, located in
+``/usr/local/etc/trafficserver/``) lists all the files, directories, and/or
+hard disk partitions that make up the Traffic Server cache. After you
+modify the :file:`storage.config` file the new settings will not be effective until Traffic Server is restarted.
+
+Format
+======
+
+The format of the :file:`storage.config` file is a series of lines of the form
+
+ *pathname* *size* [ ``volume=``\ *number* ] [ ``id=``\ *string* ]
+
+where :arg:`pathname` is the name of a partition, directory or file, :arg:`size` is the size of the
+named partition, directory or file (in bytes), and :arg:`volume` is the volume number used in the
+files :file:`volume.config` and :file:`hosting.config`. :arg:`id` is used for seeding the
+:ref:`assignment-table`. You must specify a size for directories; size is optional for files and raw
+partitions. :arg:`volume` and arg:`seed` are optional.
+
+.. note::
+
+ The :arg:`volume` option is independent of the :arg:`seed` option and either can be used with or without the other,
+ and their ordering on the line is irrelevant.
+
+.. note::
+
+ If the :arg:`id` option is used every use must have a unique value for :arg:`string`.
+
+You can use any partition of any size. For best performance:
+
+- Use raw disk partitions.
+- For each disk, make all partitions the same size.
+- For each node, use the same number of partitions on all disks.
+- Group similar kinds of storage into different volumes. For example
+ split out SSD's or RAM drives into their own volume.
+
+Specify pathnames according to your operating system requirements. See
+the following examples. In the :file:`storage.config` file, a formatted or
+raw disk must be at least 128 MB.
+
+When using raw disk or partitions, you should make sure the :ts:cv:`Traffic
+Server user <proxy.config.admin.user_id>` used by the Traffic Server process
+has read and write privileges on the raw disk device or partition. One good
+practice is to make sure the device file is set with 'g+rw' and the Traffic
+Server user is in the group which owns the device file. However, some
+operating systems have stronger requirements - see the following examples for
+more information.
+
+As with standard ``records.config`` integers, human readable prefixes are also
+supported. They include
+
+ - ``K`` Kilobytes (1024 bytes)
+ - ``M`` Megabytes (1024^2 or 1,048,576 bytes)
+ - ``G`` Gigabytes (1024^3 or 1,073,741,824 bytes)
+ - ``T`` Terabytes (1024^4 or 1,099,511,627,776 bytes)
+
+.. _assignment-table:
+
+Assignment Table
+----------------
+
+Each storage element defined in :file:`storage.config` is divided in to :term:`stripes`. The
+assignment table maps from an object URL to a specific stripe. The table is initialized based on a
+pseudo-random process which is seeded by hashing a string for each stripe. This string is composed
+of a base string, an offset (the start of the stripe on the storage element), and the length of the
+stripe. By default the path for the storage is used as the base string. This ensures that each
+stripe has a unique string for the assignment hash. This does make the assignment table very
+sensitive to the path for the storage elements and changing even one can have a cascading effect
+which will effectively clear most of the cache. This can be problem when drives fail and a system
+reboot causes the path names to change.
+
+The :arg:`id` option can be used to create a fixed string that an administrator can use to keep the
+assignment table consistent by maintaing the mapping from physical device to base string even in the presence of hardware changes and failures.
+
+Examples
+========
+
+The following basic example shows 128 MB of cache storage in the
+``/big_dir`` directory::
+
+ /big_dir 134217728
+
+You can use the ``.`` symbol for the current directory. Here is an
+example for 64 MB of cache storage in the current directory::
+
+ . 134217728
+
+As an alternative, using the human readable prefixes, you can express a 64GB
+cache file with::
+
+ /really_big_dir 64G
+
+
+.. note::
+ When using on-filesystem cache disk storage, you can only have one such
+ directory specified. This will be address in a future version.
+
+
+Solaris Example
+---------------
+
+The following example is for the Solaris operating system::
+
+ /dev/rdsk/c0t0d0s5
+ /dev/rdsk/c0t0d1s5
+
+.. note:: Size is optional. If not specified, the entire partition is used.
+
+Linux Example
+-------------
+.. note::
+ Rather than refer to disk devices like ``/dev/sda``, ``/dev/sdb``, etc.,
+ modern Linux supports `alternative symlinked names for disk devices
+ <https://wiki.archlinux.org/index.php/persistent_block_device_naming#by-id_and_by-path>`_ in the ``/dev/disk``
+ directory structure. As noted for the :ref:`assignment-table` the path used for the disk can effect
+ the cache if it changes. This can be ameloriated in some cases by using one of the alternate paths
+ in via ``/dev/disk``. Note that if the ``by-id`` or ``by-path`` style is used, replacing a failed drive will cause
+ that path to change because the new drive will have a different physical ID or path. The original hash string can
+ be kept by adding :arg:`id` or :arg:`path` with the original path to the storage line.
+
+ If this is not sufficient then the :arg:`id` or :arg:`path` argument should be used to create a more permanent
+ assignment table. An example would be::
+
+ /dev/sde id=cache.disk.0
+ /dev/sdg id=cache.disk.1
+
+The following example will use an entire raw disk in the Linux operating
+system::
+
+ /dev/disk/by-id/[DiskA_ID] volume=1
+ /dev/disk/by-path/[DiskB_Path] volume=2
+
+In order to make sure :program:`traffic_server` will have access to this disk
+you can use :manpage:`udev(7)` to persistently set the right permissions. The
+following rules are targeted for an Ubuntu system, and stored in
+``/etc/udev/rules.d/51-cache-disk.rules``::
+
+ # Assign DiskA and DiskB to the tserver group
+ # make the assignment final, no later changes allowed to the group!
+ SUBSYSTEM=="block", KERNEL=="sd[ef]", GROUP:="tserver"
+
+In order to apply these settings, trigger a reload with :manpage:`udevadm(8)`:::
+
+ udevadm trigger --subsystem-match=block
+
+
+FreeBSD Example
+---------------
+
+Starting with 5.1 FreeBSD dropped support for explicit raw devices. All
+devices on FreeBSD can be accessed raw now.
+
+The following example will use an entire raw disk in the FreeBSD
+operating system::
+
+ /dev/ada1
+ /dev/ada2
+
+In order to make sure :program:`traffic_server` will have access to this disk
+you can use :manpage:`devfs(8)` to persistently set the right permissions. The
+following rules are stored in :manpage:`devfs.conf(5)`::
+
+ # Assign /dev/ada1 and /dev/ada2 to the tserver user
+ own ada[12] tserver:tserver
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/update.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/update.config.en.rst b/doc/admin-guide/files/update.config.en.rst
new file mode 100644
index 0000000..33a7931
--- /dev/null
+++ b/doc/admin-guide/files/update.config.en.rst
@@ -0,0 +1,213 @@
+.. 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.
+
+=============
+update.config
+=============
+
+.. configfile:: update.config
+
+The :file:`update.config` file controls how Traffic Server performs a
+scheduled update of specific local cache content. The file contains a
+list of URLs specifying objects that you want to schedule for update.
+
+A scheduled update performs a local HTTP ``GET`` on the objects at the
+specific time or interval. You can control the following parameters for
+each specified object:
+
+- The URL
+- URL-specific request headers, which overrides the default
+- The update time and interval
+- The recursion depth
+
+After you modify the :file:`update.config` file,
+run the :option:`traffic_line -x`
+command to apply changes. When you apply changes to one node in a
+cluster, Traffic Server automatically applies the changes to all other
+nodes in the cluster.
+
+Supported Tag/Attribute Pairs
+=============================
+
+Scheduled update supports the following tag/attribute pairs when
+performing recursive URL updates:
+
+- ``<a href=" ">``
+- ``<img src=" ">``
+- ``<img href=" ">``
+- ``<body background=" ">``
+- ``<frame src=" ">``
+- ``<iframe src=" ">``
+- ``<fig src=" ">``
+- ``<overlay src=" ">``
+- ``<applet code=" ">``
+- ``<script src=" ">``
+- ``<embed src=" ">``
+- ``<bgsound src=" ">``
+- ``<area href=" ">``
+- ``<base href=" ">``
+- ``<meta content=" ">``
+
+Scheduled update is designed to operate on URL sets consisting of
+hundreds of input URLs (expanded to thousands when recursive URLs are
+included); it is *not* intended to operate on extremely large URL sets,
+such as those used by Internet crawlers.
+
+Format
+======
+
+Each line in the :file:`update.config` file uses the following format::
+
+ URL\request_headers\offset_hour\interval\recursion_depth\
+
+The following list describes each field.
+
+.. _update-config-format-url:
+
+*URL*
+ HTTP-based URLs.
+
+.. _update-config-format-request-headers:
+
+*request_headers*
+ Optional. A list of headers, separated by semicolons, passed in each
+ ``GET`` request. You can define any request header that conforms to
+ the HTTP specification; the default is no request header.
+
+.. _update-config-format-offset-hour:
+
+*offset_hour*
+ The base hour used to derive the update periods. The range is 00-23
+ hours.
+
+.. _update-config-format-interval:
+
+*interval*
+ The interval (in seconds) at which updates should occur, starting at
+ the offset hour.
+
+.. _update-config-format-reecursion-depth:
+
+*recursion_depth*
+ The depth to which referenced URLs are recursively updated, starting
+ at the given URL. This field applies only to HTTP.
+
+Examples
+========
+
+An example HTTP scheduled update is provided below:
+
+::
+
+ http://www.company.com\User-Agent: noname user agent\13\3600\5\
+
+The example specifies the URL and request headers, an offset hour of 13
+(1 pm), an interval of one hour, and a recursion depth of 5. This would
+result in updates at 13:00, 14:00, 15:00, and so on. To schedule an
+update that occurs only once a day, use an interval value 86400 (i.e.,
+24 hours x 60 minutes x 60 seconds = 86400).
+
+.. XXX: The following seems misplaced here, and is probably better off placed in an apendix.
+
+Specifying URL Regular Expressions (``url_regex``)
+==================================================
+
+This section describes how to specify a ``url_regex``. Entries of type
+``url_regex`` within the configuration files use regular expressions to
+perform a match.
+
+The following list provides examples to show how to create a valid
+``url_regex``.
+
+``x``
+ Matches the character ``x``
+
+``.``
+ Match any character
+
+``^``
+ Specifies beginning of line
+
+``$``
+ Specifies end of line
+
+``[xyz]``
+ A **character class**. In this case, the pattern matches either
+ ``x``, ``y``, or\ ``z``
+
+``[abj-oZ]``
+ A **character class** with a range. This pattern matches ``a``,
+ ``b``, any letter from ``j`` through ``o``, or ``Z``
+
+``[^A-Z]``
+ A **negated character class**. For example, this pattern matches any
+ character except those in the class.
+
+``r*``
+ Zero or more ``r``, where ``r`` is any regular expression.
+
+``r+``
+ One or more ``r``, where ``r`` is any regular expression.
+
+``r?``
+ Zero or one ``r``, where ``r`` is any regular expression.
+
+``r{2,5}``
+ From two to five ``r``, where ``r`` is any regular expression.
+
+``r{2,}``
+ Two or more ``r``, where ``r`` is any regular expression.
+
+``r{4}``
+ Exactly four ``r``, where ``r`` is any regular expression.
+
+``"[xyz]\"images"``
+ The literal string ``[xyz]"images"``
+
+``\X``
+ If ``X`` is ``a, b, f, n, r, t,`` or ``v``, then the ``ANSI-C``
+ interpretation of ``\x``; otherwise, a literal ``X``. This is used
+ to escape operators such as ``*``
+
+``\0``
+ A ``NULL`` character
+
+``\123``
+ The character with octal value ``123``
+
+``\x2a``
+ The character with hexadecimal value ``2a``
+
+``(r)``
+ Matches an ``r``, where ``r`` is any regular expression. You can use
+ parentheses to override precedence.
+
+``rs``
+ The regular expression ``r``, followed by the regular expression
+ ``s``
+
+``r|s``
+ Either an ``r`` or an ``s``
+
+``#<n>#``
+ Inserts an **end node**, which causes regular expression matching to
+ stop when reached. The value ``n`` is returned.
+
+You can specify ``dest_domain=mydomain.com`` to match any host in
+``mydomain.com``. Likewise, you can specify ``dest_domain=.`` to match
+any request.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/files/volume.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/volume.config.en.rst b/doc/admin-guide/files/volume.config.en.rst
new file mode 100644
index 0000000..7c6d594
--- /dev/null
+++ b/doc/admin-guide/files/volume.config.en.rst
@@ -0,0 +1,69 @@
+.. 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.
+
+=============
+volume.config
+=============
+
+.. configfile:: volume.config
+
+The :file:`volume.config` file enables you to manage your cache space more
+efficiently and restrict disk usage by creating cache volumes of
+different sizes for specific protocols. You can further configure these
+volumes to store data from certain origin servers and/or domains in the
+:file:`hosting.config` file.
+
+.. important::
+
+ The volume configuration must be the same on all nodes in
+ a cluster. You must stop Traffic Server before you change the cache
+ volume size and protocol assignment. For step-by-step instructions about
+ partitioning the cache, refer to :ref:`partitioning-the-cache`.
+
+Format
+======
+
+For each volume you want to create, enter a line with the following
+format: ::
+
+ volume=volume_number scheme=protocol_type size=volume_size
+
+where ``volume_number`` is a number between 1 and 255 (the maximum
+number of volumes is 255) and ``protocol_type`` is ``http``. Traffic
+Server supports ``http`` for HTTP volume types; ``volume_size`` is the
+amount of cache space allocated to the volume. This value can be either
+a percentage of the total cache space or an absolute value. The absolute
+value must be a multiple of 128 MB, where 128 MB is the smallest value.
+If you specify a percentage, then the size is rounded down to the
+closest multiple of 128 MB.
+
+Each volume is striped across several disks to achieve parallel I/O. For
+example: if there are four disks, then a 1-GB volume will have 256 MB on
+each disk (assuming each disk has enough free space available). If you
+do not allocate all the disk space in the cache, then the extra disk
+space is not used. You can use the extra space later to create new
+volumes without deleting and clearing the existing volumes.
+
+Examples
+========
+
+The following example partitions the cache evenly between HTTP and HTTPS
+requests::
+
+ volume=1 scheme=http size=50%
+ volume=2 scheme=https size=50%
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/hierachical-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/hierachical-caching.en.rst b/doc/admin-guide/hierachical-caching.en.rst
new file mode 100644
index 0000000..3987717
--- /dev/null
+++ b/doc/admin-guide/hierachical-caching.en.rst
@@ -0,0 +1,221 @@
+.. 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
+
+.. _admin-hierarchical-caching:
+
+Hierarchical Caching
+********************
+
+.. 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
+==============
+
+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 multiple parent caches so that
+if one parent is unavailable, the other parent caches will be checked in turn
+until either the request is serviced properly or no further parent caches are
+available and the origin server is contacted. This is called `Parent Failover`_.
+Traffic Server supports parent caching for both HTTP and HTTPS requests.
+
+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. This may be achieved by setting parent
+proxy rules in :file:`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
+
+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.
+
+Interaction with Remap.config
+-----------------------------
+
+If remap rules are required (:ts:cv:`proxy.config.reverse_proxy.enabled`),
+when a request comes in to a child node, its :file:`remap.config` is evaluated before
+parent selection. This means that the client request is translated according to the
+remap rule, and therefore, any parent selection should be made against the remapped
+host name. This is true regardless of pristine host headers
+(:ts:cv:`proxy.config.url_remap.pristine_host_hdr`) being enabled or not. The parent node
+will receive the translated request (and thus needs to be configured to accept it).
+
+
+Example
+~~~~~~~
+The client makes a request to Traffic Server for http://example.com. The origin server
+for the request is http://origin.example.com; the parent node is ``parent1.example.com``,
+and the child node is configured as a reverse proxy.
+
+If the child's :file:`remap.config` contains
+
+``map http://example.com http://origin.example.com``
+
+with the child's :file:`parent.config` containing
+
+``dest_domain=origin.example.com method=get parent="parent1.example.com:80`` )
+
+and parent cache (parent1.example.com) would need to have a :file:`remap.config`
+line similar to
+
+``map http://origin.example.com http://origin.example.com``
+
+With this example, if parent1.example.com is down, the child node would automatically
+directly contact the ``origin.example.com`` on a cache miss.
+
+
+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 :file:`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:
+
+Configuring Traffic Server to Use a Parent Cache
+------------------------------------------------
+
+To configure Traffic Server to use one or more parent caches, you must perform
+the configuration adjustments detailed below.
+
+.. note::
+
+ You need to configure the child cache only. Assuming the parent nodes are
+ configured to serve the child's origin server, no additional configuration is
+ needed for the nodes acting as Traffic Server parent caches.
+
+#. Enable the parent caching option by adjusting
+ :ts:cv:`proxy.config.http.parent_proxy_routing_enable` in
+ :file:`records.config`. ::
+
+ CONFIG proxy.config.http.parent_proxy_routing_enable INT 1
+
+#. 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.
+
+#. Edit :file:`parent.config` to set parent proxy rules which will 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 :option:`traffic_ctl config reload` to apply the configuration changes.
+
+.. _admin-icp-peering:
+
+ICP Peering
+===========
+
+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 :file:`records.config` file:
+
+* :ts:cv:`proxy.config.icp.enabled`
+* :ts:cv:`proxy.config.icp.icp_port`
+* :ts:cv:`proxy.config.icp.multicast_enabled`
+* :ts:cv:`proxy.config.icp.query_timeout`
+
+Edit :file:`icp.config` file located in the Traffic Server `config` directory:
+For each ICP peer you want to identify, enter a separate rule in the :file:`icp.config` file.
+
+Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/index.en.rst b/doc/admin-guide/index.en.rst
new file mode 100644
index 0000000..9fc3f35
--- /dev/null
+++ b/doc/admin-guide/index.en.rst
@@ -0,0 +1,56 @@
+.. 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
+
+.. _admin-guide:
+
+Administrator's Guide
+**********************
+
+Table of Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction.en
+ installation/index.en
+ configuration/index.en
+ interaction/index.en
+ security/index.en
+ storage/index.en
+ plugins/index.en
+ monitoring/index.en
+ performance/index.en
+ files/index.en
+ troubleshooting.en
+
+Audience
+========
+
+This section of the |ATS| Manual is aimed at those individuals looking to
+install and configure |TS| for use as a caching proxy server. The section
+assumes basic knowledge of the command line and system administration tasks.
+Detailed steps are provided on how to build and configure the software, so
+even if you have never used a compiler or looked at a Makefile before, you
+will find everything you need in the following chapters to get you up and
+running with your own instance of |TS|. Or so is our hope.
+
+Should you encounter problems, or find any of the instructions unclear or
+lacking, please seek help through one of the avenues listed in
+:ref:`intro-other-resources`.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/installation/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/installation/index.en.rst b/doc/admin-guide/installation/index.en.rst
new file mode 100644
index 0000000..d272bd5
--- /dev/null
+++ b/doc/admin-guide/installation/index.en.rst
@@ -0,0 +1,270 @@
+.. 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
+
+.. _admin-installing:
+
+Installing Traffic Server
+*************************
+
+.. toctree::
+ :maxdepth: 2
+
+.. _admin-supported-platforms:
+
+Supported Platforms
+===================
+
+.. _admin-traffic-server-versioning:
+
+Traffic Server Versioning
+=========================
+
+Before you get started with Traffic Server you may have to decide which
+version you want to use. Traffic Server follows the `Semantic Versioning
+<http://semver.org>`_ guidelines.
+
+A complete version number is made of a version-triplet: ``MAJOR.MINOR.PATCH``.
+
+As of v4.0.0, there are no longer any development (or unstable) releases.
+All releases are considered stable and ready for production use. Releases
+within a major version are always upgrade compatible. More details are
+available on the `New Release Processes
+<https://cwiki.apache.org/confluence/display/TS/Release+Process>`_ wiki
+page.
+
+Sometimes we speak of *trunk*, *master* or *HEAD*, all of which are used
+interchangeably. Trunk and master, or sometimes TIP or HEAD, refer to the
+latest code in a Git version control system (also referred to as a *repository*
+or *Git repo*). Master is always kept releasable, and compatible with the
+current major release version. Incompatible changes are sometimes committed on
+a next-major release branch; for example, we have the ``5.0.x`` branch where
+changes incompatible with 4.x are managed.
+
+.. _admin-binary-distributions:
+
+Binary Distributions
+====================
+
+.. _admin-build-from-source:
+
+Building From Source
+====================
+
+.. _admin-retrieving-tarballs:
+
+Retrieving Tarballs
+-------------------
+
+Compressed archives of the source code for |TS| are available on the official
+website's `Downloads <https://trafficserver.apache.org/downloads>`_ page. From
+there you may select the version most appropriate for your needs. The |TS|
+project does not provide binary downloads.
+
+.. _admin-cloning-from-version-control:
+
+Cloning from Version Control
+----------------------------
+
+|TS| uses a `public Git repository <https://git-wip-us.apache.org/repos/asf/trafficserver.git>`_
+for version control. This repository will also provide the most cutting edge
+source code if you wish to test out the latest features and bug fixes.
+
+.. note::
+
+ We do also have a `GitHub Mirror <https://github.com/apache/trafficserver>`_
+ that you may use to submit pull requests. However, it may not be
+ entirely up-to-date, and you should always refer to our official project
+ Git repository for the very latest state of the source code.
+
+.. _admin-build-dependencies:
+
+Build Dependencies
+------------------
+
+In order to build Traffic Server from source you will need the following
+development tools and libraries installed:
+
+- pkgconfig
+- libtool
+- gcc (>= 4.3 or clang > 3.0)
+- GNU make
+- openssl
+- tcl
+- expat
+- pcre
+- libcap
+- flex (for TPROXY)
+- hwloc
+- lua
+- curses (for :program:`traffic_top`)
+- curl (for :program:`traffic_top`)
+
+If you're building from a git clone, you'll also need:
+
+- git
+- autoconf
+- automake
+
+.. _admin-layouts:
+
+Layouts
+-------
+
+.. _admin-preparing-the-source-tree:
+
+Preparing the Source Tree
+-------------------------
+
+If you are buiding from a checkout of the Git repository, you will need to
+prepare the source tree by regenerating the configuration scripts. This is
+performed by running::
+
+ autoreconf -if
+
+At the base directory of your local clone.
+
+.. _admin-configuration-options:
+
+Configuration Options
+---------------------
+
+|TS| uses the standard ``configure`` script method of configuring the source
+tree for building. A full list of available options may always be obtained by
+running the following in the base directory of your unpackaged archive or Git
+working copy::
+
+ ./configure --help
+
+#. A ``configure`` script will be generated from ``configure.ac`` which may now
+ be used to configure the source tree for your build. ::
+
+ ./configure --prefix=/opt/ats
+
+ By default, Traffic Server will be built to use the ``nobody`` user and group.
+ You may change this with the ``--with-user`` argument to ``configure``::
+
+ ./configure --prefix=/opt/ats --with-user=tserver
+
+ If dependencies are not in standard paths (``/usr/local`` or ``/usr``),
+ you may need to pass options to ``configure`` to account for that::
+
+ ./configure --prefix=/opt/ats --with-lua=/opt/csw
+
+ Most ``configure`` path-options accept a format of "*INCLUDE_PATH*:*LIBRARY_PATH*"::
+
+ ./configure --prefix=/opt/ats --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
+
+#. Once the source tree has been configured, you may proceed on to building with
+ the generated Makefiles. The ``make check`` command may be used to perform
+ sanity checks on the resulting build, prior to installation, and it is
+ recommended that you use this. ::
+
+ make
+ make check
+
+#. With the source built and checked, you may now install all of the binaries,
+ header files, documentation, and other artifacts to their final locations on
+ your system. ::
+
+ sudo make install
+
+#. Finally, it is recommended that you run the regression test suite. Please note
+ that the regression tests will only be successful with the default layout. ::
+
+ cd /opt/ats
+ sudo bin/traffic_server -R 1
+
+.. _admin-adding-spdy-support:
+
+Adding SPDY Support
+-------------------
+
+Traffic Server v5.0.x and above are capable of supporting SPDY, but it is
+optional and must be explicitly configured during the build process.
+
+#. Clone the spdylay Git repository from tatsuhiro. ::
+
+ git clone https://github.com/tatsuhiro-t/spdylay
+
+#. Generate fresh configure scripts. ::
+
+ autoreconf -if
+
+#. Run the generated configuration script, choosing an installation location
+ for the overlay. ::
+
+ ./configure --prefix=/opt/spdylay
+
+#. Build and install the overlay. ::
+
+ make install
+
+#. Set the ``PKG_CONFIG_PATH`` enviroment variable to the appropriate path
+ in your newly-installed overlay directory. ::
+
+ export PKG_CONFIG_PATH=/opt/spdylay/lib/pkgconfig/
+
+#. Finally, you may proceed with the regular building of |TS| from source, with
+ the addition of a single new configuration option to enable SPDY support in
+ the produced binaries. ::
+
+ ./configure --enable-spdy
+
+.. _start-traffic-server:
+
+Start Traffic Server
+====================
+
+To start Traffic Server manually, issue the ``trafficserver`` command,
+passing in the subcommand ``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. ::
+
+ bin/trafficserver start
+
+
+The :program:`traffic_ctl` provides a quick way of viewing Traffic Server statistics
+and configuring the Traffic Server system via a command-line interface.
+
+:program:`traffic_ctl` commands take the following form::
+
+ bin/traffic_ctl COMMAND COMMAND ...
+
+For a list of :program:`traffic_ctl` commands, enter::
+
+ bin/traffic_ctl
+
+Please note that :program:`traffic_ctl`, while a fine tool for an
+administrator, is a poor choice for automation, especially that of
+monitoring. See our chapter on :ref:`monitoring-traffic`
+for how to do that more efficiently and effectively.
+
+.. _stop-traffic-server:
+
+Stop Traffic Server
+===================
+
+To stop Traffic Server, always use the :program:`trafficserver` command,
+passing in the attribute ``stop``. This command stops all the Traffic
+Server processes (:program:`traffic_manager`, :program:`traffic_server`, and
+:program:`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/ce162a6d/doc/admin-guide/interaction/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/interaction/index.en.rst b/doc/admin-guide/interaction/index.en.rst
new file mode 100644
index 0000000..87c11d9
--- /dev/null
+++ b/doc/admin-guide/interaction/index.en.rst
@@ -0,0 +1,35 @@
+.. 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
+
+.. _admin-interaction:
+
+Interacting with |TS|
+*********************
+
+.. toctree::
+ :maxdepth: 2
+
+Traffic Line
+============
+
+Stats Over HTTP
+===============
+
+Cache Inspector
+===============