MLD version 2 kernel implementation (rel. 20040504) 1. Introduction This is a host-side implementation of MLD version 2 applied to NetBSD-current kernel (as of 04/May/2004). This implementation supports following RFC and I-D. "Multicast Listener Discovery Version 2 (MLDv2) for IPv6", RFC3810. "Socket Interface Extensions for Multicast Source Filters", draft-ietf-magma-msf-api-03.txt. MLDv2 provides Source-Specific Multicast (SSM) architecture within IPv6 network. Since the spec of MLDv2, especially the state transition part of source address filtering produced by each application, is fairly complex, this modification causes significant kernel change. Before you apply this patch, please read "2. At the Beginning" and "6. Attention" section carefully. And we strongly recommend you to take backup before you begin. IGMPv3 and MLDv2 host-side implementations for FreeBSD 4.9-RELEASE, NetBSD 1.6.2 and OpenBSD 3.4 are available on KAME-snapshot: . 2. At the Beginning This kernel patch requires IGMPv3 kernel implementation, since IGMPv3 and MLDv2 have a lot of common procedures, and these are shared based on the concept of Protocol-Independent Programming. Therefore, before you apply this kernel patch, you MUST APPLY BOTH OF kernel and command patch for IGMPv3 Host-side Implementation, which is available on; 3. Installation (hereafter, BSDSRCDIR=/usr/src is assumed.) 3-1. Kernel Installation 1) Untar this package under proper directory. (e.g. $HOME) 2) Su to root and apply kernel patch. % su Password: # cd /usr/src # patch -p < $HOME/mldv2-20040504/kernel.patch Before applying this patch, you may want to backup original sys/netinet directory. 3) Edit your kernel configuration file to enable MLDv2. options MLDV2 4) (option) If you'd like to get some debug message, configure debug option. options MLDV2_DEBUG Note that debug message may be a little noisy but useful. 5) Recompile your kernel, install it, and reboot. Note that you are not obliged to enable IGMPv3 here, while you must apply IGMPv3 kernel patch before applying MLDv2 kernel and command patches. 3-2. Command Installation 3-2-1. mld6query and sysctl o. Setup 0) Kernel must be updated by 3-1's procedure. 1) Untar this package under proper directory. (e.g. $HOME) 2) Su to root and apply kernel patch. % su Password: # cd /usr/src # patch -p < $HOME/mldv2-20040504/command.patch 3) make includes to copy new header files under /usr/include. # cd /usr/src # make includes 4) make and make install new netstat and sysctl # cd /usr/src/usr.sbin/mld6query # make; make install # cd /usr/src/sbin/sysctl # make; make install *OR* 0) same of above 1) same of above 2) same of above 3) Do make build (or execute build.sh). o. Usage After applying this patch, this box can work with any multicast router, which speaks MLDv1/v2. (See "5-1. Compatibility with Older Versions of MLD" section.) So, monitoring above query counts are useful to recognize this box'es current MLD Report version. New "sysctl" newly controls following values. net.inet6.icmp6.mld_maxsrcfilter net.inet6.icmp6.mld_somaxsrc net.inet6.icmp6.mld_always_v2 % sysctl net.inet6.icmp6.mld_maxsrcfilter If this returns 128, then kernel can keep this number of source addresses per one multicast group address as maximum. [default: IP_MAX_SOURCE_FILTER=128] % sysctl net.inet6.icmp6.mld_somaxsrc If this returns 64, then each application can setup this number of source addresses per one multicast group address as maximum. [default: SO_MAX_SOURCE_FILTER=64] % sysctl net.inet6.icmp6.mld_always_v2 If this returns 0, then kernel maintains Host Compatibility Mode mentioned in an MLDv2 Spec. If this returnes 1, then kernel ignores v1 Query General Query messages and doesn't maintain Host compatibility Mode. It always behave as MLDv2 node. See "5-1-2. Static Configuration" section more detail. [default: 0] 3-2-2. vmstat update o. Setup 0) Kernel must be updated by 3-1's procedure. And it is assumed you already executed make includes to copy new header files under /usr/include. 1) make and make install new vmstat. # cd /usr/src/usr.bin/vmstat # make; make install *OR* 0) If you already did make build or executed build.sh for new netstat and sysctl, nothing is needed for new vmstat. o. Usage New "vmstat -m" will show current memory usage of "msfilter". This msfilter indicates a total size of MSFs managed by kernel. Per socket, "ip_moptions" indicates a total size of each multicast address assignment regularly and of each MSF newly. 4. MLDv2 Default Values Followings are main timers/counters, default values, and controls used by MLDv2. variable default value control ------------------------- ------------------ ------------- Robustness Variable 2 Query message Query Interval 125 (125 sec.) mrouter Query Responce Interval 10000 (10 sec.) Query message (Max Responce Delay) Unsolicited Report Interval 1 (1 sec.) N/A (constant) (intervals for State-Change Report retransmission) Max Source Filter (per group) 128 sysctl Max Source Filter (per socket) 64 sysctl 5. Techinical Note 5-1. Compatibility with Older Versions of MLD 5-1-1. Normal Behavior (Dynamic State Transition) This modification interoperates with applications and routers that have not yet been upgraded to MLDv2. This compatibility provides appropriate actions depending on the versions of multicast applications and on upstream routers routers within a network. So, after the modification of your kernel, you can continuously use existing applications if you'd keep using them as MLDv1 capable applications. Also, you can communicate any multicast router speaking MLDv1/v2, since modified kernel sends same version's MLD report according to the Query message. If an upstream router speaks MLDv1 and sends v1 Query, then this box sends MLD report messages using v1 format. If the upstream router changes to speak MLDv2, or another MLDv2 capable router becomes Querier, this box can gracefully change to speak v2. 5-1-2. Static Configuration In some cases, above scheme, "the kernel dynamically provides Host Compatibility Mode and transits the state, based on receiving Query messages", might be meddlesome. If you are sure that the box is attached to MLDv2 LAN, in other words, that correct upstream router(s) must be MLDv2 capable, then it may be better to setup MLD's version spoken by the box to v2 statically. ( may be useful for the information.) After this static configuration is done, any old MLD Query message doesn't affect to change the compatibility mode. Remember this is useful only when correct upstream router(s) must be MLDv2 capable and you want to filter out or ignore some bogus or unneeded old version's Report and Query messages transfered by irregular nodes. This configuration affects all interfaces of the box. Note that this configuration is turned off as the kernel's default value. 5-2. MLDv2 APIs' Semantics This implementation fully supports all of APIs described in the API draft. They can be classified as follows. o. Protocol-Independent Multicast Source Filter APIs o. Basic (Delta-based) o. Advanced (Full-state) Application can use all of them using setsockopt() for Basic APIs or ioctl() for Advanced APIs as it wants. However, kernel may return error if the combination of previous and following source filter requests is not suitable. Now, for you to understand valid API combinations easily, we'd describe sample semantics table for "Basic IPv4 Multicast Source Filter APIs" as below. previous request following request return ----------------- ----------------- ----------- MCAST_JOIN_GROUP MCAST_JOIN_GROUP EADDRINUSE MCAST_JOIN_GROUP MCAST_LEAVE_GROUP 0 MCAST_JOIN_GROUP MCAST_JOIN_SOURCE_GROUP EINVAL MCAST_JOIN_GROUP MCAST_LEAVE_SOURCE_GROUP EINVAL MCAST_JOIN_GROUP MCAST_BLOCK_SOURCE 0 MCAST_JOIN_SOURCE_GROUP MCAST_JOIN_GROUP EADDRINUSE MCAST_JOIN_SOURCE_GROUP MCAST_LEAVE_GROUP 0 MCAST_JOIN_SOURCE_GROUP MCAST_JOIN_SOURCE_GROUP (*1) MCAST_JOIN_SOURCE_GROUP MCAST_LEAVE_SOURCE_GROUP (*2) MCAST_JOIN_SOURCE_GROUP MCAST_BLOCK_SOURCE EINVAL MCAST_JOIN_SOURCE_GROUP MCAST_UNBLOCK_SOURCE EINVAL MCAST_BLOCK_SOURCE MCAST_JOIN_GROUP EADDRINUSE MCAST_BLOCK_SOURCE MCAST_LEAVE_GROUP 0 MCAST_BLOCK_SOURCE MCAST_JOIN_SOURCE_GROUP EINVAL MCAST_BLOCK_SOURCE MCAST_LEAVE_SOURCE_GROUP EINVAL MCAST_BLOCK_SOURCE MCAST_BLOCK_SOURCE (*1) MCAST_BLOCK_SOURCE MCAST_UNBLOCK_SOURCE (*2) (*1) EADDRNOTAVAIL if source address is same of filtered one. Otherwise 0. (*2) EADDRNOTAVAIL if source address is not same of filtered one. Otherwise 0. With the Advanced APIs, the legality is not dependent on the previous state, since new request overwrites previous filtering condition. So, only the case that Advanced APIs return error is previous request and following request are completely same. See below. e.g. previous request following request return ----------------- ----------------- ----------- INCLUDE{a,b} INCLUDE{a,b} error INCLUDE{a,b} INCLUDE{a} not error INCLUDE{a,b} EXCLUDE{a,b} not error 6. Attention This patch would be worked with NetBSD-current kernel, 2.0E (04/May/2004). This may cause reject files when you apply this patch, if your kernel source is not the same version. This release is not a final release since this implementation requires more tests and improvements. We'll make new release without any announcement. Please visit both of *and* , and check the release number, "IGMP version 3 (and MLD version 2) kernel implementation (rel. XXXXXXXX)", periodically. (This release number may be independent on the cvs date of -current.) If you encounter any problems or you have some comments, please mail to the author. We'd deeply appreciate your feedback. 7. Copyright Please see "COPYRIGHT" in a same directory. October 2002. - One good day of the first public release - Hitoshi Asaeda