IGMP version 3 kernel implementation (rel. 20040622) 1. Introduction This is a host-side implementation of IGMP version 3 applied to NetBSD-current kernel (as of 04/May/2004). This implementation supports following RFCs and I-D. "IP Router Alert Option", RFC2113. "Internet Group Management Protocol, Version 3", RFC3376. "Socket Interface Extensions for Multicast Source Filters", draft-ietf-magma-msf-api-03.txt. IGMPv3 provides Source-Specific Multicast (SSM) architecture. Since the spec of IGMPv3, 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 "5. Attention" section carefully. And we strongly recommend you to take backup before you begin. Note that MLDv2 host-side implementations is also available on: . 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. Installation (hereafter, BSDSRCDIR=/usr/src is assumed.) 2-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/igmpv3-20040622/kernel.patch Before applying this patch, you may want to backup original sys/netinet directory. 3) Edit your kernel configuration file to enable IGMPv3. options IGMPV3 4) (option) If you'd like to get some debug message, configure debug option. options IGMPV3_DEBUG Note that debug message may be a little noisy but useful. 5) Recompile your kernel, install it, and reboot. 2-2. Command Installation 2-2-1. netstat and sysctl o. Setup 0) Kernel must be updated by 2-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/igmpv3-20040622/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.bin/netstat # 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 New "netstat -s -p igmp" newly shows following 5 statistics. [count] messages received over MTU size [count] messages received with no router alert [count] v1 membership queries received [count] v2 membership queries received [count] v3 membership queries received [count] v1/v2 membership reports sent [count] v3 membership reports sent This kernel modification supports to be enable/disable Router Alert option [RFC2113] check for each IGMPv2/v3 packet. Router Alert option would be used not only with IGMPv3 but with IGMPv2 by any multicast router. You can see how many IGMPv2/v3 messages with no Router Alert option are received by netstat command, if the box is working as a multicast router. See "4-3. Router Alert Option" section for more detail. After applying this patch, this box can work with any multicast router, which speaks IGMPv1/v2/v3. (See "4-1. Compatibility with Older Versions of IGMP" section.) So, monitoring above query counts are useful to recognize this box'es current IGMP Report version. New "sysctl" newly controls following values. net.inet.igmp.sendwithra net.inet.igmp.dropwithnora net.inet.igmp.maxsrcfilter net.inet.igmp.somaxsrc net.inet.igmp.always_v3 % sysctl net.inet.igmp.sendwithra If this returns 0, then kernel doesn't send IGMPv2/v3 Query or Report message with Router Alert (RA) option. % sysctl net.inet.igmp.dropwithnora If this returns 0, then kernel doesn't drop IGMPv2/v3 Query or Report message with no RA option when the node behave as a multicast router. % sysctl net.inet.igmp.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.inet.igmp.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.inet.igmp.always_v3 If this returns 0, then kernel maintains Host Compatibility Mode mentioned in an IGMPv3 Spec. If this returnes 1, then kernel ignores v1 Query and v2 General Query messages and doesn't maintain Host compatibility Mode. It always behave as IGMPv3 node. See "4-1-2. Static Configuration" section more detail. [default: 0] 2-2-2. vmstat update o. Setup 0) Kernel must be updated by 2-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. 3. IGMPv3 Default Values Followings are main timers/counters, default values, and controls used by IGMPv3. variable default value control ------------------------- ------------------ ------------- Robustness Variable 2 Query message Query Interval 125 (125 sec.) mrouter Query Responce Interval 100 (10 sec.) Query message (Max Responce Time) 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 4. Techinical Note 4-1. Compatibility with Older Versions of IGMP 4-1-1. Normal Behavior (Dynamic State Transition) This modification interoperates with applications and routers that have not yet been upgraded to IGMPv3. 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 IGMPv1 or v2 capable applications. Also, you can communicate any multicast router speaking IGMPv1/v2/v3, since modified kernel sends same version's IGMP report according to the Query message. If an upstream router speaks IGMPv2 and sends v2 Query, then this box sends IGMP report messages using v2 format. If the upstream router changes to speak IGMPv3, or another IGMPv3 capable router becomes Querier, this box can gracefully change to speak v3. 4-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 IGMPv3 LAN, in other words, that correct upstream router(s) must be IGMPv3 capable, then it may be better to setup IGMP's version spoken by the box to v3 statically. ( may be useful for the information.) After this static configuration is done, any old IGMP Query message doesn't affect to change the compatibility mode. Remember this is useful only when correct upstream router(s) must be IGMPv3 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 not mentioned in a spec and turned off as the kernel's default value. 4-2. IGMPv3 APIs' Semantics This implementation fully supports all of APIs described in the API draft. They can be classified as follows. o. IPv4 Multicast Source Filter APIs o. Basic (Delta-based) o. Advanced (Full-state) 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 ----------------- ----------------- ----------- IP_ADD_MEMBERSHIP IP_ADD_MEMBERSHIP EADDRINUSE IP_ADD_MEMBERSHIP IP_DROP_MEMBERSHIP 0 IP_ADD_MEMBERSHIP IP_ADD_SOURCE_MEMBERSHIP EINVAL IP_ADD_MEMBERSHIP IP_DROP_SOURCE_MEMBERSHIP EINVAL IP_ADD_MEMBERSHIP IP_BLOCK_SOURCE 0 IP_ADD_SOURCE_MEMBERSHIP IP_ADD_MEMBERSHIP EADDRINUSE IP_ADD_SOURCE_MEMBERSHIP IP_DROP_MEMBERSHIP 0 IP_ADD_SOURCE_MEMBERSHIP IP_ADD_SOURCE_MEMBERSHIP (*1) IP_ADD_SOURCE_MEMBERSHIP IP_DROP_SOURCE_MEMBERSHIP (*2) IP_ADD_SOURCE_MEMBERSHIP IP_BLOCK_SOURCE EINVAL IP_ADD_SOURCE_MEMBERSHIP IP_UNBLOCK_SOURCE EINVAL IP_BLOCK_SOURCE IP_ADD_MEMBERSHIP EADDRINUSE IP_BLOCK_SOURCE IP_DROP_MEMBERSHIP 0 IP_BLOCK_SOURCE IP_ADD_SOURCE_MEMBERSHIP EINVAL IP_BLOCK_SOURCE IP_DROP_SOURCE_MEMBERSHIP EINVAL IP_BLOCK_SOURCE IP_BLOCK_SOURCE (*1) IP_BLOCK_SOURCE IP_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. As for "Basic Protocol-Independent Multicast Source Filter APIs", each condition is same, so please map to each one based on above semantics table. Also, it is no problem with mixing "Basic IPv4 Multicast Source Filter APIs" (IP_* options) and "Basic Protocol-Independent Multicast Source Filter APIs" (MCAST_* options). 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 4-3. Router Alert Option 4-3-1. Implementation One of important meanings of checking Router Alert option is that we'd like to forward regular datagrams as rapidly as possible, while ensuring that the router processes these special control datagrams appropriately. This implementation checks Time-to-Live and Router Alert option if it's required, by using igmp_get_router_alert() with ip_check_router_alert(), which is invoked from ip_input(). If the node is not a multicast router, then it doesn't check these values. This means net.inet.igmp.dropwithnora set by sysctl is only affected for multicast router. However, when net.inet.igmp.sendwithra is set to 1, whatever the node behaves as a multicast router or just a receiver, every IGMPv2/v3 message is sent with Router Alert option with TTL=1. IGMPv1 doesn't require Router Alert option at all. So, if the node uses IGMPv1, this implementation doesn't affect its behevior. 4-3-2. Configuration RFC2236 (aka IGMPv2 spec.) says; All IGMP messages described in this document are sent with IP TTL 1, and contain the IP Router Alert option [RFC 2113] in their IP header. Ignore Report messages without Router Alert options [RFC 2113], and require that routers not forward Report messages. Ignore Leave messages without Router Alert options [RFC 2113], and require that routers not forward Leave messages. And IGMPv3 also requires Router Alert option. However, many of IGMPv2 host and router implementations don't follow above statements. They may not ignore IGMPv2 messages with no RA option and may not send IGMPv2 messages with RA option. So, now, both of these default values, net.inet.igmp.sendwithra and net.inet.igmp.dropwithnora, are 0 (i.e. turned off), if your new kernel is compiled *with no* "IGMPV3" option. If your new kernel is compiled *with* "IGMPV3" option, net.inet.igmp.sendwithra is set 1 (i.e. turned on) and net.inet.igmp.dropwithnora is set 0 as default values. If you decide to change this policy, please overwrite these values using "sysctl" command with "-w" option as you want. 4-4. Destination Address of IGMPv2 Leave Message Original code sends IGMPv2 Leave to each group address. This could be accepted by a Querier, but this is old spec. (i.e. not RFC2236 spec.) RFC2236 says a host SHOULD send Leave Group message to ALL-ROUTERS (224.0.0.2). This implementation changes the destination address of IGMPv2 Leave message. 5. 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 and check the release number, "IGMP version 3 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. 6. Copyright Please see "COPYRIGHT" in a same directory. March 2002. - One good day of the first public release - Hitoshi Asaeda