ipn/README

   1 Inter Process Networking (and Kernel Virtual Distributed Ethernet)
   2 for Linux Kernel 2.6.25 and newer
   3
   4 WHAT IS IT?
   5 -----------
   6 Berkeley socket been designed for client server or point to point
   7 communication. All existing Address Families implement this idea.
   8 IPN is a new family designed for one-to-many, many-to-many and peer-to-peer
   9 communication.
  10 IPN is an Inter Process Communication paradigm where all the processes
  11 appear as they were connected by a networking bus.
  12 On IPN, processes can interoperate using real networking protocols
  13 (e.g. ethernet) but also using application defined protocols (maybe
  14 just sending ascii strings, video or audio frames, etc).
  15 IPN provides networking (in the broaden definition you can imagine) to
  16 the processes. Processes can be ethernet nodes, run their own TCP-IP stacks
  17 if they like, mount ATAonEthernet disks, etc.etc.
  18 IPN networks can be interconnected with real networks or IPN networks
  19 running on different computers can interoperate (can be connected by
  20 virtual cables).
  21 IPN is part of the Virtual Square Project (vde, lwipv6, view-os,
  22 umview/kmview, see wiki.virtualsquare.org).
  23
  24 WHY?
  25 ----
  26 Many applications can benefit from IPN.
  27 First of all VDE (Virtual Distributed Ethernet): one service of IPN is a
  28 kernel implementation of VDE.
  29 IPN can be useful for applications where one or some processes feed their
  30 data to several consuming processes (maybe joining the stream at run time).
  31 IPN sockets can be also connected to tap (tuntap) like interfaces or
  32 to real interfaces (like "brctl addif").
  33 There are specific ioctls to define a tap interface or grab an existing
  34 one.
  35 Several existing services could be implemented (and often could have extended
  36 features) on the top of IPN:
  37 - kernel bridge
  38 - tuntap
  39 - macvlan
  40 IPN could be used (IMHO) to provide multicast services to processes.
  41 Audio frames or video frames could be multiplexed such that multiple
  42 applications can use them. I think that something like Jack can be
  43 implemented on the top of IPN. Something like a VideoJack can
  44 provide videoframe to several applications: e.g. the same image from a
  45 camera can be viewed by xawtv, recorded and sent to a streaming service.
  46 IPN sockets can be used wherever there is the idea of broadcasting channel
  47 i.e. where processes can "join (and leave) the information flow".
  48 Different delivery policies can be defined as IPN protocols (loaded
  49 as submodules of ipnvde.ko).
  50 e.g. ethernet switch is a policy (kvde_switch.ko: packets are unicast
  51 delivered if the MAC address is already in the switching hash table),
  52 we are designing an extendended switch, full of interesting features like
  53 our userland vde_switch (with vlan/fst/manamement etc..), and a layer3
  54 switch, but other policies can be defined to implement the specific
  55 requirements of other services. I feel that there is no limits to creativity
  56 about multicast services for processes.
  57
  58 HOW?
  59 ----
  60 The complete specifications for IPN can be found here:
  61 http://wiki.virtualsquare.org/index.php/IPN
  62
  63 Bind create the socket (if it does not already exist). When bind succeeds,
  64 the process has the right to manage the "network".
  65 No data is received or can be send if the socket is not connected
  66 (only get/setsockopt and ioctl work on bound unconnected sockets).
  67 Connect is used to join the network. When the socket is connected it
  68 is possible to send/receive data. If the socket is already bound it is
  69 useless to specify the socket again (you can use NULL, or specify the same
  70 address).
  71 Connect can be also used without bind. In this case the process send and
  72 receive data but it cannot manage the network (in this case the socket
  73 address specification is required).
  74 Listen and Accept are for servers, thus they does not exist for IPN.
  75
  76 1- Peer-to-Peer Communication:
  77 Several processes run the same code:
  78
  79   struct sockaddr_un sun={.sun_family=AF_IPN,.sun_path="/tmp/sockipnvde"};
  80   int s=socket(AF_IPN,SOCK_RAW,IPN_BROADCAST);
  81   err=bind(s,(struct sockaddr *)&sun,sizeof(sun));
  82   err=connect(s,NULL,0);
  83
  84 In this case all the messages sent by each process get received by all the
  85 other processes (IPN_BROADCAST).
  86 The processes need to be able to receive data when there are pending packets,
  87 e.g. using poll/select and event driven programming or multithreading.
  88
  89 2- (One or) Some senders/many receivers
  90 The sender runs the following code:
  91
  92   struct sockaddr_un sun={.sun_family=AF_IPN,.sun_path="/tmp/sockipnvde"};
  93   int s=socket(AF_IPN,SOCK_RAW,IPN_BROADCAST);
  94   err=shutdown(s,SHUT_RD);
  95   err=bind(s,(struct sockaddr *)&sun,sizeof(sun));
  96   err=connect(s,NULL,0);
  97
  98 The receivers do not need to define the network, thus they skip the bind:
  99
 100   struct sockaddr_un sun={.sun_family=AF_IPN,.sun_path="/tmp/sockipnvde"};
 101   int s=socket(AF_IPN,SOCK_RAW,IPN_BROADCAST);
 102   err=shutdown(s,SHUT_WR);
 103   err=connect(s,(struct sockaddr *)&sun,sizeof(sun));
 104
 105 In the previous examples processes can send and receive every kind of
 106 data. When messages are ethernet packets (maybe from virtual machines), IPN
 107 works lile a Hub.
 108
 109 Different protocols (delivery policies) can be specified by changing
 110 IPN_BROADCAST with a different tag.
 111 A IPN protocol specific submodule must have been registered
 112 the protocol tag in advance. (e.g. when kvde_switch.ko is loaded
 113 IPN_VDESWITCH can be used too).
 114 The basic broadcasting protocol IPN_BROADCAST is built-in (all the
 115 messages get delivered to all the connected processes but the sender).
 116
 117 IPN sockets use the filesystem for naming and access control.
 118 srwxr-xr-x 1 renzo renzo 0 2007-12-04 22:28 /tmp/sockipnvde
 119 An IPN socket appear in the file like a UNIX socket.
 120 r/w permissions represent the right to receive from/send data to the
 121 socket. The 'x' permission represent the right to manage the socket.
 122 "Connect" automatically shuts down SHUT_WR or SHUT_RD if the user has not
 123 the correspondent right.
 124
 125 WHAT WE NEED FROM THE LINUX KERNEL COMMUNITY
 126 --------------------------------------------
 127 0- (Constructive) comments.
 128
 129 1- The "official" assignment of an Address Family.
 130 (It is enough for everything but interface grabbing, see 2)
 131
 132 in include/linux/net.h:
 133 - #define NPROTO          34              /* should be enough for now..  */
 134 + #define NPROTO          35              /* should be enough for now..  */
 135
 136 in include/linux/socket.h
 137 + #define AF_IPN 34
 138 + #define PF_IPN AF_IPN
 139 - #define AF_MAX          34      /* For now.. */
 140 + #define AF_MAX          35      /* For now.. */
 141
 142 This seems to be quite simple.
 143
 144 +-----
 145 |Note (2009 January): unfortunately it is not.
 146 |The Address Family #34 has been already assigned to AF_ISDN.
 147 |So, we'll continue using AF stealing of AF_NETBEI (13) until
 148 |we have an AF officially assigned. (we are not superstitious!)
 149 +-----
 150
 151 2- Another "grabbing hook" for the interface (like the ones already
 152 existing for the kernel bridge and for the macvlan).
 153
 154 In include/linux/netdevice.h:
 155 among the fields of struct net_device:
 156
 157         /* bridge stuff */
 158                                 struct net_bridge_port  *br_port;
 159                                 /* macvlan */
 160                                 struct macvlan_port     *macvlan_port;
 161 +        /* ipnvde */
 162 +        struct ipn_node        *ipn_port;
 163
 164                                 /* class/net/name entry */
 165                                 struct device           dev;
 166
 167 In net/core/dev.c, we need another "stanza" for grabbing packets....
 168 like the one defined for CONFIG_BRIDGE and CONFIG_MACVLAN.
 169 I can write the patch (it needs just tens of minutes of cut&paste).
 170 We are studying some way to register/deregister grabbing services,
 171 I feel this would be the cleanest way.
 172
 173 +-----
 174 |Note (2011 January): This issue seems to have been solved in 2.6.37
 175 | the new interface netdev_rx_handler_{register,unregister} can
 176 | be effectively used for ipn.
 177 +-----
 178
 179 WHERE?
 180 ------
 181 There is an experimental version in the VDE svn tree.
 182 WARNING/SUGGESTION: The code has not been extensively tested. It is safer
 183 to run it on virtual machines or experimental systems where a kernel panic
 184 or a forced reboot do not result in loss of data/service.
 185 The current implementation can be compiled as a module on linux >= 2.6.22.
 186 We have currently "stolen" the AF_RXRPC and the kernel bridge hook, thus
 187 this experimental implementation is incompatible with RXRPC and the kernel
 188 bridge (sharing the same data structure). This is just to show the
 189 effectiveness of the idea, in this way it can be compiled as a module
 190 without patching the kernel.
 191 We'll migrate IPN to its specific AF and grabbing hook as soon as they
 192 have been defined.
 193
 194 NOTE FOR UBUNTU USERS:
 195 If the compilation fails try:
 196 make CFLAGS="-DAPPARMOR"
 197
 198 renzo