From ea230f73173e54b111cde37f3f33d8f47f2a58c1 Mon Sep 17 00:00:00 2001 From: Roopa Prabhu Date: Tue, 10 Mar 2015 13:46:08 -0700 Subject: [PATCH] Move python-ifupdown2 addons documentation into the ifupdown2 folder. --- .../docs.addons/source/developmentcorner.rst | 26 ++++++-- ifupdown2/docs/source/addonsapiref.rst | 61 ++++++++++++++++++ ifupdown2/docs/source/addonshelperapiref.rst | 44 +++++++++++++ ifupdown2/docs/source/conf.py | 4 ++ ifupdown2/docs/source/developmentcorner.rst | 63 +++++++++++++++++-- ifupdown2/docs/source/gettingstarted.rst | 10 +-- ifupdown2/docs/source/intro.rst | 33 ++++++---- 7 files changed, 213 insertions(+), 28 deletions(-) create mode 100644 ifupdown2/docs/source/addonsapiref.rst create mode 100644 ifupdown2/docs/source/addonshelperapiref.rst diff --git a/ifupdown2/docs.addons/source/developmentcorner.rst b/ifupdown2/docs.addons/source/developmentcorner.rst index be5c563..960d688 100644 --- a/ifupdown2/docs.addons/source/developmentcorner.rst +++ b/ifupdown2/docs.addons/source/developmentcorner.rst @@ -1,11 +1,26 @@ Development Corner ================== +Getting started +--------------- +Unlike original ifupdown, all interface configuration is moved to external +python modules. That includes inet, inet6 and dhcp configurations. + +* if you are looking at fixing bugs or adding new features to the ifupdown2 + infrastructure package, pls look at the apiref, documentation and code + for python-ifupdown2 + + Writing a ifupdown2 addon module -------------------------------- -ifupdown2 addon modules are part of the python-ifupdown2-addons package. -They are installed under /usr/share/ifupdownaddons directory on the target -system. +Addon modules are a nice way to add additional functionality to ifupdown2. +Typically a new addon module will include support for a new network interface +configuration which is not already supported by existing ifupdown2 addon +modules. + +ifupdown2 addon modules are written in python. python-ifupdown2 package +comes with default addon modules. All addon modules are installed under +/usr/share/ifupdownaddons directory. The center of the universe for an addon module is the 'class iface' object exported by the python-ifupdown2 package. @@ -43,9 +58,8 @@ to implement a few methods. * provide a dictionary of all supported attributes in the _modinfo attribute. This is useful for syntax help and man page generation. -python-ifupdown2-addons package also installs ifupdownaddons python package -that contains helper modules for all addon modules. Its optional for the addon -module to use this package. +python-ifupdown2 package also installs ifupdownaddons python package +that contains helper modules for all addon modules. see example address handling module /usr/share/ifupdownaddons/address.py diff --git a/ifupdown2/docs/source/addonsapiref.rst b/ifupdown2/docs/source/addonsapiref.rst new file mode 100644 index 0000000..0954d27 --- /dev/null +++ b/ifupdown2/docs/source/addonsapiref.rst @@ -0,0 +1,61 @@ +Documentation for the ifupdownaddons default addons modules +*********************************************************** + +address +======= + +.. automodule:: address + +.. autoclass:: address + :members: run, get_ops + + +bridge +====== + +.. automodule:: bridge + +.. autoclass:: bridge + :members: run, get_ops + +dhcp +==== + +.. automodule:: dhcp + +.. autoclass:: dhcp + +ethtool +======= + +.. automodule:: ethtool + +.. autoclass:: ethtool + +ifenslave +========= + +.. automodule:: ifenslave + +.. autoclass:: ifenslave + +mstpctl +======= + +.. automodule:: mstpctl + +.. autoclass:: mstpctl + +usercmds +======== + +.. automodule:: usercmds + +.. autoclass:: usercmds + +vlan +==== + +.. automodule:: vlan + +.. autoclass:: vlan diff --git a/ifupdown2/docs/source/addonshelperapiref.rst b/ifupdown2/docs/source/addonshelperapiref.rst new file mode 100644 index 0000000..01d9a41 --- /dev/null +++ b/ifupdown2/docs/source/addonshelperapiref.rst @@ -0,0 +1,44 @@ +Documentation for the ifupdownaddons package helper modules +*********************************************************** + +This package contains modules that provide helper methods +for ifupdown2 addon modules to interact directly with tools +like iproute2, brctl etc. + + +bridgeutils +=========== + +Helper module to work with bridgeutil commands + +.. automodule:: bridgeutils + +.. autoclass:: brctl + +ifenslaveutil +============= + +Helper module to interact with linux api to create bonds. +Currently this is via sysfs. + +.. automodule:: ifenslaveutil + +.. autoclass:: ifenslaveutil + +dhclient +======== + +Helper module to interact with dhclient tools. + +.. automodule:: dhclient + +.. autoclass:: dhclient + +iproute2 +======== + +Helper module to interact with iproute2 tools. + +.. automodule:: iproute2 + +.. autoclass:: iproute2 diff --git a/ifupdown2/docs/source/conf.py b/ifupdown2/docs/source/conf.py index 19cbdb2..01bc5cc 100644 --- a/ifupdown2/docs/source/conf.py +++ b/ifupdown2/docs/source/conf.py @@ -17,6 +17,10 @@ import sys, os # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../../ifupdown')) +sys.path.append(os.path.abspath('../../addons')) +sys.path.append(os.path.abspath('../../')) +sys.path.append(os.path.abspath('../../ifupdownaddons')) +sys.path.append(os.path.abspath('../../../ifupdown2')) # -- General configuration ----------------------------------------------------- diff --git a/ifupdown2/docs/source/developmentcorner.rst b/ifupdown2/docs/source/developmentcorner.rst index c4ea51b..960d688 100644 --- a/ifupdown2/docs/source/developmentcorner.rst +++ b/ifupdown2/docs/source/developmentcorner.rst @@ -1,7 +1,7 @@ Development Corner ================== -getting started +Getting started --------------- Unlike original ifupdown, all interface configuration is moved to external python modules. That includes inet, inet6 and dhcp configurations. @@ -10,12 +10,63 @@ python modules. That includes inet, inet6 and dhcp configurations. infrastructure package, pls look at the apiref, documentation and code for python-ifupdown2 -* if you are looking at developing a new module, pls look at writing a addon - module in the python-ifupdown2-addons documentation -Apiref ------- +Writing a ifupdown2 addon module +-------------------------------- +Addon modules are a nice way to add additional functionality to ifupdown2. +Typically a new addon module will include support for a new network interface +configuration which is not already supported by existing ifupdown2 addon +modules. + +ifupdown2 addon modules are written in python. python-ifupdown2 package +comes with default addon modules. All addon modules are installed under +/usr/share/ifupdownaddons directory. + +The center of the universe for an addon module is the 'class iface' object +exported by the python-ifupdown2 package. + +The iface object is modeled after an iface entry in the user provided network +configuration file (eg. /etc/network/interfaces). For more details see +the api reference for the iface class. + +ifupdown2 dynamically loads a python addon module. It expects the addon module +to implement a few methods. + +* all addon modules must inherit from moduleBase class +* the module must implement a class by the same name +* the network interface object (class iface) and the operation to be performed + is passed to the modules. Operation can be any of 'pre-up', 'up', 'post-up', + 'pre-down', 'down', 'post-down', 'query-check', 'query-running'. + The module can choose to support a subset or all operations. + In cases when the operation is query-check, the module must compare between + the given and running state and return the checked state of the object in + queryobjcur passed as argument to the run menthod. +* the python addon class must provide a few methods: + * run() : method to configure the interface. + * get_ops() : must return a list of operations it supports. + eg: 'pre-up', 'post-down' + * get_dependent_ifacenames() : must return a list of interfaces the + supported interface is dependent on. This is used to build the + dependency list for sorting and executing interfaces in dependency order. + * if the module supports -r option to ifquery, ie ability to construct the + ifaceobj from running state, it can optionally implement the + get_dependent_ifacenames_running() method, to return the list of + dependent interfaces derived from running state of the interface. + This is different from get_dependent_ifacenames() where the dependent + interfaces are derived from the interfaces config file (provided by the + user). + * provide a dictionary of all supported attributes in the _modinfo + attribute. This is useful for syntax help and man page generation. + +python-ifupdown2 package also installs ifupdownaddons python package +that contains helper modules for all addon modules. + +see example address handling module /usr/share/ifupdownaddons/address.py + +API reference +------------- .. toctree:: :maxdepth: 2 - apiref.rst + addonsapiref.rst + addonshelperapiref.rst diff --git a/ifupdown2/docs/source/gettingstarted.rst b/ifupdown2/docs/source/gettingstarted.rst index 16db725..4d7f6cb 100644 --- a/ifupdown2/docs/source/gettingstarted.rst +++ b/ifupdown2/docs/source/gettingstarted.rst @@ -5,10 +5,10 @@ Prerequisites ------------- * python-ifupdown2 is currently only tested on debian wheezy * python-ifupdown2 needs python version 2.6 or greater -* build depends on: python-stdeb (for deb builds), python-docutils (for rst2man) -* depends on python-gvgen package for printing interface graphs (this will be made optional in the future) -* optional dependency for template engine: python-mako -* python-ifupdown2 needs python-ifupdown2-addons to function correctly +* Depends on: python-stdeb (for deb builds), python-docutils + (for rst2man), python-argcomplete, 'python-ipaddr' +* Depends on python-gvgen package for printing interface graphs (this will be made optional in the future) +* Optional dependency for template engine: python-mako Building @@ -23,5 +23,5 @@ Installing ---------- install generated python-ifupdown2-.deb -$dpkg -i .deb +$dpkg -i .deb diff --git a/ifupdown2/docs/source/intro.rst b/ifupdown2/docs/source/intro.rst index d81ab95..7293e3f 100644 --- a/ifupdown2/docs/source/intro.rst +++ b/ifupdown2/docs/source/intro.rst @@ -4,17 +4,28 @@ python-ifupdown2 The python-ifupdown2 package provides the infrastructure for parsing /etc/network/interfaces file, loading, scheduling, template parsing, state management and interface dependency generation of interfaces. +It dynamically loads python addon modules from /usr/share/ifupdownmodules. +To remain compatible with other packages that depend on ifupdown, it also +executes scripts under /etc/network/. To make the transition smoother, a +python module under /usr/share/ifupdownmodules will override a script by +the same name under /etc/network/. ifupdown2 publishes an interface object which +is passed to all loadble python addon modules. All lodable modules are +called for every interface declared in the /etc/network/interfaces file. -It dynamically loads python modules from /usr/share/ifupdownmodules (provided -by the python-ifupdown2-addons package). To remain compatible with other -packages that depend on ifupdown, it also executes scripts under /etc/network/. -To make the transition smoother, a python module under -/usr/share/ifupdownmodules will override a script by the same name under -/etc/network/. +Addon modules are responsible for applying interface configuration. +python-ifupdown2 ships with a set of default addon modules. Each module can +declare its own set of supported attributes. Each module is passed the iface +object (which is a representation of /etc/network/interfaces +iface entry). Each module is also passed the operation to be performed. -It publishes an interface object which is passed to all loadble python -modules. For more details on adding a addon module, see the section on -adding python modules. +Example modules are /usr/share/ifupdownmodules/address.py, +/usr/share/ifupdownmodules/bridge.py etc + +The order in which these modules are invoked is listed in +/var/lib/ifupdownaddons/addons.conf. There is an ifaddon utility in the works +to better manage the module ordering. + +For more details on adding an addon module, see the section on adding python +modules. For details on how to write a module, see the api reference and +development documentation. -ifupdown2 module calls all modules for every interface declared in the -/etc/network/interfaces file.