Traffic Router is a Java Tomcat application that routes clients to the closest available cache on the CDN using both HTTP and DNS. Cache availability is determined by Traffic Monitor; consequently Traffic Router polls Traffic Monitor for its configuration and cache health state information, and uses this data to make routing decisions. HTTP routing is performed by localizing the client based on the request’s source IP address (IPv4 or IPv6), and issues an HTTP 302 redirect to the nearest cache. HTTP routing utilizes consistent hashing on request URLs to optimize cache performance and request distribution. DNS routing is performed by localizing clients, resolvers in most cases, requesting
AAAA records for a configurable name such as
foo.deliveryservice.somecdn.net. Traffic Router is comprised of seven separate Maven modules:
- shared - A reusable utility JAR for defining Delivery Service Certificates
- configuration - A resuable JAR defining the ConfigurationListener interface
- connector - A JAR that overrides Tomcat’s standard Http11Protocol Connector class and allows Traffic Router to delay opening listen sockets until it is in a state suitable for routing traffic
- geolocation - Submodule for defining geolocation services
- neustar - A Jar that provides a bean “neustarGeolocationService” that implements the GeolocationService interface defined in the geolocation maven submodule, which can optionally be added to the build of Traffic Router
- core - Services DNS and HTTP requests, performs localization on routing requests, and is deployed as a WAR to a Service (read: connector/listen port) within Tomcat which is separate from api
- build - A simple Maven project which gathers the artifacts from the modules and builds an RPM
To work on Traffic Router you need a *nix (MacOS and Linux are most commonly used) environment that has the following installed:
- Eclipse >= Kepler SR2 (or another Java IDE)
- Maven >= 3.3.1
- JDK >= 8.0
- OpenSSL >= 1.0.2
- APR (Apache Portable Runtime) >= 1.4.8-3
- Tomcat Native >= 1.2.16
- Not Tomcat - You do not need a Tomcat installation for development. An embedded version is launched for development testing instead.
Traffic Router Project Tree Overview¶
traffic_control/traffic_traffic_router/- base directory for Traffic Router
connector/- Source code for Traffic Router Connector;
src/main/java- Java source directory for Traffic Router Connector
core/- Source code for Traffic Router Core, which is built as its own deployable WAR file and communicates with Traffic Router API using JMX
src/main- Main source directory for Traffic Router Core
lib/systemd/system/traffic_router.service- Unit script for launching the Traffic Router with Tomcat
conf/- All of the required configuration files for running the traffic_router web application, including those needed for Tomcat
java/- Java source code for Traffic Router Core
resources/- Resources pulled in during an RPM build
scripts/- Scripts used by the RPM build process
webapp/- Java webapp resources
var/log/- location of all the Traffic Router runtime logs
src/test- Test source directory for Traffic Router Core
conf/- Minimal Configuration files that make it possible to run junit tests
db/- Files downloaded by unit tests
java/- JUnit based unit tests for Traffic Router Core
resources/- Example data files used by junit tests
var/auto-zones- BIND formatted zone files generated by Traffic Router Core during unit testing
Java Formatting Conventions¶
None at this time. The codebase will eventually be formatted per Java standards.
Installing The Developer Environment¶
To install the Traffic Router Developer environment:
- Clone the traffic_control repository using Git.
- Change directories into
- Follow the instructions in “README.DNSSEC” for DNSSEC support.
- Set the environment variable TRAFFIC_MONITOR_HOSTS to be a semicolon delimited list of Traffic Monitors that can be accessed during integration tests OR install the traffic_monitor.properties file as described below.
- Additional configuration is set using the below files:
core/src/test/conf/dns.properties - copy from core/src/main/conf
core/src/test/conf/http.properties - copy from core/src/main/conf
core/src/test/conf/log4j.properties - copy from core/src/main/conf
core/src/test/conf/traffic_monitor.properties - copy from core/src/main/conf and then edit the ‘traffic_monitor.bootstrap.hosts’ property.
core/src/test/conf/traffic_ops.properties file holds the credentials for accessing Traffic Ops. - copy from core/src/main/conf and then edit the credentials as approriate for the Traffic Ops instance you will be using.
Default configuration values now reside in core/src/main/webapp/WEB-INF/applicationContext.xml
The above values may be overridden by creating and/or modifying the property files listed in core/src/main/resources/applicationProperties.xml
Pre-existing properties files are still honored by Traffic Router. For example traffic_monitor.properties:
FQDN and port of the Traffic Monitor instance(s), separated by semicolons as necessary (do not include http://).
Import the existing git repo as projects into your IDE (Eclipse):
- File -> Import -> Git -> Projects from Git; Next
- Existing local repository; Next
- Add -> browse to find
- Ensure “Import existing projects” is selected, expand
traffic_router_coreare checked; Finish (this step can take several minutes to complete)
traffic_router_corehave been opened by Eclipse after importing
From the terminal or your IDE, run
mvn clean verifyfrom the
traffic_routerdirectory. This will run a series of integration tests and will temporarily start and embeded version of Traffic Router and a ‘fake’ simulated instance of Traffic Monitor.
Start the embedded Tomcat instance for Core from within your IDE by following these steps:
In the package explorer, expand
Expand the package
Open and run
If an error is displayed in the Console, run
mvn clean verifyfrom the
9. Traffic Router Core should now be running; the Traffic Router API is available at http://localhost:3333, the HTTP routing interface is available on http://localhost:8888 and HTTPS is available on http://localhost:8443. The DNS server and routing interface is available on localhost:1053 via TCP and UDP.
Look up the URL for your test ‘http’ Delivery Service in Traffic Ops and then:
curl -vs -H [Delivery Service FQDN] http://localhost:8888/x
or to test an ‘https’ enabled service:
curl -vs -k –resolve [Delivery Serice FQDN]:8443:127.0.0.1 https://[Delivery Service FQDN]:8443/x
- Unit tests can be executed using Maven by running
mvn testat the root of the
- Unit and Integration tests can be executed using Maven by running
mvn verifyat the root of the
mvn package on a Linux based distribution will trigger the build process to create the Traffic Router rpm and the Traffic Router .war file, but will not run the integration tests, so it is a good way to update those artifacts quickly during development. But the prefered way to build the Traffic Router RPMs is to navigate to the root of the Traffic Control source tree and run:
./pkg -v traffic_router_build
This will create the traffic_router.rpm and the tomcat.rpm and copy them to the ./dist directory.