cleanup, documentation and enable ifupdown2 by default

Ticket: CM-1438
Reviewed By:
Testing Done:

There are a few known issues listed in the TODO and KNOWN_ISSUES files

man.rst/ifquery.8.rst

@@ -0,0 +1,94 @@
+=======
+ifquery
+=======
+
+-------------------------------------
+query network interface configuration
+-------------------------------------
+
+:Author: roopa@cumulusnetworks.com
+:Date:   2014-02-05
+:Copyright: Copyright 2014 Cumulus Networks, Inc.  All rights reserved.
+:Version: 0.1
+:Manual section: 8
+
+SYNOPSIS
+========
+    ifquery [-h] [-a] [-v] [-d] [--allow CLASS] [--with-depends]
+            [-X EXCLUDEPATS] [-r | -c | --raw]
+            [--print-dependency {list,dot}] [--syntax-help]
+            [IFACE [IFACE ...]]
+
+DESCRIPTION
+===========
+    ifquery can be used to parse interface configuration file, dump
+    running state or check running state of the interface with configuration
+    in /etc/network/interfaces file.
+
+    ifquery always works on the current interfaces(5) file
+    /etc/network/interfaces.
+
+OPTIONS
+=======
+    positional arguments:
+    IFACE                 interface list separated by spaces. IFACE list and '-a' argument are mutually exclusive.
+
+    optional arguments:
+    -h, --help            show this help message and exit
+
+    -a, --all             process all interfaces marked "auto"
+
+    -v, --verbose         verbose
+
+    -d, --debug           output debug info
+
+    --allow CLASS         ignore non-"allow-CLASS" interfaces
+
+    --with-depends        run with all dependent interfaces. This option
+                          is redundant when -a is specified. When '-a' is
+                          specified, interfaces are always executed in
+                          dependency order.
+
+    -X EXCLUDEPATS, --exclude EXCLUDEPATS
+                          Exclude interfaces from the list of interfaces to
+                          operate on. Can be specified multiple times
+
+    -r, --running         print raw interfaces file entries
+
+    -c, --check           check interface file contents against running state
+                          of an interface. Returns exit code 0 on success and
+                          1 on error
+
+    --print-dependency {list,dot} print iface dependency in list or dot format.
+
+    --syntax-help         print supported interface config syntax. Scans all
+                          addon modules and dumps supported syntax from them
+                          if provided by the module.
+
+EXAMPLES
+========
+    # dump all or some interfaces config file entries
+    # (pretty prints user provided entries)
+    ifquery -a
+    ifquery br0 
+
+    # Same as above but dump with dependencies
+    ifquery br0 --with-depends
+
+    # Check running state with the config in /etc/network/interfaces
+    ifquery --check br0
+    ifquery --check --with-depends br0 
+    ifquery --check -a         
+
+    # dump running state of all interfaces in /etc/network/interfaces format
+    ifquery --running br0
+    ifquery --running --with-depends br0
+    ifquery --running -a
+
+SEE ALSO
+========
+    ifup(8)
+    ifdown(8)
+    ifreload(8)
+    interfaces(5)
+    interfaces-addons(5)

man.rst/ifreload.8.rst

