Getting Started

Introduction

Apache Traffic Server™ 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 Traffic Server 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 Acme Widgets as a basis for the configuration examples. Acme Widgets 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 Traffic Server as a caching proxy layer to improve site performance.

Separately, Acme Widgets has decided to use Traffic Server 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 Traffic Server. 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 Traffic Server 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 Glossary.

Installation

As with many other software packages, you may have the option of installing Apache Traffic Server™ 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 Traffic Server, 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 Traffic Server when discussing configuration parameters and available features.

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 Traffic Server.

Ubuntu

The Canonical repositories up through, and including, Utopic Unicorn only provide Traffic Server v3.2.x.

sudo apt-get install trafficserver

RHEL / CentOS

Traffic Server 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 Traffic Server itself.

sudo yum install trafficserver

OmniOS (illumos)

OmniOS (an illumos-based distribution) provides the Traffic Server 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 Traffic Server v4.2.1.

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 Traffic Server:

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 Traffic Server 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, Traffic Server 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 Traffic Server 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 Traffic Server with the generated Makefiles, and test the results:
```
make
make check
```
Install Traffic Server to the configured location:
```
sudo make install
```
Optionally, you may find it prudent to run the regression tests on your newly installed Traffic Server:
```
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 Installing From Source Code above.

For these examples, we will be assuming that Traffic Server is running on the same host machine as the origin website. This is not a requirement, and you may choose to run Traffic Server on an entirely different host, even connected to entirely different networks, as long as Traffic Server is able to reach the origin host.

Enable Reverse Proxying

Within the 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

proxy.config.http.cache.http: Enables caching of proxied HTTP requests.
proxy.config.reverse_proxy.enabled: Enables reverse proxying support.
proxy.config.url_remap.remap_required: This setting requires that a remap rule exist before Traffic Server 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).
proxy.config.url_remap.pristine_host_hdr: This setting causes Traffic Server 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.
proxy.config.http.server_ports: This configures Traffic Server 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 Traffic Server needs to know what to proxy. This is achieved by writing remap rules, which make use of the core Configuration Remap Plugin. For our Getting Started guide’s Acme Widgets 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 remap.config configuration:

map http://www.acme.com/ http://localhost:80/

With this mapping rule, all paths that Traffic Server 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 Traffic Server itself which should be responding to HTTP requests made to your public domain. While you first configure and evaluate whether Traffic Server 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 Traffic Server configuration into production your DNS records for the domain(s) you wish to proxy and cache should resolve to the host(s) running Traffic Server (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 Traffic Server on the same host) and should no longer receive requests sent to the primary domain on its default ports.

In our Acme Widgets scenario, they ultimately decide to deploy Traffic Server at which point, since they are running both Traffic Server 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 Traffic Server 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 Traffic Server 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 Acme Widgets decides to use Traffic Server 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 Acme Widgets decides to secure their site with https, they will need two additional remap rules to handle the https requests. Traffic Server 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 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 Traffic Server for TLS can be found Basic SSL Termination section of the documentation.

Adjust Cache Parameters

The default Traffic Server 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 storage.config configuration file. In our example, Acme Widgets 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 storage.config:

/cache/trafficserver 500G

Note

Changes to the cache configuration require a restart of Traffic Server.

You may also wish to use raw devices, or partition your cache storage. Details on these features may be found in the Proxy Cache Configuration section of the Administrator’s Guide.

Final Configurations

Once completed, the following configuration files for Acme Widgets contain the following entries:

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

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/

storage.config:

/cache/trafficserver 500G

ssl_multicert.config:

ssl_cert_name=/path/to/secret/acme.rsa

Configuring A Forward Proxy

Configuring a forward proxy with Traffic Server 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 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 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

proxy.config.url_remap.remap_required: Disables the requirement for a remap rule to exist and match the incoming request before Traffic Server will proxy the request to the remote host.
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 Forward Proxy section of the Administrator’s Guide.

Logging and Monitoring

Configuring Log Output

The log formats used by Traffic Server 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 Traffic Server logs.

The Administrator’s Guide discusses logging options in great detail in 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 Apache Traffic Server™ has to offer. It is strongly recommended that you consult the Performance Tuning guide.

You may also want to learn more about Monitoring, or ensuring that your installation is properly secured by reading the Security section. Properly sizing your cache, both the on-disk cache and the companion memory cache, are important topics covered in Proxy Cache Configuration.