feat(src): add start/stop functionality via API

Start and stop commands allow to control network the networking
activities without starting and stopping the program.

see #63

README.md

@@ -132,6 +132,11 @@ below for details.
      Restrict to the given address family. If both options are specified no
      addreses will be available and wsdd will exit.
 
+ * `-A`, `--no-autostart`
+     Do not start networking activities automatically when the program is started.
+	 The API interface (see man page) can be used to start and stop the
+	 networking activities while the application is running.
+
  * `-c DIRECTORY`, `--chroot DIRECTORY`
 
      Chroot into a separate directory to prevent access to other directories of
@@ -156,6 +161,11 @@ below for details.
      This option also accepts IP addresses that the service should bind to.
      For IPv6, only link local addresses are actually considered as noted above.
 
+ * `-l PATH/PORT`, `--listen PATH/PORT`
+	 Enable the API server on the with a Unix domain socket on the given PATH
+	 or a local TCP socket bound to the given PORT. Refer to the man page for
+	 details on the API.
+
  * `-s`, `--shortlog`
 
      Use a shorter logging format that only includes the level and message.
@@ -242,8 +252,6 @@ This mode allows to search for other WSD-compatible devices.
 	 option) can be used for a programatic interface. Refer to the man page for
 	 details of the API.
 
- * `-l PATH/PORT`, `--listen PATH/PORT`
-
 
 ## Example Usage
 

man/wsdd.1

@@ -24,6 +24,11 @@ See below.
 Restrict to the given address family. If both options are specified no
 addreses will be available and wsdd will exit.
 .TP
+\fB\-A\fR, \fB\-\-no-autostart\fR
+Do not start networking activities automatically when the program is started.
+The API interface (see below) can be used to start and stop the networking
+activities while the application is running.
+.TP
 \fB\-c \fIDIRECTORY\fR, \fB\-\-chroot \fIDIRECTORY\fR
 chroot into the given \fIDIRECTORY\fR after initialization has been performed
 and right before the handling of incoming messages starts. The new root directory
@@ -147,24 +152,19 @@ Traffic for the following ports, directions and addresses must be allowed:
 .PP
 You should further restrict the traffic to the (link-)local subnet, e.g. by
 using the `fe80::/10` address space for IPv6.
-.SH SERVER INTERFACE
-When the discovery mode is used, wsdd provides a text-based line-oriented
-server interface to query information and trigger actions. The interface can be
-used with TCP and UNIX domain sockets (see above). The TCP socket is bound to
-the local host only. The following commands can be issued:
-.SS probe - Search for devices
-\fBprobe \fI[INTERFACE]\fR
-
-Triggers a Probe message on the provided INTERFACE (eth0, e.g.) to search for
-WSD hosts. If no interface is provided, all interfaces wsdd listens on are probed.
-A Probe messages initiates the discovery message flow. It may take some time for
-hosts to be actually discovered. This command does not return any data.
-.SS list - List discovered devices
-\fBlist\fR
-
+.SH API INTERFACE
+Wsdd provides a text-based, line-oriented API interface to query information
+and trigger actions. The interface can be used with TCP and UNIX domain sockets
+(see \fB\-l/\-\-listen\fR option). The TCP socket is bound to the local host
+only. The following commands can be issued:
+.SS \fBclear\fR - Clear list of discovered devices
+Clears the list of all discovered devices. Use the \fBprobe\fR command to
+search for devices again. This command does not return any data and is only
+available in discover mode.
+.SS \fBlist\fR - List discovered devices
 Returns a tab-separated list of discovered devices with the following information.
 The possibly empty list of detected hosts is always terminated with a single
-dot ('.') in an otherwise empty line.
+dot ('.') in an otherwise empty line. This command is only available in discover mode.
 .TP
 UUID
 UUID of the discovered device. Note that a multi-homed device should appear
