File: irtt-server.html

package info (click to toggle)
irtt 0.9.1-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 648 kB
sloc: sh: 157; makefile: 9
file content (477 lines) | stat: -rw-r--r-- 13,427 bytes
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <meta name="author" content="" />
  <meta name="dcterms.date" content="2018-02-11" />
  <title>IRTT-SERVER(1) v0.9.0 | IRTT Manual</title>
  <style>
    html {
      line-height: 1.5;
      font-family: Georgia, serif;
      font-size: 20px;
      color: #1a1a1a;
      background-color: #fdfdfd;
    }
    body {
      margin: 0 auto;
      max-width: 36em;
      padding-left: 50px;
      padding-right: 50px;
      padding-top: 50px;
      padding-bottom: 50px;
      hyphens: auto;
      word-wrap: break-word;
      text-rendering: optimizeLegibility;
      font-kerning: normal;
    }
    @media (max-width: 600px) {
      body {
        font-size: 0.9em;
        padding: 1em;
      }
    }
    @media print {
      body {
        background-color: transparent;
        color: black;
        font-size: 12pt;
      }
      p, h2, h3 {
        orphans: 3;
        widows: 3;
      }
      h2, h3, h4 {
        page-break-after: avoid;
      }
    }
    p {
      margin: 1em 0;
    }
    a {
      color: #1a1a1a;
    }
    a:visited {
      color: #1a1a1a;
    }
    img {
      max-width: 100%;
    }
    h1, h2, h3, h4, h5, h6 {
      margin-top: 1.4em;
    }
    h5, h6 {
      font-size: 1em;
      font-style: italic;
    }
    h6 {
      font-weight: normal;
    }
    ol, ul {
      padding-left: 1.7em;
      margin-top: 1em;
    }
    li > ol, li > ul {
      margin-top: 0;
    }
    blockquote {
      margin: 1em 0 1em 1.7em;
      padding-left: 1em;
      border-left: 2px solid #e6e6e6;
      color: #606060;
    }
    code {
      font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
      font-size: 85%;
      margin: 0;
    }
    pre {
      margin: 1em 0;
      overflow: auto;
    }
    pre code {
      padding: 0;
      overflow: visible;
    }
    .sourceCode {
     background-color: transparent;
     overflow: visible;
    }
    hr {
      background-color: #1a1a1a;
      border: none;
      height: 1px;
      margin: 1em 0;
    }
    table {
      margin: 1em 0;
      border-collapse: collapse;
      width: 100%;
      overflow-x: auto;
      display: block;
      font-variant-numeric: lining-nums tabular-nums;
    }
    table caption {
      margin-bottom: 0.75em;
    }
    tbody {
      margin-top: 0.5em;
      border-top: 1px solid #1a1a1a;
      border-bottom: 1px solid #1a1a1a;
    }
    th {
      border-top: 1px solid #1a1a1a;
      padding: 0.25em 0.5em 0.25em 0.5em;
    }
    td {
      padding: 0.125em 0.5em 0.25em 0.5em;
    }
    header {
      margin-bottom: 4em;
      text-align: center;
    }
    #TOC li {
      list-style: none;
    }
    #TOC a:not(:hover) {
      text-decoration: none;
    }
    code{white-space: pre-wrap;}
    span.smallcaps{font-variant: small-caps;}
    span.underline{text-decoration: underline;}
    div.column{display: inline-block; vertical-align: top; width: 50%;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    ul.task-list{list-style: none;}
    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
  </style>
  <!--[if lt IE 9]>
    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
  <![endif]-->
  <meta name=viewport content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="https://unpkg.com/purecss@1.0.0/build/pure-min.css"
  	integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w"
  	crossorigin="anonymous">
  <style>
  	body {
  		margin-left: auto;
  		margin-right: auto;
  		max-width: 768px;
  		padding-left: 2em;
  		padding-right: 2em;
  		color: #24292e;
  	}
  	
  	table th {
  		text-align: left;
  	}
  	
  	dt {
  		font-weight: bold;
  	}
  	
  	dd {
  		padding-bottom: 1em;
  		padding-top: 1em;
  	}
  	
  	dd p:first-child {
  		margin-top: 0;
  	}
  	
  	blockquote {
  		font-style: italic;
  	}
  </style>
</head>
<body>
<header id="title-block-header">
<h1 class="title">IRTT-SERVER(1) v0.9.0 | IRTT Manual</h1>
<p class="author"></p>
<p class="date">February 11, 2018</p>
</header>
<h1 id="name">NAME</h1>
<p>irtt-server - Isochronous Round-Trip Time Server</p>
<h1 id="synopsis">SYNOPSIS</h1>
<p>irtt server [<em>args</em>]</p>
<h1 id="description">DESCRIPTION</h1>
<p><em>irtt server</em> is the server for <a href="irtt.html">irtt(1)</a>.</p>
<h1 id="options">OPTIONS</h1>
<dl>
<dt>-b <em>addresses</em></dt>
<dd><p>Bind addresses (default “:2112”), comma separated list of:</p>
<table class="pure-table pure-table-striped">
<thead>
<tr class="header">
<th>Format</th>
<th>Address Type</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>:port</td>
<td>unspecified address with port, use with care</td>
</tr>
<tr class="even">
<td>host</td>
<td>host with default port 2112, see <a href="#host-formats">Host formats</a> below</td>
</tr>
<tr class="odd">
<td>host:port</td>
<td>host with specified port, see <a href="#host-formats">Host formats</a> below</td>
</tr>
<tr class="even">
<td>%iface</td>
<td>all addresses on interface iface with default port 2112</td>
</tr>
<tr class="odd">
<td>%iface:port</td>
<td>all addresses on interface iface with port</td>
</tr>
</tbody>
</table>
<p><strong>Note:</strong> iface strings may contain * to match multiple interfaces</p>
</dd>
<dt>-d <em>duration</em></dt>
<dd>Max test duration, or 0 for no maximum (default 0s, see <a href="#duration-units">Duration units</a> below)
</dd>
<dt>-i <em>interval</em></dt>
<dd>Min send interval, or 0 for no minimum (default 10ms, see <a href="#duration-units">Duration units</a> below)
</dd>
<dt>-l <em>length</em></dt>
<dd>Max packet length (default 0), or 0 for no maximum. Numbers less than size of required headers will cause test packets to be dropped.
</dd>
<dt>--hmac=<em>key</em></dt>
<dd><p>Add HMAC with <em>key</em> (0x for hex) to all packets, provides:</p>
<ul>
<li>Dropping of all packets without a correct HMAC</li>
<li>Protection for server against unauthorized discovery and use</li>
</ul>
</dd>
<dt>--syslog=<em>uri</em></dt>
<dd><p>Log events to syslog (default don’t use syslog). URI format: protocol://host:port/tag. Examples:</p>
<table class="pure-table pure-table-striped">
<thead>
<tr class="header">
<th>URI</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>local:</td>
<td>Log to local syslog, default tag irtt</td>
</tr>
<tr class="even">
<td>local:/irttsrv</td>
<td>Log to local syslog, tag irttsrv</td>
</tr>
<tr class="odd">
<td>udp://logsrv:514/irttsrv</td>
<td>UDP to logsrv:514, tag irttsrv</td>
</tr>
<tr class="even">
<td>tcp://logsrv:8514/</td>
<td>TCP to logsrv:8514, default tag irtt</td>
</tr>
</tbody>
</table>
<p><strong>Note:</strong> not available on Windows, Plan 9 or Google Native Client</p>
</dd>
<dt>--timeout=<em>duration</em></dt>
<dd>Timeout for closing connections if no requests received on a connection (default 1m0s, see <a href="#duration-units">Duration units</a> below). 0 means no timeout (not recommended, especially on public servers). Max client interval will be restricted to timeout/4.
</dd>
<dt>--pburst=<em>#</em></dt>
<dd>Packet burst allowed before enforcing minimum interval (default 5)
</dd>
<dt>--fill=<em>fill</em></dt>
<dd><p>Payload fill if not requested (default pattern:69727474). Possible values include:</p>
<table class="pure-table pure-table-striped">
<thead>
<tr class="header">
<th>Value</th>
<th>Fill</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><em>none</em></td>
<td>Echo client payload (insecure on public servers)</td>
</tr>
<tr class="even">
<td><em>rand</em></td>
<td>Use random bytes from Go’s math.rand</td>
</tr>
<tr class="odd">
<td><em>pattern:</em>XX</td>
<td>Use repeating pattern of hex (default 69727474)</td>
</tr>
</tbody>
</table>
</dd>
<dt>--allow-fills=<em>fills</em></dt>
<dd><p>Comma separated patterns of fill requests to allow (default rand). See options for <em>–fill</em>. Notes:</p>
<ul>
<li>Patterns may contain * for matching</li>
<li>Allowing non-random fills insecure on public servers</li>
<li>Use <em>--allow-fills=""</em> to disallow all fill requests</li>
</ul>
</dd>
<dt>--tstamp=<em>modes</em></dt>
<dd><p>Timestamp modes to allow (default dual). Possible values:</p>
<table class="pure-table pure-table-striped">
<thead>
<tr class="header">
<th>Value</th>
<th>Allowed Timestamps</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><em>none</em></td>
<td>Don’t allow any timestamps</td>
</tr>
<tr class="even">
<td><em>single</em></td>
<td>Allow a single timestamp (send, receive or midpoint)</td>
</tr>
<tr class="odd">
<td><em>dual</em></td>
<td>Allow dual timestamps</td>
</tr>
</tbody>
</table>
</dd>
<dt>--no-dscp</dt>
<dd>Don’t allow setting dscp (default false)
</dd>
<dt>--set-src-ip</dt>
<dd>Set source IP address on all outgoing packets from listeners on unspecified IP addresses (use for more reliable reply routing, but increases per-packet heap allocations)
</dd>
<dt>--thread</dt>
<dd>Lock request handling goroutines to OS threads
</dd>
<dt>-h</dt>
<dd>Show help
</dd>
<dt>-v</dt>
<dd>Show version
</dd>
</dl>
<h2 id="host-formats">Host formats</h2>
<p>Hosts may be either hostnames (for IPv4 or IPv6) or IP addresses. IPv6 addresses must be surrounded by brackets and may include a zone after the % character. Examples:</p>
<table class="pure-table pure-table-striped">
<thead>
<tr class="header">
<th>Type</th>
<th>Example</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>IPv4 IP</td>
<td>192.168.1.10</td>
</tr>
<tr class="even">
<td>IPv6 IP</td>
<td>[2001:db8:8f::2/32]</td>
</tr>
<tr class="odd">
<td>IPv4/6 hostname</td>
<td>localhost</td>
</tr>
</tbody>
</table>
<p><strong>Note:</strong> IPv6 addresses must be quoted in most shells.</p>
<h2 id="duration-units">Duration units</h2>
<p>Durations are a sequence of decimal numbers, each with optional fraction, and unit suffix, such as: “300ms”, “1m30s” or “2.5m”. Sanity not enforced.</p>
<table class="pure-table pure-table-striped">
<thead>
<tr class="header">
<th>Suffix</th>
<th>Unit</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>h</td>
<td>hours</td>
</tr>
<tr class="even">
<td>m</td>
<td>minutes</td>
</tr>
<tr class="odd">
<td>s</td>
<td>seconds</td>
</tr>
<tr class="even">
<td>ms</td>
<td>milliseconds</td>
</tr>
<tr class="odd">
<td>ns</td>
<td>nanoseconds</td>
</tr>
</tbody>
</table>
<h1 id="security">SECURITY</h1>
<p>Running an IRTT server that’s open to the outside world requires some additional attention. For starters, the command line flags should be used to, at a minimum:</p>
<ul>
<li>Restrict the duration (<em>-d</em>), interval (<em>-i</em>) and length (<em>-l</em>) of tests, particularly for public servers</li>
<li>Set an HMAC key (<em>--hmac</em>) for private servers to prevent unauthorized discovery and use</li>
</ul>
<p>In addition, there are various systemd(1) options available for securing services. The irtt.service file included with the distribution sets some commonly used options, but should not be considered exhaustive.</p>
<p>To secure a server for public use, additional steps may be taken that are outside of the scope of this documentation, including but not limited to:</p>
<ul>
<li>Installing irtt in an unprivileged container</li>
<li>Setting up an iptables firewall (only UDP port 2112 must be open)</li>
<li>Setting up a chroot jail</li>
</ul>
<p>It should be noted that there are no known security vulnerabilities in the Go language at this time, and the steps above, in particular the chroot jail, may or may not serve to enhance security in any way. Go-based servers are generally regarded as safe because of Go’s high-level language constructs for memory management, and at this time IRTT makes no use of Go’s <a href="https://golang.org/pkg/unsafe/">unsafe</a> package.</p>
<h1 id="exit-status">EXIT STATUS</h1>
<p><em>irtt server</em> exits with one of the following status codes:</p>
<table class="pure-table pure-table-striped">
<thead>
<tr class="header">
<th>Code</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td>0</td>
<td>Success</td>
</tr>
<tr class="even">
<td>1</td>
<td>Runtime error</td>
</tr>
<tr class="odd">
<td>2</td>
<td>Command line error</td>
</tr>
<tr class="even">
<td>3</td>
<td>Two interrupt signals received</td>
</tr>
</tbody>
</table>
<h1 id="examples">EXAMPLES</h1>
<dl>
<dt>$ irtt server</dt>
<dd>Starts the server and listens on all addresses (unspecified address)
</dd>
<dt>$ irtt server -d 30s -i 20ms -l 256 --fill=rand --allow-fills=""</dt>
<dd>Starts the server and listens on all addresses, setting the maximum test duration to 30 seconds, minimum interval to 20 ms, and maximum packet length to 256 bytes. Disallows fill requests and forces all return packets to be filled with random data.
</dd>
<dt>$ irtt server -b 192.168.100.11:64381 --hmac=secret</dt>
<dd>Starts the server and binds to IPv4 address 192.168.100.11, port 64381. Requires a valid HMAC on all packets with the key <em>secret</em>, otherwise packets are dropped.
</dd>
</dl>
<h1 id="see-also">SEE ALSO</h1>
<p><a href="irtt.html">irtt(1)</a>, <a href="irtt-client.html">irtt-client(1)</a></p>
<p><a href="https://github.com/heistp/irtt/">IRTT GitHub repository</a></p>
</body>
</html>