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 August 4, 2006
  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 indent
 128 .It Dv NGM_ETHER_GET_IFNAME Pq Li 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 Li getifindex
 135 Returns the global index of the associated interface as a 32 bit integer.
 136 .It Dv NGM_ETHER_GET_ENADDR Pq Li getenaddr
 137 Returns the device's unique six byte Ethernet address.
 138 .It Dv NGM_ETHER_SET_ENADDR Pq Li 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 Li 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 Li 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 Li 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 Li 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 Li 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 Li 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 Li 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 and the source address override flag is re-enabled,
 187 but the node is not removed.
 188 Node can be shut down only using
 189 .Dv NGM_ETHER_DETACH
 190 control message.
 191 If the interface itself is detached (e.g., because of PC Card removal), the
 192 node disappears as well.
 193 .Sh EXAMPLES
 194 This command dumps all unrecognized packets received by the
 195 .Dq Li fxp0
 196 interface to standard output decoded in hex and
 197 .Tn ASCII :
 198 .Pp
 199 .Dl "nghook -a fxp0: orphans"
 200 .Pp
 201 This command sends the contents of
 202 .Pa sample.pkt
 203 out the interface
 204 .Dq Li fxp0 :
 205 .Pp
 206 .Dl "cat sample.pkt | nghook fxp0: orphans"
 207 .Pp
 208 These commands insert an
 209 .Xr ng_tee 4
 210 node between the
 211 .Va lower
 212 and
 213 .Va upper
 214 protocol layers, which can be used for
 215 tracing packet flow, statistics, etc.:
 216 .Bd -literal -offset indent
 217 ngctl mkpeer fxp0: tee lower right
 218 ngctl connect fxp0: lower upper left
 219 .Ed
 220 .Sh SEE ALSO
 221 .Xr arp 4 ,
 222 .Xr netgraph 4 ,
 223 .Xr netintro 4 ,
 224 .Xr ifconfig 8 ,
 225 .Xr ngctl 8 ,
 226 .Xr nghook 8
 227 .Sh AUTHORS
 228 .An Julian Elischer Aq julian@FreeBSD.org
 229 .An Archie Cobbs Aq archie@FreeBSD.org
 230 .Sh BUGS
 231 The automatic KLD module loading mechanism that works for most
 232 other Netgraph node types does not work for the
 233 .Nm ether
 234 node type,
 235 because
 236 .Nm ether
 237 nodes are not created on demand; instead, they are created when
 238 Ethernet interfaces are attached or when the KLD is first loaded.
 239 Therefore, if the KLD is not statically compiled into the kernel,
 240 it is necessary to load the KLD manually in order to bring the
 241 .Nm ether
 242 nodes into existence.