@@ -0,0 +1,62 @@
+========
+ifreload
+========
+
+--------------------------------------
+reload network interface configuration
+--------------------------------------
+
+:Author: roopa@cumulusnetworks.com
+:Date:   2014-02-05
+:Copyright: Copyright 2014 Cumulus Networks, Inc.  All rights reserved.
+:Version: 0.1
+:Manual section: 8
+
+SYNOPSIS
+========
+    ifreload [-h] [-a] [-v] [-d] [--allow CLASS] [--with-depends]
+             [-X EXCLUDEPATS] [-f] [-n] [--print-dependency {list,dot}]
+             [--down-changediface]
+             [IFACE [IFACE ...]]
+
+DESCRIPTION
+===========
+    reloads network interfaces(5) file /etc/network/interfaces.
+
+    runs ifdown on interfaces that were there previously but are no longer
+    in the interfaces file and ifup on all interfaces in the current
+    /etc/network/interfaces file.
+
+OPTIONS
+=======
+    -h, --help            show this help message and exit
+
+    -a, --all             process all interfaces marked "auto"
+
+    -v, --verbose         verbose
+
+    -d, --debug           output debug info
+
+    -f, --force           force run all operations
+
+    --down-changediface   run down and then up on interfaces that changed from
+                          the last installed version of the interfaces file.
+                          Without this option, ifup is executed on all
+                          interfaces
+                          
+
+CHEATSHEET
+==========
+    # reload /etc/network/interfaces file
+    ifreload -a
+
+    # reload all interfaces using service command
+    service networking reload
+
+SEE ALSO
+========
+    ifup(8)
+    ifdown(8)
+    ifquery(8)
+    interfaces(5)
+    interfaces-addons(5)

man.rst/ifup.8.rst

@@ -0,0 +1,132 @@
+====
+ifup
+====
+
+-------------------------------------
+network interface management commands 
+-------------------------------------
+
+:Author: roopa@cumulusnetworks.com
+:Date:   2014-02-05
+:Copyright: Copyright 2014 Cumulus Networks, Inc.  All rights reserved.
+:Version: 0.1
+:Manual section: 8
+
+NAME
+====
+    ifup - bring a network interface up
+
+    ifdown - take a network interface down
+
+SYNOPSIS
+========
+    ifup [-h] [-a] [-v] [-d] [--allow CLASS] [--with-depends]
+         [-X EXCLUDEPATS] [-f] [-n] [--print-dependency {list,dot}]
+         [IFACE [IFACE ...]]
+
+    ifdown [-h] [-a] [-v] [-d] [--allow CLASS] [--with-depends]
+           [-X EXCLUDEPATS] [-f] [-n] [--print-dependency {list,dot}]
+           [IFACE [IFACE ...]]
+
+DESCRIPTION
+===========
+    The ifup and ifdown commands may be used to configure (or, respectively,
+    deconfigure) network interfaces based on interface definitions in the
+    file /etc/network/interfaces/ file.
+
+    ifquery(8) maybe used in conjunction with ifup and ifdown commands to query
+    and validate applied/running configuration.
+
+    ifup always works on the current interfaces(5) file under
+    /etc/network/interfaces. ifdown works on the last applied interface
+    configuration.
+
+    ifup on an already ifup'ed interface will re-apply the configuration,
+    skipping already applied configuration whereever possible. In many cases
+    where config commands are idempotent, you will see that ifup/ifdown will
+    reapply the config even if the interface already has that config.
+
+    ifup and ifdown understands interface dependency order.
+
+
+OPTIONS
+=======
+    positional arguments:
+    IFACE                 interface list separated by spaces. IFACE list and '-a' argument are mutually exclusive.
+
+    optional arguments:
+    -h, --help            show this help message and exit
+
+    -a, --all             process all interfaces marked "auto"
+
+    -v, --verbose         verbose
+
+    -d, --debug           output debug info
+
+    --allow CLASS         ignore non-"allow-CLASS" interfaces
+
+    --with-depends        run with all dependent interfaces. This option
+                          is redundant when -a is specified. When '-a' is
+                          specified, interfaces are always executed in
+                          dependency order.
+                        
+
+    -X EXCLUDEPATS, --exclude EXCLUDEPATS
+                          Exclude interfaces from the list of interfaces to
+                          operate on. Can be specified multiple times
+
+    -f, --force           force run all operations
+
+    -n, --no-act          print out what would happen,but don't do it
+
+    --print-dependency {list,dot} print iface dependency in list or dot format.
+
+CHEATSHEET
+==========
+    # bringing up all interfaces
+    ifup -a
+
+    # bringing up interface list
+    ifup swp1 swp2
+
+    # bringing up interface with its dependents. 
+    ifup br0 --with-depends
+
+    # bringing down all interfaces
+    ifdown -a
+
+    # bringing down a single interface
+    ifdown swp1
+
+    # excluding interfaces using -X option
+    ifdown -X eth0 -a
+    ifup -X eth0 -a
+    ifdown -X eth0 -X lo -a
+
+    # using verbose -v option to see what is going on
+    ifup -v -a
+
+    # using debug -d option to see more of what is going on
+    ifup -d -a
+
+    # ignore errors
+    ifup -a -f
+    ifdown -a -f
+
+    # ifdown and ifup on all interfaces using service command/init script
+    service networking restart
+
+    # ifup on all interfaces using service command/init script
+    service networking start
+
+    # ifdown on all interfaces using service command/init script
+    service networking stop
+
+    # Also see ifreload(8)
+
+SEE ALSO
+========
+    ifquery(8)
+    ifreload(8)
+    interfaces(5)
+    interfaces-addons(5)

