.. automodule:: netdumplings

Overview
========

netdumplings allows you to run multiple packet sniffers on any number of hosts.
Those sniffers -- called **dumpling kitchens** -- pass any sniffed network
packets to your Python code for processing. Your Python code is implemented as
classes called **dumpling chefs** which use the network packets to generate
**dumplings**. Dumpling contents are entirely up to you but they'll usually
describe the information contained in the sniffed network packets.

The dumplings created by the dumpling chefs are sent from the dumpling kitchens
to a single **dumpling hub**, which forwards them on to any connected
**dumpling eaters** for display or for any other sort of processing or
visualization.

The **kitchens**, **chefs**, **dumplings**, **hub**, and **eaters**, are shown
below. You write the bits in green (the chefs and eaters) and netdumplings
does the rest:

.. image:: ../_static/overview.svg
   :align: center

Dumplings are sent between the kitchens, hub, and eaters, over WebSockets.

.. Note::
   Every network packet sniffed by a single kitchen is passed to every chef
   registered with that kitchen. Also, every dumpling sent to the hub is
   forwarded on to every connected eater. Any packet filtering should be done
   by the kitchen's PCAP filter (see the ``--filter`` flag to ``nd-sniff``) or
   by the chef implementation. Eaters can also filter out dumplings they don't
   care about.

Dumpling chefs are written in Python by subclassing :class:`DumplingChef`.
Dumpling eaters can be written in any language but netdumplings provides the
:class:`DumplingEater` convenience class for writing them in Python.

Dumpling kitchens are started with the ``nd-sniff`` commandline tool (which is
told where to find the chefs), and the hub is started with the ``nd-hub``
commandline tool.

Even though the above diagram shows everything running on different hosts, you
can instead run everything on the same host if that better suits your needs.

What does a dumpling look like?
-------------------------------

Dumplings are just JSON data. Following is an example dumpling created from the
work of a chef which takes every network packet it's given and maintains a
count of packets by protocol: ::

    {
        "metadata": {
            "chef": "PacketCountChef",
            "creation_time": 1515990765.925951,
            "driver": "interval",
            "kitchen": "default_kitchen"

        },
        "payload": {
            "packet_counts": {
                "Ethernet": 1426745,
                "IP": 1423352,
                "TCP": 12382,
                "UDP": 1413268
            }
        }
    }

The ``payload`` section is generated by the dumpling chef and the ``metadata``
section is created automatically when the dumpling is sent to the hub by the
kitchen.

See the `PacketCountChef`_ source code to see how the above dumpling is
created.

What's in the box?
------------------

netdumplings comes with:

* The packet sniffer kitchen commandline tool ``nd-sniff``
* The dumpling hub commandline tool ``nd-hub``
* Sample dumpling chefs in the ``netdumplings.dumplingchefs`` module
* Sample dumpling eater commandline tools ``nd-print``, ``nd-hubdetails``, and
  ``nd-hubstatus``
* Classes to help you write your own chefs and eaters: :class:`DumplingChef`
  and :class:`DumplingEater`

There's enough in the installation package to get started without writing any
code, but to get the most out of netdumplings you'll write your own chefs and
eaters.


.. _PacketCountChef: https://github.com/mjoblin/netdumplings/blob/master/netdumplings/dumplingchefs/packetcountchef.py