like iproute2, brctl etc.
-bridgeutils.py
-==============
+bridgeutils
+===========
Helper module to work with bridgeutil commands
.. autoclass:: brctl
-ifenslaveutil.py
-================
+ifenslaveutil
+=============
Helper module to interact with linux api to create bonds.
Currently this is via sysfs.
.. autoclass:: ifenslaveutil
-dhclient.py
-===========
+dhclient
+========
Helper module to interact with dhclient tools.
.. autoclass:: dhclient
-iproute2.py
-===========
+iproute2
+========
Helper module to interact with iproute2 tools.
# -*- coding: utf-8 -*-
#
-# ifupdown2 documentation build configuration file, created by
-# sphinx-quickstart on Sun Jul 6 23:49:20 2014.
+# ifupdown2-addons documentation build configuration file, created by
+# sphinx-quickstart on Mon Jul 21 11:17:17 2014.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# If extensions (or modules to document with autodoc) are in another directory,
# 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('.'))
+
sys.path.insert(0, os.path.abspath('../../addons'))
sys.path.append(os.path.abspath('../../'))
sys.path.append(os.path.abspath('../../ifupdownaddons'))
sys.path.append(os.path.abspath('../../../ifupdown2'))
-#sys.path.insert(0, os.path.abspath('/work/monster-03/roopa/cumulus-2.1-multimac/packages/ifupdown2-addons/pkg'))
-#sys.path.append(os.path.abspath('/work/monster-03/roopa/cumulus-2.1-multimac/packages/ifupdown2/pkg'))
-#sys.path.append(os.path.abspath('/work/monster-03/roopa/cumulus-2.1-multimac/packages/ifupdown2/'))
-
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo']
+extensions = ['sphinx.ext.autodoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
#html_file_suffix = None
# Output file base name for HTML help builder.
-htmlhelp_basename = 'ifupdown2doc'
+htmlhelp_basename = 'ifupdown2-addonsdoc'
# -- Options for LaTeX output --------------------------------------------------
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
- ('index', 'ifupdown2.tex', u'ifupdown2 Documentation',
+ ('index', 'ifupdown2-addons.tex', u'ifupdown2-addons Documentation',
u'Roopa Prabhu', 'manual'),
]
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'ifupdown2', u'ifupdown2 Documentation',
+ ('index', 'ifupdown2-addons', u'ifupdown2-addons Documentation',
[u'Roopa Prabhu'], 1)
]
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'ifupdown2', u'ifupdown2 Documentation',
- u'Roopa Prabhu', 'ifupdown2', 'One line description of project.',
+ ('index', 'ifupdown2-addons', u'ifupdown2-addons Documentation',
+ u'Roopa Prabhu', 'ifupdown2-addons', 'One line description of project.',
'Miscellaneous'),
]
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
Writing a ifupdown2 addon module
--------------------------------
-ifupdown2 addon modules are part of the python-ifupdown2 package.
-They are installed under /usr/share/ifupdownaddons directory on the target box.
+ifupdown2 addon modules are part of the python-ifupdown2-addons package.
+They are installed under /usr/share/ifupdownaddons directory on the target
+system.
The center of the universe for an addon module is the 'class iface' object
exported by the python-ifupdown2 package.
-The iface object contains all config the user wanted. For more details see
-the api refernce for the iface class.
-
-ifupdown2 invokes the addon module by invoking a few methods. And hence
-it expects a few interfaces from the addon modules.
-
-* all modules must inherit from moduleBase class
-* the module should implement a class by the same name
-* the interface object (class iface) and the operation to be performed is
- passed to the modules. In cases when the operation is query-check, where
- the module has to compare between the given and running state, the module
- also takes an addional queryobjcur iface object
-* the python addon class should provide a few methods:
+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
- interface is dependent on. This is used to build the dependency list
- for sorting and executing interfaces in dependency order.
+ 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
* 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 a ifupdownaddons python package that
-contains helper modules for all addon modules.
+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.
see example address handling module /usr/share/ifupdownaddons/address.py
-apiref
-------
+API reference
+-------------
.. toctree::
:maxdepth: 2
Prerequisites
-------------
-* python-ifupdown2 is current only tested on a debian release wheezy or greater
-* python-ifupdown2 needs python version 2.6 or greater
+* python-ifupdown2-addons is currently only tested on debian wheezy
+* python-ifupdown2-addons 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 soon)
+* 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-addons has an install dependency on python-ifupdown2
Building
--------
-git clone <ifupdown2 git url>
-cd ifupdown2-addons
-./build.sh
+$git clone <ifupdown2 git url> ifupdown2
+
+$cd ifupdown2/ifupdown2-addons
+
+$./build.sh
Installing
----------
-install generated python-ifupdown2-addons-<ver>.deb
+install generated python-ifupdown2-addons-<ver>.deb using dpkg
+
+$dpkg -i <python-ifupdown2-addons-<ver>.deb
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to ifupdown2's documentation!
-=====================================
+Welcome to ifupdown2-addons documentation!
+==========================================
Contents:
=========
Prerequisites
-------------
-* python-ifupdown2 is current only tested on a debian release wheezy or greater
+* 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 soon)
+* 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
Building
--------
-git clone <ifupdown2 git url>
-cd ifupdown2
-./build.sh
+$git clone <ifupdown2 git url> ifupdown2
+$cd ifupdown2/ifupdown2
+
+$./build.sh
Installing
----------
install generated python-ifupdown2-<ver>.deb
+
+$dpkg -i <python-ifupdown2-addons-<ver>.deb
+