| .. Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| .. include:: ../common.defs |
| |
| .. _getting-started: |
| |
| Getting Started |
| *************** |
| |
| .. toctree:: |
| :maxdepth: 2 |
| |
| Introduction |
| ============ |
| |
| |ATS| provides a high-performance and scalable software solution for both |
| forward and reverse proxying of HTTP/HTTPS traffic, and may be configured to |
| run in either or both modes simultaneously. This Getting Started guide explains |
| the basic steps an administrator new to |TS| will need to perform to get the |
| software up and running in a minimal configuration as quickly as possible. |
| |
| Example Scenario |
| ---------------- |
| |
| In this guide, we will use the fictional company |AW| as a basis for the |
| configuration examples. |AW| has a product brochure website (assumed to reside |
| at the domain ``www.acme.com``) that performs very poorly. The content management |
| software they chose takes an unbearable amount of time to generate pages on |
| every request and their engineering team has chosen |TS| as a caching proxy |
| layer to improve site performance. |
| |
| Separately, |AW| has decided to use |TS| to help improve the performance of |
| their office's Internet access, which is hobbled by their reliance on an aging |
| leased line and certain employees' predilection for extracurricular web |
| browsing. |
| |
| Terminology |
| ----------- |
| |
| This guide uses some terms which may be unfamiliar to administrators new to |
| proxy servers. |
| |
| Origin Server |
| The server which generates the content you wish to proxy (and optionally |
| cache) with |TS|. In a forward proxy configuration, the origin server may be |
| any remote server to which a proxied client attempts to connect. In a |
| reverse proxy configuration, the origin servers are typically a known set of |
| servers for which you are using |TS| as a performance-enhancing caching |
| layer. |
| |
| Reverse Proxy |
| A reverse proxy appears to outside users as if it were the origin server, |
| though it does not generate the content itself. Instead, it intercepts the |
| requests and, based on the configured rules and contents of its cache, will |
| either serve a cached copy of the requested content itself, or forward the |
| request to the origin server, possibly caching the content returned for use |
| with future requests. |
| |
| Forward Proxy |
| A forward proxy brokers access to external resources, intercepting all |
| matching outbound traffic from a network. Forward proxies may be used to |
| speed up external access for locations with slow connections (by caching the |
| external resources and using those cached copies to service requests |
| directly in the future), or may be used to restrict or monitor external |
| access. |
| |
| Transparent Proxy |
| A transparent proxy may be either a reverse or forward proxy (though nearly |
| all reverse proxies are deployed transparently), the defining feature being |
| the use of network routing to send requests through the proxy without any |
| need for clients to configure themselves to do so, and often without the |
| ability for those clients to bypass the proxy. |
| |
| For a more complete list of definitions, please see the :ref:`glossary`. |
| |
| Installation |
| ============ |
| |
| As with many other software packages, you may have the option of installing |
| |ATS| from your operating system distribution'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 https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.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 |
| - pcre |
| - libcap |
| - flex (for TPROXY) |
| - hwloc |
| - lua |
| - zlib |
| - 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 8080:ipv6 |
| |
| :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 unknowing 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, |
| for both IPv4 and IPv6. |
| |
| 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:`admin-plugins-conf-remap`. For |
| our Getting 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:: |
| |
| map http://www.acme.com/ http://localhost:80/ |
| |
| With this mapping rule, all paths that |TS| receives with a Host: header of |
| ``www.acme.com`` will be proxied to ``localhost:80``. For instance, a request |
| for ``http://www.acme.com/foo/bar`` will be proxied to ``http://localhost:80/foo/bar``, |
| while requests with other Host: headers will be rejected. |
| |
| 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:: |
| |
| map http://www.acme.com/ 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. |
| |
| If |AW| decides to use |TS| to reverse proxy a second domain ``static.acme.com`` |
| with a different origin server than the original, they need to make further |
| changes, as a new remap line needs to be added to handle the additional domain:: |
| |
| map http://static.acme.com/ http://origin-static.acme.com/ |
| |
| If they also decide to have requests to ``www.acme.com`` with paths that start with |
| ``/api`` to a different origin server. The api origin server shouldn't get the ``/api``, |
| they will remap it away. And, since the above remap rules catch all paths, |
| this remap rule needs to be above it:: |
| |
| map http://www.acme.com/api/ http://api-origin.acme.com/ |
| |
| With this remap rule in place, a request to ``http://www.acme.com/api/example/foo`` |
| will be proxied to ``http://api-origin.acme.com/example/foo``. |
| |
| Finally, if |AW| decides to secure their site with https, they will need two |
| additional remap rules to handle the https requests. |TS| can translate an inbound |
| https request to an http request to origin. So, they would have additional remap |
| rules like:: |
| |
| map https://www.acme.com/ http://localhost:8080/ |
| map https://static.acme.com/ https://origin-static.acme.com/ |
| |
| This will require installing a certificate, and adding a line to |
| :file:`ssl_multicert.config`. Assuming the cert has the static.acme.com alternate |
| name, and that cert should be presented by default:: |
| |
| dest_ip=* ssl_cert_name=/path/to/secret/privatekey/acme.rsa |
| |
| Further information about configuring |TS| for TLS can be found :ref:`admin-ssl-termination` |
| section of the documentation. |
| |
| Adjust Cache Parameters |
| ~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| The default |TS| configuration will provide a 256 MB disk cache, located in |
| ``var/trafficserver/`` underneath your install prefix. You may wish to adjust |
| either or both of the size and location of this cache. This is done with the |
| :file:`storage.config` configuration file. In our example, |AW| has dedicated |
| a large storage pool on their cache server which is mounted at ``/cache``. To |
| use this, and to disable the default cache storage setting, the following will |
| be the sole entry in :file:`storage.config`:: |
| |
| /cache/trafficserver 500G |
| |
| .. note:: Changes to the cache configuration require a restart of |TS|. |
| |
| You may also wish to use raw devices, or partition your cache storage. Details |
| on these features may be found in the :ref:`admin-configuration` section of |
| the Administrator's Guide. |
| |
| Final Configurations |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| Once completed, the following configuration files for |AW| contain the following |
| entries: |
| |
| :file:`records.config`:: |
| |
| CONFIG proxy.config.http.cache.http INT 1 |
| CONFIG proxy.config.reverse_proxy.enabled INT 1 |
| CONFIG proxy.config.url_remap.remap_required INT 1 |
| CONFIG proxy.config.url_remap.pristine_host_hdr INT 1 |
| CONFIG proxy.config.http.server_ports STRING 80 80:ipv6 |
| |
| :file:`remap.config`:: |
| |
| map http://www.acme.com/api/ http://api-origin.acme.com/ |
| map https://www.acme.com/api/ https://api-origin.acme.com/ |
| map http://www.acme.com/ http://localhost:8080/ |
| map https://www.acme.com/ http://localhost:8080/ |
| map http://static.acme.com/ http://origin-static.acme.com/ |
| map https://static.acme.com/ https://origin-static.acme.com/ |
| |
| :file:`storage.config`:: |
| |
| /cache/trafficserver 500G |
| |
| :file:`ssl_multicert.config`:: |
| |
| ssl_cert_name=/path/to/secret/acme.rsa |
| |
| 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:`admin-logging`. |
| |
| Further Steps |
| ============= |
| |
| By this point, you should have a fully functioning caching proxy, whether to |
| help improve the customer facing performance of your website, or to assist in |
| speeding up Internet access for your office while allowing for the possibility |
| of access control, content filtering, and/or usage monitoring. However, it is |
| quite likely that your installation is not yet tuned properly and may not be |
| providing the best experience |ATS| has to offer. It is strongly recommended |
| that you consult the :ref:`performance-tuning` guide. |
| |
| You may also want to learn more about :ref:`admin-monitoring`, or ensuring |
| that your installation is properly secured by reading the :ref:`admin-security` |
| section. Properly sizing your cache, both the on-disk cache and the companion |
| memory cache, are important topics covered in :ref:`admin-configuration`. |
| |