.TH MTR-PACKET 8 "@VERSION@" "mtr-packet" "System Administration"

.HP 7

.SH NAME

mtr-packet - send and receive network probes

.SH DESCRIPTION

.B mtr-packet

is a tool for sending network probes to measure network connectivity and

performance.  Many network probes can be sent simultaneously by a single

process instance of

.B mtr-packet

and additional probes can be generated by an instance of

.B 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.

.LP

.B mtr-packet

reads command requests from

.IR stdin ,

each separated by a newline character, and responds with command replies to

.IR stdout ,

also each separated by a newline character.  The syntactic structure of

requests and replies are the same.  The following format is used:

.LP

.RS

.I TOKEN

.I COMMAND

[\c

.I ARGUMENT-NAME

.I ARGUMENT-VALUE

\&...]

.RE

.LP

.I TOKEN

is a unique integer value.  The same value will be used as the

.I 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

.B mtr-packet

should always use the

.I TOKEN

value to determine which command request has completed.

.LP

.I COMMAND

is a string identifying the command request type.  A common command is

.BR send-probe ,

which will transmit one network probe.

.LP

.I ARGUMENT-NAME

strings and

.I ARGUMENT-VALUE

strings always come in pairs.  It is a syntactic error to provide an

.I ARGUMENT-NAME

without a corresponding

.IR ARGUMENT-VALUE .

Valid

.I ARGUMENT-NAME

strings depend on the

.I COMMAND

being used.

.SH REQUESTS

.TP

.B send-probe

Send a network probe to a particular IP address.  Either an

.B ip-4

or

.B ip-6

argument must be provided.

A valid

.B send-probe

command will reply with

.BR reply ,

.BR no-reply ,

or

.BR ttl-expired .

.IP

The following arguments may be used:

.IP

.B ip-4

.I IP-ADDRESS

.HP 14

.IP

The Internet Protocol version 4 address to probe.

.HP 7

.IP

.B ip-6

.I IP-ADDRESS

.HP 14

.IP

The Internet Protocol version 6 address to probe.

.HP 7

.IP

.B protocol

.I PROTOCOL

.HP 14

.IP

The protocol to use for the network probe.

.BR icmp ,

.BR sctp ,

.BR tcp ,

and

.B udp

may be used.  The default protocol is

.BR icmp.

.HP 7

.IP

.B port

.I PORT-NUMBER

.HP 14

.IP

The destination port to use for

.BR sctp ,

.BR tcp ,

or

.B udp

probes.

.HP 7

.IP

.B local-ip-4

.I IP-ADDRESS

.HP 14

.IP

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

.HP 7

.IP

.B local-ip-6

.I IP-ADDRESS

.HP 14

.IP

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

.HP 7

.IP

.B local-port

.I PORT-NUMBER

.HP 14

.IP

For

.B udp

probes, the local port number from which to send probes.

.HP 7

.IP

.B timeout

.I TIMEOUT-SECONDS

.HP 14

.IP

The number of seconds to wait for a response to the probe before discarding

the probe as lost, and generating a

.B no-reply

command reply.

.HP 7

.IP

.B ttl

.I TIME-TO-LIVE

.HP 14

.IP

The time-to-live value for the Internet Protocol packet header used in

constructing the probe.  This value determines the number of network hops

through which the probe will travel before a response is generated by an

intermediate network host.

.HP 7

.IP

.B size

.I PACKET-SIZE

.HP 14

.IP

The size of the packet used to send the probe, in bytes, including the

Internet Protocol header and transport protocol header.

.HP 7

.IP

.B bit-pattern

.I PATTERN-VALUE

.HP 14

.IP

The packet payload is filled with bytes of the value specified.

Valid pattern values are in the range 0 through 255.

.HP 7

.IP

.IP

.B tos

.I TYPE-OF-SERVICE

.HP 14

.IP

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.

.HP 7

.IP

.B mark

.I ROUTING-MARK

.HP 14

.IP

The packet mark value to be used by mark-based routing.

(Available only on Linux.)

.HP 7

.TP

.B check-support

Check for support for a particular feature in this version of

.B mtr-packet

and in this particular operating environment.

.B check-support

will reply with

.BR feature-supported .

A

.B feature

argument is required.

.HP 7

.IP

.B feature

.I FEATURE-NAME

.HP 14

.IP

The name of a feature requested.

.HP 7

.IP

Some features which can be checked are

.BR send-probe ,

.BR ip-4 ,

.BR ip-6 ,

.BR icmp ,

.BR sctp ,

.BR tcp ,

.BR udp ,

and

.BR mark .

The feature

.B version

can be checked to retrieve the version of

