share/man/man4/ng_ether.4

   1 .\" Copyright (c) 2000 Whistle Communications, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Subject to the following obligations and disclaimer of warranty, use and
   5 .\" redistribution of this software, in source or object code forms, with or
   6 .\" without modifications are expressly permitted by Whistle Communications;
   7 .\" provided, however, that:
   8 .\" 1. Any and all reproductions of the source or object code must include the
   9 .\"    copyright notice above and the following disclaimer of warranties; and
  10 .\" 2. No rights are granted, in any manner or form, to use Whistle
  11 .\"    Communications, Inc. trademarks, including the mark "WHISTLE
  12 .\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
  13 .\"    such appears in the above copyright notice or in the software.
  14 .\"
  15 .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
  16 .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
  17 .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
  18 .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
  20 .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
  21 .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
  22 .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
  23 .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
  24 .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
  25 .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  26 .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
  27 .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
  31 .\" OF SUCH DAMAGE.
  32 .\"
  33 .\" Author: Archie Cobbs <archie@FreeBSD.org>
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd June 23, 2011
  38 .Dt NG_ETHER 4
  39 .Os
  40 .Sh NAME
  41 .Nm ng_ether
  42 .Nd Ethernet netgraph node type
  43 .Sh SYNOPSIS
  44 .In netgraph/ng_ether.h
  45 .Sh DESCRIPTION
  46 The
  47 .Nm ether
  48 netgraph node type allows Ethernet interfaces to interact with
  49 the
  50 .Xr netgraph 4
  51 networking subsystem.
  52 Once the
  53 .Nm
  54 module is loaded into the kernel, a node is automatically created
  55 for each Ethernet interface in the system.
  56 Each node will attempt to name itself with the same name
  57 as the associated interface.
  58 .Pp
  59 Three hooks are supported:
  60 .Va lower , upper ,
  61 and
  62 .Va orphans .
  63 The hook name
  64 .Va divert
  65 may be used as an alias for
  66 .Va lower ,
  67 and is provided for backward compatibility.
  68 In reality, the two names represent the same hook.
  69 .Pp
  70 The
  71 .Va lower
  72 hook is a connection to the raw Ethernet device.
  73 When connected, all incoming packets are forwarded to this hook,
  74 instead of being passed to the kernel for upper layer processing.
  75 Writing to this hook results in a raw Ethernet frame being transmitted
  76 by the device.
  77 Normal outgoing packets are not affected by
  78 .Va lower
  79 being connected.
  80 .Pp
  81 The
  82 .Va upper
  83 hook is a connection to the upper protocol layers.
  84 When connected, all outgoing packets are forwarded to this hook,
  85 instead of being transmitted by the device.
  86 Writing to this hook results in a raw Ethernet frame being received by
  87 the kernel just as if it had come in over the wire.
  88 Normal incoming packets are not affected by
  89 .Va upper
  90 being connected.
  91 .Pp
  92 The
  93 .Va orphans
  94 hook is equivalent to
  95 .Va lower ,
  96 except that only unrecognized packets (that would otherwise be discarded)
  97 are written to the hook, while other normal incoming traffic is unaffected.
  98 Unrecognized packets written to
  99 .Va upper
 100 will be forwarded back out to
 101 .Va orphans
 102 if connected.
 103 .Pp
 104 In all cases, frames are raw Ethernet frames with the standard
 105 14 byte Ethernet header (but no checksum).
 106 .Pp
 107 When no hooks are connected,
 108 .Va upper
 109 and
 110 .Va lower
 111 are in effect connected together,
 112 so that packets flow normally upwards and downwards.
 113 .Sh HOOKS
 114 This node type supports the following hooks:
 115 .Bl -tag -width ".Va orphans"
 116 .It Va lower
 117 Connection to the lower device link layer.
 118 .It Va upper
 119 Connection to the upper protocol layers.
 120 .It Va orphans
 121 Like
 122 .Va lower ,
 123 but only receives unrecognized packets.
 124 .El
 125 .Sh CONTROL MESSAGES
 126 This node type supports the generic control messages, plus the following:
 127 .Bl -tag -width foo
 128 .It Dv NGM_ETHER_GET_IFNAME Pq Ic getifname
 129 Returns the name of the associated interface as a
 130 .Dv NUL Ns -terminated
 131 .Tn ASCII
 132 string.
 133 Normally this is the same as the name of the node.
 134 .It Dv NGM_ETHER_GET_IFINDEX Pq Ic getifindex
 135 Returns the global index of the associated interface as a 32 bit integer.
 136 .It Dv NGM_ETHER_GET_ENADDR Pq Ic getenaddr
 137 Returns the device's unique six byte Ethernet address.
 138 .It Dv NGM_ETHER_SET_ENADDR Pq Ic setenaddr
 139 Sets the device's unique six byte Ethernet address.
 140 This control message is equivalent to using the
 141 .Dv SIOCSIFLLADDR
 142 .Xr ioctl 2
 143 system call.
 144 .It Dv NGM_ETHER_SET_PROMISC Pq Ic setpromisc
 145 Enable or disable promiscuous mode.
 146 This message includes a single 32 bit integer flag that enables or
 147 disables promiscuous mode on the interface.
 148 Any non-zero value enables promiscuous mode.
 149 .It Dv NGM_ETHER_GET_PROMISC Pq Ic getpromisc
 150 Get the current value of the node's promiscuous flag.
 151 The returned value is always either one or zero.
 152 Note that this flag reflects the node's own promiscuous setting
 153 and does not necessarily reflect the promiscuous state of the actual
 154 interface, which can be affected by other means (e.g.,
 155 .Xr bpf 4 ) .
 156 .It Dv NGM_ETHER_SET_AUTOSRC Pq Ic setautosrc
 157 Sets the automatic source address override flag.
 158 This message includes a single 32 bit integer flag that causes
 159 all outgoing packets to have their source Ethernet
 160 address field overwritten with the device's unique Ethernet address.
 161 If this flag is set to zero, the source address in outgoing packets
 162 is not modified.
 163 The default setting for this flag is disabled.
 164 .It Dv NGM_ETHER_GET_AUTOSRC Pq Ic getautosrc
 165 Get the current value of the node's source address override flag.
 166 The returned value is always either one or zero.
 167 .It Dv NGM_ETHER_ADD_MULTI Pq Ic addmulti
 168 Join Ethernet multicast group.
 169 This control message is equivalent to using the
 170 .Dv SIOCADDMULTI
 171 .Xr ioctl 2
 172 system call.
 173 .It Dv NGM_ETHER_DEL_MULTI Pq Ic delmulti
 174 Leave Ethernet multicast group.
 175 This control message is equivalent to using the
 176 .Dv SIOCDELMULTI
 177 .Xr ioctl 2
 178 system call.
 179 .It Dv NGM_ETHER_DETACH Pq Ic detach
 180 Detach from underlying Ethernet interface and shut down node.
 181 .El
 182 .Sh SHUTDOWN
 183 Upon receipt of the
 184 .Dv NGM_SHUTDOWN
 185 control message, all hooks are disconnected, promiscuous mode is disabled,
 186 but the node is not removed.
 187 Node can be shut down only using
 188 .Dv NGM_ETHER_DETACH
 189 control message.
 190 If the interface itself is detached (e.g., because of PC Card removal), the
 191 node disappears as well.
 192 .Sh EXAMPLES
 193 This command dumps all unrecognized packets received by the
 194 .Dq Li fxp0
 195 interface to standard output decoded in hex and
 196 .Tn ASCII :
 197 .Pp
 198 .Dl "nghook -a fxp0: orphans"
 199 .Pp
 200 This command sends the contents of
 201 .Pa sample.pkt
 202 out the interface
 203 .Dq Li fxp0 :
 204 .Pp
 205 .Dl "cat sample.pkt | nghook fxp0: orphans"
 206 .Pp
 207 These commands insert an
 208 .Xr ng_tee 4
 209 node between the
 210 .Va lower
 211 and
 212 .Va upper
 213 protocol layers, which can be used for
 214 tracing packet flow, statistics, etc.:
 215 .Bd -literal -offset indent
 216 ngctl mkpeer fxp0: tee lower right
 217 ngctl connect fxp0: lower upper left
 218 .Ed
 219 .Sh SEE ALSO
 220 .Xr arp 4 ,
 221 .Xr netgraph 4 ,
 222 .Xr netintro 4 ,
 223 .Xr ifconfig 8 ,
 224 .Xr ngctl 8 ,
 225 .Xr nghook 8
 226 .Sh AUTHORS
 227 .An Julian Elischer Aq julian@FreeBSD.org
 228 .An Archie Cobbs Aq archie@FreeBSD.org
 229 .Sh BUGS
 230 The automatic KLD module loading mechanism that works for most
 231 other Netgraph node types does not work for the
 232 .Nm ether
 233 node type,
 234 because
 235 .Nm ether
 236 nodes are not created on demand; instead, they are created when
 237 Ethernet interfaces are attached or when the KLD is first loaded.
 238 Therefore, if the KLD is not statically compiled into the kernel,
 239 it is necessary to load the KLD manually in order to bring the
 240 .Nm ether
 241 nodes into existence.