usr.sbin/mtest/mtest.8

   1 .\"
   2 .\" Copyright (c) 2007-2009 Bruce Simpson.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote products
  14 .\"    derived from this software without specific prior written permission
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd April 29, 2009
  30 .Dt MTEST 8
  31 .Os
  32 .Sh NAME
  33 .Nm mtest
  34 .Nd test multicast socket operations
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 utility
  41 is a small program for testing multicast socket operations.
  42 .Pp
  43 It accepts the following commands, interactively, or as part of a scripted
  44 input file (useful for automated testing):
  45 .Pp
  46 .Bl -tag -width "a ifname e.e.e.e e.e.e.e" -compact -offset indent
  47 .\"
  48 .It Ic a Ar ifname Ar mac-addr
  49 Join the link-layer group address
  50 .Ar mac-addr
  51 on interface
  52 .Ar ifname .
  53 The group address should be in IEEE 802 MAC format,
  54 delimited by colon (':') characters.
  55 .It Ic d Ar ifname Ar mac-addr
  56 Leave the link-layer group address
  57 .Ar mac-addr
  58 on interface
  59 .Ar ifname .
  60 .It Ic m Ar ifname Ar 1/0
  61 Set or reset ALLMULTI mode on interface
  62 .Ar ifname .
  63 This option is deprecated and is now a no-op.
  64 .It Ic p Ar ifname Ar 1/0
  65 Set or reset promiscuous mode on interface
  66 .Ar ifname .
  67 .Pp
  68 .It Ic j Ar mcast-addr Ar ifname Op Ar source-addr
  69 Join the multicast address
  70 .Ar mcast-addr
  71 on the interface with name
  72 .Ar ifname .
  73 .Pp
  74 If an optional source
  75 .Ar source-addr
  76 is specified, a source-specific join will be performed;
  77 if
  78 .Nm
  79 is already joined to the multicast address, the source
  80 will be added to its filter list.
  81 .Pp
  82 .It Ic l Ar mcast-addr Ar ifname Op Ar source-addr
  83 Leave the multicast address
  84 .Ar mcast-addr
  85 on the interface with address
  86 .Ar ifname .
  87 If a source
  88 .Ar source-addr
  89 is specified, only that source will be left.
  90 .\"
  91 .It Ic i Ar mcast-addr Ar ifname Ar n Ar source-addr ...
  92 Set the socket with membership of
  93 .Ar mcast-addr
  94 on interface
  95 .Ar ifname
  96 to include filter mode, and add
  97 .Ar n
  98 sources beginning with
  99 .Ar source-addr
 100 to the inclusion filter list.
 101 .\"
 102 .It Ic e Ar mcast-addr Ar ifname Ar n Ar source-addr ...
 103 Set the socket with membership of
 104 .Ar mcast-addr
 105 on interface
 106 .Ar ifname
 107 to exclude filter mode, and add
 108 .Ar n
 109 sources beginning with
 110 .Ar source-addr
 111 to the exclusion filter list.
 112 .\"
 113 .It Ic t Ar mcast-addr Ar ifname Ar source-addr
 114 Set the socket with membership of
 115 .Ar mcast-addr
 116 on interface
 117 .Ar ifname
 118 to block traffic from source
 119 .Ar source-addr .
 120 .\"
 121 .It Ic b Ar mcast-addr Ar ifname Ar source-addr
 122 Set the socket with membership of
 123 .Ar mcast-addr
 124 on interface
 125 .Ar ifname
 126 to allow traffic from source
 127 .Ar source-addr .
 128 .\"
 129 .Pp
 130 .It Ic g Ar mcast-addr Ar ifname Ar n
 131 Print
 132 .Ar n
 133 source filter entries for
 134 .An mcast-addr
 135 on interface
 136 .An ifname .
 137 .\"
 138 .Pp
 139 .It Ic f Ar filename
 140 Read commands from the file
 141 .Ar filename .
 142 .It Ic s Ar n
 143 Sleep for
 144 .Ar n
 145 seconds.
 146 .It Ic ?\&
 147 List legal commands.
 148 .It Ic q
 149 Quit the program.
 150 .El
 151 .Sh IMPLEMENTATION NOTES
 152 For each command implemented by
 153 .Nm ,
 154 the address family of each argument must be identical; it is not possible
 155 to mix IPv4 multicast memberships with IPv6, for example.
 156 .Pp
 157 To support IPv6, all commands have now changed to accept an interface
 158 name rather than an interface address.
 159 For IPv4, the program will perform
 160 a lookup of the primary IP address based on the interface name.
 161 This may fail if no primary IP address is assigned.
 162 .Sh SEE ALSO
 163 .Rs
 164 .%A D. Thaler
 165 .%A B. Fenner
 166 .%A B. Quinn
 167 .%T "Socket Interface Extensions for Multicast Filters"
 168 .%O RFC 3678
 169 .Re
 170 .Sh AUTHORS
 171 .An -split
 172 .An "Bruce Simpson"
 173 .An "Steve Deering"
 174 .An "Wilbert De Graaf"