{ "content": [ { "type": "text", "text": "# mtr-packet (man)\n\n## NAME\n\nmtr-packet - send and receive network probes\n\n## DESCRIPTION\n\nmtr-packet is a tool for sending network probes to measure network connectivity and perfor‐\nmance. Many network probes can be sent simultaneously by a single process instance of mtr-\npacket and additional probes can be generated by an instance of mtr-packet which already has\nnetwork probes in flight. It is intended to be used by programs which invoke it with Unix\npipes attached to its standard input and output streams.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **REQUESTS** (2 subsections)\n- **REPLIES** (8 subsections)\n- **EXAMPLES**\n- **LANGUAGE BINDINGS**\n- **CONTACT INFORMATION**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "mtr-packet", "section": "", "mode": "man", "summary": "mtr-packet - send and receive network probes", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "A controlling program may start mtr-packet as a child process and issue the following command", "on stdin:", "42 send-probe ip-4 127.0.0.1", "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 127.0.0.1 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 commands, each with a dif‐", "ferent ttl value, are used.", "11 send-probe ip-4 8.8.8.8 ttl 1", "12 send-probe ip-4 8.8.8.8 ttl 2", "13 send-probe ip-4 8.8.8.8 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 192.168.254.254 round-trip-time 1634", "12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609", "13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643", "14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755", "15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695", "17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077", "16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253", "18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080", "19 reply ip-4 8.8.8.8 round-trip-time 17039", "Note that the replies in this example are printed out of order. (The reply to probe 17 ar‐", "rives prior to the reply to probe 16.) This is the reason that it is important to send com‐", "mands with unique token values, and to use those token values to match replies with their", "originating commands." ], "see_also": [ { "name": "mtr", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/mtr/8/json" }, { "name": "icmp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/icmp/7/json" }, { "name": "tcp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/tcp/7/json" }, { "name": "udp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/udp/7/json" }, { "name": "MTR-PACKET", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/MTR-PACKET/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 24, "subsections": [] }, { "name": "REQUESTS", "lines": 1, "subsections": [ { "name": "send-probe", "lines": 119 }, { "name": "check-support", "lines": 17 } ] }, { "name": "REPLIES", "lines": 30, "subsections": [ { "name": "no-reply", "lines": 2 }, { "name": "ttl-expired", "lines": 46 }, { "name": "no-route", "lines": 2 }, { "name": "network-down", "lines": 2 }, { "name": "probes-exhausted", "lines": 3 }, { "name": "permission-denied", "lines": 2 }, { "name": "invalid-argument", "lines": 2 }, { "name": "feature-support", "lines": 17 } ] }, { "name": "EXAMPLES", "lines": 39, "subsections": [] }, { "name": "LANGUAGE BINDINGS", "lines": 3, "subsections": [] }, { "name": "CONTACT INFORMATION", "lines": 5, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "mtr-packet - send and receive network probes\n", "subsections": [] }, "DESCRIPTION": { "content": "mtr-packet is a tool for sending network probes to measure network connectivity and perfor‐\nmance. Many network probes can be sent simultaneously by a single process instance of mtr-\npacket and additional probes can be generated by an instance of mtr-packet which already has\nnetwork probes in flight. It is intended to be used by programs which invoke it with Unix\npipes attached to its standard input and output streams.\n\nmtr-packet reads command requests from stdin, each separated by a newline character, and re‐\nsponds with command replies to stdout, also each separated by a newline character. The syn‐\ntactic structure of requests and replies are the same. The following format is used:\n\nTOKEN COMMAND [ARGUMENT-NAME ARGUMENT-VALUE ...]\n\nTOKEN is a unique integer value. The same value will be used as the TOKEN for the response.\nThis is necessary for associating replies with requests, as commands may be completed in a\ndifferent order than they are requested. The invoker of mtr-packet should always use the TO‐\nKEN value to determine which command request has completed.\n\nCOMMAND is a string identifying the command request type. A common command is send-probe,\nwhich will transmit one network probe.\n\nARGUMENT-NAME strings and ARGUMENT-VALUE strings always come in pairs. It is a syntactic er‐\nror to provide an ARGUMENT-NAME without a corresponding ARGUMENT-VALUE. Valid ARGUMENT-NAME\nstrings depend on the COMMAND being used.\n", "subsections": [] }, "REQUESTS": { "content": "", "subsections": [ { "name": "send-probe", "content": "Send a network probe to a particular IP address. Either an ip-4 or ip-6 argument must\nbe provided. A valid send-probe command will reply with reply, no-reply, or ttl-ex‐‐\npired.\n\nThe following arguments may be used:\n\nip-4 IP-ADDRESS\n\n\n\nThe Internet Protocol version 4 address to probe.\n\n\n\nip-6 IP-ADDRESS\n\n\n\nThe Internet Protocol version 6 address to probe.\n\n\n\nprotocol PROTOCOL\n\n\n\nThe protocol to use for the network probe. icmp, sctp, tcp, and udp may be\nused. The default protocol is icmp.\n\n\n\nport PORT-NUMBER\n\n\n\nThe destination port to use for sctp, tcp, or udp probes.\n\n\n\nlocal-ip-4 IP-ADDRESS\n\n\n\nThe local Internet Protocol version 4 address to use when sending probes.\n\n\n\nlocal-ip-6 IP-ADDRESS\n\n\n\nThe local Internet Protocol version 6 address to use when sending probes.\n\n\n\nlocal-port PORT-NUMBER\n\n\n\nFor udp probes, the local port number from which to send probes.\n\n\n\ntimeout TIMEOUT-SECONDS\n\n\n\nThe number of seconds to wait for a response to the probe before discarding the\nprobe as lost, and generating a no-reply command reply.\n\n\n\nttl TIME-TO-LIVE\n\n\n\nThe time-to-live value for the Internet Protocol packet header used in con‐\nstructing the probe. This value determines the number of network hops through\nwhich the probe will travel before a response is generated by an intermediate\nnetwork host.\n\n\n\nsize PACKET-SIZE\n\n\n\nThe size of the packet used to send the probe, in bytes, including the Internet\nProtocol header and transport protocol header.\n\n\n\nbit-pattern PATTERN-VALUE\n\n\n\nThe packet payload is filled with bytes of the value specified. Valid pattern\nvalues are in the range 0 through 255.\n\n\n\ntos TYPE-OF-SERVICE\n\n\n\nIn the case of IPv4, the \"type of service\" field in the IP header is set to\nthis value. In the case of IPv6, the \"traffic class\" field is set.\n\n\n\nmark ROUTING-MARK\n\n\n\nThe packet mark value to be used by mark-based routing. (Available only on\nLinux.)\n\n\n" }, { "name": "check-support", "content": "Check for support for a particular feature in this version of mtr-packet and in this\nparticular operating environment. check-support will reply with feature-supported. A\nfeature argument is required.\n\n\n\nfeature FEATURE-NAME\n\n\n\nThe name of a feature requested.\n\n\n\nSome features which can be checked are send-probe, ip-4, ip-6, icmp, sctp, tcp, udp,\nand mark. The feature version can be checked to retrieve the version of mtr-packet.\n" } ] }, "REPLIES": { "content": "reply The destination host received the send-probe probe and replied. Arguments of reply\nare:\n\n\n\nip-4 IP-ADDRESS\n\n\n\nThe Internet Protocol version 4 address of the host which replied to the probe.\n\n\n\nip-6 IP-ADDRESS\n\n\n\nThe Internet Protocol version 6 address of the host which replied to the probe.\n\n\n\nround-trip-time TIME\n\n\n\nThe time which passed between the transmission of the probe and its response.\nThe time is provided as a integral number of microseconds elapsed.\n\n\n", "subsections": [ { "name": "no-reply", "content": "No response to the probe request was received before the timeout expired.\n" }, { "name": "ttl-expired", "content": "The time-to-live value of the transmitted probe expired before the probe arrived at\nits intended destination. Arguments of ttl-expired are:\n\n\n\nip-4 IP-ADDRESS\n\n\n\nThe Internet Protocol version 4 address of the host at which the time-to-live\nvalue expired.\n\n\n\nip-6 IP-ADDRESS\n\n\n\nThe Internet Protocol version 6 address of the host at which the time-to-live\nvalue expired.\n\n\n\nround-trip-time TIME\n\n\n\nThe time which passed between the transmission of the probe and its response.\nThe time is provided as a integral number of microseconds elapsed.\n\n\n\nmpls MPLS-LABEL-LIST\n\n\n\nA list of Multiprotocol Label Switching values returned with the probe re‐\nsponse. If the mpls argument is present, one or more MPLS labels will be rep‐\nresented by a comma separated list of values. The values are provided in\ngroups of four. The first four values in the list correspond to the first MPLS\nlabel, the next four values correspond to the second MPLS label, and so on.\nThe values are provided in this order: label, traffic-class, bottom-of-stack,\nttl.\n\n\n" }, { "name": "no-route", "content": "There was no route to the host used in a send-probe request.\n" }, { "name": "network-down", "content": "A probe could not be sent because the network is down.\n" }, { "name": "probes-exhausted", "content": "A probe could not be sent because there are already too many unresolved probes in\nflight.\n" }, { "name": "permission-denied", "content": "The operating system denied permission to send the probe with the specified options.\n" }, { "name": "invalid-argument", "content": "The command request contained arguments which are invalid.\n" }, { "name": "feature-support", "content": "A reply to provided to check-support indicating the availability of a particular fea‐\nture. The argument provided is:\n\n\n\nsupport PRESENT\n\n\n\nIn most cases, the PRESENT value will be either ok, indicating the feature is\nsupported, or no, indicating no support for the feature.\n\nIn the case that version is the requested FEATURE-NAME, the version of mtr-\npacket is provided as the PRESENT value.\n\n\n" } ] }, "EXAMPLES": { "content": "A controlling program may start mtr-packet as a child process and issue the following command\non stdin:\n\n42 send-probe ip-4 127.0.0.1\n\nThis will send a network probe to the loopback interface. When the probe completes, mtr-\npacket will provide a response on stdout such as the following:\n\n42 reply ip-4 127.0.0.1 round-trip-time 126\n\nThis indicates that the loopback address replied to the probe, and the round-trip time of the\nprobe was 126 microseconds.\n\nIn order to trace the route to a remote host, multiple send-probe commands, each with a dif‐\nferent ttl value, are used.\n\n11 send-probe ip-4 8.8.8.8 ttl 1\n12 send-probe ip-4 8.8.8.8 ttl 2\n13 send-probe ip-4 8.8.8.8 ttl 3\n...\n\nEach intermediate host would respond with a ttl-expired message, and the destination host\nwould respond with a reply:\n\n11 ttl-expired ip-4 192.168.254.254 round-trip-time 1634\n12 ttl-expired ip-4 184.19.243.240 round-trip-time 7609\n13 ttl-expired ip-4 172.76.20.169 round-trip-time 8643\n14 ttl-expired ip-4 74.40.1.101 round-trip-time 9755\n15 ttl-expired ip-4 74.40.5.126 round-trip-time 10695\n17 ttl-expired ip-4 108.170.245.97 round-trip-time 14077\n16 ttl-expired ip-4 74.40.26.131 round-trip-time 15253\n18 ttl-expired ip-4 209.85.245.101 round-trip-time 17080\n19 reply ip-4 8.8.8.8 round-trip-time 17039\n\nNote that the replies in this example are printed out of order. (The reply to probe 17 ar‐\nrives prior to the reply to probe 16.) This is the reason that it is important to send com‐\nmands with unique token values, and to use those token values to match replies with their\noriginating commands.\n", "subsections": [] }, "LANGUAGE BINDINGS": { "content": "A Python 3.x package for sending asynchronous network probes using mtr-packet is available.\nSee ⟨https://pypi.org/project/mtrpacket/⟩\n", "subsections": [] }, "CONTACT INFORMATION": { "content": "For the latest version, see the mtr web page at ⟨http://www.bitwizard.nl/mtr/⟩\n\nFor patches, bug reports, or feature requests, please open an issue on GitHub at: ⟨https://\ngithub.com/traviscross/mtr⟩.\n", "subsections": [] }, "SEE ALSO": { "content": "mtr(8), icmp(7), tcp(7), udp(7), TCP/IP Illustrated (Stevens, ISBN 0201633469).\n\n\n\nmtr-packet 0.95 MTR-PACKET(8)", "subsections": [] } } } }