.. 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-latest-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 - C++ compiler (gcc >= 4.3 or clang > 3.0) - GNU make - OpenSSL or BoringSSL - 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-`` 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`.