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 2013/06/02 07:02:18 UTC
[21/26] Separate the Admin and SDK guides.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/monitoring-traffic.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/monitoring-traffic.en.rst b/doc/admin/monitoring-traffic.en.rst
new file mode 100644
index 0000000..f5af50e
--- /dev/null
+++ b/doc/admin/monitoring-traffic.en.rst
@@ -0,0 +1,110 @@
+Monitoring Traffic
+******************
+
+.. 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.
+
+Traffic Server provides several options for monitoring system
+performance and analyzing network traffic.
+
+This chapter discusses the following topics:
+
+.. toctree::
+ :maxdepth: 2
+
+Traffic Server Monitoring Tools
+===============================
+
+Traffic Server provides the following tools to monitor system
+performance and analyze network traffic:
+
+- Traffic Server can send email that's triggered by alarms that signal
+ any detected failure conditions; refer to `Working with Traffic
+ Manager Alarms <#WorkingTrafficManagerAlarms>`_.
+- The Traffic Line command-line interface provides an alternative
+ method of viewing Traffic Server performance and network traffic
+ information; refer to `Viewing Statistics from Traffic
+ Line <#ViewingStatisticsTrafficLine>`_.
+- The Traffic Shell command-line tool provides yet another alternative
+ method of viewing Traffic Server performance and network traffic
+ information; refer to `Starting Traffic
+ Shell <../getting-started#StartTrafficShell>`_.
+
+Working with Traffic Manager Alarms
+===================================
+
+Traffic Server signals an alarm when it detects a problem. For example,
+the space allocated to event logs could be full or Traffic Server may
+not be able to write to a configuration file.
+
+Configuring Traffic Server to Email Alarms
+------------------------------------------
+
+To configure Traffic Server to send an email to a specific address
+whenever an alarm occurs, follow the steps below:
+
+1. In the ```records.config`` <../configuration-files/records.config>`_
+ file
+2. Set the
+ `*``proxy.config.alarm_email``* <../configuration-files/records.config#proxy.config.alarm_email>`_
+ variable to the email address alarms will be routed to.
+3. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+Using a Script File for Alarms
+------------------------------
+
+Alarm messages are built into Traffic Server - you cannot change them.
+However, you can write a script file to execute certain actions when an
+alarm is signaled. Traffic Server provides a sample script file named
+``example_alarm_bin.sh`` in the ``bin`` directory; simply modify the
+file to suit your needs.
+
+Viewing Statistics from Traffic Line
+====================================
+
+You can use the Traffic Line command-line interface to view statistics
+about Traffic Server performance and web traffic. In addition to viewing
+statistics, you can also configure, stop, and restart the Traffic Server
+system. For additional information, refer to `Configuring Traffic Server
+Using Traffic Line <configure.htm#ConfiguringTSUsingTrafficLine>`_ and
+`Traffic Line Commands <../traffic-line-commands>`_. You can view
+specific information about a Traffic Server node or cluster by
+specifying the variable that corresponds to the statistic you want to
+see.
+
+**To view a statistic**, enter the following command:
+
+::
+
+ traffic_line -r variable
+
+where *``variable``* is the variable representing the information you
+want to view. For a list of variables you can specify, refer to `Traffic
+Line Variables <../traffic-line-commands##TrafficLineVariables>`_.
+
+For example, the following command displays the document hit rate for
+the Traffic Server node:
+
+::
+
+ traffic_line -r proxy.node.http.cache_hit_ratio
+
+If the Traffic Server ``bin`` directory is not in your path, then
+prepend the Traffic Line command with ``./`` (for example:
+``./traffic_line -r variable``).
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins.en.rst b/doc/admin/plugins.en.rst
new file mode 100644
index 0000000..c82bf9f
--- /dev/null
+++ b/doc/admin/plugins.en.rst
@@ -0,0 +1,81 @@
+Apache Traffic Server Plugins
+*****************************
+
+.. 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.
+
+
+Overview
+========
+
+One of the key features of Apache Traffic Server is modularity. Features
+that aren't needed in the core simply aren't there. This is a good
+thing, because it guarantees that our core can remain fast by
+concentrating on the things that we always provide: Caching and
+proxying.
+
+All other things can be moved into plugins, by opening up a consitent C
+API, everyone can implement their own functionality, without having to
+touch the core.
+
+Download
+========
+
+Apache Traffic Server Plugins considered stable are released together
+with the server. See `downloads </downloads>`_.
+
+All plugins, whether they have received enough production testing from
+our developers or feedback from our users to be consiered stable can
+still be optained seperately in source form via git:
+
+::
+ git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git/
+
+Plugins considered experimental are located under
+```plugins/experimental`` <https://git-wip-us.apache.org/repos/asf?p=trafficserver.git;a=tree;f=plugins/experimental;hb=HEAD>`_
+
+Build
+=====
+
+Most plugins can be build by simply issueing
+
+::
+ make
+
+in their source tree. Note that this requires you to have ``tsxs`` in
+your ``PATH``
+
+Plugins
+=======
+
+.. toctree::
+ :maxdepth: 2
+
+ plugins/balancer.en
+ plugins/buffer_upload.en
+ plugins/cacheurl.en
+ plugins/combo_handler.en
+ plugins/esi.en
+ plugins/geoip_acl.en
+ plugins/header_filter.en
+ plugins/hipes.en
+ plugins/mysql_remap.en
+ plugins/regex_remap.en
+ plugins/stale_while_revalidate.en
+ plugins/stats_over_http.en
+ plugins/gzip.en
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/balancer.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/balancer.en.rst b/doc/admin/plugins/balancer.en.rst
new file mode 100644
index 0000000..9d54d91
--- /dev/null
+++ b/doc/admin/plugins/balancer.en.rst
@@ -0,0 +1,92 @@
+Balancer Plugin
+***************
+
+.. 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 is a plugin for Traffic Server, that allows you to configure
+mapping rules.
+
+To use this plugin, configure a remap.config rule like
+
+::
+ map http://foo.com http://bar.com @plugin=balancer.so @pparam=rotation:news
+
+The "To-Url" in the remap.config rule is generally not used, unless the
+lookup completely fails (i.e. this is a backup URL for extreme error
+cases).
+
+This is a list of all available options (set via @pparam):
+
+::
+ rotation The name of the rotation (e.g. news) [to-host in remap]
+ hash What to hash on, url, path, cookie, ip, header (primary)
+ hash2 Optional, secondary hash, to hash within a multi-host bucket
+ bucketw Width of each hash bucket [1]
+
+The rotation parameter specifies which rotation to do the lookup on. If
+not specified, we will default to the same name as used in the To URL in
+the remap rule.
+
+The bucket width specifies how many hosts a particular hash bucket
+should contain, for example:
+
+::
+ @pparam=bucketw:2
+
+The hash parameter can be used zero or more times, without it, no
+hashing is done at all. If you have more than one hash keys, they are
+concatenated in the order specified. For example:
+
+::
+ @pparam=hash:ip @pparam=hash:cookie/B
+
+The "header" hash key takes a required extra value, for example:
+
+::
+ @pparam=hash:header/Host
+
+For "cookie" hash keys, you can optionally specify an identifier for
+which cookie to use (without it, the entire cookie header is used). For
+example:
+
+::
+ @pparam=hash:cookie/B
+
+The secondary hash ("hash2") is used to provide "stickiness" within a
+bucket that's larger than one host (i.e. bucketw > 1). This allows you
+to (for example) have a primary hash on the URL, where each URL is
+served by some number of servers. A secondary hash on B-cookie would
+then provide user stickiness, so that for a particular URL, a particular
+user will always hit the same server.
+
+If the hashes you've requested (either "hash" or "hash2") can not be
+generated, we default to using the URL instead for the primary hash. For
+the secondary hash, if set, we'll default to the src-IP. If these
+defaults are not desirable, make sure that you have at least one hash
+key that is guaranteed to exist (e.g. @pparam=hash:ip).
+
+If no "hash" parameters are specified, no hashing is done. This is the
+default behavior, obviously. In this cash, the "hash2" directive has no
+effect as well.
+
+Finally, a couple of "flag" options (parameters) are available, to
+control some of the lookup mechanisms:
+
+- @pparam=hostip will use the IP returned by the lookup
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/buffer_upload.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/buffer_upload.en.rst b/doc/admin/plugins/buffer_upload.en.rst
new file mode 100644
index 0000000..ab5f209
--- /dev/null
+++ b/doc/admin/plugins/buffer_upload.en.rst
@@ -0,0 +1,89 @@
+Buffer Upload Plugin
+********************
+
+.. 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.
+
+
+.. XXX Discribe what the heck this plugin actually does.
+
+Upload proxy specs for phase I:
+
+1. Memory buffering (buffer the entire POST data in IOBuffer before
+ connecting to OS) 1.1. Memory buffer size is configured with
+ "mem_buffer_size" in config file. Default and minimum value is 32K
+ You can increase it in the config file. If the size of a request is
+ larger than the "mem_buffer_size" value specifiied in the config
+ file, then the upload proxy feature will be disabled for this
+ particular request
+
+2. Disk buffering (buffer the entire POST data on disk before connecting
+ to OS) 2.1. Use disk async IO. This involved some changes in ATS core
+ . new APIs wrapping around ink_aio_read() and ink_aio_write() .
+ change to distinguish between api call's AIO and cache's AIO .
+ guarantee api call's AIO only involves certain amount of threads .
+ the number of threads is configurable in plugin's config file
+ (default is 4)
+
+3.
+
+ 2. Directories and files generated on disk . base directory:
+ FOOBAR/var/buffer_upload_tmp/ (configurable in config file) .
+ number of subdirectories: 64 (configurable in config file) .
+ filename are randomly generated . files will be removed when the
+ entire data have been sent out to OS . remove dangling files (left
+ on disk due to transaction interruption or traffic server crash)
+ at startup time
+
+4.
+
+ 3. Default chunk size when reading from disk: 16K, configurable in
+ config file
+
+5. Default buffering mode: disk aio buffering mode 3.1. to turn off disk
+ buffering, add a "use_disk_buffer 0" line in config file
+
+6. Trigger POST buffering on certain URLs 4.1. certain URLs will be
+ provided in a plain text file (one URL each line) 4.2. specify
+ filename in config file by "url_list_file" 4.3. max length of each
+ URL: 4096 (configurable in config file) 4.4. use exact match, don't
+ support regex for now
+
+7. URL conversion for Mail's specific URL format 5.1. for now check if
+ the "host" part in the URL is same as the proxy server name, then
+ will do this conversion 5.2. To turn on URL conversion feature, set
+ "convert_url 1" in config file
+
+8. All request headers inlcuding cookies plus the entire POST data will
+ be buffered (either in memory or on disk)
+
+9. Config file can be explicitly sepcified as a parameter in command
+ line (in plugin.config file)
+
+a sample config file:
+
+use_disk_buffer 1 convert_url 1 chunk_size 1024 url_list_file
+/tmp/url_list.conf max_url_length 10000 base_dir /tmp/test1
+subdir_num 100 thread_num 10 mem_buffer_size 40000
+
+default config file: FOOBAR/etc/upload.conf
+
+default config values: use_disk_buffer 1 convert_url 0 chunk_size
+16384 url_list_file none max_url_length 4096 base_dir
+FOOBAR/var/buffer_upload_tmp subdir_num 64 thread_num 4
+mem_buffer_size 32768
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/cacheurl.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/cacheurl.en.rst b/doc/admin/plugins/cacheurl.en.rst
new file mode 100644
index 0000000..0bda6e9
--- /dev/null
+++ b/doc/admin/plugins/cacheurl.en.rst
@@ -0,0 +1,58 @@
+CacheURL Plugin
+***************
+
+.. 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 plugin allows you to change the key that is used for caching a
+request.
+
+It is designed so that multiple requests that have different URLs but
+the same content (for example, site mirrors) need be cached only once.
+
+Installation
+============
+
+::
+ make
+ sudo make install
+
+If you don't have the traffic server binaries in your path, then you
+will need to specify the path to tsxs manually:
+
+::
+ make TSXS=/opt/ts/bin/tsxs
+ sudo make TSXS=/opt/ts/bin/tsxs install
+
+Configuration
+=============
+
+Create a ``cacheurl.config`` file in the plugin directory with the url
+patterns to match. See the ``cacheurl.config.example`` file for what to
+put in this file.
+
+Add the plugin to your
+```plugins.config`` <../../configuration-files/plugins.config>`_ file:
+
+::
+ cacheurl.so
+
+Start traffic server. Any rewritten URLs will be written to
+``cacheurl.log`` in the log directory by default.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/combo_handler.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/combo_handler.en.rst b/doc/admin/plugins/combo_handler.en.rst
new file mode 100644
index 0000000..11e4633
--- /dev/null
+++ b/doc/admin/plugins/combo_handler.en.rst
@@ -0,0 +1,74 @@
+Combohandler Plugin
+*******************
+
+.. 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 plugin provides that functionality (and more) with the same
+interface but with these differences in configuration:
+
+The arguments in the
+```plugin.config`` <../../configuration-files/plugin.config>`_ line in
+order represent
+
+1. The path that should triggers combo handler (defaults to
+ "admin/v1/combo")
+
+2. The name of the key used for signature verification (disabled by
+ default)
+
+A "-" can be supplied as a value for any of these arguments to request
+default value be applied.
+
+Also, just like the original combohandler, this plugin generates URLs of
+the form ``http://localhost/<dir>/<file-path>``. ``<dir>`` here defaults
+to ``l`` unless specified by the file path in the query parameter using
+a colon. For example:
+
+::
+ http://combo.com/admin/v1/combo?filepath1&dir1:filepath2&filepath3
+
+Will result in these three pages being fetched:
+
+::
+ http://localhost/l/filepath1
+ http://localhost/dir1/filepath2
+ http://localhost/l/filepath3
+
+Remap rules have to be specified to map the above URLs to desired
+content servers.
+
+The plugin also supports a prefix parameter. Common parts of successive
+file paths can be extracted and specified separately using a 'p' query
+parameter. Successive file path parameters are appended to this prefix
+to create complete file paths. The prefix will remain active until
+changed or cleared (set to an empty string). For example, the query
+
+::
+ "/file1&p=/path1/&file2&file3&p=&/file4&p=/dir:path2/&file5&file6"
+
+results in these file paths being "reconstructed":
+
+::
+ /file1
+ /path1/file2
+ /path1/file3
+ /file4
+ /dir:path2/file5
+ /dir:path2/file6
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/esi.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/esi.en.rst b/doc/admin/plugins/esi.en.rst
new file mode 100644
index 0000000..9130791
--- /dev/null
+++ b/doc/admin/plugins/esi.en.rst
@@ -0,0 +1,22 @@
+ESI Plugin (undocumented)
+*************************
+
+.. 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 plugin implements the ESI specification.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/geoip_acl.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/geoip_acl.en.rst b/doc/admin/plugins/geoip_acl.en.rst
new file mode 100644
index 0000000..774c146
--- /dev/null
+++ b/doc/admin/plugins/geoip_acl.en.rst
@@ -0,0 +1,111 @@
+GeoIP ACLs Plugin
+*****************
+
+.. 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 is a simple ATS plugin for denying (or allowing) requests based on
+the source IP geo-location. Currently only the Maxmind APIs are
+supported, but we'd be happy to other other (open) APIs if you let us
+know.
+
+Building
+========
+
+The build and installation requires a full installation of Apache
+Traffic Server v3.0.0 or later. In particular, the include files must be
+available, and the tsxs build script should be in the path (or modify
+the Makefile).
+
+::
+ % gmake
+ % sudo gmake install
+
+Configuration
+=============
+
+Once installed, there are three primary use cases, which we will discuss
+in details. Note that in all configurations, the first plugin parameter
+must specify what the matches should be applied to. Currently, only one
+rule set is supported, for Country ISO codes. This is specified with a
+parameter of
+
+::
+ @pparam=country
+
+Future additions to this plugin could include other regions, such as
+city, state, continent etc.
+
+The three typical use cases are as follows:
+
+1. Per remap configurations, applicable to the entire remap rule. This
+ is useful when you can partition your content so that entire prefix
+ paths should be filtered. For example, lets assume that
+ http://example.com/music is restricted to US customers only, and
+ everything else is world wide accessible. In remap.config, you would
+ have something like
+
+ ::
+ map http://example.com/music http://music.example.com \
+ @plugin=geoip_acl.so @pparam=country @pparam=allow @pparam=US
+
+ map http://example.com http://other.example.com
+
+2. If you can not partition the data with a path prefix, you can specify
+ a separate regex mapping filter. The remap.config file might then
+ look like
+
+ ::
+ map http://example.com http://music.example.com \
+ @plugin=geoip_acl.so @pparam=country \
+ @pparam=regex::/etc/music.regex
+
+where music.regex is a format with PCRE (perl compatible) regular
+expressions, and unique rules for match. E.g.
+
+::
+ .*\.mp3 allow US
+ .*\.ogg deny US
+
+Note that the default in the case of no matches on the regular
+expressions is to "allow" the request. This can be overriden, see next
+use case.
+
+3. You can also combine 1) and 2), and provide defaults in the
+ remap.config configuration, which then applies for the cases where no
+ regular expressions matches at all. This would be useful to override
+ the default which is to allow all requests that don't match. For
+ example
+
+ ::
+ map http://example.com http://music.example.com \
+ @plugin=geoip_acl.so @pparam=country @pparam=allow @pparam= US
+ @pparam=regex::/etc/music.regex
+
+This tells the plugin that in the situation where there is no matching
+regular expression, only allow requests originating from the US.
+
+Finally, there's one additional parameter option that can be used:
+
+::
+ @pparam=html::/some/path.html
+
+This will override the default reponse body for the denied responses
+with a custom piece of HTML. This can be useful to explain to your users
+why they are getting denied access to a particular piece of content.
+This configuration can be used with any of the use cases described
+above.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/gzip.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/gzip.en.rst b/doc/admin/plugins/gzip.en.rst
new file mode 100644
index 0000000..d601f0d
--- /dev/null
+++ b/doc/admin/plugins/gzip.en.rst
@@ -0,0 +1,98 @@
+gzip / deflate Plugin
+*********************
+
+.. 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 plugin gzips or deflates responses, whichever is applicable. It can
+compress origin respones as well as cached responses.
+
+Installation
+============
+
+First, run:
+
+::
+ make && sudo make install
+
+Then, add the following line to
+```plugin.config`` <../../configuration-files/plugin.config>`_:
+
+::
+ gzip.so
+
+In this case, the plugin will use the default behaviour:
+
+- Enable caching
+- Compress text/\* for every origin
+- Don't hide accept encoding from origin servers (for an offloading
+ reverse proxy)
+- No urls are disallowed from compression
+
+Configuration
+=============
+
+Alternatively, a configuration can also be specified:
+
+::
+ gzip.so <path-to-plugin>/sample.gzip.config
+
+After modifying plugin.cofnig, restart traffic server (sudo
+traffic_line -L) the configuration is re-read when a management update
+is given (sudo traffic_line -x)
+
+Options
+=======
+
+Flags and options are:
+
+``enabled``: (``true`` or ``false``) Enable or disable compression for a
+host.
+
+``remove-accept-encoding``: (``true`` or ``false``) Sets whether the
+plugin should hide the accept encoding from origin servers:
+
+- To ease the load on the origins.
+- For when the proxy parses responses, and the resulting
+ compression/decompression is wasteful.
+
+``cache``: (``true`` or ``false``) When set, the plugin stores the
+uncompressed and compressed response as alternates.
+
+``compressible-content-type``: Wildcard pattern for matching
+compressible content types.
+
+``disallow``: Wildcard pattern for disabling compression on urls.
+
+Options can be set globally or on a per-site basis, as such:
+
+::
+ # Set some global options first
+ cache true
+ enabled true
+ remove-accept-encoding false
+ compressible-content-type text/*
+
+ # Now set a configuration for www.example.com
+ [www.example.com]
+ cache false
+ remove-accept-encoding true
+ disallow /notthis/*.js
+
+See example.gzip.config for example configurations.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/header_filter.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/header_filter.en.rst b/doc/admin/plugins/header_filter.en.rst
new file mode 100644
index 0000000..755a458
--- /dev/null
+++ b/doc/admin/plugins/header_filter.en.rst
@@ -0,0 +1,143 @@
+Header Filter Plugin
+********************
+
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+The ``header_filter`` is a simple plugin for filtering out headers from
+requests (or responses). Typical configuration is done either with a
+global configuration, in
+```plugin.config`` <../../configuration-files/plugin.config>`_:
+
+::
+ header_filter.so /usr/local/etc/hdr_filters.conf
+
+Or, alternatively, in a
+```per-remap`` <../../configuration-files/remap.config>`_ rule
+configuration
+
+::
+ map http://a.com/ http://b.com @plugin=header_filter.so @pparam=hdr_filters.conf
+
+Even if you don't have a global configuration, if your remap rules
+schedules actions in hooks other than during remap, you must also add
+the ``header_filter.so`` to the
+```plugin.config`` <../../configuration-files/remap.config>`_ (see
+above), but without args:
+
+::
+ header_filter.so
+
+The configuration files looks like
+
+::
+ [READ_REQUEST_HDR]
+ X-From-Someone
+ Cookie
+
+ [READ_RESPONSE_HDR]
+ X-From-Server
+ Set-Cookie
+
+ [SEND_RESPONSE_HDR]
+ X-Fie "Test" # Match the entire string
+ X-Foo /Test/ # Match the (Perl) regex
+ X-Bar [Test* # Match the prefix string
+ X-Fum *Test] # Match the postfix string
+
+Comments are prefixed with ``#``, and in most cases, the regular
+expression matching is the best choice (very little overhead). The
+pattern matches can also take an option '``!``\ ' to reverse the test.
+The default action is to delete all headers that do (not) match the
+pattern. E.g.
+
+::
+ [SEND_REQUEST_HDR]
+ X-Fie /test/
+ X-Foo ! /test/i
+
+The final "``i``\ " qualifier (works on all pattern matches) forces the
+match or comparison to be made case insensitive (just like in Perl).
+
+It's also possible to replace or add headers, using the = and +
+operators. For example
+
+::
+ [SEND_REQUEST_HDR]
+ Host =www.example.com=
+ X-Foo +ATS+
+
+This will force the Host: header to have exactly one value,
+``www.example.com``, while ``X-Foo`` will have at least one header with
+the value ATS, but there could be more instances of the header from the
+existing header in the request.
+
+Possible hooks are
+
+::
+ READ_REQUEST_HDR
+ SEND_REQUEST_HDR
+ READ_RESPONSE_HDR
+ SEND_RESPONSE_HDR
+
+If not specified, the default hook to add the rules (headers to filter)
+is ``READ_REQUEST_HDR``. It's completely acceptable (and useful) to
+configure a remap rule to delete headers in a later hook (e.g. when
+reading a response from the server). This is what actually makes the
+plugin even remotely useful.
+
+Examples
+========
+
+Set X-Forwarded-Proto https on SSL connections
+----------------------------------------------
+
+Often times a backend wants to know whether it's running under HTTP or
+HTTPS. While not regulated standard, we can use the
+``X-Forwarded-Proto`` header for this purpose.
+
+In ```plugin.config`` <../../configuration-files/plugin.config>`_ we
+need to add:
+
+::
+ header_filter.so
+
+Then, in ```remap.config`` <../../configuration-files/remap.config>`_ we
+can configure ``header_filter`` on a case by case basis:
+
+::
+ map http://example.org http://172.16.17.42:8080
+ map https://example.org http://172.16.17.42:8080 @plugin=header_filter.so @pparam=/etc/trafficserver/x_fwd_proto.conf
+
+The configuration that ties everything together is then
+``/etc/trafficserver/x_fwd_proto.config``, to which we add:
+
+::
+ [SEND_REQUEST_HDR]
+ X-Forwarded-Proto =https=
+
+To activate this configuration, we need to restart Traffic Server with
+``traffic_line -L``.
+
+In the backend servers we can now pick this up and do appropriately set
+server variables that will be picked up by CGI programs for instance. In
+the case of Apache httpd backend, this can be acomplished with
+```mod_setenvif`` <http://httpd.apache.org/docs/current/mod/mod_setenvif.html#setenvif>`_:
+
+::
+ SetEnvIf X-Forwarded-Proto https HTTPS=on SSL=on
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/hipes.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/hipes.en.rst b/doc/admin/plugins/hipes.en.rst
new file mode 100644
index 0000000..2651c67
--- /dev/null
+++ b/doc/admin/plugins/hipes.en.rst
@@ -0,0 +1,64 @@
+HIPES system (undocumented)
+***************************
+
+.. 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 plugin implements the HIPES system.
+
+Configuration
+=============
+
+``server:<host>``
+ Name of the server to send this request to
+
+``urlp:<name>``
+ Default: ``url``
+ Name of the query parameter for the service URL
+
+``path:<path>``
+ Default: ``/``
+ Path to use for the service URL
+
+``ssl``
+ Default: ``no``
+ Use SSL when connecting to the service
+
+``service``
+ Service server, ``host[:port]``
+
+``server``
+ Default: ``hipes.yimg.com``
+ Name of HIPES server, ``host[:port]``
+
+``active_timeout``
+ The active connection timeout in ms
+
+``no_activity_timeout``
+ The no activity timeout in ms
+
+``connect_timeout``
+ The connect timeout in ms
+
+``dns_timeout``
+ The DNS timeout
+
+The timeout options override the server defaults (from
+```records.config`` <../../configuration-files/records.config>`_), and
+only apply to the connection to the specific "service" host.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/mysql_remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/mysql_remap.en.rst b/doc/admin/plugins/mysql_remap.en.rst
new file mode 100644
index 0000000..671e83b
--- /dev/null
+++ b/doc/admin/plugins/mysql_remap.en.rst
@@ -0,0 +1,93 @@
+MySQL Remap Plugin
+******************
+
+.. 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 is a basic plugin for doing dynamic "remaps" from a database. It
+essentially rewrites the incoming request's Host header / origin server
+connection to one retrieved from a database.
+
+The generic proxying setup is the following:
+
+::
+ UA ----> Traffic Server ----> Origin Server
+
+Without the plugin a request like:
+
+::
+ GET /path/to/something HTTP/1.1
+ Host: original.host.com
+
+Ends up requesting ``http://original.host.com/path/to/something``
+
+With this plugin enabled, you can easily change that to anywhere you
+desire. Imagine the many possibilities....
+
+We have benchmarked the plugin with ab at about 9200 requests/sec (1.7k
+object) on a commodity hardware with a local setup of both, MySQL and
+Traffic Server local. Real performance is likely to be substantially
+higher, up to the MySQL's max queries / second.
+
+Installation
+============
+
+::
+ % make install
+
+should do it, assuming ``tsxs`` script in your search path. This script
+is installed with your installation of Apache Traffic Server.
+
+NOTE: you may need to open the Makefile and adjust the paths to MySQL
+client includes & libraries
+
+Configuration
+=============
+
+Import the default schema to a database you create:
+
+::
+ mysql -u root -p -e "CREATE DATABASE mysql_remap;" # create a new database
+ mysql -u root -p mysql_remap < schema/import.sql # import the provided schema
+
+insert some interesting values in mysql_remap.hostname &
+mysql_remap.map
+
+Traffic Server plugin configuration is done inside a global
+configuration file: ``/etc/trafficserver/plugin.config``:
+
+::
+ mysql_remap.so /etc/trafficserver/mysql_remap.ini
+
+The INI file should contain the following values:
+
+::
+ [mysql_remap]
+ mysql_host = localhost #default
+ mysql_port = 3306 #default
+ mysql_username = remap_user
+ mysql_password =
+ mysql_database = mysql_remap #default
+
+To debug errors, start trafficserver manually using:
+
+::
+ traffic_server -T "mysql_remap"
+
+And resolve any errors or warnings displayed.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/regex_remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/regex_remap.en.rst b/doc/admin/plugins/regex_remap.en.rst
new file mode 100644
index 0000000..b486eec
--- /dev/null
+++ b/doc/admin/plugins/regex_remap.en.rst
@@ -0,0 +1,162 @@
+Regex Remap Plugin
+******************
+
+.. 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 allows you to configure mapping rules based on regular expressions.
+This is similar to what you can accomplish using mod_rewrite in Apache
+httpd, but obviously not as flexible or sophisticated (yet).
+
+To use this plugin, configure a remap.config rule like
+
+::
+ map http://a.com http://b.com @plugin=regex_remap.so @pparam=maps.reg
+
+An optional argument (``@@pparam``) with the string "``profile``\ " will
+enable profiling of this regex remap rule, e.g.
+
+::
+ ... @pparam=maps.reg @pparam=profile
+
+Profiling is very low overhead, and the information is dumped to
+``traffic.out``, located in the log directory. In order to force a
+profile dump, you can do
+
+::
+ $ sudo touch remap.config
+ $ sudo traffic_line -x
+
+By default, only the path and query string of the URL is provided for
+the regular expressions to match. The following optional parameters can
+be used to modify the plugin instance behavior:
+
+::
+ @pparam=[no-]full-url [default: off]
+ @pparam=[no-]method [default: off]
+ @pparam=[no-]query-string [default: on]
+ @pparam=[no-]matrix-parameters [default: off]
+
+If you want the full (original) URL, use the parameter
+``@pparam=full-url``. For example:
+
+::
+ ... @pparam=maps.reg @pparam=full-url
+
+The string that you will need to match against looks like
+
+::
+ http://server/path?query=bar
+
+If you also wish to match on the HTTP method used (e.g. "``GET``\ "),
+you must use the option ``@pparam=method``. For example:
+
+::
+ ... @pparam=maps.reg @pparam=method
+
+With this enabled, the string that you will need to match will look like
+
+::
+ GET/path?query=bar
+
+The "``method``\ " parameter can also be used in combination with
+"``full-url``\ ", and the string to match against will then look like
+
+::
+ GET http://server.com/path?query=bar
+
+The methods are always all upper-case, and always followed by one single
+space. There is no space between the method and the rest of the URL (or
+URI path).
+
+By default, the query string is part of the string that is matched
+again, to turn this off use the option 'no-query-string', e.g.
+
+::
+ ... @pparam=maps.reg @pparam=no-query-string
+
+Finally, you can also include the matrix parameters in the string, using
+the option 'matrix-parameters', e.g.
+
+::
+ ... @pparam=maps.reg @pparam=matrix-parameters
+
+Note that the path to the plugin must be absolute, and by default it is
+
+.. XXX why?
+
+::
+ /usr/local/libexec/trafficserver/regex_remap.so
+
+The config file (``maps.reg`` above) can be placed anywhere, but unless
+you specify an absolute path (as above), it will default to the
+directory
+
+::
+ /usr/local/etc/regex_remap
+
+A typical regex would look like
+
+::
+ ^/(ogre.*)/more http://www.ogre.com/$h/$0/$1
+
+The regular expression must not contain any white spaces!
+
+When the regular expression is matched, only the URL path + query string
+is matched (without any of the optional configuration options). The path
+will always start with a "/". Various substitution strings are allowed
+on the right hand side:
+
+::
+ $0 - The entire matched string
+ $1-9 - Regular expression groups ($1 first group etc.)
+ $h - The original host header from the request
+ $f - The host as used in the "from" portion of the remap rule
+ $t - The host as used in the "to" portion of the remap rule
+ $p - The original port number
+ $s - The scheme (e.g. http) of the request
+ $P - The entire path of the request
+ $q - The query part of the request
+ $r - The path parameters of the request (not implemented yet)
+ $c - The cookie string from the request
+ $i - The client IP for this request
+
+You can also provide options, similar to how you configure your
+remap.config. The following options are available
+
+::
+ @status=<nnn> - Force the response code to <nnn>
+ @active_timeout=<nnn> - Active timeout (in ms)
+ @no_activity_timeout=<nnn> - No activity timeout (in ms)
+ @connect_timeout=<nnn> - Connect timeouts (in ms)
+ @dns_timeout=<nnn> - Connect timeouts (in ms)
+
+For example, this can be useful to force a particular response for some
+URLs, e.g.
+
+::
+ ^/(ogre.*)/bad http://www.examle.com/ @status=404
+
+Or, to force a 302 redirect
+
+::
+ ^/oldurl/(.*)$ http://news.example.com/new/$1 @status=302
+
+Note: Setting the status to 301 or 302 will force the new URL to be used
+as a redirect (Location:).
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/stale_while_revalidate.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/stale_while_revalidate.en.rst b/doc/admin/plugins/stale_while_revalidate.en.rst
new file mode 100644
index 0000000..0a59c90
--- /dev/null
+++ b/doc/admin/plugins/stale_while_revalidate.en.rst
@@ -0,0 +1,21 @@
+Stale While Revalidate Plugin (undocumented)
+********************************************
+
+.. 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.
+
+refresh content asynchronously while serving stale data
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/plugins/stats_over_http.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/plugins/stats_over_http.en.rst b/doc/admin/plugins/stats_over_http.en.rst
new file mode 100644
index 0000000..95ffb49
--- /dev/null
+++ b/doc/admin/plugins/stats_over_http.en.rst
@@ -0,0 +1,37 @@
+Stats over HTTP Plugin (underdocumented)
+****************************************
+
+.. 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.
+
+Statistics are available in JSON format via direct HTTP access to
+Traffic Server.
+
+::
+
+ make
+ sudo make install
+
+Add the following to
+```plugin.config`` <../../configuration-files/plugin.config>`_:
+
+::
+
+ stats_over_http.so
+
+start traffic server and visit ``http://IP:port/_stats``
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/reverse-proxy-http-redirects.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/reverse-proxy-http-redirects.en.rst b/doc/admin/reverse-proxy-http-redirects.en.rst
new file mode 100644
index 0000000..babe751
--- /dev/null
+++ b/doc/admin/reverse-proxy-http-redirects.en.rst
@@ -0,0 +1,329 @@
+Reverse Proxy and HTTP Redirects
+********************************
+
+.. 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.
+
+
+Reverse Proxy and HTTP Redirects
+================================
+
+As a reverse proxy cache, Traffic Server serves requests on behalf of
+origin servers. Traffic Server is configured in such a way that it
+appears to clients like a normal origin server.
+
+This chapter discusses the following topics:
+
+.. toctree::
+ :maxdepth: 2
+
+
+Understanding Reverse Proxy Caching
+===================================
+
+With **forward proxy caching**, Traffic Server handles web requests to
+distant origin servers on behalf of the clients requesting the content.
+**Reverse proxy caching** (also known as \*\*server acceleration \*\*or
+**virtual web hosting**) is different because Traffic Server acts as a
+proxy cache on behalf of the origin servers that store the content.
+Traffic Server is configured to be *the* origin server which the client
+is trying to connect to. In a typical scenario the advertised hostname
+of the origin server resolves to Traffic Server, which acts as the real
+origin server.
+
+Reverse Proxy Solutions
+-----------------------
+
+There are many ways to use Traffic Server as a reverse proxy. Below are
+a few example scenarios.
+
+You can use Traffic Server in reverse proxy mode to:
+
+- Offload heavily-used origin servers
+- Deliver content efficiently in geographically distant areas
+- Provide security for origin servers that contain sensitive
+ information
+
+Offloading Heavily-Used Origin Servers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Traffic Server can absorb requests to the main origin server and improve
+the speed & quality of web serving by reducing load and hot spots on
+backup origin servers. For example, a web hoster can maintain a scalable
+Traffic Server serving engine with a set of low-cost, low-performance,
+less-reliable PC origin servers as backup servers. In fact, a single
+Traffic Server can act as the virtual origin server for multiple backup
+origin servers, as shown in the figure below.
+
+.. figure:: ../_static/images/admin/revproxy.jpg
+ :align: center
+ :alt: Traffic Server as reverse proxy for a pair of origin servers
+
+ Traffic Server as reverse proxy for a pair of origin servers
+
+Delivering Content in Geographically-Dispersed Areas
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Traffic Server can be used in reverse proxy mode to accelerate origin
+servers that provide content to areas not located within close
+geographical proximity. Caches are typically easier to manage and are
+more cost-effective than replicating data. For example, Traffic Server
+can be used as a mirror site on the far side of a trans-Atlantic link to
+serve users without having to fetch the request and content across
+expensive international connections. Unlike replication, for which
+hardware must be configured to replicate all data and to handle peak
+capacity, Traffic Server dynamically adjusts to optimally use the
+serving and storing capacity of the hardware. Traffic Server is also
+designed to keep content fresh automatically, thereby eliminating the
+complexity of updating remote origin servers.
+
+Providing Security for an Origin Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Traffic Server can be used in reverse proxy mode to provide security for
+an origin server. If an origin server contains sensitive information
+that you want to keep secure inside your firewall, then you can use a
+Traffic Server outside the firewall as a reverse proxy for that origin
+server. When outside clients try to access the origin server, the
+requests instead go to Traffic Server. If the desired content is *not*
+sensitive, then it can be served from the cache. If the content is
+sensitive and not cacheable, then Traffic Server obtains the content
+from the origin server (the firewall allows only Traffic Server access
+to the origin server). The sensitive content resides on the origin
+server, safely inside the firewall.
+
+How Does Reverse Proxy Work?
+----------------------------
+
+When a browser makes a request, it normally sends that request directly
+to the origin server. When Traffic Server is in reverse proxy mode, it
+intercepts the request before it reaches the origin server. Typically,
+this is done by setting up the DNS entry for the origin server (i.e.,
+the origin server's 'advertised' hostname) so it resolves to the Traffic
+Server IP address. When Traffic Server is configured as the origin
+server, the browser connects to Traffic Server rather than the origin
+server. For additional information, see `HTTP Reverse
+Proxy <#HTTPReverseProxy>`_.
+
+**Note:** To avoid a DNS conflict, the origin server’s hostname and its
+advertised hostname must not be the same.
+
+HTTP Reverse Proxy
+==================
+
+In reverse proxy mode, Traffic Server serves HTTP requests on behalf of
+a web server. The figure below illustrates how Traffic Server in reverse
+proxy mode serves an HTTP request from a client browser.
+
+.. figure:: ../_static/images/admin/httprvs.jpg
+ :align: center
+ :alt: HTTP reverse proxy
+
+ HTTP reverse proxy
+
+The figure above demonstrates the following steps:
+
+1. A client browser sends an HTTP request addressed to a host called
+ ``www.host.com`` on port 80. Traffic Server receives the request
+ because it is acting as the origin server (the origin server’s
+ advertised hostname resolves to Traffic Server).
+2. Traffic Server locates a map rule in the ``remap.config`` file and
+ remaps the request to the specified origin server (``realhost.com``).
+3. Traffic Server opens an HTTP connection to the origin server. (This
+ step is optional)
+4. If the request is a cache hit and the content is fresh, then Traffic
+ Server sends the requested object to the client from the cache.
+ Otherwise, Traffic Server obtains the requested object from the
+ origin server, sends the object to the client, and saves a copy in
+ its cache.
+
+To configure HTTP reverse proxy, you must perform the following tasks:
+
+- Create mapping rules in the ``remap.config`` file (refer to `Creating
+ Mapping Rules for HTTP
+ Requests <#CreatingMappingRulesHTTPRequests>`_).
+
+ :::text # remap.config map http://www.host.com http://realhost.com
+
+- Enable the reverse proxy option (refer to `Enabling HTTP Reverse
+ Proxy <#EnablingHTTPReverseProxy>`_).
+
+In addition to the tasks above, you can also `Set Optional HTTP Reverse
+Proxy Options <#SettingOptionalHTTPReverseProxyOptions>`_.
+
+Handling Origin Server Redirect Responses
+-----------------------------------------
+
+Origin servers often send redirect responses back to browsers
+redirecting them to different pages. For example, if an origin server is
+overloaded, then it might redirect browsers to a less loaded server.
+Origin servers also redirect when web pages that have moved to different
+locations. When Traffic Server is configured as a reverse proxy, it must
+readdress redirects from origin servers so that browsers are redirected
+to Traffic Server and *not* to another origin server.
+
+To readdress redirects, Traffic Server uses reverse-map rules. Unless
+you have
+`proxy.config.url_remap.pristine_host_hdr <configuration-files/records.config#proxy.config.url_remap.pristine_host_hdr>`_
+enabled (the default) you should generally set up a reverse-map rule for
+each map rule.d To create reverse-map rules, refer to `Using Mapping
+Rules for HTTP Requests <#UsingMappingRulesHTTPRequests>`_.
+
+Using Mapping Rules for HTTP Requests
+-------------------------------------
+
+Traffic Server uses two types of mapping rules for HTTP reverse proxy.
+
+map rule
+~~~~~~~~
+
+A **map rule** translates the URL in client requests into the URL where
+the content is located. When Traffic Server is in reverse proxy mode and
+receives an HTTP client request, it first constructs a complete request
+URL from the relative URL and its headers. Traffic Server then looks for
+a match by comparing the complete request URL with its list of target
+URLs in the ```remap.config`` <../configuration-files/remap.config>`_
+file. For the request URL to match a target URL, the following
+conditions must be true:
+
+- The scheme of both URLs must be the same
+- The host in both URLs must be the same. If the request URL contains
+ an unqualified hostname, then it will never match a target URL with a
+ fully-qualified hostname.
+- The ports in both URLs must be the same. If no port is specified in a
+ URL, then the default port for the scheme of the URL is used.
+- The path portion of the target URL must match a prefix of the request
+ URL path
+
+If Traffic Server finds a match, then it translates the request URL into
+the replacement URL listed in the map rule: it sets the host and path of
+the request URL to match the replacement URL. If the URL contains path
+prefixes, then Traffic Server removes the prefix of the path that
+matches the target URL path and substitutes it with the path from the
+replacement URL. If two mappings match a request URL, then Traffic
+Server applies the first mapping listed in the
+```remap.config`` <configuration-files/remap.config>`_ file.
+
+reverse-map rule
+~~~~~~~~~~~~~~~~
+
+A **reverse-map rule** translates the URL in origin server redirect
+responses to point to Traffic Server so that clients are **redirected**
+to Traffic Server instead of accessing an origin server directly. For
+example, if there is a directory ``/pub`` on an origin server at
+``www.molasses.com`` and a client sends a request to that origin server
+for ``/pub``, then the origin server might reply with a redirect by
+sending the Header ``Location: http://www.test.com/pub/`` to let the
+client know that it was a directory it had requested, not a document (a
+common use of redirects is to normalize URLs so that clients can
+bookmark documents properly).
+
+Traffic Server uses ``reverse_map`` rules to prevent clients (that
+receive redirects from origin servers) from bypassing Traffic Server and
+directly accessing the origin servers. In many cases the client would be
+hitting a wall because ``realhost.com`` actually does not resolve for
+the client. (E.g.: Because it's running on a port shielded by a
+firewall, or because it's running on a non-routable LAN IP)
+
+Both map and reverse-map rules consist of a **target** (origin) URL and
+a **replacement** (destination) URL. In a **map rule**, the target URL
+points to Traffic Server and the replacement URL specifies where the
+original content is located. In a **reverse-map rule**, the target URL
+specifies where the original content is located and the replacement URL
+points to Traffic Server. Traffic Server stores mapping rules in the
+``remap.config`` file located in the Traffic Server ``config``
+directory.
+
+Creating Mapping Rules for HTTP Requests
+----------------------------------------
+
+To create mapping rules
+
+1. Enter the map and reverse-map rules into the
+ ```remap.config`` <configuration-files/remap.config>`_ file
+2. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+Enabling HTTP Reverse Proxy
+---------------------------
+
+To enable HTTP reverse proxy, follow the steps below.
+
+1. Edit the following variable in
+ ```records.config`` <configuration-files/records.config>`_
+
+ - `*``proxy.config.reverse_proxy.enabled``* <configuration-files/records.config#proxy.config.reverse_proxy.enabled>`_
+
+2. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+Setting Optional HTTP Reverse Proxy Options
+-------------------------------------------
+
+Traffic Server provides several reverse proxy configuration options in
+```records.config`` <configuration-files/records.config>`_ that
+enable you to:
+
+- Configure Traffic Server to retain the client host header information
+ in a request during translation
+ (`*``proxy.config.url_remap.pristine_host_hdr``* <configuration-files/records.config#proxy.config.url_remap.pristine_host_hdr>`_)
+
+- Configure Traffic Server to serve requests only to the origin servers
+ listed in the mapping rules. As a result, requests to origin servers
+ not listed in the mapping rules are not served.
+ (`*``proxy.config.url_remap.remap_required``* <configuration-files/records.config#proxy.config.url_remap.remap_required>`_)
+- Specify an alternate URL to which incoming requests from older
+ clients (i.e., ones that do not provide ``Host`` headers) are
+ directed
+ (`*``proxy.config.header.parse.no_host_url_reedirect``* <configuration-files/records.config#proxy.config.header.parse.no_host_url_redirect>`_)
+
+Don't forget to run the command ``traffic_line -x`` to apply the
+configuration changes.
+
+Redirecting HTTP Requests
+=========================
+
+You can configure Traffic Server to redirect HTTP requests without
+having to contact any origin servers. For example, if you redirect all
+requests for ``http://www.ultraseek.com`` to
+``http://www.server1.com/products/portal/search/``, then all HTTP
+requests for ``www.ultraseek.com`` go directly to
+``www.server1.com/products/portal/search``.
+
+You can configure Traffic Server to perform permanent or temporary
+redirects. **Permanent redirects** notify the browser of the URL change
+(by returning the HTTP status code **``301``**) so that the browser can
+update bookmarks. **Temporary redirects** notify the browser of the URL
+change for the current request only (by returning the HTTP status code
+**``307``** ).
+
+To set redirect rules
+
+1. For each redirect you want to set enter a mapping rule in the
+ ```remap.config`` <../configuration-files/remap.config>`_ file
+2. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+**Example**
+
+The following permanently redirects all HTTP requests for
+``www.server1.com`` to ``www.server2.com``:
+
+::
+ redirect http://www.server1.com http://www.server2.com
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/admin/security-options.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/security-options.en.rst b/doc/admin/security-options.en.rst
new file mode 100644
index 0000000..fd00052
--- /dev/null
+++ b/doc/admin/security-options.en.rst
@@ -0,0 +1,248 @@
+Security Options
+****************
+
+.. 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.
+
+Traffic Server provides a number of security features.
+
+This chapter discusses the following topics:
+
+.. toctree::
+ :maxdepth: 2
+
+Controlling Client Access to the Proxy Cache
+============================================
+
+You can configure Traffic Server to allow only certain clients to use
+the proxy cache by editing a configuration file.
+
+2. Add a line in the file ``ip_allow.config`` for each IP address or
+ range of IP addresses allowed to access Traffic Server (refer to
+ `ip_allow.config <configuration-files/ip_allow.config>`_).
+3. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+Configuring DNS Server Selection (Split DNS)
+============================================
+
+The **Split DNS** option enables you to configure Traffic Server to use
+multiple DNS servers, as dictated by your security requirements. For
+example, you might configure Traffic Server to use one set of DNS
+servers to resolve hostnames on your internal network, while allowing
+DNS servers outside the firewall to resolve hosts on the Internet. This
+maintains the security of your intranet, while continuing to provide
+direct access to sites outside your organization.
+
+To configure Split DNS, you must do the following:
+
+- Specify the rules for performing DNS server selection based on the
+ destination domain, the destination host, or a URL regular
+ expression.
+- Enable the **Split DNS** option.
+
+To do this, we
+
+2. Add rules to the ``splitdns.config`` file. (Refer to
+ ```splitdns.config`` <../configuration-files/splitdns.config>`_.
+3. In the file ``records.config`` the variable
+ `*``proxy.process.dns.splitDNS.enabled``* <configuration-files/records.config#proxy.process.dns.splitDNS.enabled>`_
+ to ``1`` to enable split DNS.
+4. Run the command ``traffic_line -x`` to apply the configuration
+ changes.
+
+Using SSL Termination
+=====================
+
+The Traffic Server **SSL termination** option enables you to secure
+connections in reverse proxy mode between a client and a Traffic Server
+and/or Traffic Server and an origin server.
+
+The following sections describe how to enable and configure the SSL
+termination option.
+
+- Enable and configure SSL termination for client/Traffic Server
+ connections: `Client and Traffic Server
+ Connections <#ClientTSConnections>`_.
+- Enable and configure SSL termination for Traffic Server/origin server
+ connections: `Traffic Server and Origin Server
+ Connections <#TSOriginServerConnections>`_.
+- Enable and configure SSL termination for both client/Traffic Server
+ and Traffic Server/origin server connections: `Client and Traffic
+ Server Connections <#ClientTSConnections>`_ and `Traffic Server and
+ Origin Server Connections <#TSOriginServerConnections>`_,
+ respectively.
+
+Client and Traffic Server Connections
+-------------------------------------
+
+The figure below illustrates communication between a client and Traffic
+Server (and between Traffic Server and an origin server) when the SSL
+termination option is enabled & configured for\ *\* client/Traffic
+Server connections only*\ \*.
+
+.. figure:: ../_static/images/admin/ssl_c.jpg
+ :align: center
+ :alt: Client and Traffic Server communication using SSL termination
+
+ Client and Traffic Server communication using SSL termination
+
+The figure above depicts the following:
+
+**Step 1:** The client sends an HTTPS request for content. Traffic
+Server receives the request and performs the SSL 'handshake' to
+authenticate the client (depending on the authentication options
+configured) and determine the encryption method that will be used. If
+the client is allowed access, then Traffic Server checks its cache for
+the requested content.
+
+**Step 2:** If the request is a cache hit and the content is fresh, then
+Traffic Server encrypts the content and sends it to the client. The
+client decrypts the content (using the method determined during the
+handshake) and displays it.
+
+**Step 3:** If the request is a cache miss or cached content is stale,
+then Traffic Server communicates with the origin server via HTTP and
+obtains a plain text version of the content. Traffic Server saves the
+plain text version of the content in its cache, encrypts the content,
+and sends it to the client. The client decrypts and displays the
+content.
+
+To configure Traffic Server to use the SSL termination option for
+client/Traffic Server connections, you must do the following:
+
+- Obtain and install an SSL server certificate from a recognized
+ certificate authority. The SSL server certificate contains
+ information that enables the client to authenticate Traffic Server
+ and exchange encryption keys.
+- Configure SSL termination options:
+- Enable the **SSL termination** option.
+
+ - Set the port number used for SSL communication.
+ - Specify the filename and location of the server certificate.
+ - (Optional) Configure the use of client certificates: Client
+ certificates are located on the client. If you configure Traffic
+ Server to require client certificates, then Traffic Server
+ verifies the client certificate during the SSL handshake that
+ authenticates the client. If you configure Traffic Server to *not*
+ require client certificates, then access to Traffic Server is
+ managed through other Traffic Server options that have been set
+ (such as rules in the
+ ```ip_allow.config`` <configuration-files/ip_allow.config>`_
+ file).
+ - Specify the filename and location of the Traffic Server private
+ key (if the private key is not located in the server certificate
+ file). Traffic Server uses its private key during the SSL
+ handshake to decrypt the session encryption keys. The private key
+ must be stored and protected against theft.
+ - (Optional) Configure the use of Certification Authorities (CAs).
+ CAs add security by verifying the identity of the person
+ requesting a certificate.
+
+In order to accomplish this, we
+
+2. Edit the following variables in the ``SSL Termination`` section of
+ the ``records.config`` file:
+
+ - `*``proxy.config.ssl.enabled``* <configuration-files/records.config#proxy.config.ssl.enabled>`_
+ - `*``proxy.config.ssl.server_port``* <configuration-files/records.config#proxy.config.ssl.server_port>`_
+ - `*``proxy.config.ssl.client.certification_level``* <configuration-files/records.config#proxy.config.ssl.client.certification_level>`_
+ - `*``proxy.config.ssl.server.cert.filename``* <configuration-files/records.config#proxy.config.ssl.server.cert.filename>`_
+ - `*``proxy.config.ssl.server.cert.path``* <configuration-files/records.config#proxy.config.ssl.server.cert.path>`_
+ - `*``proxy.config.ssl.server.private_key.filename``* <configuration-files/records.config#proxy.config.ssl.server.private_key.filename>`_
+ - `*``proxy.config.ssl.server.private_key.path``* <configuration-files/records.config#proxy.config.ssl.server.private_key.path>`_
+ - `*``proxy.config.ssl.CA.cert.filename``* <configuration-files/records.config#proxy.config.ssl.CA.cert.filename>`_
+ - `*``proxy.config.ssl.CA.cert.path``* <configuration-files/records.config#proxy.config.ssl.CA.cert.path>`_
+
+3. Run the command ``traffic_line -L`` to restart Traffic Server on the
+ local node or ``traffic_line -M`` to restart Traffic Server on all
+ the nodes in a cluster.
+
+Traffic Server and Origin Server Connections
+--------------------------------------------
+
+The figure below illustrates communication between Traffic Server and an
+origin server when the SSL termination option is enabled for **Traffic
+Server/origin server connections**.
+
+.. figure:: ../_static/images/admin/ssl_os.jpg
+ :align: center
+ :alt: Traffic Server and origin server communication using SSL termination
+
+ Traffic Server and origin server communication using SSL termination
+
+The figure above depicts the following:
+
+**Step 1:** If a client request is a cache miss or is stale, then
+Traffic Server sends an HTTPS request for the content to the origin
+server. The origin server receives the request and performs the SSL
+handshake to authenticate Traffic Server and determine the encryption
+method to be used.
+
+**Step 2:** If Traffic Server is allowed access, then the origin server
+encrypts the content and sends it to Traffic Server, where it is
+decrypted (using the method determined during the handshake). A plain
+text version of the content is saved in the cache.
+
+**Step 3:** If SSL termination is enabled for client /Traffic Server
+connections, then Traffic Server re-encrypts the content and sends it to
+the client via HTTPS, where it is decrypted and displayed. If SSL
+termination is not enabled for client/Traffic Server connections, then
+Traffic Server sends the plain text version of the content to the client
+via HTTP.
+
+To configure Traffic Server to use the SSL termination option for
+Traffic Server and origin server connections, you must do the following:
+
+- Obtain and install an SSL client certificate from a recognized
+ certificate authority. The SSL client certificate contains
+ information that allows the origin server to authenticate Traffic
+ Server (the client certificate is optional).
+- Configure SSL termination options:
+- Enable the SSL termination option.
+
+ - Set the port number used for SSL communication.
+ - Specify the filename and location of the SSL client certificate
+ (if you choose to use a client certificate).
+ - Specify the filename and location of the Traffic Server private
+ key (if the private key is not located in the client certificate
+ file). Traffic Server uses its private key during the SSL
+ handshake to decrypt the session encryption keys. The private key
+ must be stored and protected against theft.
+ - Configure the use of CAs. CAs allow the Traffic Server that's
+ acting as a client to verify the identity of the server with which
+ it is communicating, thereby enabling exchange of encryption keys.
+
+In order to accomplish this, we:
+
+2. Edit the following variables in the ``SSL Termination`` section of
+ the ``records.config`` file:
+
+ - `*``proxy.config.ssl.auth.enabled``* <configuration-files/records.config#proxy.config.ssl.auth.enabled>`_
+ - ```proxy.config.ssl.server_port`` <configuration-files/records.config#proxy.config.ssl.server_port>`_
+ - ```proxy.config.ssl.client.verify.server`` <configuration-files/records.config#proxy.config.ssl.client.verify.server>`_
+ - ```proxy.config.ssl.client.cert.filename`` <configuration-files/records.config#proxy.config.ssl.client.cert.filename>`_
+ - ```proxy.config.ssl.client.cert.path`` <configuration-files/records.config#proxy.config.ssl.client.cert.path>`_
+ - ```proxy.config.ssl.client.private_key.filename`` <configuration-files/records.config#proxy.config.ssl.client.private_key.filename>`_
+ - ```proxy.config.ssl.client.private_key.path`` <configuration-files/records.config#proxy.config.ssl.client.private_key.path>`_
+ - ```proxy.config.ssl.client.CA.cert.filename`` <configuration-files/records.config#proxy.config.ssl.client.CA.cert.filename>`_
+ - ```proxy.config.ssl.client.CA.cert.path`` <configuration-files/records.config#proxy.config.ssl.client.CA.cert.path>`_
+
+3. Run the command ``traffic_line -L`` to restart Traffic Server on the
+ local node or ``traffic_line -M`` to restart Traffic Server on all
+ the nodes in a cluster.
+