1IRTT-CLIENT(1) IRTT Manual IRTT-CLIENT(1)
2
6 irtt-client - Isochronous Round-Trip Time Client
7
9 irtt client [args]
10
12 irtt client is the client for irtt(1).
13
15 -d duration
16 Total time to send (default 1m0s, see Duration units below)
17 -i interval
19 Send interval (default 1s, see Duration units below)
20 -l length
22 Length of packet (default 0, increased as necessary for required
23 headers), common values:
24 • 1472 (max unfragmented size of IPv4 datagram for 1500 byte
26 MTU)
27 • 1452 (max unfragmented size of IPv6 datagram for 1500 byte
29 MTU)
30 -o file
32 Write JSON output to file (use `-' for stdout). The extension
33 used for file controls the gzip behavior as follows (output to
34 stdout is not gzipped):
35 Extension Behavior
37 ───────────────────────────────────────
38 none extension .json.gz is
39 added, output is gzipped
40 .json.gz output is gzipped
41 .gz output is gzipped, exten‐
42 sion changed to .json.gz
43 .json output is not gzipped
44 -q Quiet, suppress per-packet output
46 -Q Really quiet, suppress all output except errors to stderr
48 -n No test, connect to the server and validate test parameters but
50 don’t run the test
51 --stats=stats
53 Server stats on received packets (default both). Possible val‐
54 ues:
55 Value Meaning
57 ────────────────────────────────────
58 none no server stats on re‐
59 ceived packets
60 count total count of received
61 packets
62 window receipt status of last 64
63 packets with each reply
64 both both count and window
65 --tstamp=mode
67 Server timestamp mode (default both). Possible values:
68 Value Meaning
70 ──────────────────────────────────────
71 none request no timestamps
72 send request timestamp at serv‐
73 er send
74 receive request timestamp at serv‐
75 er receive
76 both request both send and re‐
77 ceive timestamps
78 midpoint request midpoint timestamp
79 (send/receive avg)
80 --clock=clock
82 Clock/s used for server timestamps (default both). Possible
83 values:
84 Value Meaning
86 ─────────────────────────────────
87 wall wall clock only
88 monotonic monotonic clock only
89 both both clocks
90 --dscp=dscp
92 DSCP (ToS) value (default 0, 0x prefix for hex). Common values:
93 Value Meaning
95 ─────────────────────────────────
96 0 Best effort
97 8 CS1- Bulk
98 40 CS5- Video
99 46 EF- Expedited forwarding
100 DSCP & ToS (https://www.tucny.com/Home/dscp-tos)
102 --df=DF
104 Setting for do not fragment (DF) bit in all packets. Possible
105 values:
106 Value Meaning
108 ─────────────────────────
109 default OS default
110 false DF bit not set
111 true DF bit set
112 --wait=wait
114 Wait time at end of test for unreceived replies (default 3x4s).
115 Possible values:
116 Format Meaning
118 ────────────────────────────────────────
119 #xduration # times max RTT, or dura‐
120 tion if no response
121 #rduration # times RTT, or duration
122 if no response
123 duration fixed duration (see Dura‐
124 tion units below)
125 Examples:
127 Example Meaning
129 ─────────────────────────────────────
130 3x4s 3 times max RTT, or 4 sec‐
131 onds if no response
132 1500ms fixed 1500 milliseconds
133 --timer=timer
135 Timer for waiting to send packets (default comp). Possible val‐
136 ues:
137 Value Meaning
139 ──────────────────────────────────────
140 simple Go’s standard time.Timer
141 comp Simple timer with error
142 compensation (see -tcomp)
143 hybrid:# Hybrid comp/busy timer
144 with sleep factor (default
145 0.95)
146 busy busy wait loop (high pre‐
147 cision and CPU, blasphemy)
148 --tcomp=alg
150 Comp timer averaging algorithm (default exp:0.10). Possible
151 values:
152 Value Meaning
154 ───────────────────────────────────
155 avg Cumulative average error
156 win:# Moving average error with
157 window # (default 5)
158 exp:# Exponential average with
159 alpha # (default 0.10)
160 --fill=fill
162 Fill payload with given data (default none). Possible values:
163 Value Meaning
165 ────────────────────────────────────────
166 none Leave payload as all ze‐
167 roes
168 rand Use random bytes from Go’s
169 math.rand
170 pattern:XX Use repeating pattern of
171 hex (default 69727474)
172 --fill-one
174 Fill only once and repeat for all packets
175 --sfill=fill
177 Request server fill (default not specified). See values for
178 –fill. Server must support and allow this fill with –allow-
179 fills.
180 --local=addr
182 Local address (default from OS). Possible values:
183 Value Meaning
185 ───────────────────────────────────────
186 :port Unspecified address (all
187 IPv4/IPv6 addresses) with
188 port
189 host Host with dynamic port,
190 see Host formats below
191 host:port Host with specified port,
192 see Host formats below
193 --hmac=key
195 Add HMAC with key (0x for hex) to all packets, provides:
196 • Dropping of all packets without a correct HMAC
198 • Protection for server against unauthorized discovery and use
200 -4 IPv4 only
202 -6 IPv6 only
204 --timeouts=durations
206 Timeouts used when connecting to server (default 1s,2s,4s,8s).
207 Comma separated list of durations (see Duration units below).
208 Total wait time will be up to the sum of these Durations. Max
209 packets sent is up to the number of Durations. Minimum timeout
210 duration is 200ms.
211 --ttl=ttl
213 Time to live (default 0, meaning use OS default)
214 --loose
216 Accept and use any server restricted test parameters instead of
217 exiting with nonzero status.
218 --thread
220 Lock sending and receiving goroutines to OS threads
221 -h Show help
223 -v Show version
225 Host formats
227 Hosts may be either hostnames (for IPv4 or IPv6) or IP addresses. IPv6
228 addresses must be surrounded by brackets and may include a zone after
229 the % character. Examples:
230 Type Example
232 ──────────────────────────────────────
233 IPv4 IP 192.168.1.10
234 IPv6 IP [2001:db8:8f::2/32]
235 IPv4/6 hostname localhost
236 Note: IPv6 addresses must be quoted in most shells.
238 Duration units
240 Durations are a sequence of decimal numbers, each with optional frac‐
241 tion, and unit suffix, such as: “300ms”, “1m30s” or “2.5m”. Sanity not
242 enforced.
243 Suffix Unit
245 ──────────────────────
246 h hours
247 m minutes
248 s seconds
249 ms milliseconds
250 ns nanoseconds
251
253 IRTT’s JSON output format consists of five top-level objects:
254 1. version
256 2. system_info
258 3. config
260 4. stats
262 5. round_trips
264 These are documented through the examples below. All attributes are
266 present unless otherwise noted.
267 version
269 version information
270 "version": {
272 "irtt": "0.9.0",
273 "protocol": 1,
274 "json_format": 1
275 },
276 • irtt the IRTT version number
278 • protocol the protocol version number (increments mean incompatible
280 changes)
281 • json_format the JSON format number (increments mean incompatible
283 changes)
284 system_info
286 a few basic pieces of system information
287 "system_info": {
289 "os": "darwin",
290 "cpus": 8,
291 "go_version": "go1.9.2",
292 "hostname": "tron.local"
293 },
294 • os the Operating System from Go’s runtime.GOOS
296 • cpus the number of CPUs reported by Go’s runtime.NumCPU(), which re‐
298 flects the number of logical rather than physical CPUs. In the exam‐
299 ple below, the number 8 is reported for a Core i7 (quad core) with
300 hyperthreading (2 threads per core).
301 • go_version the version of Go the executable was built with
303 • hostname the local hostname
305 config
307 the configuration used for the test
308 "config": {
310 "local_address": "127.0.0.1:51203",
311 "remote_address": "127.0.0.1:2112",
312 "open_timeouts": "1s,2s,4s,8s",
313 "params": {
314 "proto_version": 1,
315 "duration": 600000000,
316 "interval": 200000000,
317 "length": 48,
318 "received_stats": "both",
319 "stamp_at": "both",
320 "clock": "both",
321 "dscp": 0,
322 "server_fill": ""
323 },
324 "loose": false,
325 "ip_version": "IPv4",
326 "df": 0,
327 "ttl": 0,
328 "timer": "comp",
329 "waiter": "3x4s",
330 "filler": "none",
331 "fill_one": false,
332 "thread_lock": false,
333 "supplied": {
334 "local_address": ":0",
335 "remote_address": "localhost",
336 "open_timeouts": "1s,2s,4s,8s",
337 "params": {
338 "proto_version": 1,
339 "duration": 600000000,
340 "interval": 200000000,
341 "length": 0,
342 "received_stats": "both",
343 "stamp_at": "both",
344 "clock": "both",
345 "dscp": 0,
346 "server_fill": ""
347 },
348 "loose": false,
349 "ip_version": "IPv4+6",
350 "df": 0,
351 "ttl": 0,
352 "timer": "comp",
353 "waiter": "3x4s",
354 "filler": "none",
355 "fill_one": false,
356 "thread_lock": false
357 }
358 },
359 • local_address the local address (IP:port) for the client
361 • remote_address the remote address (IP:port) for the server
363 • open_timeouts a list of timeout durations used after an open packet
365 is sent
366 • params are the parameters that were negotiated with the server, in‐
368 cluding:
369 • proto_version protocol version number
371 • duration duration of the test, in nanoseconds
373 • interval send interval, in nanoseconds
375 • length packet length
377 • received_stats statistics for packets received by server (none,
379 count, window or both, --stats flag for irtt client)
380 • stamp_at timestamp selection parameter (none, send, receive, both
382 or midpoint, --tstamp flag for irtt client)
383 • clock clock selection parameter (wall or monotonic, --clock flag
385 for irtt client)
386 • dscp the DSCP (https://en.wikipedia.org/wiki/Differentiated_ser‐
388 vices) value
389 • server_fill the requested server fill (--sfill flag for irtt
391 client)
392 • loose if true, client accepts and uses restricted server parameters,
394 with a warning
395 • ip_version the IP version used (IPv4 or IPv6)
397 • df the do-not-fragment setting (0 == OS default, 1 == false, 2 ==
399 true)
400 • ttl the IP time-to-live (https://en.wikipedia.org/wiki/Time_to_live)
402 value
403 • timer the timer used: simple, comp, hybrid or busy (irtt client
405 --timer flag)
406 • time_source the time source used: go or windows
408 • waiter the waiter used: fixed duration, multiple of RTT or multiple
410 of max RTT (irtt client --wait flag)
411 • filler the packet filler used: none, rand or pattern (irtt client
413 --fill flag)
414 • fill_one whether to fill only once and repeat for all packets (irtt
416 client --fill-one flag)
417 • thread_lock whether to lock packet handling goroutines to OS threads
419 • supplied a nested config object with the configuration as originally
421 supplied to the API or irtt command. The supplied configuration can
422 differ from the final configuration in the following ways:
423 • local_address and remote_address may have hostnames or named ports
425 before being resolved to an IP and numbered port
426 • ip_version may be IPv4+6 before it is determined after address res‐
428 olution
429 • params may be different before the server applies restrictions
431 based on its configuration
432 stats
434 statistics for the results
435 "stats": {
437 "start_time": {
438 "wall": 1528621979787034330,
439 "monotonic": 5136247
440 },
441 "send_call": {
442 "total": 79547,
443 "n": 3,
444 "min": 17790,
445 "max": 33926,
446 "mean": 26515,
447 "stddev": 8148,
448 "variance": 66390200
449 },
450 "timer_error": {
451 "total": 227261,
452 "n": 2,
453 "min": 59003,
454 "max": 168258,
455 "mean": 113630,
456 "stddev": 77254,
457 "variance": 5968327512
458 },
459 "rtt": {
460 "total": 233915,
461 "n": 2,
462 "min": 99455,
463 "max": 134460,
464 "mean": 116957,
465 "median": 116957,
466 "stddev": 24752,
467 "variance": 612675012
468 },
469 "send_delay": {
470 "total": 143470,
471 "n": 2,
472 "min": 54187,
473 "max": 89283,
474 "mean": 71735,
475 "median": 71735,
476 "stddev": 24816,
477 "variance": 615864608
478 },
479 "receive_delay": {
480 "total": 90445,
481 "n": 2,
482 "min": 45177,
483 "max": 45268,
484 "mean": 45222,
485 "median": 45222,
486 "stddev": 64,
487 "variance": 4140
488 },
489 "server_packets_received": 2,
490 "bytes_sent": 144,
491 "bytes_received": 96,
492 "duplicates": 0,
493 "late_packets": 0,
494 "wait": 403380,
495 "duration": 400964028,
496 "packets_sent": 3,
497 "packets_received": 2,
498 "packet_loss_percent": 33.333333333333336,
499 "upstream_loss_percent": 33.333333333333336,
500 "downstream_loss_percent": 0,
501 "duplicate_percent": 0,
502 "late_packets_percent": 0,
503 "ipdv_send": {
504 "total": 35096,
505 "n": 1,
506 "min": 35096,
507 "max": 35096,
508 "mean": 35096,
509 "median": 35096,
510 "stddev": 0,
511 "variance": 0
512 },
513 "ipdv_receive": {
514 "total": 91,
515 "n": 1,
516 "min": 91,
517 "max": 91,
518 "mean": 91,
519 "median": 91,
520 "stddev": 0,
521 "variance": 0
522 },
523 "ipdv_round_trip": {
524 "total": 35005,
525 "n": 1,
526 "min": 35005,
527 "max": 35005,
528 "mean": 35005,
529 "median": 35005,
530 "stddev": 0,
531 "variance": 0
532 },
533 "server_processing_time": {
534 "total": 20931,
535 "n": 2,
536 "min": 9979,
537 "max": 10952,
538 "mean": 10465,
539 "stddev": 688,
540 "variance": 473364
541 },
542 "timer_err_percent": 0.056815,
543 "timer_misses": 0,
544 "timer_miss_percent": 0,
545 "send_rate": {
546 "bps": 2878,
547 "string": "2.9 Kbps"
548 },
549 "receive_rate": {
550 "bps": 3839,
551 "string": "3.8 Kbps"
552 }
553 },
554 Note: In the stats object, a duration stats class of object repeats and
556 will not be repeated in the individual descriptions. It contains sta‐
557 tistics about nanosecond duration values and has the following at‐
558 tributes:
559 • total the total of the duration values
561 • n the number of duration values
563 • min the minimum duration value
565 • max the maximum duration value
567 • mean the mean duration value
569 • stddev the standard deviation
571 • variance the variance
573 The regular attributes in stats are as follows:
575 • start_time the start time of the test (see round_trips Notes for de‐
577 scriptions of wall and monotonic values)
578 • send_call a duration stats object for the call time when sending
580 packets
581 • timer_error a duration stats object for the observed sleep time error
583 • rtt a duration stats object for the round-trip time
585 • send_delay a duration stats object for the one-way send delay (only
587 available if server timestamps are enabled)
588 • receive_delay a duration stats object for the one-way receive delay
590 (only available if server timestamps are enabled)
591 • server_packets_received the number of packets received by the server,
593 including duplicates (always present, but only valid if the Received‐
594 Stats parameter includes ReceivedStatsCount, or the --stats flag to
595 the irtt client is count or both)
596 • bytes_sent the number of UDP payload bytes sent during the test
598 • bytes_received the number of UDP payload bytes received during the
600 test
601 • duplicates the number of packets received with the same sequence num‐
603 ber
604 • late_packets the number of packets received with a sequence number
606 lower than the previously received sequence number (one simple metric
607 for out-of-order packets)
608 • wait the actual time spent waiting for final packets, in nanoseconds
610 • duration the actual duration of the test, in nanoseconds, from the
612 time just before the first packet was sent to the time after the last
613 packet was received and results are starting to be calculated
614 • packets_sent the number of packets sent to the server
616 • packets_received the number of packets received from the server
618 • packet_loss_percent 100 * (packets_sent - packets_received) / pack‐
620 ets_sent
621 • upstream_loss_percent 100 * (packets_sent - server_packets_received /
623 packets_sent) (always present, but only valid if server_packets_re‐
624 ceived is valid)
625 • downstream_loss_percent 100 * (server_packets_received - packets_re‐
627 ceived / server_packets_received) (always present, but only valid if
628 server_packets_received is valid)
629 • duplicate_percent 100 * duplicates / packets_received
631 • late_packets_percent 100 * late_packets / packets_received
633 • ipdv_send a duration stats object for the send IPDV
635 (https://en.wikipedia.org/wiki/Packet_delay_variation) (only avail‐
636 able if server timestamps are enabled)
637 • ipdv_receive a duration stats object for the receive IPDV
639 (https://en.wikipedia.org/wiki/Packet_delay_variation) (only avail‐
640 able if server timestamps are enabled)
641 • ipdv_round_trip a duration stats object for the round-trip IPDV
643 (https://en.wikipedia.org/wiki/Packet_delay_variation) (available re‐
644 gardless of whether server timestamps are enabled or not)
645 • server_processing_time a duration stats object for the time the serv‐
647 er took after it received the packet to when it sent the response
648 (only available when both send and receive timestamps are enabled)
649 • timer_err_percent the mean of the absolute values of the timer error,
651 as a percentage of the interval
652 • timer_misses the number of times the timer missed the interval (was
654 at least 50% over the scheduled time)
655 • timer_miss_percent 100 * timer_misses / expected packets sent
657 • send_rate the send bitrate (bits-per-second and corresponding
659 string), calculated using the number of UDP payload bytes sent be‐
660 tween the time right before the first send call and the time right
661 after the last send call
662 • receive_rate the receive bitrate (bits-per-second and corresponding
664 string), calculated using the number of UDP payload bytes received
665 between the time right after the first receive call and the time
666 right after the last receive call
667 round_trips
669 each round-trip is a single request to / reply from the server
670 "round_trips": [
672 {
673 "seqno": 0,
674 "lost": false,
675 "timestamps": {
676 "client": {
677 "receive": {
678 "wall": 1508180723502871779,
679 "monotonic": 2921143
680 },
681 "send": {
682 "wall": 1508180723502727340,
683 "monotonic": 2776704
684 }
685 },
686 "server": {
687 "receive": {
688 "wall": 1508180723502816623,
689 "monotonic": 32644353327
690 },
691 "send": {
692 "wall": 1508180723502826602,
693 "monotonic": 32644363306
694 }
695 }
696 },
697 "delay": {
698 "receive": 45177,
699 "rtt": 134460,
700 "send": 89283
701 },
702 "ipdv": {}
703 },
704 {
705 "seqno": 1,
706 "lost": false,
707 "timestamps": {
708 "client": {
709 "receive": {
710 "wall": 1508180723702917735,
711 "monotonic": 202967099
712 },
713 "send": {
714 "wall": 1508180723702807328,
715 "monotonic": 202856692
716 }
717 },
718 "server": {
719 "receive": {
720 "wall": 1508180723702861515,
721 "monotonic": 32844398219
722 },
723 "send": {
724 "wall": 1508180723702872467,
725 "monotonic": 32844409171
726 }
727 }
728 },
729 "delay": {
730 "receive": 45268,
731 "rtt": 99455,
732 "send": 54187
733 },
734 "ipdv": {
735 "receive": 91,
736 "rtt": -35005,
737 "send": -35096
738 }
739 },
740 {
741 "seqno": 2,
742 "lost": true,
743 "timestamps": {
744 "client": {
745 "receive": {},
746 "send": {
747 "wall": 1508180723902925971,
748 "monotonic": 402975335
749 }
750 },
751 "server": {
752 "receive": {},
753 "send": {}
754 }
755 },
756 "delay": {},
757 "ipdv": {}
758 }
759 ]
760 Note: wall values are from Go’s time.Time.UnixNano(), the number of
762 nanoseconds elapsed since January 1, 1970 UTC
763 Note: monotonic values are the number of nanoseconds since some arbi‐
765 trary point in time, so can only be relied on to measure duration
766 • seqno the sequence number
768 • lost the lost status of the packet, which can be one of false, true,
770 true_down or true_up. The true_down and true_up values are only pos‐
771 sible if the ReceivedStats parameter includes ReceivedStatsWindow
772 (irtt client --stats flag). Even then, if it could not be determined
773 whether the packet was lost upstream or downstream, the value true is
774 used.
775 • timestamps the client and server timestamps
777 • client the client send and receive wall and monotonic timestamps
779 (receive values only present if lost is false)
780 • server the server send and receive wall and monotonic timestamps
782 (both send and receive values not present if lost is true), and ad‐
783 ditionally:
784 • send values are not present if the StampAt (irtt client --tstamp
786 flag) does not include send timestamps
787 • receive values are not present if the StampAt (irtt client
789 --tstamp flag) does not include receive timestamps
790 • wall values are not present if the Clock (irtt client --clock
792 flag) does not include wall values or server timestamps are not
793 enabled
794 • monotonic values are not present if the Clock (irtt client
796 --clock flag) does not include monotonic values or server time‐
797 stamps are not enabled
798 • delay an object containing the delay values
800 • receive the one-way receive delay, in nanoseconds (present only if
802 server timestamps are enabled and at least one wall clock value is
803 available)
804 • rtt the round-trip time, in nanoseconds, always present
806 • send the one-way send delay, in nanoseconds (present only if server
808 timestamps are enabled and at least one wall clock value is avail‐
809 able)
810 • ipdv an object containing the IPDV (https://en.wikipedia.org/wi‐
812 ki/Packet_delay_variation) values (attributes present only for seqno
813 > 0, and if lost is false for both the current and previous
814 round_trip)
815 • receive the difference in receive delay relative to the previous
817 packet (present only if at least one server timestamp is available)
818 • rtt the difference in round-trip time relative to the previous
820 packet (always present for seqno > 0)
821 • send the difference in send delay relative to the previous packet
823 (present only if at least one server timestamp is available)
824
826 irtt client exits with one of the following status codes:
827 Code Meaning
829 ──────────────────────────────────
830 0 Success
831 1 Runtime error
832 2 Command line error
833 3 Two interrupt signals re‐
834 ceived
835
837 It is possible with the irtt client to dramatically harm network per‐
838 formance by using intervals that are too low, particularly in combina‐
839 tion with large packet lengths. Careful consideration should be given
840 before using sub-millisecond intervals, not only because of the impact
841 on the network, but also because:
842 • Timer accuracy at sub-millisecond intervals may begin to suffer with‐
844 out the use of a custom kernel or the busy timer (which pins the CPU)
845 • Memory consumption for results storage and system CPU time both rise
847 rapidly
848 • The granularity of the results reported may very well not be required
850
852 $ irtt client localhost
853 Sends requests once per second for one minute to localhost.
854 $ irtt client -i 200ms -d 10s -o - localhost
856 Sends requests every 0.2 sec for 10 seconds to localhost.
857 Writes JSON output to stdout.
858 $ irtt client -i 20ms -d 1m -l 172 --fill=rand --sfill=rand
860 192.168.100.10
861 Sends requests every 20ms for one minute to 192.168.100.10.
862 Fills both the client and server payload with random data. This
863 simulates a G.711 VoIP conversation, one of the most commonly
864 used codecs for VoIP as of this writing.
865 $ irtt client -i 0.1s -d 5s -6 --dscp=46 irtt.example.org
867 Sends requests with IPv6 every 100ms for 5 seconds to irtt.exam‐
868 ple.org. Sets the DSCP value (ToS field) of requests and re‐
869 sponses to 46 (Expedited Forwarding).
870 $ irtt client --hmac=secret -d 10s “[2001:db8:8f::2/32]:64381”
872 Sends requests to the specified IPv6 IP on port 64381 every sec‐
873 ond for 10 seconds. Adds an HMAC to each packet with the key
874 secret.
875
877 irtt(1), irtt-server(1)
878 IRTT GitHub repository (https://github.com/heistp/irtt/)
880v0.9.0 February 11, 2018 IRTT-CLIENT(1)