[src/trunk]: src/share/man/man4 Documentation on the PIM kernel options and o...

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/share/man/man4 Documentation on the PIM kernel options and o...
From: manu <manu%NetBSD.org@localhost>
Date: Fri, 24 Jan 2020 15:41:18 +0000
details:   https://anonhg.NetBSD.org/src/rev/15b00ea36eed
branches:  trunk
changeset: 569765:15b00ea36eed
user:      manu <manu%NetBSD.org@localhost>
date:      Sat Sep 04 23:54:51 2004 +0000

description:
Documentation on the PIM kernel options and on multicast, from Pavlin
Radoslavov, imported from FreeBSD.

diffstat:

 share/man/man4/Makefile    |    8 +-
 share/man/man4/multicast.4 |  976 +++++++++++++++++++++++++++++++++++++++++++++
 share/man/man4/options.4   |    8 +-
 share/man/man4/pim.4       |  203 +++++++++
 4 files changed, 1190 insertions(+), 5 deletions(-)

diffs (truncated from 1234 to 300 lines):

diff -r 1328c9a25219 -r 15b00ea36eed share/man/man4/Makefile
--- a/share/man/man4/Makefile   Sat Sep 04 23:35:43 2004 +0000
+++ b/share/man/man4/Makefile   Sat Sep 04 23:54:51 2004 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.329 2004/08/26 14:19:56 itohy Exp $
+#      $NetBSD: Makefile,v 1.330 2004/09/04 23:54:51 manu Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/18/93
 
 MAN=   aac.4 acardide.4 aceride.4 acphy.4 adc.4 adv.4 \
@@ -23,12 +23,12 @@
        ld.4 lkm.4 lo.4 lxtphy.4 mainbus.4 makphy.4 \
        mbe.4 mca.4 mcclock.4 md.4 mfb.4 mhzc.4 midi.4 \
        mii.4 mk48txx.4 mlx.4 mly.4 mpt.4 mpu.4 mtd.4 \
-       mtio.4 ne.4 neo.4 netintro.4 netsmb.4 njs.4 ns.4 \
+       mtio.4 multicast.4 ne.4 neo.4 netintro.4 netsmb.4 njs.4 ns.4 \
        nsclpcsio.4 nsip.4 nsphy.4 nsphyter.4 ntwoc.4 \
        null.4 nsmb.4 oak.4 oosiop.4 opl.4 options.4 \
        optiide.4 osiop.4 pas.4 pcdisplay.4 pciide.4 \
-       pdcide.4 piixide.4 pckbc.4 pckbd.4 pcn.4 \
-       pcppi.4 pcscp.4 pcweasel.4 plip.4 pms.4 pnaphy.4 ppbus.4 ppp.4 \
+       pdcide.4 piixide.4 pckbc.4 pckbd.4 pcn.4 pcppi.4 pcscp.4 \
+       pcweasel.4 pim.4 plip.4 pms.4 pnaphy.4 ppbus.4 ppp.4 \
        pppoe.4 ptm.4 pty.4 puc.4 px.4 pxg.4 qe.4 qec.4 qsphy.4 \
        raid.4 ray.4 rcons.4 re.4 rnd.4 route.4 rtk.4 satalink.4 \
        sbus.4 scc.4 scsi.4 sd.4 se.4 ses.4 sf.4 sfb.4 shb.4 \
