blob: 92f20f43a27b1b08afb282ab79dd897c90a1510d [file] [log] [blame]
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Traffic Router &mdash; Traffic Control 1.4 documentation </title>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/theme_overrides.css" type="text/css" />
<link rel="top" title="Traffic Control 1.4 documentation" href="../index.html"/>
<link rel="up" title="Developer’s Guide" href="index.html"/>
<link rel="next" title="Traffic Router API" href="traffic_router/traffic_router_api.html"/>
<link rel="prev" title="Users" href="traffic_ops_api/v12/user.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="/" class="icon icon-home"> Traffic Control
<img src="../_static/tc_logo.png" class="logo" />
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../basics/index.html">CDN Basics</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../basics/content_delivery_networks.html">Content Delivery Networks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../basics/http_11.html">HTTP 1.1</a></li>
<li class="toctree-l2"><a class="reference internal" href="../basics/caching_proxies.html">Caching Proxies</a></li>
<li class="toctree-l2"><a class="reference internal" href="../basics/cache_revalidation.html">Cache Control Headers and Revalidation</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../overview/index.html">Traffic Control Overview</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../overview/introduction.html">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/traffic_ops.html">Traffic Ops</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/traffic_router.html">Traffic Router</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/traffic_monitor.html">Traffic Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/traffic_stats.html">Traffic Stats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/traffic_portal.html">Traffic Portal</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/traffic_server.html">Traffic Server</a></li>
<li class="toctree-l2"><a class="reference internal" href="../overview/traffic_vault.html">Traffic Vault</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin/index.html">Administrator&#8217;s Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_ops_install.html">Installing Traffic Ops</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_ops_config.html">Configuring Traffic Ops</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_ops_using.html">Using Traffic Ops</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_ops_extensions.html">Managing Traffic Ops Extensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_monitor.html">Traffic Monitor Administration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_router.html">Traffic Router Administration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_stats.html">Traffic Stats Administration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_server.html">Traffic Server Administration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/traffic_vault.html">Traffic Vault Administration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../admin/quick_howto/index.html">Quick How To Guides</a></li>
</ul>
</li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer&#8217;s Guide</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="traffic_ops.html">Traffic Ops</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="">Traffic Router</a></li>
<li class="toctree-l2"><a class="reference internal" href="traffic_monitor.html">Traffic Monitor</a></li>
<li class="toctree-l2"><a class="reference internal" href="traffic_stats.html">Traffic Stats</a></li>
<li class="toctree-l2"><a class="reference internal" href="traffic_server.html">Traffic Server</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../faq/general.html">General</a></li>
<li class="toctree-l2"><a class="reference internal" href="../faq/development.html">Development</a></li>
<li class="toctree-l2"><a class="reference internal" href="../faq/administration.html">Running a Traffic Control CDN</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Traffic Control</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Traffic Control 1.4</a> &raquo;</li>
<li><a href="index.html">Developer&#8217;s Guide</a> &raquo;</li>
<li>Traffic Router</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/development/traffic_router.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="traffic_router/traffic_router_api.html" class="btn btn-neutral float-right" title="Traffic Router API">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="traffic_ops_api/v12/user.html" class="btn btn-neutral" title="Users"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<div role="main" class="document">
<div class="section" id="traffic-router">
<h1>Traffic Router<a class="headerlink" href="#traffic-router" title="Permalink to this headline"></a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline"></a></h2>
<p>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&#8217;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 <code class="docutils literal"><span class="pre">A</span></code> and <code class="docutils literal"><span class="pre">AAAA</span></code> records for a configurable name such as <code class="docutils literal"><span class="pre">edge.deliveryservice.somecdn.net</span></code>. Traffic Router is comprised of four separate Maven modules:</p>
<blockquote>
<div><ul class="simple">
<li>api - Provides a simple JSON interface into certain aspects of core and is deployed as a WAR to a Service (read: connector/listen port) within Tomcat which is separate from core</li>
<li>connector - A JAR that overrides Tomcat&#8217;s standard Http11Protocol Connector class and allows Traffic Router to delay opening listen sockets until it is in a state suitable for routing traffic</li>
<li>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</li>
<li>rpm - A simple Maven project which gathers the artifacts from the prior three modules and builds an RPM</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="software-requirements">
<h2>Software Requirements<a class="headerlink" href="#software-requirements" title="Permalink to this headline"></a></h2>
<p>To work on Traffic Router you need a *nix (MacOS and Linux are most commonly used) environment that has the following installed:</p>
<ul class="simple">
<li>Eclipse &gt;= Kepler SR2 (or another Java IDE)</li>
<li>Maven &gt;= 3.3.1</li>
<li>JDK &gt;= 6.0</li>
</ul>
</div>
<div class="section" id="traffic-router-project-tree-overview">
<h2>Traffic Router Project Tree Overview<a class="headerlink" href="#traffic-router-project-tree-overview" title="Permalink to this headline"></a></h2>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre">traffic_control/traffic_traffic_router/</span></code> - base directory for Traffic Router</p>
<blockquote>
<div><ul>
<li><p class="first"><code class="docutils literal"><span class="pre">api/</span></code> - Source code for Traffic Router API, which is built as its own deployable WAR file and communicates with Traffic Router Core using JMX</p>
<blockquote>
<div><ul>
<li><p class="first"><code class="docutils literal"><span class="pre">src/main</span></code> - Main source directory for Traffic Router API</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">java/</span></code> - Java source code for Traffic Router API</li>
<li><code class="docutils literal"><span class="pre">resources/</span></code> - Spring resources pulled in during an RPM build</li>
<li><code class="docutils literal"><span class="pre">webapp/</span></code> - Java webapp resources</li>
</ul>
</div></blockquote>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">src/test</span></code> - Test source directory for Traffic Router API</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">java/</span></code> - JUnit based unit tests for Traffic Router API</li>
<li><code class="docutils literal"><span class="pre">resources/</span></code> - Resources pulled in by unit tests</li>
</ul>
</div></blockquote>
</li>
</ul>
</div></blockquote>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">connector/</span></code> - Source code for Traffic Router Connector;</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">src/main/java</span></code> - Java source directory for Traffic Router Connector</li>
</ul>
</div></blockquote>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">core/</span></code> - Source code for Traffic Router Core, which is built as its own deployable WAR file and communicates with Traffic Router API using JMX</p>
<blockquote>
<div><ul>
<li><p class="first"><code class="docutils literal"><span class="pre">src/main</span></code> - Main source directory for Traffic Router Core</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">etc/init.d</span></code> - Init script for Tomcat</li>
<li><code class="docutils literal"><span class="pre">conf/</span></code> - Configuration files</li>
<li><code class="docutils literal"><span class="pre">java/</span></code> - Java source code for Traffic Router Core</li>
<li><code class="docutils literal"><span class="pre">opt/tomcat/conf</span></code> - Contains Tomcat configuration file(s) pulled in during an RPM build</li>
<li><code class="docutils literal"><span class="pre">resources/</span></code> - Resources pulled in during an RPM build</li>
<li><code class="docutils literal"><span class="pre">scripts/</span></code> - Scripts used by the RPM build process</li>
<li><code class="docutils literal"><span class="pre">webapp/</span></code> - Java webapp resources</li>
</ul>
</div></blockquote>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">src/test</span></code> - Test source directory for Traffic Router Core</p>
<blockquote>
<div><ul>
<li><p class="first"><code class="docutils literal"><span class="pre">db</span></code> - Files downloaded by unit tests</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">java/</span></code> - JUnit based unit tests for Traffic Router Core</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">resources/</span></code> - Configuration files used by unit tests</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">var/auto-zones</span></code> - BIND formatted zone files generated by Traffic Router Core during unit testing</li>
</ul>
</div></blockquote>
</li>
</ul>
</div></blockquote>
</li>
</ul>
</div></blockquote>
</li>
</ul>
</div></blockquote>
</li>
</ul>
</div>
<div class="section" id="java-formatting-conventions">
<h2>Java Formatting Conventions<a class="headerlink" href="#java-formatting-conventions" title="Permalink to this headline"></a></h2>
<p>None at this time. The codebase will eventually be formatted per Java standards.</p>
</div>
<div class="section" id="installing-the-developer-environment">
<h2>Installing The Developer Environment<a class="headerlink" href="#installing-the-developer-environment" title="Permalink to this headline"></a></h2>
<p>To install the Traffic Router Developer environment:</p>
<ol class="arabic simple">
<li>Clone the traffic_control repository using Git.</li>
<li>Change directories into <code class="docutils literal"><span class="pre">traffic_control/traffic_router</span></code>.</li>
<li>If you are not running Traffic Monitor locally (<a class="reference external" href="http://localhost:8080">http://localhost:8080</a>) from within Eclipse, edit the following parameter in core/src/test/resources/traffic_monitor.properties and point it to an instance, or instances of Traffic Monitor for your chosen CDN:</li>
</ol>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal"><span class="pre">traffic_monitor.bootstrap.hosts</span></code></td>
<td>FQDN and port of the Traffic Monitor instance(s), separated by semicolons as necessary (do not include <a class="reference external" href="http://">http://</a>).</td>
</tr>
</tbody>
</table>
<ol class="arabic" start="4">
<li><p class="first">Import the existing git repo into Eclipse:</p>
<blockquote>
<div><ol class="loweralpha simple">
<li>File -&gt; Import -&gt; Git -&gt; Projects from Git; Next</li>
<li>Existing local repository; Next</li>
<li>Add -&gt; browse to find <code class="docutils literal"><span class="pre">traffic_control</span></code>; Open</li>
<li>Select <code class="docutils literal"><span class="pre">traffic_control</span></code>; Next</li>
<li>Ensure &#8220;Import existing projects&#8221; is selected, expand <code class="docutils literal"><span class="pre">traffic_control</span></code>, select <code class="docutils literal"><span class="pre">traffic_router</span></code>; Next</li>
<li>Ensure <code class="docutils literal"><span class="pre">traffic_router_api</span></code>, <code class="docutils literal"><span class="pre">traffic_router_connector</span></code>, and <code class="docutils literal"><span class="pre">traffic_router_core</span></code> are checked; Finish (this step can take several minutes to complete)</li>
<li>Ensure <code class="docutils literal"><span class="pre">traffic_router_api</span></code>, <code class="docutils literal"><span class="pre">traffic_router_connector</span></code>, and <code class="docutils literal"><span class="pre">traffic_router_core</span></code> have been opened by Eclipse after importing</li>
</ol>
</div></blockquote>
</li>
<li><p class="first">From the terminal, run <code class="docutils literal"><span class="pre">mvn</span> <span class="pre">clean</span> <span class="pre">verify</span></code> from the <code class="docutils literal"><span class="pre">traffic_router</span></code> directory</p>
</li>
<li><p class="first">Start the embedded Jetty instance for Core from within Eclipse</p>
<blockquote>
<div><ol class="loweralpha">
<li><p class="first">In the package explorer, expand <code class="docutils literal"><span class="pre">traffic_router_core</span></code></p>
</li>
<li><p class="first">Expand <code class="docutils literal"><span class="pre">src/test/java</span></code></p>
</li>
<li><p class="first">Expand the package <code class="docutils literal"><span class="pre">com.comcast.cdn.traffic_control.traffic_router.core</span></code></p>
</li>
<li><p class="first">Open and run <code class="docutils literal"><span class="pre">TrafficRouterStart.java</span></code></p>
<blockquote>
<div><div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If an error is displayed in the Console, run <code class="docutils literal"><span class="pre">mvn</span> <span class="pre">clean</span> <span class="pre">verify</span></code> from the <code class="docutils literal"><span class="pre">traffic_router</span></code> directory</p>
</div>
</div></blockquote>
</li>
</ol>
</div></blockquote>
</li>
<li><p class="first">Traffic Router Core should now be running; the HTTP routing interface is available on <a class="reference external" href="http://localhost:8081">http://localhost:8081</a>, while the DNS server and routing interface is available on localhost:1053 via TCP and UDP.</p>
</li>
</ol>
</div>
<div class="section" id="test-cases">
<h2>Test Cases<a class="headerlink" href="#test-cases" title="Permalink to this headline"></a></h2>
<p>Unit tests can be executed using Maven by running <code class="docutils literal"><span class="pre">mvn</span> <span class="pre">test</span></code> at the root of the <code class="docutils literal"><span class="pre">traffic_router</span></code> project.</p>
</div>
<div class="section" id="api">
<h2>API<a class="headerlink" href="#api" title="Permalink to this headline"></a></h2>
<p><a class="reference internal" href="traffic_router/traffic_router_api.html#reference-tr-api"><span>Traffic Router API</span></a></p>
<div class="toctree-wrapper compound">
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="traffic_router/traffic_router_api.html" class="btn btn-neutral float-right" title="Traffic Router API">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="traffic_ops_api/v12/user.html" class="btn btn-neutral" title="Users"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'1.4',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>