tests/topotests/lib/topogen.py

   1 #
   2 # topogen.py
   3 # Library of helper functions for NetDEF Topology Tests
   4 #
   5 # Copyright (c) 2017 by
   6 # Network Device Education Foundation, Inc. ("NetDEF")
   7 #
   8 # Permission to use, copy, modify, and/or distribute this software
   9 # for any purpose with or without fee is hereby granted, provided
  10 # that the above copyright notice and this permission notice appear
  11 # in all copies.
  12 #
  13 # THE SOFTWARE IS PROVIDED "AS IS" AND NETDEF DISCLAIMS ALL WARRANTIES
  14 # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  15 # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL NETDEF BE LIABLE FOR
  16 # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
  17 # DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  18 # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  19 # ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  20 # OF THIS SOFTWARE.
  21 #
  22
  23 """
  24 Topogen (Topology Generator) is an abstraction around Topotest and Mininet to
  25 help reduce boilerplate code and provide a stable interface to build topology
  26 tests on.
  27
  28 Basic usage instructions:
  29
  30 * Define a Topology class with a build method using mininet.topo.Topo.
  31   See examples/test_template.py.
  32 * Use Topogen inside the build() method with get_topogen.
  33   e.g. get_topogen(self).
  34 * Start up your topology with: Topogen(YourTopology)
  35 * Initialize the Mininet with your topology with: tgen.start_topology()
  36 * Configure your routers/hosts and start them
  37 * Run your tests / mininet cli.
  38 * After running stop Mininet with: tgen.stop_topology()
  39 """
  40
  41 import grp
  42 import inspect
  43 import json
  44 import logging
  45 import os
  46 import platform
  47 import pwd
  48 import re
  49 import subprocess
  50 import sys
  51 from collections import OrderedDict
  52
  53 if sys.version_info[0] > 2:
  54     import configparser
  55 else:
  56     import ConfigParser as configparser
  57
  58 import lib.topolog as topolog
  59 from lib.micronet import Commander
  60 from lib.micronet_compat import Mininet
  61 from lib.topolog import logger
  62 from lib.topotest import g_extra_config
  63
  64 from lib import topotest
  65
  66 CWD = os.path.dirname(os.path.realpath(__file__))
  67
  68 # pylint: disable=C0103
  69 # Global Topogen variable. This is being used to keep the Topogen available on
  70 # all test functions without declaring a test local variable.
  71 global_tgen = None
  72
  73
  74 def get_topogen(topo=None):
  75     """
  76     Helper function to retrieve Topogen. Must be called with `topo` when called
  77     inside the build() method of Topology class.
  78     """
  79     if topo is not None:
  80         global_tgen.topo = topo
  81     return global_tgen
  82
  83
  84 def set_topogen(tgen):
  85     "Helper function to set Topogen"
  86     # pylint: disable=W0603
  87     global global_tgen
  88     global_tgen = tgen
  89
  90
  91 def is_string(value):
  92     """Return True if value is a string."""
  93     try:
  94         return isinstance(value, basestring)  # type: ignore
  95     except NameError:
  96         return isinstance(value, str)
  97
  98
  99 def get_exabgp_cmd(commander=None):
 100     """Return the command to use for ExaBGP version < 4."""
 101
 102     if commander is None:
 103         commander = Commander("topogen")
 104
 105     def exacmd_version_ok(exacmd):
 106         logger.debug("checking %s for exabgp < version 4", exacmd)
 107         _, stdout, _ = commander.cmd_status(exacmd + " -v", warn=False)
 108         m = re.search(r"ExaBGP\s*:\s*((\d+)\.(\d+)(?:\.(\d+))?)", stdout)
 109         if not m:
 110             return False
 111         version = m.group(1)
 112         if topotest.version_cmp(version, "4") >= 0:
 113             logging.debug("found exabgp version >= 4 in %s will keep looking", exacmd)
 114             return False
 115         logger.info("Using ExaBGP version %s in %s", version, exacmd)
 116         return True
 117
 118     exacmd = commander.get_exec_path("exabgp")
 119     if exacmd and exacmd_version_ok(exacmd):
 120         return exacmd
 121     py2_path = commander.get_exec_path("python2")
 122     if py2_path:
 123         exacmd = py2_path + " -m exabgp"
 124         if exacmd_version_ok(exacmd):
 125             return exacmd
 126     py2_path = commander.get_exec_path("python")
 127     if py2_path:
 128         exacmd = py2_path + " -m exabgp"
 129         if exacmd_version_ok(exacmd):
 130             return exacmd
 131     return None
 132
 133
 134 #
 135 # Main class: topology builder
 136 #
 137
 138 # Topogen configuration defaults
 139 tgen_defaults = {
 140     "verbosity": "info",
 141     "frrdir": "/usr/lib/frr",
 142     "routertype": "frr",
 143     "memleak_path": "",
 144 }
 145
 146
 147 class Topogen(object):
 148     "A topology test builder helper."
 149
 150     CONFIG_SECTION = "topogen"
 151
 152     def __init__(self, topodef, modname="unnamed"):
 153         """
 154         Topogen initialization function, takes the following arguments:
 155         * `cls`: OLD:uthe topology class that is child of mininet.topo or a build function.
 156         * `topodef`: A dictionary defining the topology, a filename of a json file, or a
 157           function that will do the same
 158         * `modname`: module name must be a unique name to identify logs later.
 159         """
 160         self.config = None
 161         self.net = None
 162         self.gears = {}
 163         self.routern = 1
 164         self.switchn = 1
 165         self.modname = modname
 166         self.errorsd = {}
 167         self.errors = ""
 168         self.peern = 1
 169         self.cfg_gen = 0
 170         self.exabgp_cmd = None
 171         self._init_topo(topodef)
 172
 173         logger.info("loading topology: {}".format(self.modname))
 174
 175     # @staticmethod
 176     # def _mininet_reset():
 177     #     "Reset the mininet environment"
 178     #     # Clean up the mininet environment
 179     #     os.system("mn -c > /dev/null 2>&1")
 180
 181     def __str__(self):
 182         return "Topogen()"
 183
 184     def _init_topo(self, topodef):
 185         """
 186         Initialize the topogily provided by the user. The user topology class
 187         must call get_topogen() during build() to get the topogen object.
 188         """
 189         # Set the global variable so the test cases can access it anywhere
 190         set_topogen(self)
 191
 192         # Increase host based limits
 193         topotest.fix_host_limits()
 194
 195         # Test for MPLS Kernel modules available
 196         self.hasmpls = False
 197         if not topotest.module_present("mpls-router"):
 198             logger.info("MPLS tests will not run (missing mpls-router kernel module)")
 199         elif not topotest.module_present("mpls-iptunnel"):
 200             logger.info("MPLS tests will not run (missing mpls-iptunnel kernel module)")
 201         else:
 202             self.hasmpls = True
 203
 204         # Load the default topology configurations
 205         self._load_config()
 206
 207         # Create new log directory
 208         self.logdir = topotest.get_logs_path(g_extra_config["rundir"])
 209         subprocess.check_call(
 210             "mkdir -p {0} && chmod 1777 {0}".format(self.logdir), shell=True
 211         )
 212         try:
 213             routertype = self.config.get(self.CONFIG_SECTION, "routertype")
 214             # Only allow group, if it exist.
 215             gid = grp.getgrnam(routertype)[2]
 216             os.chown(self.logdir, 0, gid)
 217             os.chmod(self.logdir, 0o775)
 218         except KeyError:
 219             # Allow anyone, but set the sticky bit to avoid file deletions
 220             os.chmod(self.logdir, 0o1777)
 221
 222         # Remove old twisty way of creating sub-classed topology object which has it's
 223         # build method invoked which calls Topogen methods which then call Topo methods
 224         # to create a topology within the Topo object, which is then used by
 225         # Mininet(Micronet) to build the actual topology.
 226         assert not inspect.isclass(topodef)
 227
 228         self.net = Mininet(controller=None)
 229
 230         # New direct way: Either a dictionary defines the topology or a build function
 231         # is supplied, or a json filename all of which build the topology by calling
 232         # Topogen methods which call Mininet(Micronet) methods to create the actual
 233         # topology.
 234         if not inspect.isclass(topodef):
 235             if callable(topodef):
 236                 topodef(self)
 237                 self.net.configure_hosts()
 238             elif is_string(topodef):
 239                 # topojson imports topogen in one function too,
 240                 # switch away from this use here to the topojson
 241                 # fixutre and remove this case
 242                 from lib.topojson import build_topo_from_json
 243
 244                 with open(topodef, "r") as topof:
 245                     self.json_topo = json.load(topof)
 246                 build_topo_from_json(self, self.json_topo)
 247                 self.net.configure_hosts()
 248             elif topodef:
 249                 self.add_topology_from_dict(topodef)
 250
 251     def add_topology_from_dict(self, topodef):
 252
 253         keylist = (
 254             topodef.keys()
 255             if isinstance(topodef, OrderedDict)
 256             else sorted(topodef.keys())
 257         )
 258         # ---------------------------
 259         # Create all referenced hosts
 260         # ---------------------------
 261         for oname in keylist:
 262             tup = (topodef[oname],) if is_string(topodef[oname]) else topodef[oname]
 263             for e in tup:
 264                 desc = e.split(":")
 265                 name = desc[0]
 266                 if name not in self.gears:
 267                     logging.debug("Adding router: %s", name)
 268                     self.add_router(name)
 269
 270         # ------------------------------
 271         # Create all referenced switches
 272         # ------------------------------
 273         for oname in keylist:
 274             if oname is not None and oname not in self.gears:
 275                 logging.debug("Adding switch: %s", oname)
 276                 self.add_switch(oname)
 277
 278         # ----------------
 279         # Create all links
 280         # ----------------
 281         for oname in keylist:
 282             if oname is None:
 283                 continue
 284             tup = (topodef[oname],) if is_string(topodef[oname]) else topodef[oname]
 285             for e in tup:
 286                 desc = e.split(":")
 287                 name = desc[0]
 288                 ifname = desc[1] if len(desc) > 1 else None
 289                 sifname = desc[2] if len(desc) > 2 else None
 290                 self.add_link(self.gears[oname], self.gears[name], sifname, ifname)
 291
 292         self.net.configure_hosts()
 293
 294     def _load_config(self):
 295         """
 296         Loads the configuration file `pytest.ini` located at the root dir of
 297         topotests.
 298         """
 299         self.config = configparser.ConfigParser(tgen_defaults)
 300         pytestini_path = os.path.join(CWD, "../pytest.ini")
 301         self.config.read(pytestini_path)
 302
 303     def add_router(self, name=None, cls=None, **params):
 304         """
 305         Adds a new router to the topology. This function has the following
 306         options:
 307         * `name`: (optional) select the router name
 308         * `daemondir`: (optional) custom daemon binary directory
 309         * `routertype`: (optional) `frr`
 310         Returns a TopoRouter.
 311         """
 312         if cls is None:
 313             cls = topotest.Router
 314         if name is None:
 315             name = "r{}".format(self.routern)
 316         if name in self.gears:
 317             raise KeyError("router already exists")
 318
 319         params["frrdir"] = self.config.get(self.CONFIG_SECTION, "frrdir")
 320         params["memleak_path"] = self.config.get(self.CONFIG_SECTION, "memleak_path")
 321         if "routertype" not in params:
 322             params["routertype"] = self.config.get(self.CONFIG_SECTION, "routertype")
 323
 324         self.gears[name] = TopoRouter(self, cls, name, **params)
 325         self.routern += 1
 326         return self.gears[name]
 327
 328     def add_switch(self, name=None):
 329         """
 330         Adds a new switch to the topology. This function has the following
 331         options:
 332         name: (optional) select the switch name
 333         Returns the switch name and number.
 334         """
 335         if name is None:
 336             name = "s{}".format(self.switchn)
 337         if name in self.gears:
 338             raise KeyError("switch already exists")
 339
 340         self.gears[name] = TopoSwitch(self, name)
 341         self.switchn += 1
 342         return self.gears[name]
 343
 344     def add_exabgp_peer(self, name, ip, defaultRoute):
 345         """
 346         Adds a new ExaBGP peer to the topology. This function has the following
 347         parameters:
 348         * `ip`: the peer address (e.g. '1.2.3.4/24')
 349         * `defaultRoute`: the peer default route (e.g. 'via 1.2.3.1')
 350         """
 351         if name is None:
 352             name = "peer{}".format(self.peern)
 353         if name in self.gears:
 354             raise KeyError("exabgp peer already exists")
 355
 356         self.gears[name] = TopoExaBGP(self, name, ip=ip, defaultRoute=defaultRoute)
 357         self.peern += 1
 358         return self.gears[name]
 359
 360     def add_host(self, name, ip, defaultRoute):
 361         """
 362         Adds a new host to the topology. This function has the following
 363         parameters:
 364         * `ip`: the peer address (e.g. '1.2.3.4/24')
 365         * `defaultRoute`: the peer default route (e.g. 'via 1.2.3.1')
 366         """
 367         if name is None:
 368             name = "host{}".format(self.peern)
 369         if name in self.gears:
 370             raise KeyError("host already exists")
 371
 372         self.gears[name] = TopoHost(self, name, ip=ip, defaultRoute=defaultRoute)
 373         self.peern += 1
 374         return self.gears[name]
 375
 376     def add_link(self, node1, node2, ifname1=None, ifname2=None):
 377         """
 378         Creates a connection between node1 and node2. The nodes can be the
 379         following:
 380         * TopoGear
 381           * TopoRouter
 382           * TopoSwitch
 383         """
 384         if not isinstance(node1, TopoGear):
 385             raise ValueError("invalid node1 type")
 386         if not isinstance(node2, TopoGear):
 387             raise ValueError("invalid node2 type")
 388
 389         if ifname1 is None:
 390             ifname1 = node1.new_link()
 391         if ifname2 is None:
 392             ifname2 = node2.new_link()
 393
 394         node1.register_link(ifname1, node2, ifname2)
 395         node2.register_link(ifname2, node1, ifname1)
 396         self.net.add_link(node1.name, node2.name, ifname1, ifname2)
 397
 398     def get_gears(self, geartype):
 399         """
 400         Returns a dictionary of all gears of type `geartype`.
 401
 402         Normal usage:
 403         * Dictionary iteration:
 404         ```py
 405         tgen = get_topogen()
 406         router_dict = tgen.get_gears(TopoRouter)
 407         for router_name, router in router_dict.items():
 408             # Do stuff
 409         ```
 410         * List iteration:
 411         ```py
 412         tgen = get_topogen()
 413         peer_list = tgen.get_gears(TopoExaBGP).values()
 414         for peer in peer_list:
 415             # Do stuff
 416         ```
 417         """
 418         return dict(
 419             (name, gear)
 420             for name, gear in self.gears.items()
 421             if isinstance(gear, geartype)
 422         )
 423
 424     def routers(self):
 425         """
 426         Returns the router dictionary (key is the router name and value is the
 427         router object itself).
 428         """
 429         return self.get_gears(TopoRouter)
 430
 431     def exabgp_peers(self):
 432         """
 433         Returns the exabgp peer dictionary (key is the peer name and value is
 434         the peer object itself).
 435         """
 436         return self.get_gears(TopoExaBGP)
 437
 438     def start_topology(self):
 439         """Starts the topology class."""
 440         logger.info("starting topology: {}".format(self.modname))
 441         self.net.start()
 442
 443     def start_router(self, router=None):
 444         """
 445         Call the router startRouter method.
 446         If no router is specified it is called for all registred routers.
 447         """
 448         if router is None:
 449             # pylint: disable=r1704
 450             # XXX should be hosts?
 451             for _, router in self.routers().items():
 452                 router.start()
 453         else:
 454             if isinstance(router, str):
 455                 router = self.gears[router]
 456
 457             router.start()
 458
 459     def stop_topology(self):
 460         """
 461         Stops the network topology. This function will call the stop() function
 462         of all gears before calling the mininet stop function, so they can have
 463         their oportunity to do a graceful shutdown. stop() is called twice. The
 464         first is a simple kill with no sleep, the second will sleep if not
 465         killed and try with a different signal.
 466         """
 467         logger.info("stopping topology: {}".format(self.modname))
 468         errors = ""
 469         for gear in self.gears.values():
 470             errors += gear.stop()
 471         if len(errors) > 0:
 472             logger.error(
 473                 "Errors found post shutdown - details follow: {}".format(errors)
 474             )
 475
 476         self.net.stop()
 477
 478     def get_exabgp_cmd(self):
 479         if not self.exabgp_cmd:
 480             self.exabgp_cmd = get_exabgp_cmd(self.net)
 481         return self.exabgp_cmd
 482
 483     def cli(self):
 484         """
 485         Interrupt the test and call the command line interface for manual
 486         inspection. Should be only used on non production code.
 487         """
 488         self.net.cli()
 489
 490     mininet_cli = cli
 491
 492     def is_memleak_enabled(self):
 493         "Returns `True` if memory leak report is enable, otherwise `False`."
 494         # On router failure we can't run the memory leak test
 495         if self.routers_have_failure():
 496             return False
 497
 498         memleak_file = os.environ.get("TOPOTESTS_CHECK_MEMLEAK") or self.config.get(
 499             self.CONFIG_SECTION, "memleak_path"
 500         )
 501         if memleak_file == "" or memleak_file == None:
 502             return False
 503         return True
 504
 505     def report_memory_leaks(self, testname=None):
 506         "Run memory leak test and reports."
 507         if not self.is_memleak_enabled():
 508             return
 509
 510         # If no name was specified, use the test module name
 511         if testname is None:
 512             testname = self.modname
 513
 514         router_list = self.routers().values()
 515         for router in router_list:
 516             router.report_memory_leaks(self.modname)
 517
 518     def set_error(self, message, code=None):
 519         "Sets an error message and signal other tests to skip."
 520         logger.info(message)
 521
 522         # If no code is defined use a sequential number
 523         if code is None:
 524             code = len(self.errorsd)
 525
 526         self.errorsd[code] = message
 527         self.errors += "\n{}: {}".format(code, message)
 528
 529     def has_errors(self):
 530         "Returns whether errors exist or not."
 531         return len(self.errorsd) > 0
 532
 533     def routers_have_failure(self):
 534         "Runs an assertion to make sure that all routers are running."
 535         if self.has_errors():
 536             return True
 537
 538         errors = ""
 539         router_list = self.routers().values()
 540         for router in router_list:
 541             result = router.check_router_running()
 542             if result != "":
 543                 errors += result + "\n"
 544
 545         if errors != "":
 546             self.set_error(errors, "router_error")
 547             assert False, errors
 548             return True
 549         return False
 550
 551
 552 #
 553 # Topology gears (equipment)
 554 #
 555
 556
 557 class TopoGear(object):
 558     "Abstract class for type checking"
 559
 560     def __init__(self, tgen, name, **params):
 561         self.tgen = tgen
 562         self.name = name
 563         self.params = params
 564         self.links = {}
 565         self.linkn = 0
 566
 567         # Would be nice for this to point at the gears log directory rather than the
 568         # test's.
 569         self.logdir = tgen.logdir
 570         self.gearlogdir = None
 571
 572     def __str__(self):
 573         links = ""
 574         for myif, dest in self.links.items():
 575             _, destif = dest
 576             if links != "":
 577                 links += ","
 578             links += '"{}"<->"{}"'.format(myif, destif)
 579
 580         return 'TopoGear<name="{}",links=[{}]>'.format(self.name, links)
 581
 582     @property
 583     def net(self):
 584         return self.tgen.net[self.name]
 585
 586     def start(self):
 587         "Basic start function that just reports equipment start"
 588         logger.info('starting "{}"'.format(self.name))
 589
 590     def stop(self, wait=True, assertOnError=True):
 591         "Basic stop function that just reports equipment stop"
 592         logger.info('"{}" base stop called'.format(self.name))
 593         return ""
 594
 595     def cmd(self, command, **kwargs):
 596         """
 597         Runs the provided command string in the router and returns a string
 598         with the response.
 599         """
 600         return self.net.cmd_legacy(command, **kwargs)
 601
 602     def cmd_raises(self, command, **kwargs):
 603         """
 604         Runs the provided command string in the router and returns a string
 605         with the response. Raise an exception on any error.
 606         """
 607         return self.net.cmd_raises(command, **kwargs)
 608
 609     run = cmd
 610
 611     def popen(self, *params, **kwargs):
 612         """
 613         Creates a pipe with the given command. Same args as python Popen.
 614         If `command` is a string then will be invoked with shell, otherwise
 615         `command` is a list and will be invoked w/o shell. Returns a popen object.
 616         """
 617         return self.net.popen(*params, **kwargs)
 618
 619     def add_link(self, node, myif=None, nodeif=None):
 620         """
 621         Creates a link (connection) between myself and the specified node.
 622         Interfaces name can be speficied with:
 623         myif: the interface name that will be created in this node
 624         nodeif: the target interface name that will be created on the remote node.
 625         """
 626         self.tgen.add_link(self, node, myif, nodeif)
 627
 628     def link_enable(self, myif, enabled=True, netns=None):
 629         """
 630         Set this node interface administrative state.
 631         myif: this node interface name
 632         enabled: whether we should enable or disable the interface
 633         """
 634         if myif not in self.links.keys():
 635             raise KeyError("interface doesn't exists")
 636
 637         if enabled is True:
 638             operation = "up"
 639         else:
 640             operation = "down"
 641
 642         logger.info(
 643             'setting node "{}" link "{}" to state "{}"'.format(
 644                 self.name, myif, operation
 645             )
 646         )
 647         extract = ""
 648         if netns is not None:
 649             extract = "ip netns exec {} ".format(netns)
 650
 651         return self.run("{}ip link set dev {} {}".format(extract, myif, operation))
 652
 653     def peer_link_enable(self, myif, enabled=True, netns=None):
 654         """
 655         Set the peer interface administrative state.
 656         myif: this node interface name
 657         enabled: whether we should enable or disable the interface
 658
 659         NOTE: this is used to simulate a link down on this node, since when the
 660         peer disables their interface our interface status changes to no link.
 661         """
 662         if myif not in self.links.keys():
 663             raise KeyError("interface doesn't exists")
 664
 665         node, nodeif = self.links[myif]
 666         node.link_enable(nodeif, enabled, netns)
 667
 668     def new_link(self):
 669         """
 670         Generates a new unique link name.
 671
 672         NOTE: This function should only be called by Topogen.
 673         """
 674         ifname = "{}-eth{}".format(self.name, self.linkn)
 675         self.linkn += 1
 676         return ifname
 677
 678     def register_link(self, myif, node, nodeif):
 679         """
 680         Register link between this node interface and outside node.
 681
 682         NOTE: This function should only be called by Topogen.
 683         """
 684         if myif in self.links.keys():
 685             raise KeyError("interface already exists")
 686
 687         self.links[myif] = (node, nodeif)
 688
 689     def _setup_tmpdir(self):
 690         topotest.setup_node_tmpdir(self.logdir, self.name)
 691         self.gearlogdir = "{}/{}".format(self.logdir, self.name)
 692         return "{}/{}.log".format(self.logdir, self.name)
 693
 694
 695 class TopoRouter(TopoGear):
 696     """
 697     Router abstraction.
 698     """
 699
 700     # The default required directories by FRR
 701     PRIVATE_DIRS = [
 702         "/etc/frr",
 703         "/etc/snmp",
 704         "/var/run/frr",
 705         "/var/log",
 706     ]
 707
 708     # Router Daemon enumeration definition.
 709     RD_FRR = 0  # not a daemon, but use to setup unified configs
 710     RD_ZEBRA = 1
 711     RD_RIP = 2
 712     RD_RIPNG = 3
 713     RD_OSPF = 4
 714     RD_OSPF6 = 5
 715     RD_ISIS = 6
 716     RD_BGP = 7
 717     RD_LDP = 8
 718     RD_PIM = 9
 719     RD_EIGRP = 10
 720     RD_NHRP = 11
 721     RD_STATIC = 12
 722     RD_BFD = 13
 723     RD_SHARP = 14
 724     RD_BABEL = 15
 725     RD_PBRD = 16
 726     RD_PATH = 17
 727     RD_SNMP = 18
 728     RD = {
 729         RD_FRR: "frr",
 730         RD_ZEBRA: "zebra",
 731         RD_RIP: "ripd",
 732         RD_RIPNG: "ripngd",
 733         RD_OSPF: "ospfd",
 734         RD_OSPF6: "ospf6d",
 735         RD_ISIS: "isisd",
 736         RD_BGP: "bgpd",
 737         RD_PIM: "pimd",
 738         RD_LDP: "ldpd",
 739         RD_EIGRP: "eigrpd",
 740         RD_NHRP: "nhrpd",
 741         RD_STATIC: "staticd",
 742         RD_BFD: "bfdd",
 743         RD_SHARP: "sharpd",
 744         RD_BABEL: "babeld",
 745         RD_PBRD: "pbrd",
 746         RD_PATH: "pathd",
 747         RD_SNMP: "snmpd",
 748     }
 749
 750     def __init__(self, tgen, cls, name, **params):
 751         """
 752         The constructor has the following parameters:
 753         * tgen: Topogen object
 754         * cls: router class that will be used to instantiate
 755         * name: router name
 756         * daemondir: daemon binary directory
 757         * routertype: 'frr'
 758         """
 759         super(TopoRouter, self).__init__(tgen, name, **params)
 760         self.routertype = params.get("routertype", "frr")
 761         if "privateDirs" not in params:
 762             params["privateDirs"] = self.PRIVATE_DIRS
 763
 764         # Propagate the router log directory
 765         logfile = self._setup_tmpdir()
 766         params["logdir"] = self.logdir
 767
 768         self.logger = topolog.get_logger(name, log_level="debug", target=logfile)
 769         params["logger"] = self.logger
 770         tgen.net.add_host(self.name, cls=cls, **params)
 771         topotest.fix_netns_limits(tgen.net[name])
 772
 773         # Mount gear log directory on a common path
 774         self.net.bind_mount(self.gearlogdir, "/tmp/gearlogdir")
 775
 776         # Ensure pid file
 777         with open(os.path.join(self.logdir, self.name + ".pid"), "w") as f:
 778             f.write(str(self.net.pid) + "\n")
 779
 780     def __str__(self):
 781         gear = super(TopoRouter, self).__str__()
 782         gear += " TopoRouter<>"
 783         return gear
 784
 785     def check_capability(self, daemon, param):
 786         """
 787         Checks a capability daemon against an argument option
 788         Return True if capability available. False otherwise
 789         """
 790         daemonstr = self.RD.get(daemon)
 791         self.logger.info('check capability {} for "{}"'.format(param, daemonstr))
 792         return self.net.checkCapability(daemonstr, param)
 793
 794     def load_frr_config(self, source, daemons=None):
 795         """
 796         Loads the unified configuration file source
 797         Start the daemons in the list
 798         If daemons is None, try to infer daemons from the config file
 799         """
 800         self.load_config(self.RD_FRR, source)
 801         if not daemons:
 802             # Always add zebra
 803             self.load_config(self.RD_ZEBRA)
 804             for daemon in self.RD:
 805                 # This will not work for all daemons
 806                 daemonstr = self.RD.get(daemon).rstrip("d")
 807                 if daemonstr == "pim":
 808                     grep_cmd = "grep 'ip {}' {}".format(daemonstr, source)
 809                 else:
 810                     grep_cmd = "grep 'router {}' {}".format(daemonstr, source)
 811                 result = self.run(grep_cmd).strip()
 812                 if result:
 813                     self.load_config(daemon)
 814         else:
 815             for daemon in daemons:
 816                 self.load_config(daemon)
 817
 818     def load_config(self, daemon, source=None, param=None):
 819         """Loads daemon configuration from the specified source
 820         Possible daemon values are: TopoRouter.RD_ZEBRA, TopoRouter.RD_RIP,
 821         TopoRouter.RD_RIPNG, TopoRouter.RD_OSPF, TopoRouter.RD_OSPF6,
 822         TopoRouter.RD_ISIS, TopoRouter.RD_BGP, TopoRouter.RD_LDP,
 823         TopoRouter.RD_PIM, TopoRouter.RD_PBR, TopoRouter.RD_SNMP.
 824
 825         Possible `source` values are `None` for an empty config file, a path name which is
 826         used directly, or a file name with no path components which is first looked for
 827         directly and then looked for under a sub-directory named after router.
 828
 829         This API unfortunately allows for source to not exist for any and
 830         all routers.
 831         """
 832         daemonstr = self.RD.get(daemon)
 833         self.logger.info('loading "{}" configuration: {}'.format(daemonstr, source))
 834         self.net.loadConf(daemonstr, source, param)
 835
 836     def check_router_running(self):
 837         """
 838         Run a series of checks and returns a status string.
 839         """
 840         self.logger.info("checking if daemons are running")
 841         return self.net.checkRouterRunning()
 842
 843     def start(self):
 844         """
 845         Start router:
 846         * Load modules
 847         * Clean up files
 848         * Configure interfaces
 849         * Start daemons (e.g. FRR)
 850         * Configure daemon logging files
 851         """
 852
 853         nrouter = self.net
 854         result = nrouter.startRouter(self.tgen)
 855
 856         # Enable command logging
 857
 858         # Enable all daemon command logging, logging files
 859         # and set them to the start dir.
 860         for daemon, enabled in nrouter.daemons.items():
 861             if enabled and daemon != "snmpd":
 862                 self.vtysh_cmd(
 863                     "\n".join(
 864                         [
 865                             "clear log cmdline-targets",
 866                             "conf t",
 867                             "log file {}.log debug".format(daemon),
 868                             "log commands",
 869                             "log timestamp precision 3",
 870                         ]
 871                     ),
 872                     daemon=daemon,
 873                 )
 874
 875         if result != "":
 876             self.tgen.set_error(result)
 877         elif nrouter.daemons["ldpd"] == 1 or nrouter.daemons["pathd"] == 1:
 878             # Enable MPLS processing on all interfaces.
 879             for interface in self.links:
 880                 topotest.sysctl_assure(
 881                     nrouter, "net.mpls.conf.{}.input".format(interface), 1
 882                 )
 883
 884         return result
 885
 886     def stop(self):
 887         """
 888         Stop router cleanly:
 889         * Signal daemons twice, once with SIGTERM, then with SIGKILL.
 890         """
 891         self.logger.debug("stopping (no assert)")
 892         return self.net.stopRouter(False)
 893
 894     def startDaemons(self, daemons):
 895         """
 896         Start Daemons: to start specific daemon(user defined daemon only)
 897         * Start daemons (e.g. FRR)
 898         * Configure daemon logging files
 899         """
 900         self.logger.debug("starting")
 901         nrouter = self.net
 902         result = nrouter.startRouterDaemons(daemons)
 903
 904         if daemons is None:
 905             daemons = nrouter.daemons.keys()
 906
 907         # Enable all daemon command logging, logging files
 908         # and set them to the start dir.
 909         for daemon in daemons:
 910             enabled = nrouter.daemons[daemon]
 911             if enabled and daemon != "snmpd":
 912                 self.vtysh_cmd(
 913                     "\n".join(
 914                         [
 915                             "clear log cmdline-targets",
 916                             "conf t",
 917                             "log file {}.log debug".format(daemon),
 918                             "log commands",
 919                             "log timestamp precision 3",
 920                         ]
 921                     ),
 922                     daemon=daemon,
 923                 )
 924
 925         if result != "":
 926             self.tgen.set_error(result)
 927
 928         return result
 929
 930     def killDaemons(self, daemons, wait=True, assertOnError=True):
 931         """
 932         Kill specific daemon(user defined daemon only)
 933         forcefully using SIGKILL
 934         """
 935         self.logger.debug("Killing daemons using SIGKILL..")
 936         return self.net.killRouterDaemons(daemons, wait, assertOnError)
 937
 938     def vtysh_cmd(self, command, isjson=False, daemon=None):
 939         """
 940         Runs the provided command string in the vty shell and returns a string
 941         with the response.
 942
 943         This function also accepts multiple commands, but this mode does not
 944         return output for each command. See vtysh_multicmd() for more details.
 945         """
 946         # Detect multi line commands
 947         if command.find("\n") != -1:
 948             return self.vtysh_multicmd(command, daemon=daemon)
 949
 950         dparam = ""
 951         if daemon is not None:
 952             dparam += "-d {}".format(daemon)
 953
 954         vtysh_command = 'vtysh {} -c "{}" 2>/dev/null'.format(dparam, command)
 955
 956         self.logger.info('vtysh command => "{}"'.format(command))
 957         output = self.run(vtysh_command)
 958
 959         dbgout = output.strip()
 960         if dbgout:
 961             if "\n" in dbgout:
 962                 dbgout = dbgout.replace("\n", "\n\t")
 963                 self.logger.info("vtysh result:\n\t{}".format(dbgout))
 964             else:
 965                 self.logger.info('vtysh result: "{}"'.format(dbgout))
 966
 967         if isjson is False:
 968             return output
 969
 970         try:
 971             return json.loads(output)
 972         except ValueError as error:
 973             logger.warning(
 974                 "vtysh_cmd: %s: failed to convert json output: %s: %s",
 975                 self.name,
 976                 str(output),
 977                 str(error),
 978             )
 979             return {}
 980
 981     def vtysh_multicmd(self, commands, pretty_output=True, daemon=None):
 982         """
 983         Runs the provided commands in the vty shell and return the result of
 984         execution.
 985
 986         pretty_output: defines how the return value will be presented. When
 987         True it will show the command as they were executed in the vty shell,
 988         otherwise it will only show lines that failed.
 989         """
 990         # Prepare the temporary file that will hold the commands
 991         fname = topotest.get_file(commands)
 992
 993         dparam = ""
 994         if daemon is not None:
 995             dparam += "-d {}".format(daemon)
 996
 997         # Run the commands and delete the temporary file
 998         if pretty_output:
 999             vtysh_command = "vtysh {} < {}".format(dparam, fname)