man.rst/interfaces.5.rst

@@ -0,0 +1,134 @@
+==========
+interfaces
+==========
+
+--------------------------------------------
+network interface configuration for ifupdown
+--------------------------------------------
+
+:Author: roopa@cumulusnetworks.com
+:Date:   2014-02-05
+:Copyright: Copyright 2014 Cumulus Networks, Inc.  All rights reserved.
+:Version: 0.1
+:Manual section: 5 
+
+DESCRIPTION
+===========
+    /etc/network/interfaces contains network interface configuration
+    information for the ifup(8), ifdown(8) and ifquery(8) commands.
+
+    This is where you configure how your system is connected to the network.
+
+    Lines starting with # are ignored. Note that end-of-line comments are
+    NOT supported, comments must be on a line of their own.
+
+    A line may be extended across multiple lines by making the last character
+    a backslash.
+
+    The file consists of zero or more "iface", "auto",  "allow-"
+    and "source" stanzas. Here is an example.
+
+    auto lo eth0
+    allow-hotplug eth1
+
+    iface lo inet loopback
+
+    source /etc/network/interfaces.d/machine-dependent
+
+    iface eth0-home inet static
+        address 192.168.1.1/24
+        up flush-mail
+
+    iface eth0-work inet dhcp
+
+    iface eth1 inet dhcp
+
+    Lines beginning with the word "auto" are used to identify the physical
+    interfaces to be brought up when ifup is run with the -a option.
+    (This option is used by the system boot scripts.) Physical interface names
+    should follow the word "auto" on the same line.  There can be  multiple
+    "auto"  stanzas.
+
+    Lines beginning with "allow-" are  used  to  identify  interfaces  that
+    should  be  brought  up automatically by various subsytems. This may be
+    done using a command such as "ifup --allow=hotplug  eth0  eth1",  which
+    will  only  bring up eth0 or eth1 if it is listed in an "allow-hotplug"
+    line. Note that "allow-auto" and "auto" are synonyms.
+
+    Lines beginning with "source" are used to include  stanzas  from  other
+    files, so configuration can be split into many files. The word "source"
+    is followed by the path of file to be sourced. Shell wildcards  can  be
+    used.  (See wordexp(3) for details.). Currently only supports absolute
+    path names.
+
+    ifup is normally given a physical interface name as its first non-option
+    argument. 
+
+    The interface name is followed by the name of the address family that the
+    interface uses. This will be "inet" for TCP/IP networking and inet6 for
+    ipv6. Following that is the name of the method used to configure the
+    interface.
+
+    ifupdown2 supports iface stanzas without a family or a method. This enables
+    using the same stanza for inet and inet6 family addresses.
+
+    Interface options can be given on subsequent lines in the iface stanza.
+    These options come from addon modules. see interfaces-addons(5) for
+    these options.
+
+METHODS
+=======
+    Both inet and inet6 address family interfaces can use the following
+    methods (However they are not required):
+
+    The loopback Method
+           This method may be used to define the loopback interface.
+
+    The static Method
+           This method may be used to define ethernet interfaces with
+           statically allocated addresses.
+
+    The dhcp Method
+           This method may be used to obtain an address via DHCP.
+
+BUILTIN INTERFACES
+==================
+    iface sections for some interfaces like physical interfaces or vlan
+    interfaces in dot notation (like eth1.100) are understood by ifupdown2.
+    These kind of interfaces do not need an entry in the interfaces file.
+    However, if these interfaces need extra configuration like addresses, they
+    will need to be specified.
+
+EXAMPLES
+========
+    auto lo
+    iface lo
+    address 192.168.2.0/24
+    address 2001:dee:eeee:1::4/128
+
+    auto eth0
+    iface eth0 inet dhcp
+
+    auto eth1
+    iface eth1 inet manual
+    address 192.168.2.0/24
+    address 2001:dee:eeee:1::4/128
+
+    # source files from a directory /etc/network/interfaces.d
+    # /etc/network/interfaces.d/bridge0  /etc/network/interfaces.d/bridge1
+    source /etc/network/interfaces.d/*
+
+
+    For more examples with addon config
+
+
+FILES
+=====
+    /etc/network/interfaces
+
+SEE ALSO
+========
+    interfaces-addons(5)
+    ifup(8)
+    ifquery(8)
+    ifreload(8)

pkg/ifupdownmain.py

@@ -686,6 +686,9 @@ class ifupdownMain():
         else:
             self.run_without_dependents(ops, filtered_ifacenames)
 
+        if self.DRYRUN:
+            return
+
         # Update persistant iface states
         try:
             if self.ALL:
@@ -749,6 +752,9 @@ class ifupdownMain():
         else:
             self.run_without_dependents(ops, filtered_ifacenames)
 
+        if self.DRYRUN:
+            return
+
         if loaded_newconfig:
             # Update persistant iface states
             try:
@@ -944,6 +950,9 @@ class ifupdownMain():
         else:
             self.run_without_dependents(upops, filtered_ifacenames)
 
+        if self.DRYRUN:
+            return
+
         # Update persistant iface states
         try:
             if self.ALL:

scripts/genmanpages.sh

@@ -0,0 +1,28 @@
+#!/bin/sh
+#
+# Copyright 2013 Cumulus Networks, Inc.
+# All rights reserved.
+#
+
+# Install the man pages into the sysroot
+SRC_MAN_DIR=$1
+DST_MAN_DIR=$2
+
+echo -n "Generating man pages .."
+# Loop over all the man directories
+mkdir -p $(DST_MAN_DIR)
+for p in $(ls $SRC_MAN_DIR/*.rst) ; do
+    # strip src man path
+    src_file=$p
+    dst_file=${p##.*\/}
+    dst_file="${DST_MAN_DIR}/${dst_file%.rst}"
+    # treat warnings as errors
+    rst2man --halt=2 "$p" > $dst_file || {
+        echo
+        echo "Error: problems generating man page: $p"
+        rm -f $dst_file &>/dev/null
+        exit 1
+    }
+    echo -n "."
+done
+echo " done."

setup.py

@@ -10,7 +10,9 @@ setup(name='ifupdown2',
       packages=['ifupdown'],
       scripts = ['sbin/ifupdown'],
       data_files=[('share/man/man8/',
-                      ['man/ifup.8', 'man/ifdown.8', 'man/ifquery.8']),
+                      ['man/ifup.8', 'man/ifquery.8', 'man/ifreload.8']),
+                  ('share/man/man5/',
+                      ['man/interfaces.5']),
                   ('/etc/init.d/',
                       ['init.d/networking']),
                   ('/sbin/', ['sbin/ifupdown']),