Return to mtr-packet.8 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / mtr

mtr ver 0.92

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