Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MTR-PACKET(8)		     System Administration		 MTR-PACKET(8)

       mtr-packet - send and receive network probes

       mtr-packet is a tool for	sending	network	probes to measure network con-
       nectivity and performance.  Many	network	probes can be sent  simultane-
       ously  by a single process instance of mtr-packet and additional	probes
       can be generated	by an instance of mtr-packet which already has network
       probes  in  flight.  It is intended to be used by programs which	invoke
       it with Unix pipes attached to its standard input and output streams.

       mtr-packet reads	command	requests from stdin, each separated by a  new-
       line  character,	and responds with command replies to stdout, also each
       separated by a newline character.  The syntactic	structure of  requests
       and replies are the same.  The following	format is used:


       TOKEN  is  a  unique integer value.  The	same value will	be used	as the
       TOKEN for the response.	This is	necessary for associating replies with
       requests,  as  commands may be completed	in a different order than they
       are requested.  The invoker of mtr-packet should	always use  the	 TOKEN
       value to	determine which	command	request	has completed.

       COMMAND	is  a  string  identifying the command request type.  A	common
       command is send-probe, which will transmit one network probe.

       ARGUMENT-NAME strings and ARGUMENT-VALUE	strings	always come in	pairs.
       It  is  a  syntactic error to provide an	ARGUMENT-NAME without a	corre-
       sponding	ARGUMENT-VALUE.	 Valid ARGUMENT-NAME  strings  depend  on  the
       COMMAND being used.

	      Send a network probe to a	particular IP address.	Either an ip-4
	      or ip-6 argument must be provided.  A valid  send-probe  command
	      will reply with reply, no-reply, or ttl-expired.

	      The following arguments may be used:

	      ip-4 IP-ADDRESS

		     The Internet Protocol version 4 address to	probe.

	      ip-6 IP-ADDRESS

		     The Internet Protocol version 6 address to	probe.

	      protocol PROTOCOL

		     The  protocol  to use for the network probe.  icmp, sctp,
		     tcp, and udp may be used.	The default protocol is	icmp.

	      port PORT-NUMBER

		     The destination port to use for sctp, tcp,	or udp probes.

	      local-ip-4 IP-ADDRESS

		     The local Internet	Protocol version 4 address to use when
		     sending probes.

	      local-ip-6 IP-ADDRESS

		     The local Internet	Protocol version 6 address to use when
		     sending probes.

	      local-port PORT-NUMBER

		     For udp probes, the local port number from	which to  send

	      timeout TIMEOUT-SECONDS

		     The number	of seconds to wait for a response to the probe
		     before discarding the probe as lost, and generating a no-
		     reply command reply.

	      ttl TIME-TO-LIVE

		     The  time-to-live	value for the Internet Protocol	packet
		     header used in constructing the probe.  This value	deter-
		     mines  the	number of network hops through which the probe
		     will travel before	a response is generated	by an interme-
		     diate network host.

	      size PACKET-SIZE

		     The  size of the packet used to send the probe, in	bytes,
		     including the Internet Protocol header and	transport pro-
		     tocol header.

	      bit-pattern PATTERN-VALUE

		     The  packet  payload  is  filled  with bytes of the value
		     specified.	 Valid pattern	values	are  in	 the  range  0
		     through 255.

	      tos TYPE-OF-SERVICE

		     In	 the  case of IPv4, the	"type of service" field	in the
		     IP	header is set to this value.  In the case of IPv6, the
		     "traffic class" field is set.

	      mark ROUTING-MARK

		     The  packet  mark value to	be used	by mark-based routing.
		     (Available	only on	Linux.)

	      Check for	support	for a particular feature in  this  version  of
	      mtr-packet and in	this particular	operating environment.	check-
	      support will reply with feature-supported.  A  feature  argument
	      is required.

	      feature FEATURE-NAME

		     The name of a feature requested.

	      Some  features  which can	be checked are send-probe, ip-4, ip-6,
	      icmp, sctp, tcp, udp, and	mark.	The  feature  version  can  be
	      checked to retrieve the version of mtr-packet.

       reply  The  destination host received the send-probe probe and replied.
	      Arguments	of reply are:

	      ip-4 IP-ADDRESS

		     The Internet Protocol version 4 address of	the host which
		     replied to	the probe.

	      ip-6 IP-ADDRESS

		     The Internet Protocol version 6 address of	the host which
		     replied to	the probe.

	      round-trip-time TIME

		     The time which passed between  the	 transmission  of  the
		     probe  and	its response.  The time	is provided as a inte-
		     gral number of microseconds elapsed.

	      No response to the probe request was received before the timeout

	      The  time-to-live	 value of the transmitted probe	expired	before
	      the probe	arrived	at its	intended  destination.	 Arguments  of
	      ttl-expired are:

	      ip-4 IP-ADDRESS

		     The  Internet  Protocol  version 4	address	of the host at
		     which the time-to-live value expired.

	      ip-6 IP-ADDRESS

		     The Internet Protocol version 6 address of	 the  host  at
		     which the time-to-live value expired.

	      round-trip-time TIME

		     The  time	which  passed  between the transmission	of the
		     probe and its response.  The time is provided as a	 inte-
		     gral number of microseconds elapsed.

	      mpls MPLS-LABEL-LIST

		     A	list  of Multiprotocol Label Switching values returned
		     with  the	probe  response.   If  the  mpls  argument  is
		     present, one or more MPLS labels will be represented by a
		     comma separated list of values.  The values are  provided
		     in	 groups	 of  four.   The first four values in the list
		     correspond	to the first MPLS label, the next four	values
		     correspond	to the second MPLS label, and so on.  The val-
		     ues are provided in  this	order:	label,	traffic-class,
		     bottom-of-stack, ttl.

	      There was	no route to the	host used in a send-probe request.

	      A	probe could not	be sent	because	the network is down.

	      A	probe could not	be sent	because	there are already too many un-
	      resolved probes in flight.

	      The operating system denied permission to	send  the  probe  with
	      the specified options.

	      The command request contained arguments which are	invalid.

	      A	reply to provided to check-support indicating the availability
	      of a particular feature.	The argument provided is:

	      support PRESENT

		     In	most cases, the	PRESENT	value will be either ok, indi-
		     cating  the  feature  is  supported, or no, indicating no
		     support for the feature.

		     In	the case that version is the  requested	 FEATURE-NAME,
		     the  version  of  mtr-packet  is  provided	as the PRESENT

       A controlling program may start mtr-packet as a child process and issue
       the following command on	stdin:

	      42 send-probe ip-4

       This  will  send	 a  network probe to the loopback interface.  When the
       probe completes,	mtr-packet will	provide	a response on stdout  such  as
       the following:

	      42 reply ip-4 round-trip-time 126

       This  indicates that the	loopback address replied to the	probe, and the
       round-trip time of the probe was	126 microseconds.

       In order	to trace the route to a	remote host, multiple send-probe  com-
       mands, each with	a different ttl	value, are used.

	      11 send-probe ip-4 ttl 1
	      12 send-probe ip-4 ttl 2
	      13 send-probe ip-4 ttl 3

       Each  intermediate  host	 would respond with a ttl-expired message, and
       the destination host would respond with a reply:

	      11 ttl-expired ip-4 round-trip-time 1634
	      12 ttl-expired ip-4 round-trip-time 7609
	      13 ttl-expired ip-4	round-trip-time	8643
	      14 ttl-expired ip-4 round-trip-time 9755
	      15 ttl-expired ip-4 round-trip-time 10695
	      17 ttl-expired ip-4 round-trip-time 14077
	      16 ttl-expired ip-4 round-trip-time 15253
	      18 ttl-expired ip-4 round-trip-time 17080
	      19 reply ip-4 round-trip-time 17039

       Note that the replies in	this example are printed out of	 order.	  (The
       reply to	probe 17 arrives prior to the reply to probe 16.)  This	is the
       reason that it is important to send commands with unique	token  values,
       and  to	use those token	values to match	replies	with their originating

       A Python	3.x package for	sending	asynchronous network probes using mtr-
       packet is available.  See <>

       For  the	latest version,	see the	mtr web	page at	<http://www.bitwizard.

       For patches, bug	reports, or feature requests, please open an issue  on
       GitHub at: <>.

       mtr(8),	icmp(7),  tcp(7),  udp(7),  TCP/IP  Illustrated	(Stevens, ISBN

mtr-packet			     0.94			 MTR-PACKET(8)


Want to link to this manual page? Use this URL:

home | help