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