diff -r 1328c9a25219 -r 15b00ea36eed share/man/man4/multicast.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/multicast.4        Sat Sep 04 23:54:51 2004 +0000
@@ -0,0 +1,976 @@
+.\" Copyright (c) 2001-2003 International Computer Science Institute
+.\"
+.\" Permission is hereby granted, free of charge, to any person obtaining a
+.\" copy of this software and associated documentation files (the "Software"),
+.\" to deal in the Software without restriction, including without limitation
+.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
+.\" and/or sell copies of the Software, and to permit persons to whom the
+.\" Software is furnished to do so, subject to the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be included in
+.\" all copies or substantial portions of the Software.
+.\"
+.\" The names and trademarks of copyright holders may not be used in
+.\" advertising or publicity pertaining to the software without specific
+.\" prior permission. Title to copyright in this software and any associated
+.\" documentation will at all times remain with the copyright holders.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+.\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+.\" DEALINGS IN THE SOFTWARE.
+.\"
+.\" $FreeBSD: src/share/man/man4/multicast.4,v 1.4 2004/07/09 09:22:36 ru Exp $
+.\" $NetBSD: multicast.4,v 1.1 2004/09/04 23:54:51 manu Exp $
+.\"
+.Dd September 4, 2003
+.Dt MULTICAST 4
+.Os
+.\"
+.Sh NAME
+.Nm multicast
+.Nd Multicast Routing
+.\"
+.Sh SYNOPSIS
+.Cd "options MROUTING"
+.Pp
+.In sys/types.h
+.In sys/socket.h
+.In netinet/in.h
+.In netinet/ip_mroute.h
+.In netinet6/ip6_mroute.h
+.Ft int
+.Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen"
+.Ft int
+.Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen"
+.Ft int
+.Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen"
+.Ft int
+.Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen"
+.Sh DESCRIPTION
+.Tn "Multicast routing"
+is used to efficiently propagate data
+packets to a set of multicast listeners in multipoint networks.
+If unicast is used to replicate the data to all listeners,
+then some of the network links may carry multiple copies of the same
+data packets.
+With multicast routing, the overhead is reduced to one copy
+(at most) per network link.
+.Pp
+All multicast-capable routers must run a common multicast routing
+protocol.
+The Distance Vector Multicast Routing Protocol (DVMRP)
+was the first developed multicast routing protocol.
+Later, other protocols such as Multicast Extensions to OSPF (MOSPF),
+Core Based Trees (CBT),
+Protocol Independent Multicast - Sparse Mode (PIM-SM),
+and Protocol Independent Multicast - Dense Mode (PIM-DM)
+were developed as well.
+.Pp
+To start multicast routing,
+the user must enable multicast forwarding in the kernel
+(see
+.Sx SYNOPSIS
+about the kernel configuration options),
+and must run a multicast routing capable user-level process.
+From developer's point of view,
+the programming guide described in the
+.Sx "Programming Guide"
+section should be used to control the multicast forwarding in the kernel.
+.\"
+.Ss Programming Guide
+This section provides information about the basic multicast routing API.
+The so-called
+.Dq advanced multicast API
+is described in the
+.Sx "Advanced Multicast API Programming Guide"
+section.
+.Pp
+First, a multicast routing socket must be open.
+That socket would be used
+to control the multicast forwarding in the kernel.
+Note that most operations below require certain privilege
+(i.e., root privilege):
+.Bd -literal
+/* IPv4 */
+int mrouter_s4;
+mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP);
+.Ed
+.Bd -literal
+int mrouter_s6;
+mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6);
+.Ed
+.Pp
+Note that if the router needs to open an IGMP or ICMPv6 socket
+(in case of IPv4 and IPv6 respectively)
+for sending or receiving of IGMP or MLD multicast group membership messages,
+then the same
+.Va mrouter_s4
+or
+.Va mrouter_s6
+sockets should be used
+for sending and receiving respectively IGMP or MLD messages.
+In case of
+.Bx Ns
+-derived kernel, it may be possible to open separate sockets
+for IGMP or MLD messages only.
+However, some other kernels (e.g.,
+.Tn Linux )
+require that the multicast
+routing socket must be used for sending and receiving of IGMP or MLD
+messages.
+Therefore, for portability reason the multicast
+routing socket should be reused for IGMP and MLD messages as well.
+.Pp
+After the multicast routing socket is open, it can be used to enable
+or disable multicast forwarding in the kernel:
+.Bd -literal
+/* IPv4 */
+int v = 1;        /* 1 to enable, or 0 to disable */
+setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v));
+.Ed
+.Bd -literal
+/* IPv6 */
+int v = 1;        /* 1 to enable, or 0 to disable */
+setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v));
+\&...
+/* If necessary, filter all ICMPv6 messages */
+struct icmp6_filter filter;
+ICMP6_FILTER_SETBLOCKALL(&filter);
+setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter,
+           sizeof(filter));
+.Ed
+.Pp
+After multicast forwarding is enabled, the multicast routing socket
+can be used to enable PIM processing in the kernel if we are running PIM-SM or
+PIM-DM
+(see
+.Xr pim 4 ) .
+.Pp
+For each network interface (e.g., physical or a virtual tunnel)
+that would be used for multicast forwarding, a corresponding
+multicast interface must be added to the kernel:
+.Bd -literal
+/* IPv4 */
+struct vifctl vc;
+memset(&vc, 0, sizeof(vc));
+/* Assign all vifctl fields as appropriate */
+vc.vifc_vifi = vif_index;
+vc.vifc_flags = vif_flags;
+vc.vifc_threshold = min_ttl_threshold;
+vc.vifc_rate_limit = max_rate_limit;
+memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr));
+if (vc.vifc_flags & VIFF_TUNNEL)
+    memcpy(&vc.vifc_rmt_addr, &vif_remote_address,
+           sizeof(vc.vifc_rmt_addr));
+setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc,
+           sizeof(vc));
+.Ed
+.Pp
+The
+.Va vif_index
+must be unique per vif.
+The
+.Va vif_flags
+contains the
+.Dv VIFF_*
+flags as defined in
+.In netinet/ip_mroute.h .
+The
+.Va min_ttl_threshold
+contains the minimum TTL a multicast data packet must have to be
+forwarded on that vif.
+Typically, it would have value of 1.
+The
+.Va max_rate_limit
+contains the maximum rate (in bits/s) of the multicast data packets forwarded
+on that vif.
+Value of 0 means no limit.
+The
+.Va vif_local_address
+contains the local IP address of the corresponding local interface.
+The
+.Va vif_remote_address
+contains the remote IP address in case of DVMRP multicast tunnels.
+.Bd -literal
+/* IPv6 */
+struct mif6ctl mc;
+memset(&mc, 0, sizeof(mc));
+/* Assign all mif6ctl fields as appropriate */
+mc.mif6c_mifi = mif_index;
+mc.mif6c_flags = mif_flags;
+mc.mif6c_pifi = pif_index;
+setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc,
+           sizeof(mc));
+.Ed
+.Pp
+The
+.Va mif_index
+must be unique per vif.
+The
+.Va mif_flags
+contains the
+.Dv MIFF_*
+flags as defined in
+.In netinet6/ip6_mroute.h .
+The
+.Va pif_index
+is the physical interface index of the corresponding local interface.
+.Pp
+A multicast interface is deleted by:
+.Bd -literal
+/* IPv4 */
+vifi_t vifi = vif_index;
+setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi,
+           sizeof(vifi));
+.Ed
+.Bd -literal
+/* IPv6 */
+mifi_t mifi = mif_index;
+setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi,
+           sizeof(mifi));
+.Ed
+.Pp
+After the multicast forwarding is enabled, and the multicast virtual
+interfaces are
+added, the kernel may deliver upcall messages (also called signals
+later in this text) on the multicast routing socket that was open
+earlier with
+.Dv MRT_INIT
+or
+.Dv MRT6_INIT .
+The IPv4 upcalls have
+.Vt "struct igmpmsg"
+header (see
+.In netinet/ip_mroute.h )
+with field
+.Va im_mbz
+set to zero.
+Note that this header follows the structure of
+.Vt "struct ip"
+with the protocol field
+.Va ip_p
+set to zero.
+The IPv6 upcalls have
+.Vt "struct mrt6msg"
+header (see
+.In netinet6/ip6_mroute.h )
+with field
+.Va im6_mbz
+set to zero.
+Note that this header follows the structure of
+.Vt "struct ip6_hdr"
+with the next header field
+.Va ip6_nxt
+set to zero.
+.Pp
+The upcall header contains field
+.Va im_msgtype
Prev by Date: [src/trunk]: src/usr.bin/netstat IPv4 PIM support, from the submission of Pav...
Next by Date: [src/trunk]: src Kerberos support is broken in rcommands, thus making -K -k a...
Previous by Thread: [src/trunk]: src/usr.bin/netstat IPv4 PIM support, from the submission of Pav...
Next by Thread: [src/trunk]: src Kerberos support is broken in rcommands, thus making -K -k a...
Indexes:
Home | Main Index | Thread Index | Old Index