conf.route: improve doc (#4399)upstream-master

* conf.route: improve doc

* Apply guedou suggestion

Co-authored-by: Guillaume Valadon <guillaume@valadon.net>

---------

Co-authored-by: Guillaume Valadon <guillaume@valadon.net>

2 files changed, 41 insertions, 14 deletions

diff --git a/doc/scapy/routing.rst b/doc/scapy/routing.rst
index 88325962..2f9a9ec8 100644
--- a/doc/scapy/routing.rst
+++ b/doc/scapy/routing.rst
@@ -74,6 +74,12 @@ Here's an example of how to use `sshdump <https://www.wireshark.org/docs/man-pag
     ... )
 
 
+You can check the available options by using the following.
+
+.. code-block:: python
+
+    >>> conf.ifaces.dev_from_networkname("sshdump").get_extcap_config()
+
 .. todo:: The sections below can be greatly improved.
 
 IPv4 routes
@@ -138,10 +144,11 @@ Get the MAC of an interface
     >>> mac
     '54:3f:19:c9:38:6d'
 
-Get MAC by IP
--------------
+Get MAC address of the next hop to reach an IP
+----------------------------------------------
 
-This basically performs a cached ARP who-has.
+This basically performs a cached ARP who-has when the IP is on the same local link,
+returns the MAC of the gateway when it's not, and handle special cases like multicast.
 
 .. code-block:: pycon
 
diff --git a/scapy/route.py b/scapy/route.py
index f01d351f..af1411aa 100644
--- a/scapy/route.py
+++ b/scapy/route.py
@@ -69,7 +69,6 @@ class Route:
                    metric=1,  # type: int
                    ):
         # type: (...) -> Tuple[int, int, str, str, str, int]
-        from scapy.arch import get_if_addr
         if host is not None:
             thenet, msk = host, 32
         elif net is not None:
@@ -86,20 +85,41 @@ class Route:
                 nhop = thenet
             dev, ifaddr, _ = self.route(nhop)
         else:
-            ifaddr = get_if_addr(dev)
+            ifaddr = "0.0.0.0"  # acts as a 'via' in `ip addr add`
         return (atol(thenet), itom(msk), gw, dev, ifaddr, metric)
 
     def add(self, *args, **kargs):
         # type: (*Any, **Any) -> None
-        """Ex:
-        add(net="192.168.1.0/24",gw="1.2.3.4")
+        """Add a route to Scapy's IPv4 routing table.
+        add(host|net, gw|dev)
+
+        :param host: single IP to consider (/32)
+        :param net: range to consider
+        :param gw: gateway
+        :param dev: force the interface to use
+        :param metric: route metric
+
+        Examples:
+
+        - `ip route add 192.168.1.0/24 via 192.168.0.254`::
+            >>> conf.route.add(net="192.168.1.0/24", gw="192.168.0.254")
+
+        - `ip route add 192.168.1.0/24 dev eth0`::
+            >>> conf.route.add(net="192.168.1.0/24", dev="eth0")
+
+        - `ip route add 192.168.1.0/24 via 192.168.0.254 metric 1`::
+            >>> conf.route.add(net="192.168.1.0/24", gw="192.168.0.254", metric=1)
         """
         self.invalidate_cache()
         self.routes.append(self.make_route(*args, **kargs))
 
     def delt(self, *args, **kargs):
         # type: (*Any, **Any) -> None
-        """delt(host|net, gw|dev)"""
+        """Remove a route from Scapy's IPv4 routing table.
+        delt(host|net, gw|dev)
+
+        Same syntax as add()
+        """
         self.invalidate_cache()
         route = self.make_route(*args, **kargs)
         try:
@@ -148,13 +168,13 @@ class Route:
     def route(self, dst=None, verbose=conf.verb, _internal=False):
         # type: (Optional[str], int, bool) -> Tuple[str, str, str]
         """Returns the IPv4 routes to a host.
-        parameters:
-         - dst: the IPv4 of the destination host
 
-        returns: (iface, output_ip, gateway_ip)
-         - iface: the interface used to connect to the host
-         - output_ip: the outgoing IP that will be used
-         - gateway_ip: the gateway IP that will be used
+        :param dst: the IPv4 of the destination host
+
+        :returns: tuple (iface, output_ip, gateway_ip) where
+            - ``iface``: the interface used to connect to the host
+            - ``output_ip``: the outgoing IP that will be used
+            - ``gateway_ip``: the gateway IP that will be used
         """
         dst = dst or "0.0.0.0"  # Enable route(None) to return default route
         if isinstance(dst, bytes):