ifupdown2-addons/docs/source/developmentcorner.rst

   1 Development Corner
   2 ==================
   3
   4 Writing a ifupdown2 addon module
   5 --------------------------------
   6 ifupdown2 addon modules are part of the python-ifupdown2 package.
   7 They are installed under /usr/share/ifupdownaddons directory on the target box.
   8
   9 The center of the universe for an addon module is the 'class iface' object
  10 exported by the python-ifupdown2 package.
  11
  12 The iface object contains all config the user wanted. For more details see
  13 the api refernce for the iface class.
  14
  15 ifupdown2 invokes the addon module by invoking a few methods. And hence
  16 it expects a few interfaces from the addon modules.
  17
  18 * all modules must inherit from moduleBase class
  19 * the module should implement a class by the same name
  20 * the interface object (class iface) and the operation to be performed is
  21   passed to the modules. In cases when the operation is query-check, where
  22   the module has to compare between the given and running state, the module
  23   also takes an addional queryobjcur iface object
  24 * the python addon class should provide a few methods:
  25     * run() : method to configure the interface.
  26     * get_ops() : must return a list of operations it supports.
  27       eg: 'pre-up', 'post-down'
  28     * get_dependent_ifacenames() : must return a list of interfaces the
  29       interface is dependent on. This is used to build the dependency list
  30       for sorting and executing interfaces in dependency order.
  31     * if the module supports -r option to ifquery, ie ability to construct the
  32       ifaceobj from running state, it can optionally implement the
  33       get_dependent_ifacenames_running() method, to return the list of
  34       dependent interfaces derived from running state of the interface.
  35       This is different from get_dependent_ifacenames() where the dependent
  36       interfaces are derived from the interfaces config file (provided by the
  37       user).
  38     * provide a dictionary of all supported attributes in the _modinfo
  39       attribute. This is useful for syntax help and man page generation.
  40
  41 python-ifupdown2 package also installs a ifupdownaddons python package that
  42 contains helper modules for all addon modules.
  43
  44 see example address handling module /usr/share/ifupdownaddons/address.py
  45
  46 apiref
  47 ------
  48 .. toctree::
  49    :maxdepth: 2
  50
  51    addonsapiref.rst
  52    addonshelperapiref.rst