Add flag to request discovered devices by discovery state

Also refresh the manpage to reflect the current state of nodediscover
command, and flesh out the discovery states there.

confluent_client/bin/nodediscover

@@ -191,6 +191,10 @@ def list_matching_macs(options, session):
         path += 'by-uuid/{0}/'.format(options.uuid)
     if options.type:
         path += 'by-type/{0}/'.format(options.type)
+    if options.state:
+        if options.state == 'unknown':
+            options.state = 'unidentified'
+        path += 'by-state/{0}/'.format(options.state).lower()
     if options.mac:
         path += 'by-mac/{0}'.format(options.mac)
         result = list(session.read(path))[0]
@@ -241,6 +245,9 @@ def main():
     parser.add_option('-m', '--model', dest='model',
                       help='Operate with nodes matching the specified model '
                        'number', metavar='MODEL')
+    parser.add_option('-d', '--discoverystate', dest='state',
+                      help='The discovery state of the entries (discovered, '
+                           'identified, and unidentified)')
     parser.add_option('-s', '--serial', dest='serial',
                       help='Operate against the system matching the specified '
                            'serial number', metavar='SERIAL')

confluent_client/doc/man/nodediscover.ronn

@@ -5,7 +5,9 @@ nodediscover(8)  -- List or manage confluent node discovery
 
 `nodediscover rescan`  
 `nodediscover [options] list`  
-`nodeattrib [options] assign`  
+`nodediscover [options] assign`
+`nodediscover [options] rescan`
+`nodediscover [options] clear`
 
 ## DESCRIPTION
 
@@ -22,6 +24,14 @@ data may be filtered by various parameters, as denoted in the options below.
 identity or, using `-i`, using a csv file to assign nodes all at once.  For
 example, a spreadsheet of serial numbers to desired node names could be used.
 
+**nodediscover rescan** requests the server to do an active sweep for new
+devices.  Generally every effort is made to passively detect devices as they
+become available (as they boot or are plugged in), however sometimes an active
+scan is the best approach to catch something that appears to be missing.
+
+**nodedsicover clear** requests the server forget about a selection of
+detected device.  It takes the same arguments as **nodediscover list**.
+
 ## CSV FORMAT
 
 The CSV format used by nodediscover consists of one header describing the
@@ -67,8 +77,22 @@ the nodes.
   address
 * `-t TYPE, --type=TYPE`:
   Operate against the system of the specified type
-* `-c, --csv`:
+* `-c`, ``--csv`:
   Use CSV formatted output
+* `-d`, `--discoverystate`:
+  Indicate devices with a particular state.  The states are:
+     * discovered - The device has been identified and has also had discovery
+                    activities performed, including any relevant certificate
+                    exchanges and deploying user and network configuration.
+     * identified - The device has been identified as to what node it is
+                    supposed to be, however no active changes to the attributes
+                    or device configuration has been performed.  This is
+                    generally discovery awaiting approval due to
+                    discovery.policy specifying a strict security model.
+     * unidentified - A device has been sensed, but no node identity has been
+                     established at all.  It provides data that can be used
+                     for nodediscover assign, as well as current IP addresses
+                     that can be used for manual efforts as possible.
 * `-i IMPORT.CSV`, `--import=IMPORT.CSV`:
   Import bulk assignment data from given CSV file