.BR mtr-packet .

.SH REPLIES

.TP

.B reply

The destination host received the

.B send-probe

probe and replied.  Arguments of

.B reply

are:

.HP 7

.IP

.B ip-4

.I IP-ADDRESS

.HP 14

.IP

The Internet Protocol version 4 address of the host which replied

to the probe.

.HP 7

.IP

.B ip-6

.I IP-ADDRESS

.HP 14

.IP

The Internet Protocol version 6 address of the host which replied

to the probe.

.HP 7

.IP

.B round-trip-time

.I TIME

.HP 14

.IP

The time which passed between the transmission of the probe and its

response.  The time is provided as a integral number of microseconds

elapsed.

.HP 7

.TP

.B no-reply

No response to the probe request was received before the timeout

expired.

.TP

.B ttl-expired

The time-to-live value of the transmitted probe expired before the probe

arrived at its intended destination.  Arguments of

.B ttl-expired

are:

.HP 7

.IP

.B ip-4

.I IP-ADDRESS

.HP 14

.IP

The Internet Protocol version 4 address of the host at which the

time-to-live value expired.

.HP 7

.IP

.B ip-6

.I IP-ADDRESS

.HP 14

.IP

The Internet Protocol version 6 address of the host at which the

time-to-live value expired.

.HP 7

.IP

.B round-trip-time

.I TIME

.HP 14

.IP

The time which passed between the transmission of the probe and its

response.  The time is provided as a integral number of microseconds

elapsed.

.HP 7

.IP

.B mpls

.I MPLS-LABEL-LIST

.HP 14

.IP

A list of Multiprotocol Label Switching values returned

with the probe response.

If the

.B 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 values are provided in this order:

.IR label ,

.IR experimental-use ,

.IR bottom-of-stack ,

.IR ttl .

.HP 7

.TP

.B no-route

There was no route to the host used in a

.B send-probe

request.

.TP

.B network-down

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

.TP

.B probes-exhausted

A probe could not be sent because there are already too many unresolved

probes in flight.

.TP

.B permission-denied

The operating system denied permission to send the probe with the

specified options.

.TP

.B invalid-argument

The command request contained arguments which are invalid.

.TP

.B feature-support

A reply to provided to

.B check-support

indicating the availability of a particular feature.  The argument provided

is:

.HP 7

.IP

.B support

.I PRESENT

.HP 14

.IP

In most cases, the

.I PRESENT

value will be either

.BR ok ,

indicating the feature is supported, or

.BR no ,

indicating no support for the feature.

.IP

In the case that

.B version

is the requested

.IR FEATURE-NAME ,

the version of

.B mtr-packet

is provided as the

.I PRESENT

value.

.HP 7

.IP

.SH EXAMPLES

A controlling program may start

.B mtr-packet

as a child process and issue the following command on

.IR stdin :

.LP

.RS

42 send-probe ip-4 127.0.0.1

.RE

.LP

This will send a network probe to the loopback interface.  When the probe

completes,

.B

mtr-packet

will provide a response on

.I stdout

such as the following:

.LP

.RS

42 reply ip-4 127.0.0.1 round-trip-time 126

.RE

.LP

This indicates that the loopback address replied to the probe, and the

round-trip time of the probe was 126 microseconds.

.LP

In order to trace the route to a remote host, multiple

.B send-probe

commands, each with a different

.B ttl

value, are used.

.LP

.RS

11 send-probe ip-4 8.8.8.8 ttl 1

.RS 0

12 send-probe ip-4 8.8.8.8 ttl 2

.RS 0

13 send-probe ip-4 8.8.8.8 ttl 3

.RS 0

\&...

.RE 0

.LP

Each interemediate host would respond with a

.B ttl-expired

message, and the destination host would respond with a

.BR reply :

.LP

.RS

11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634

.RS 0

12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609

.RS 0

13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643

.RS 0

14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755

.RS 0

15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695

.RS 0

17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077

.RS 0

16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253

.RS 0

18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080

.RS 0

19 reply ip-4 8.8.8.8 round-trip-time 17039

.RE 0

.LP

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 commands.

.SH CONTACT INFORMATION

.PP

For the latest version, see the mtr web page at

.UR http://\:www.\:bitwizard.\:nl/\:mtr/

.UE

.PP

For patches, bug reports, or feature requests, please open an issue on

GitHub at:

.UR https://\:github\:.com/\:traviscross/\:mtr

.UE .

.SH "SEE ALSO"

.BR mtr (8),

.BR icmp (7),

.BR tcp (7),

.BR udp (7),

TCP/IP Illustrated (Stevens, ISBN 0201633469).