docs/source/developmentcorner.rst

   1 Development Corner
   2 ==================
   3
   4 Getting started
   5 ---------------
   6 Unlike original ifupdown, all interface configuration is moved to external
   7 python modules. That includes inet, inet6 and dhcp configurations.
   8
   9 * if you are looking at fixing bugs or adding new features to the ifupdown2
  10   infrastructure package, pls look at the apiref, documentation and code
  11   for python-ifupdown2
  12
  13
  14 Writing a ifupdown2 addon module
  15 --------------------------------
  16 Addon modules are a nice way to add additional functionality to ifupdown2.
  17 Typically a new addon module will include support for a new network interface
  18 configuration which is not already supported by existing ifupdown2 addon
  19 modules.
  20
  21 ifupdown2 addon modules are written in python. python-ifupdown2 package
  22 comes with default addon modules. All addon modules are installed under
  23 /usr/share/ifupdownaddons directory.
  24
  25 The center of the universe for an addon module is the 'class iface' object
  26 exported by the python-ifupdown2 package.
  27
  28 The iface object is modeled after an iface entry in the user provided network
  29 configuration file (eg. /etc/network/interfaces). For more details see
  30 the api reference for the iface class.
  31
  32 ifupdown2 dynamically loads a python addon module. It expects the addon module
  33 to implement a few methods.
  34
  35 * all addon modules must inherit from moduleBase class
  36 * the module must implement a class by the same name
  37 * the network interface object (class iface) and the operation to be performed
  38   is passed to the modules. Operation can be any of 'pre-up', 'up', 'post-up',
  39   'pre-down', 'down', 'post-down', 'query-check', 'query-running'.
  40   The module can choose to support a subset or all operations.
  41   In cases when the operation is query-check, the module must compare between
  42   the given and running state and return the checked state of the object in
  43   queryobjcur passed as argument to the run menthod.
  44 * the python addon class must provide a few methods:
  45     * run() : method to configure the interface.
  46     * get_ops() : must return a list of operations it supports.
  47       eg: 'pre-up', 'post-down'
  48     * get_dependent_ifacenames() : must return a list of interfaces the
  49       supported interface is dependent on. This is used to build the
  50       dependency list for sorting and executing interfaces in dependency order.
  51     * if the module supports -r option to ifquery, ie ability to construct the
  52       ifaceobj from running state, it can optionally implement the
  53       get_dependent_ifacenames_running() method, to return the list of
  54       dependent interfaces derived from running state of the interface.
  55       This is different from get_dependent_ifacenames() where the dependent
  56       interfaces are derived from the interfaces config file (provided by the
  57       user).
  58     * provide a dictionary of all supported attributes in the _modinfo
  59       attribute. This is useful for syntax help and man page generation.
  60
  61 python-ifupdown2 package also installs ifupdownaddons python package
  62 that contains helper modules for all addon modules.
  63
  64 see example address handling module /usr/share/ifupdownaddons/address.py
  65
  66 API reference
  67 -------------
  68 .. toctree::
  69    :maxdepth: 2
  70
  71    addonsapiref.rst
  72    addonshelperapiref.rst