1000         else:
1001             vtysh_command = "vtysh {} -f {}".format(dparam, fname)
1002
1003         dbgcmds = commands if is_string(commands) else "\n".join(commands)
1004         dbgcmds = "\t" + dbgcmds.replace("\n", "\n\t")
1005         self.logger.info("vtysh command => FILE:\n{}".format(dbgcmds))
1006
1007         res = self.run(vtysh_command)
1008         os.unlink(fname)
1009
1010         dbgres = res.strip()
1011         if dbgres:
1012             if "\n" in dbgres:
1013                 dbgres = dbgres.replace("\n", "\n\t")
1014                 self.logger.info("vtysh result:\n\t{}".format(dbgres))
1015             else:
1016                 self.logger.info('vtysh result: "{}"'.format(dbgres))
1017         return res
1018
1019     def report_memory_leaks(self, testname):
1020         """
1021         Runs the router memory leak check test. Has the following parameter:
1022         testname: the test file name for identification
1023
1024         NOTE: to run this you must have the environment variable
1025         TOPOTESTS_CHECK_MEMLEAK set or memleak_path configured in `pytest.ini`.
1026         """
1027         memleak_file = (
1028             os.environ.get("TOPOTESTS_CHECK_MEMLEAK") or self.params["memleak_path"]
1029         )
1030         if memleak_file == "" or memleak_file == None:
1031             return
1032
1033         self.stop()
1034
1035         self.logger.info("running memory leak report")
1036         self.net.report_memory_leaks(memleak_file, testname)
1037
1038     def version_info(self):
1039         "Get equipment information from 'show version'."
1040         output = self.vtysh_cmd("show version").split("\n")[0]
1041         columns = topotest.normalize_text(output).split(" ")
1042         try:
1043             return {
1044                 "type": columns[0],
1045                 "version": columns[1],
1046             }
1047         except IndexError:
1048             return {
1049                 "type": None,
1050                 "version": None,
1051             }
1052
1053     def has_version(self, cmpop, version):
1054         """
1055         Compares router version using operation `cmpop` with `version`.
1056         Valid `cmpop` values:
1057         * `>=`: has the same version or greater
1058         * '>': has greater version
1059         * '=': has the same version
1060         * '<': has a lesser version
1061         * '<=': has the same version or lesser
1062
1063         Usage example: router.has_version('>', '1.0')
1064         """
1065         return self.net.checkRouterVersion(cmpop, version)
1066
1067     def has_type(self, rtype):
1068         """
1069         Compares router type with `rtype`. Returns `True` if the type matches,
1070         otherwise `false`.
1071         """
1072         curtype = self.version_info()["type"]
1073         return rtype == curtype
1074
1075     def has_mpls(self):
1076         return self.net.hasmpls
1077
1078
1079 class TopoSwitch(TopoGear):
1080     """
1081     Switch abstraction. Has the following properties:
1082     * cls: switch class that will be used to instantiate
1083     * name: switch name
1084     """
1085
1086     # pylint: disable=too-few-public-methods
1087
1088     def __init__(self, tgen, name, **params):
1089         super(TopoSwitch, self).__init__(tgen, name, **params)
1090         tgen.net.add_switch(name)
1091
1092     def __str__(self):
1093         gear = super(TopoSwitch, self).__str__()
1094         gear += " TopoSwitch<>"
1095         return gear
1096
1097
1098 class TopoHost(TopoGear):
1099     "Host abstraction."
1100     # pylint: disable=too-few-public-methods
1101
1102     def __init__(self, tgen, name, **params):
1103         """
1104         Mininet has the following known `params` for hosts:
1105         * `ip`: the IP address (string) for the host interface
1106         * `defaultRoute`: the default route that will be installed
1107           (e.g. 'via 10.0.0.1')
1108         * `privateDirs`: directories that will be mounted on a different domain
1109           (e.g. '/etc/important_dir').
1110         """
1111         super(TopoHost, self).__init__(tgen, name, **params)
1112
1113         # Propagate the router log directory
1114         logfile = self._setup_tmpdir()
1115         params["logdir"] = self.logdir
1116
1117         # Odd to have 2 logfiles for each host
1118         self.logger = topolog.get_logger(name, log_level="debug", target=logfile)
1119         params["logger"] = self.logger
1120         tgen.net.add_host(name, **params)
1121         topotest.fix_netns_limits(tgen.net[name])
1122
1123         # Mount gear log directory on a common path
1124         self.net.bind_mount(self.gearlogdir, "/tmp/gearlogdir")
1125
1126     def __str__(self):
1127         gear = super(TopoHost, self).__str__()
1128         gear += ' TopoHost<ip="{}",defaultRoute="{}",privateDirs="{}">'.format(
1129             self.params["ip"],
1130             self.params["defaultRoute"],
1131             str(self.params["privateDirs"]),
1132         )
1133         return gear
1134
1135
1136 class TopoExaBGP(TopoHost):
1137     "ExaBGP peer abstraction."
1138     # pylint: disable=too-few-public-methods
1139
1140     PRIVATE_DIRS = [
1141         "/etc/exabgp",
1142         "/var/run/exabgp",
1143         "/var/log",
1144     ]
1145
1146     def __init__(self, tgen, name, **params):
1147         """
1148         ExaBGP usually uses the following parameters:
1149         * `ip`: the IP address (string) for the host interface
1150         * `defaultRoute`: the default route that will be installed
1151           (e.g. 'via 10.0.0.1')
1152
1153         Note: the different between a host and a ExaBGP peer is that this class
1154         has a privateDirs already defined and contains functions to handle ExaBGP
1155         things.
1156         """
1157         params["privateDirs"] = self.PRIVATE_DIRS
1158         super(TopoExaBGP, self).__init__(tgen, name, **params)
1159
1160     def __str__(self):
1161         gear = super(TopoExaBGP, self).__str__()
1162         gear += " TopoExaBGP<>".format()
1163         return gear
1164
1165     def start(self, peer_dir, env_file=None):
1166         """
1167         Start running ExaBGP daemon:
1168         * Copy all peer* folder contents into /etc/exabgp
1169         * Copy exabgp env file if specified
1170         * Make all python files runnable
1171         * Run ExaBGP with env file `env_file` and configuration peer*/exabgp.cfg
1172         """
1173         exacmd = self.tgen.get_exabgp_cmd()
1174         assert exacmd, "Can't find a usabel ExaBGP (must be < version 4)"
1175
1176         self.run("mkdir -p /etc/exabgp")
1177         self.run("chmod 755 /etc/exabgp")
1178         self.run("cp {}/exa-* /etc/exabgp/".format(CWD))
1179         self.run("cp {}/* /etc/exabgp/".format(peer_dir))
1180         if env_file is not None:
1181             self.run("cp {} /etc/exabgp/exabgp.env".format(env_file))
1182         self.run("chmod 644 /etc/exabgp/*")
1183         self.run("chmod a+x /etc/exabgp/*.py")
1184         self.run("chown -R exabgp:exabgp /etc/exabgp")
1185
1186         output = self.run(exacmd + " -e /etc/exabgp/exabgp.env /etc/exabgp/exabgp.cfg")
1187         if output == None or len(output) == 0:
1188             output = "<none>"
1189
1190         logger.info("{} exabgp started, output={}".format(self.name, output))
1191
1192     def stop(self, wait=True, assertOnError=True):
1193         "Stop ExaBGP peer and kill the daemon"
1194         self.run("kill `cat /var/run/exabgp/exabgp.pid`")
1195         return ""
1196
1197
1198 #
1199 # Diagnostic function
1200 #
1201
1202 # Disable linter branch warning. It is expected to have these here.
1203 # pylint: disable=R0912
1204 def diagnose_env_linux(rundir):
1205     """
1206     Run diagnostics in the running environment. Returns `True` when everything
1207     is ok, otherwise `False`.
1208     """
1209     ret = True
1210
1211     # Load configuration
1212     config = configparser.ConfigParser(defaults=tgen_defaults)
1213     pytestini_path = os.path.join(CWD, "../pytest.ini")
1214     config.read(pytestini_path)
1215
1216     # Test log path exists before installing handler.
1217     os.system("mkdir -p " + rundir)
1218     # Log diagnostics to file so it can be examined later.
1219     fhandler = logging.FileHandler(filename="{}/diagnostics.txt".format(rundir))
1220     fhandler.setLevel(logging.DEBUG)
1221     fhandler.setFormatter(logging.Formatter(fmt=topolog.FORMAT))
1222     logger.addHandler(fhandler)
1223
1224     logger.info("Running environment diagnostics")
1225
1226     # Assert that we are running as root
1227     if os.getuid() != 0:
1228         logger.error("you must run topotest as root")
1229         ret = False
1230
1231     # Assert that we have mininet
1232     # if os.system("which mn >/dev/null 2>/dev/null") != 0:
1233     #     logger.error("could not find mininet binary (mininet is not installed)")
1234     #     ret = False
1235
1236     # Assert that we have iproute installed
1237     if os.system("which ip >/dev/null 2>/dev/null") != 0:
1238         logger.error("could not find ip binary (iproute is not installed)")
1239         ret = False
1240
1241     # Assert that we have gdb installed
1242     if os.system("which gdb >/dev/null 2>/dev/null") != 0:
1243         logger.error("could not find gdb binary (gdb is not installed)")
1244         ret = False
1245
1246     # Assert that FRR utilities exist
1247     frrdir = config.get("topogen", "frrdir")
1248     if not os.path.isdir(frrdir):
1249         logger.error("could not find {} directory".format(frrdir))
1250         ret = False
1251     else:
1252         try:
1253             pwd.getpwnam("frr")[2]
1254         except KeyError:
1255             logger.warning('could not find "frr" user')
1256
1257         try:
1258             grp.getgrnam("frr")[2]
1259         except KeyError:
1260             logger.warning('could not find "frr" group')
1261
1262         try:
1263             if "frr" not in grp.getgrnam("frrvty").gr_mem:
1264                 logger.error(
1265                     '"frr" user and group exist, but user is not under "frrvty"'
1266                 )
1267         except KeyError:
1268             logger.warning('could not find "frrvty" group')
1269
1270         for fname in [
1271             "zebra",
1272             "ospfd",
1273             "ospf6d",
1274             "bgpd",
1275             "ripd",
1276             "ripngd",
1277             "isisd",
1278             "pimd",
1279             "ldpd",
1280             "pbrd",
1281         ]:
1282             path = os.path.join(frrdir, fname)
1283             if not os.path.isfile(path):
1284                 # LDPd is an exception
1285                 if fname == "ldpd":
1286                     logger.info(
1287                         "could not find {} in {}".format(fname, frrdir)
1288                         + "(LDPd tests will not run)"
1289                     )
1290                     continue
1291
1292                 logger.warning("could not find {} in {}".format(fname, frrdir))
1293                 ret = False
1294             else:
1295                 if fname != "zebra":
1296                     continue
1297
1298                 os.system("{} -v 2>&1 >{}/frr_zebra.txt".format(path, rundir))
1299
1300     # Test MPLS availability
1301     krel = platform.release()
1302     if topotest.version_cmp(krel, "4.5") < 0:
1303         logger.info(
1304             'LDPd tests will not run (have kernel "{}", but it requires 4.5)'.format(
1305                 krel
1306             )
1307         )
1308
1309     # Test for MPLS Kernel modules available
1310     if not topotest.module_present("mpls-router", load=False) != 0:
1311         logger.info("LDPd tests will not run (missing mpls-router kernel module)")
1312     if not topotest.module_present("mpls-iptunnel", load=False) != 0:
1313         logger.info("LDPd tests will not run (missing mpls-iptunnel kernel module)")
1314
1315     if not get_exabgp_cmd():
1316         logger.warning("Failed to find exabgp < 4")
1317
1318     logger.removeHandler(fhandler)
1319     fhandler.close()
1320
1321     return ret
1322
1323
1324 def diagnose_env_freebsd():
1325     return True
1326
1327
1328 def diagnose_env(rundir):
1329     if sys.platform.startswith("linux"):
1330         return diagnose_env_linux(rundir)
1331     elif sys.platform.startswith("freebsd"):
1332         return diagnose_env_freebsd()
1333
1334     return False