start of a README.md to explain how to use the project.

README.md

@@ -0,0 +1,95 @@
+vlanmang
+========
+
+There are two parts to the tool.  The first part is the SNMPSwitch class.
+The second part is the configuration sync part.
+
+The SNMPSwitch class is used to configure the switch, such as creating
+VLANs (todo) and configuring what parts belong to which VLANs.
+
+The configuration sync part is done in two steps, first is to collect
+the differences between what the configuration is and what it should
+be.  This is done by the function checkchanges.  This function generates
+a list of changes that need to be made to the switches to make them match
+what is configured.  Then the second part, which is implemented as part
+of the main function, is to apply those changes.
+
+Usage
+-----
+
+The vlanmang command will import the Python module named data, aka
+`data.py`.  The easiest way is if there is a file named data.py in the
+current directory, if there is, it will use that.  Note that this file is
+run as Python code, so it can write files, read files, or any thing else
+that a Python program can do.  This means that putting untrusted data
+from users should never be done unless properly escaped, or handled
+appropriately.
+
+The file consists of declarations of how the switches should be
+configured, and the credentials necessary to verify configuration and
+make the necessary changes.  One slightly unusual part of the tool is
+that you have to declare ports that you do not care about.  This is to
+help ensure that you have a configuration specified for all the ports you
+care about, not just some of them.  The common ports you will ignore are
+cpu interfaces and extra lag interfaces.  You can specify the ports by
+the names the switch knows them by (the ifName column in SNMP) for
+convience, or they can be specified by their index in ifTable.
+
+Example
+-------
+
+Here is an example data.py file:
+```
+import vlanmang
+from pysnmp.hlapi import usmDESPrivProtocol
+
+# VLANs
+base = 1
+guest = 23
+dmz = 58
+
+# Range inclusive of the end points
+def rng(s, e):
+	return range(s, e + 1)
+
+lag1 = 'ch1'	# sometimes switches don't give useful names
+
+switchvlans = {
+	base:	{
+		'u':	rng(1, 10),
+		't':	lag1,
+	},
+	guest:	{
+		'u':	rng(11, 19),
+		't':	lag1,
+	},
+	dmz:	{
+		'u':	rng(20, 24),
+		't':	lag1,
+	},
+
+# You can put your passwords in another file for security
+from passwords import switchvlankey
+
+# Use SNMPv3, defaulting to SHA1 auth and DES encryption, the best
+# supported by NetGear switches.
+authdata = dict(username='admin', authKey=key, privKey=key,
+    privProtocol=usmDESPrivProtocol)
+
+switch = vlanmang.SwitchConfig('203.0.113.10', authdata, switchvlangs,
+	rng(25,26) + # part of lag1
+	[ 'ch%d' % x for x in rng(2,8) ] # ignore the extra lag interfaces
+)
+```
+
+Once that file is created and in the current directory, simply run the
+program `vlanmang`, and it will query the switch and print out a list of
+changes that need to be made to the switch to make it match the
+configuration specified.  If the changes look correct, type the entire
+word `yes` in, and press enter and the necessary changes will be made.
+
+The `NOTES.md` file has notes about dealing with particular switches.
+Please consult this if you are having troubles.  Just because a switch
+isn't listed doesn't mean it doesn't have any issues, it is likely that
+it has not be tested, or if it has, the information has not been
+submitted for inclusion.