@@ -189,10 +189,24 @@ process delimited by commas.  Addresses are provided along with the interface
 (separated by '%') on which they were discovered.  IPv6 addresses are reported
 on square brackets. Note that the reported addresses may not match the actual
 device on which the device may be reached.
+.SS \fBprobe \fI[INTERFACE]\fR - Search for devices
+Triggers a Probe message on the provided INTERFACE (eth0, e.g.) to search for
+WSD hosts. If no interface is provided, all interfaces wsdd listens on are probed.
+A Probe messages initiates the discovery message flow. It may take some time for
+hosts to be actually discovered. This command does not return any data and is
+only available in discovery mode.
+.SS \fBstart\fR - Start networking activities
+This command starts the networking acitivies of wsdd if they haven't been
+started yet. "Hello" messages are emitted and the host is announced on the
+network(s) when the host mode is active. If the discovery mode is enabled a
+probe process is also started.
+
+.SS \fBstop\fR - Stop networking activities
+This is the reverse operation to start. When this command is received, "Bye"
+messages are sent in order to notify hosts in the network about the host's
+disappearance. All networking sockets used for the WSD protocol are closed as
+well. Activities can be restarted with the start operation.
 
-.SS clear - Clear list of discovered devices \fBclear\fR
-Clears the list of all discovered devices. Use the \fBprobe\fR command to search
-for devices again. This command does not return any data.
 .SH SECURITY
 .PP
 wsdd does not implement any security feature, e.g. by using TLS for the http

src/wsdd.py

@@ -956,18 +956,23 @@ def handle_command(self, line, write_stream):
             return
 
         command = words[0]
-        args = words[1:]
-        if command == 'probe':
-            intf = args[0] if args else None
+        command_args = words[1:]
+        if command_args == 'probe' and args.discovery:
+            intf = command_args[0] if command_args else None
             logger.debug('probing devices on {} upon request'.format(intf))
             for client in self.get_clients_by_interface(intf):
                 client.send_probe()
-        elif command == 'clear':
+        elif command == 'clear' and args.discovery:
             logger.debug('clearing list of known devices')
-        elif command == 'list':
+            WSDDiscoveredDevice.instances.clear()
+        elif command == 'list' and args.discovery:
             write_stream.write(bytes(self.get_list_reply(), 'utf-8'))
         elif command == 'quit':
             write_stream.close()
+        elif command == 'start':
+            self.address_monitor.enumerate()
+        elif command == 'stop':
+            self.address_monitor.teardown()
         else:
             logger.debug('could not handle API request: {}'.format(line))
 
@@ -1008,9 +1013,10 @@ def __init__(self, name, scope):
 
 class MetaEnumAfterInit(type):
 
-    def __call__(cls, *args, **kwargs):
-        obj = super().__call__(*args, **kwargs)
-        obj.enumerate()
+    def __call__(cls, *cargs, **kwargs):
+        obj = super().__call__(*cargs, **kwargs)
+        if not args.no_autostart:
+            obj.enumerate()
         return obj
 
 
@@ -1536,6 +1542,10 @@ def parse_args():
         '-w', '--workgroup',
         help='set workgroup name (default WORKGROUP)',
         default='WORKGROUP')
+    parser.add_argument(
+        '-A', '--no-autostart',
+        help='do not start networking after launch',
+        action='store_true')
     parser.add_argument(
         '-t', '--no-http',
         help='disable http service (for debugging, e.g.)',
@@ -1677,13 +1687,6 @@ def drop_privileges(uid, gid):
 def main():
     parse_args()
 
-    if not args.discovery and args.listen:
-        logger.warning('Listen option ignored since discovery is disabled.')
-    elif args.discovery and not args.listen:
-        logger.warning('Discovery enabled but no listen option provided. '
-                       'Falling back to port {}'.format(WSDD_LISTEN_PORT))
-        args.listen = WSDD_LISTEN_PORT
-
     if args.ipv4only and args.ipv6only:
         logger.error('Listening to no IP address family.')
         return 4