Annotation of embedaddon/mtr/mtr-packet.8, revision 1.1
1.1 ! misho 1: .TH MTR-PACKET 8 "0.87.203-0e5e" "mtr-packet" "System Administration"
! 2: .HP 7
! 3: .SH NAME
! 4: mtr-packet - send and receive network probes
! 5: .SH DESCRIPTION
! 6: .B mtr-packet
! 7: is a tool for sending network probes to measure network connectivity and
! 8: performance. Many network probes can be sent simultaneously by a single
! 9: process instance of
! 10: .B mtr-packet
! 11: and additional probes can be generated by an instance of
! 12: .B mtr-packet
! 13: which already has network probes in flight. It is intended to be used
! 14: by programs which invoke it with Unix pipes attached to its standard input
! 15: and output streams.
! 16: .LP
! 17: .B mtr-packet
! 18: reads command requests from
! 19: .IR stdin ,
! 20: each separated by a newline character, and responds with command replies to
! 21: .IR stdout ,
! 22: also each separated by a newline character. The syntactic structure of
! 23: requests and replies are the same. The following format is used:
! 24: .LP
! 25: .RS
! 26: .I TOKEN
! 27: .I COMMAND
! 28: [\c
! 29: .I ARGUMENT-NAME
! 30: .I ARGUMENT-VALUE
! 31: \&...]
! 32: .RE
! 33: .LP
! 34: .I TOKEN
! 35: is a unique integer value. The same value will be used as the
! 36: .I TOKEN
! 37: for the response. This is necessary for associating replies with requests,
! 38: as commands may be completed in a different order than they are requested.
! 39: The invoker of
! 40: .B mtr-packet
! 41: should always use the
! 42: .I TOKEN
! 43: value to determine which command request has completed.
! 44: .LP
! 45: .I COMMAND
! 46: is a string identifying the command request type. A common command is
! 47: .BR send-probe ,
! 48: which will transmit one network probe.
! 49: .LP
! 50: .I ARGUMENT-NAME
! 51: strings and
! 52: .I ARGUMENT-VALUE
! 53: strings always come in pairs. It is a syntactic error to provide an
! 54: .I ARGUMENT-NAME
! 55: without a corresponding
! 56: .IR ARGUMENT-VALUE .
! 57: Valid
! 58: .I ARGUMENT-NAME
! 59: strings depend on the
! 60: .I COMMAND
! 61: being used.
! 62: .SH REQUESTS
! 63: .TP
! 64: .B send-probe
! 65: Send a network probe to a particular IP address. Either an
! 66: .B ip-4
! 67: or
! 68: .B ip-6
! 69: argument must be provided.
! 70: A valid
! 71: .B send-probe
! 72: command will reply with
! 73: .BR reply ,
! 74: .BR no-reply ,
! 75: or
! 76: .BR ttl-expired .
! 77: .IP
! 78: The following arguments may be used:
! 79: .IP
! 80: .B ip-4
! 81: .I IP-ADDRESS
! 82: .HP 14
! 83: .IP
! 84: The Internet Protocol version 4 address to probe.
! 85: .HP 7
! 86: .IP
! 87: .B ip-6
! 88: .I IP-ADDRESS
! 89: .HP 14
! 90: .IP
! 91: The Internet Protocol version 6 address to probe.
! 92: .HP 7
! 93: .IP
! 94: .B protocol
! 95: .I PROTOCOL
! 96: .HP 14
! 97: .IP
! 98: The protocol to use for the network probe.
! 99: .BR icmp ,
! 100: .BR sctp ,
! 101: .BR tcp ,
! 102: and
! 103: .B udp
! 104: may be used. The default protocol is
! 105: .BR icmp.
! 106: .HP 7
! 107: .IP
! 108: .B port
! 109: .I PORT-NUMBER
! 110: .HP 14
! 111: .IP
! 112: The destination port to use for
! 113: .BR sctp ,
! 114: .BR tcp ,
! 115: or
! 116: .B udp
! 117: probes.
! 118: .HP 7
! 119: .IP
! 120: .B local-ip-4
! 121: .I IP-ADDRESS
! 122: .HP 14
! 123: .IP
! 124: The local Internet Procol version 4 address to use when sending probes.
! 125: .HP 7
! 126: .IP
! 127: .B local-ip-6
! 128: .I IP-ADDRESS
! 129: .HP 14
! 130: .IP
! 131: The local Internet Protocol version 6 address to use when sending probes.
! 132: .HP 7
! 133: .IP
! 134: .B local-port
! 135: .I PORT-NUMBER
! 136: .HP 14
! 137: .IP
! 138: For
! 139: .B udp
! 140: probes, the local port number from which to send probes.
! 141: .HP 7
! 142: .IP
! 143: .B timeout
! 144: .I TIMEOUT-SECONDS
! 145: .HP 14
! 146: .IP
! 147: The number of seconds to wait for a response to the probe before discarding
! 148: the probe as lost, and generating a
! 149: .B no-reply
! 150: command reply.
! 151: .HP 7
! 152: .IP
! 153: .B ttl
! 154: .I TIME-TO-LIVE
! 155: .HP 14
! 156: .IP
! 157: The time-to-live value for the Internet Protocol packet header used in
! 158: constructing the probe. This value determines the number of network hops
! 159: through which the probe will travel before a response is generated by an
! 160: intermediate network host.
! 161: .HP 7
! 162: .IP
! 163: .B size
! 164: .I PACKET-SIZE
! 165: .HP 14
! 166: .IP
! 167: The size of the packet used to send the probe, in bytes, including the
! 168: Internet Protocol header and transport protocol header.
! 169: .HP 7
! 170: .IP
! 171: .B bit-pattern
! 172: .I PATTERN-VALUE
! 173: .HP 14
! 174: .IP
! 175: The packet payload is filled with bytes of the value specified.
! 176: Valid pattern values are in the range 0 through 255.
! 177: .HP 7
! 178: .IP
! 179: .IP
! 180: .B tos
! 181: .I TYPE-OF-SERVICE
! 182: .HP 14
! 183: .IP
! 184: In the case of IPv4, the "type of service" field in the IP header
! 185: is set to this value. In the case of IPv6, the "traffic class"
! 186: field is set.
! 187: .HP 7
! 188: .IP
! 189: .B mark
! 190: .I ROUTING-MARK
! 191: .HP 14
! 192: .IP
! 193: The packet mark value to be used by mark-based routing.
! 194: (Available only on Linux.)
! 195: .HP 7
! 196: .TP
! 197: .B check-support
! 198: Check for support for a particular feature in this version of
! 199: .B mtr-packet
! 200: and in this particular operating environment.
! 201: .B check-support
! 202: will reply with
! 203: .BR feature-supported .
! 204: A
! 205: .B feature
! 206: argument is required.
! 207: .HP 7
! 208: .IP
! 209: .B feature
! 210: .I FEATURE-NAME
! 211: .HP 14
! 212: .IP
! 213: The name of a feature requested.
! 214: .HP 7
! 215: .IP
! 216: Some features which can be checked are
! 217: .BR send-probe ,
! 218: .BR ip-4 ,
! 219: .BR ip-6 ,
! 220: .BR icmp ,
! 221: .BR sctp ,
! 222: .BR tcp ,
! 223: .BR udp ,
! 224: and
! 225: .BR mark .
! 226: The feature
! 227: .B version
! 228: can be checked to retrieve the version of
! 229: .BR mtr-packet .
! 230: .SH REPLIES
! 231: .TP
! 232: .B reply
! 233: The destination host received the
! 234: .B send-probe
! 235: probe and replied. Arguments of
! 236: .B reply
! 237: are:
! 238: .HP 7
! 239: .IP
! 240: .B ip-4
! 241: .I IP-ADDRESS
! 242: .HP 14
! 243: .IP
! 244: The Internet Protocol version 4 address of the host which replied
! 245: to the probe.
! 246: .HP 7
! 247: .IP
! 248: .B ip-6
! 249: .I IP-ADDRESS
! 250: .HP 14
! 251: .IP
! 252: The Internet Protocol version 6 address of the host which replied
! 253: to the probe.
! 254: .HP 7
! 255: .IP
! 256: .B round-trip-time
! 257: .I TIME
! 258: .HP 14
! 259: .IP
! 260: The time which passed between the transmission of the probe and its
! 261: response. The time is provided as a integral number of microseconds
! 262: elapsed.
! 263: .HP 7
! 264: .TP
! 265: .B no-reply
! 266: No response to the probe request was received before the timeout
! 267: expired.
! 268: .TP
! 269: .B ttl-expired
! 270: The time-to-live value of the transmitted probe expired before the probe
! 271: arrived at its intended destination. Arguments of
! 272: .B ttl-expired
! 273: are:
! 274: .HP 7
! 275: .IP
! 276: .B ip-4
! 277: .I IP-ADDRESS
! 278: .HP 14
! 279: .IP
! 280: The Internet Protocol version 4 address of the host at which the
! 281: time-to-live value expired.
! 282: .HP 7
! 283: .IP
! 284: .B ip-6
! 285: .I IP-ADDRESS
! 286: .HP 14
! 287: .IP
! 288: The Internet Protocol version 6 address of the host at which the
! 289: time-to-live value expired.
! 290: .HP 7
! 291: .IP
! 292: .B round-trip-time
! 293: .I TIME
! 294: .HP 14
! 295: .IP
! 296: The time which passed between the transmission of the probe and its
! 297: response. The time is provided as a integral number of microseconds
! 298: elapsed.
! 299: .HP 7
! 300: .IP
! 301: .B mpls
! 302: .I MPLS-LABEL-LIST
! 303: .HP 14
! 304: .IP
! 305: A list of Multiprotocol Label Switching values returned
! 306: with the probe response.
! 307: If the
! 308: .B mpls
! 309: argument is present, one or more MPLS labels will be represented by
! 310: a comma separated list of values. The values are provided in groups
! 311: of four. The first four values in the list correspond to the
! 312: first MPLS label, the next four values correspond to the second MPLS
! 313: label, and so on. The values are provided in this order:
! 314: .IR label ,
! 315: .IR experimental-use ,
! 316: .IR bottom-of-stack ,
! 317: .IR ttl .
! 318: .HP 7
! 319: .TP
! 320: .B no-route
! 321: There was no route to the host used in a
! 322: .B send-probe
! 323: request.
! 324: .TP
! 325: .B network-down
! 326: A probe could not be sent because the network is down.
! 327: .TP
! 328: .B probes-exhausted
! 329: A probe could not be sent because there are already too many unresolved
! 330: probes in flight.
! 331: .TP
! 332: .B permission-denied
! 333: The operating system denied permission to send the probe with the
! 334: specified options.
! 335: .TP
! 336: .B invalid-argument
! 337: The command request contained arguments which are invalid.
! 338: .TP
! 339: .B feature-support
! 340: A reply to provided to
! 341: .B check-support
! 342: indicating the availability of a particular feature. The argument provided
! 343: is:
! 344: .HP 7
! 345: .IP
! 346: .B support
! 347: .I PRESENT
! 348: .HP 14
! 349: .IP
! 350: In most cases, the
! 351: .I PRESENT
! 352: value will be either
! 353: .BR ok ,
! 354: indicating the feature is supported, or
! 355: .BR no ,
! 356: indicating no support for the feature.
! 357: .IP
! 358: In the case that
! 359: .B version
! 360: is the requested
! 361: .IR FEATURE-NAME ,
! 362: the version of
! 363: .B mtr-packet
! 364: is provided as the
! 365: .I PRESENT
! 366: value.
! 367: .HP 7
! 368: .IP
! 369: .SH EXAMPLES
! 370: A controlling program may start
! 371: .B mtr-packet
! 372: as a child process and issue the following command on
! 373: .IR stdin :
! 374: .LP
! 375: .RS
! 376: 42 send-probe ip-4 127.0.0.1
! 377: .RE
! 378: .LP
! 379: This will send a network probe to the loopback interface. When the probe
! 380: completes,
! 381: .B
! 382: mtr-packet
! 383: will provide a response on
! 384: .I stdout
! 385: such as the following:
! 386: .LP
! 387: .RS
! 388: 42 reply ip-4 127.0.0.1 round-trip-time 126
! 389: .RE
! 390: .LP
! 391: This indicates that the loopback address replied to the probe, and the
! 392: round-trip time of the probe was 126 microseconds.
! 393: .LP
! 394: In order to trace the route to a remote host, multiple
! 395: .B send-probe
! 396: commands, each with a different
! 397: .B ttl
! 398: value, are used.
! 399: .LP
! 400: .RS
! 401: 11 send-probe ip-4 8.8.8.8 ttl 1
! 402: .RS 0
! 403: 12 send-probe ip-4 8.8.8.8 ttl 2
! 404: .RS 0
! 405: 13 send-probe ip-4 8.8.8.8 ttl 3
! 406: .RS 0
! 407: \&...
! 408: .RE 0
! 409: .LP
! 410: Each interemediate host would respond with a
! 411: .B ttl-expired
! 412: message, and the destination host would respond with a
! 413: .BR reply :
! 414: .LP
! 415: .RS
! 416: 11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634
! 417: .RS 0
! 418: 12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609
! 419: .RS 0
! 420: 13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643
! 421: .RS 0
! 422: 14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755
! 423: .RS 0
! 424: 15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695
! 425: .RS 0
! 426: 17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077
! 427: .RS 0
! 428: 16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253
! 429: .RS 0
! 430: 18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080
! 431: .RS 0
! 432: 19 reply ip-4 8.8.8.8 round-trip-time 17039
! 433: .RE 0
! 434: .LP
! 435: Note that the replies in this example are printed out of order.
! 436: (The reply to probe 17 arrives prior to the reply to probe 16.)
! 437: This is the reason that it is important to send commands with unique
! 438: token values, and to use those token values to match replies with
! 439: their originating commands.
! 440: .SH CONTACT INFORMATION
! 441: .PP
! 442: For the latest version, see the mtr web page at
! 443: .UR http://\:www.\:bitwizard.\:nl/\:mtr/
! 444: .UE
! 445: .PP
! 446: For patches, bug reports, or feature requests, please open an issue on
! 447: GitHub at:
! 448: .UR https://\:github\:.com/\:traviscross/\:mtr
! 449: .UE .
! 450: .SH "SEE ALSO"
! 451: .BR mtr (8),
! 452: .BR icmp (7),
! 453: .BR tcp (7),
! 454: .BR udp (7),
! 455: TCP/IP Illustrated (Stevens, ISBN 0201633469).
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to mtr-packet.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / mtr