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 <[email protected]> Authored: Wed Jan 14 13:28:41 2015 -0800 Committer: James Peach <[email protected]> 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
