internet-apps: Add Ping documentation
This commit is contained in:
Tom Henderson
committed by
Tommaso Pecorella
Tommaso Pecorella
parent
da7bc9980f
commit
9049dc8d63
@@ -32,6 +32,7 @@ This document is written in `reStructuredText <http://docutils.sourceforge.net/r
|
||||
energy
|
||||
flow-monitor
|
||||
internet-models
|
||||
internet-apps
|
||||
lr-wpan
|
||||
lte
|
||||
mesh
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
Internet Models (IP, TCP, Routing, UDP, Internet Applications)
|
||||
---------------------------------------------------------------------
|
||||
Internet Models (IP, TCP, Routing, UDP)
|
||||
---------------------------------------
|
||||
|
||||
.. toctree::
|
||||
|
||||
@@ -9,4 +9,3 @@ Internet Models (IP, TCP, Routing, UDP, Internet Applications)
|
||||
routing-overview
|
||||
tcp
|
||||
udp
|
||||
internet-apps
|
||||
|
||||
@@ -24,30 +24,231 @@ directories. The users are encouraged to check the scripts therein to have a
|
||||
clear overview of the various options and usage tricks.
|
||||
|
||||
|
||||
V4Ping
|
||||
******
|
||||
Ping
|
||||
****
|
||||
|
||||
This app mimics a "ping" (ICMP Echo) using IPv4. The application allows the
|
||||
following attributes to be set:
|
||||
The ``Ping`` application supports both IPv4 and IPv6 and replaces earlier
|
||||
|ns3| implementations called ``v4Ping`` and ``Ping6`` that were
|
||||
address family dependent. ``Ping`` was introduced in the ns-3.38 release cycle.
|
||||
|
||||
* Remote address
|
||||
* Verbose mode
|
||||
* Packet size (default 56 bytes)
|
||||
* Packet interval (default 1 second)
|
||||
Model Description
|
||||
=================
|
||||
|
||||
Moreover, the user can access the measured RTT value (as a Traced Source).
|
||||
This application behaves similarly to the Unix ``ping`` application, although
|
||||
with fewer options supported. ``Ping`` sends ICMP Echo Request messages to
|
||||
a remote address, and collects statistics and reports on the ICMP Echo
|
||||
Reply responses that are received. The application can be used to send
|
||||
ICMP echo requests to unicast, broadcast, and multicast IPv4 and IPv6
|
||||
addresses. The application can produce a verbose output similar to the real
|
||||
application, and can also export statistics and results via trace sources.
|
||||
The following can be controlled via attributes of this class:
|
||||
|
||||
Ping6
|
||||
*****
|
||||
|
||||
This app mimics a "ping" (ICMP Echo) using IPv6. The application allows the
|
||||
following attributes to be set:
|
||||
|
||||
* Remote address
|
||||
* Destination address
|
||||
* Local address (sender address)
|
||||
* Packet size (default 56 bytes)
|
||||
* Packet interval (default 1 second)
|
||||
* Max number of packets to send
|
||||
* Timeout value (default 1 second)
|
||||
* The count, or maximum number of packets to send
|
||||
* Verbose mode
|
||||
|
||||
In practice, the real-world ``ping`` application behavior varies slightly
|
||||
depending on the operating system (Linux, macOS, Windows, etc.). Most
|
||||
implementations also support a very large number of options. The |ns3|
|
||||
model is intended to handle the most common use cases of testing for
|
||||
reachability.
|
||||
|
||||
Design
|
||||
######
|
||||
|
||||
The aim of |ns3| ``Ping`` application is to mimic the built-in application
|
||||
found in most operating systems. In practice, ``ping`` is usually used to
|
||||
check reachability of a destination, but additional options have been
|
||||
added over time and the tool can be used in different ways to gather
|
||||
statistics about reachability and round trip times (RTT). Since |ns3| is
|
||||
mainly used for performance studies and not for operational forensics,
|
||||
some options of real ``ping`` implementations may not be useful for simulations.
|
||||
However, the |ns3| application can deliver output and RTT samples similar
|
||||
to how the real application operates.
|
||||
|
||||
``Ping`` is usually installed on a source node and does not require any
|
||||
|ns3| application installation on the destination node. ``Ping`` is an
|
||||
``Application`` that can be started and stopped using the base class
|
||||
Application APIs.
|
||||
|
||||
Behavior
|
||||
########
|
||||
|
||||
The behavior of real ``ping`` applications varies across operating systems. For
|
||||
example, on Linux, the first ICMP sequence number sent is one, while on
|
||||
macOS, the first sequence number is zero. The behavior when pinging
|
||||
non-existent hosts also can differ (Linux is quiet while macOS is verbose).
|
||||
Windows and other operating systems like Cisco routers also can behave
|
||||
slightly differently.
|
||||
|
||||
This implementation tries to generally follow the Linux behavior, except
|
||||
that it will print out a verbose 'request timed out' message when an
|
||||
echo request is sent and no reply arrives in a timely manner. The timeout
|
||||
value (time that ping waits for a response to return) defaults to one
|
||||
second, but once there are RTT samples available, the timeout is set
|
||||
to twice the observed RTT. In contrast to Linux (but aligned with macOS),
|
||||
the first sequence number sent is zero.
|
||||
|
||||
Scope and Limitations
|
||||
#####################
|
||||
|
||||
``ping`` implementations have a lot of command-line options. The |ns3|
|
||||
implementation only supports a few of the most commonly-used options;
|
||||
patches to add additional options would be welcome.
|
||||
|
||||
At the present time, fragmentation (sending an ICMP Echo Request larger
|
||||
than the path MTU) is not handled correctly during Echo Response reassembly.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
Users may create and install ``Ping`` applications on nodes on a one-by-one
|
||||
basis using ``CreateObject`` or by using the ``PingHelper``. For
|
||||
``CreateObject``, the following can be used::
|
||||
|
||||
Ptr<Node> n = ...;
|
||||
Ptr<Ping> ping = CreateObject<Ping> ();
|
||||
// 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> ping = pingContainer.Get(0)->GetObject<Ping>();
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user