From 9049dc8d6302a19374d037c99e4122dc7c8a76ad Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Tue, 6 Dec 2022 13:58:02 -0800 Subject: [PATCH] internet-apps: Add Ping documentation --- doc/models/source/index.rst | 1 + doc/models/source/internet-models.rst | 5 +- src/internet-apps/doc/internet-apps.rst | 239 ++++++++++++++++++++++-- 3 files changed, 225 insertions(+), 20 deletions(-) diff --git a/doc/models/source/index.rst b/doc/models/source/index.rst index 0d2904078..a6b6ee6a6 100644 --- a/doc/models/source/index.rst +++ b/doc/models/source/index.rst @@ -32,6 +32,7 @@ This document is written in `reStructuredText n = ...; + Ptr ping = CreateObject (); + // Configure ping as needed... + n->AddApplication (ping); + +Users should be aware of how this application stops. For most |ns3| +applications, ``StopApplication()`` should be called before the simulation +is stopped. If the ``Count`` attribute of this application is set to +a positive integer, the application will stop (and a report will be printed) +either when ``Count`` responses have been received or when ``StopApplication()`` +is called, whichever comes first. If ``Count`` is zero, meaning infinite +pings, then ``StopApplication()`` should be used to eventually stop the +application and generate the report. If ``StopApplication()`` is called +while a packet (echo request) is in-flight, the response cannot be +received and the packet will be treated as lost in the report-- real +ping applications work this way as well. To avoid this, it is recommended +to call ``StopApplication()`` at a time when an Echo Request or Echo Response +packet is not expected to be in flight. + +Helpers +####### + +The ``PingHelper`` supports the typical ``Install`` usage pattern in |ns3|. +The following sample code is from the program ``examples/tcp/tcp-validation.cc``. + +.. sourcecode:: cpp + + PingHelper pingHelper(Ipv4Address("192.168.1.2")); + pingHelper.SetAttribute("Interval", TimeValue(pingInterval)); + pingHelper.SetAttribute("Size", UintegerValue(pingSize)); + pingHelper.SetAttribute("VerboseMode", EnumValue(Ping::VerboseMode::SILENT)); + ApplicationContainer pingContainer = pingHelper.Install(pingServer); + Ptr ping = pingContainer.Get(0)->GetObject(); + ping->TraceConnectWithoutContext("Rtt", MakeBoundCallback(&TracePingRtt, &pingOfStream)); + pingContainer.Start(Seconds(1)); + pingContainer.Stop(stopTime - Seconds(1)); + +The first statement sets the remote address (destination) for all application +instances created with this helper. The second and third statements perform +further configuration. The fourth statement configures the verbosity to +be totally silent. The fifth statement is a typical ``Install()`` +method that returns an ApplicationContainer (in this case, of size 1). +The sixth and seventh statements fetch the application instance created and +configure a trace sink (``TracePingRtt``) for the ``Rtt`` trace source. +The eigth and ninth statements configure the start and stop time, +respectively. + +The helper is most useful when there are many similarly configured +applications to install on a collection of nodes (a NodeContainer). +When there is only one Ping application to configure in a program, +or when the configuration between different instances is different, +it may be more straightforward to directly create the Ping applications +without the PingHelper. + +Attributes +########## + +The following attributes can be configured: + +* ``Destination``: The IPv4 or IPv6 address of the machine we want to ping +* ``VerboseMode``: Configure verbose, quiet, or silent output +* ``Interval``: Time interval between sending each packet +* ``Size``: The number of data bytes to be sent, before ICMP and IP headers are added +* ``Count``: The maximum number of packets the application will send +* ``InterfaceAddress``: Local address of the sender +* ``Timeout``: Time to wait for response if no RTT samples are available + +Output +###### + +If ``VerboseMode`` mode is set to ``VERBOSE``, ping will output the results of +ICMP Echo Reply responses to ``std::cout`` output stream. If the mode is +set to ``QUIET``, only the initial statement and summary are printed. If the +mode is set to ``SILENT``, no output will be printed to ``std::cout``. These +behavioral differences can be seen with the ``ping-example.cc`` as follows: + +.. sourcecode:: bash + + $ ./ns3 run --no-build 'ping-example --ns3::Ping::VerboseMode=Verbose' + $ ./ns3 run --no-build 'ping-example --ns3::Ping::VerboseMode=Quiet' + $ ./ns3 run --no-build 'ping-example --ns3::Ping::VerboseMode=Silent' + +Additional output can be gathered by using the four trace sources provided +by Ping: + +* ``Tx``: This trace executes when a new packet is sent, and returns the sequence number and full packet (including ICMP header). +* ``Rtt``: Each time an ICMP echo reply is received, this trace is called and reports the sequence number and RTT. +* ``Drop``: If an ICMP error is returned instead of an echo reply, the sequence number and reason for reported drop are returned. +* ``Report``: When ping completes and exits, it prints output statistics to the terminal. These values are copied to a ``struct PingReport`` and returned in this trace source. + +Example +####### + +A basic ``ping-example.cc`` program is provided to highlight the following +usage. The topology has three nodes interconnected by two point-to-point links. +Each link has 5 ms one-way delay, for a round-trip propagation delay +of 20 ms. The transmission rate on each link is 100 Mbps. The routing +between links is enabled by ns-3's NixVector routing. + +By default, this program will send 5 pings from node A to node C. +When using the default IPv6, the output will look like this: + +.. sourcecode::txt + + PING 2001:1:0:1:200:ff:fe00:4 - 56 bytes of data; 104 bytes including ICMP and IPv6 headers. + 64 bytes from (2001:1:0:1:200:ff:fe00:4): icmp_seq=0 ttl=63 time=20.033 ms + 64 bytes from (2001:1:0:1:200:ff:fe00:4): icmp_seq=1 ttl=63 time=20.033 ms + 64 bytes from (2001:1:0:1:200:ff:fe00:4): icmp_seq=2 ttl=63 time=20.033 ms + 64 bytes from (2001:1:0:1:200:ff:fe00:4): icmp_seq=3 ttl=63 time=20.033 ms + 64 bytes from (2001:1:0:1:200:ff:fe00:4): icmp_seq=4 ttl=63 time=20.033 ms + --- 2001:1:0:1:200:ff:fe00:4 ping statistics --- + 5 packets transmitted, 5 received, 0% packet loss, time 4020ms + rtt min/avg/max/mdev = 20/20/20/0 ms + +The example program will also produce four pcap traces (one for each +NetDevice in the scenario) that can be viewed using tcpdump or Wireshark. + +Other program options include options to change the destination and +source addresses, number of packets (count), packet size, interval, +and whether to enable logging (if logging is enabled in the build). +These program options will override any corresponding attribute settings. + +Finally, the program has some code that can be enabled to selectively +force packet drops to check such behavior. + +Validation +========== + +The following test cases have been added for regression testing: + +#. Unlimited pings, no losses, StopApplication () with no packets in flight +#. Unlimited pings, no losses, StopApplication () with one packet in flight +#. Test for operation of count attribute and exit time after all pings are received, for IPv4" +#. Test the operation of interval attribute, for IPv4 +#. Test for behavior of pinging an unreachable host when the network does not send an ICMP unreachable message +#. Test pinging to IPv4 broadcast address and IPv6 all nodes multicast address +#. Test behavior of first reply lost in a count-limited configuration +#. Test behavior of second reply lost in a count-limited configuration +#. Test behavior of last reply lost in a count-limited configuration. Radvd ***** @@ -124,3 +325,7 @@ from the DHCP server, and can renew it within a lease time period. Multiple DHCP servers can be configured, but the implementation does not support the use of a DHCP Relay yet. +V4TraceRoute +************ + +Documentation is missing for this application.