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: src/share/man/man4/ng_ether.4,v 1.4.2.12 2002/04/07 04:57:13 dd Exp $
  36 .\" $DragonFly: src/share/man/man4/ng_ether.4,v 1.5 2008/05/02 02:05:05 swildner Exp $
  37 .\"
  38 .Dd June 26, 2000
  39 .Dt NG_ETHER 4
  40 .Os
  41 .Sh NAME
  42 .Nm ng_ether
  43 .Nd Ethernet netgraph node type
  44 .Sh SYNOPSIS
  45 .In netgraph/ether/ng_ether.h
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 netgraph node type allows Ethernet interfaces to interact with
  50 the
  51 .Xr netgraph 4
  52 networking subsystem.
  53 Once the
  54 .Nm
  55 module is loaded in the kernel, a node is automatically created
  56 for each Ethernet interface in the system.
  57 Each node will attempt to name itself with the same name
  58 as the associated interface.
  59 All
  60 .Nm
  61 nodes are persistent for as long as the interface itself exists.
  62 .Pp
  63 Three hooks are supported:
  64 .Dv lower ,
  65 .Dv upper ,
  66 and
  67 .Dv orphans .
  68 The hook name
  69 .Dv divert
  70 may be used as an alias for
  71 .Dv lower ,
  72 and is provided for backward compatibility.
  73 In reality the two names represent the same hook.
  74 .Pp
  75 The
  76 .Dv lower
  77 hook is a connection to the raw Ethernet device.
  78 When connected, all incoming packets are diverted out this hook.
  79 Writing to this hook results in a raw Ethernet frame being transmitted
  80 by the device.
  81 Normal outgoing packets are not affected by
  82 .Dv lower
  83 being connected.
  84 .Pp
  85 The
  86 .Dv upper
  87 hook is a connection to the upper protocol layers.
  88 When connected, all outgoing packets are diverted out this hook.
  89 Writing to this hook results in a raw Ethernet frame being received by
  90 the kernel just as if it had come in over the wire.
  91 Normal incoming packets are not affected by
  92 .Dv upper
  93 being connected.
  94 .Pp
  95 The
  96 .Dv orphans
  97 hook is equivalent to
  98 .Dv lower ,
  99 except that only unrecognized packets (that would otherwise be discarded)
 100 are written to the hook, and normal incoming traffic is unaffected.
 101 At most one of
 102 .Dv orphans
 103 and
 104 .Dv lower
 105 may be connected at any time.
 106 .Pp
 107 In all cases, frames are raw Ethernet frames with the standard
 108 14 byte Ethernet header (but no checksum).
 109 .Pp
 110 When no hooks are connected,
 111 .Dv upper
 112 and
 113 .Dv lower
 114 are in effect connected together,
 115 so that packets flow normally upwards and downwards.
 116 .Sh HOOKS
 117 This node type supports the following hooks:
 118 .Bl -tag -width orphans
 119 .It Dv lower
 120 Connection to the lower device link layer.
 121 .It Dv upper
 122 Connection to the upper protocol layers.
 123 .It Dv orphans
 124 Like
 125 .Dv lower ,
 126 but only receives unrecognized packets.
 127 .El
 128 .Sh CONTROL MESSAGES
 129 This node type supports the generic control messages, plus the following:
 130 .Bl -tag -width foo
 131 .It Dv NGM_ETHER_GET_IFNAME
 132 Returns the name of the associated interface as a NUL-terminated ASCII string.
 133 Normally this is the same as the name of the node.
 134 .It Dv NGM_ETHER_GET_IFINDEX
 135 Returns the global index of the associated interface as a 32 bit integer.
 136 .It Dv NGM_ETHER_GET_ENADDR
 137 Returns the device's unique six byte Ethernet address.
 138 .It Dv NGM_ETHER_SET_ENADDR
 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
 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 .It Dv NGM_ETHER_GET_PROMISC
 149 Get the current value of the node's promiscuous flag.
 150 The returned value is always either one or zero.
 151 Note that this flag reflects the node's own promiscuous setting
 152 and does not necessarily reflect the promiscuous state of the actual
 153 interface, which can be affected by other means (e.g.,
 154 .Xr bpf 4 ) .
 155 .It Dv NGM_ETHER_SET_AUTOSRC
 156 Sets the automatic source address override flag.
 157 This message includes a single 32 bit integer flag that causes
 158 all outgoing packets to have their source Ethernet
 159 address field overwritten with the device's unique Ethernet address.
 160 If this flag is set to zero, the source address in outgoing packets
 161 is not modified.
 162 The default setting for this flag is enabled.
 163 .It Dv NGM_ETHER_GET_AUTOSRC
 164 Get the current value of the node's source address override flag.
 165 The returned value is always either one or zero.
 166 .El
 167 .Sh SHUTDOWN
 168 This node is persistent for as long as the interface exists.
 169 Upon receipt of a
 170 .Dv NGM_SHUTDOWN
 171 control message, all hooks are disconnected, promiscuous mode is disabled,
 172 and the source address override flag is reenabled,
 173 but the node is not removed.
 174 If the interface itself is detached (e.g., because of PCCARD removal), the
 175 node disappears as well.
 176 .Sh EXAMPLES
 177 This command dumps all unrecognized packets received by the
 178 .Dv fxp0
 179 interface to standard output decoded in hex and ASCII:
 180 .Bd -literal -offset indent
 181 nghook -a fxp0: orphans
 182 .Ed
 183 .Pp
 184 This command sends the contents of
 185 .Dv foo.pkt
 186 out the interface
 187 .Dv fxp0 :
 188 .Bd -literal -offset indent
 189 cat foo.pkt | nghook fxp0: orphans
 190 .Ed
 191 .Pp
 192 These commands insert an
 193 .Xr ng_tee 4
 194 node between the lower and upper protocol layers, which can be used for
 195 tracing packet flow, statistics, etc.:
 196 .Bd -literal -offset indent
 197 ngctl mkpeer fxp0: tee lower right
 198 ngctl connect fxp0: lower upper left
 199 .Ed
 200 .Sh SEE ALSO
 201 .Xr arp 4 ,
 202 .Xr netgraph 4 ,
 203 .Xr netintro 4 ,
 204 .Xr ifconfig 8 ,
 205 .Xr ngctl 8 ,
 206 .Xr nghook 8
 207 .Sh AUTHORS
 208 .An Julian Elischer Aq julian@FreeBSD.org
 209 .An Archie Cobbs Aq archie@FreeBSD.org
 210 .Sh BUGS
 211 The automatic KLD module loading mechanism that works for most
 212 other netgraph node types does not work for the
 213 .Nm
 214 node type,
 215 because
 216 .Nm
 217 nodes are not created on demand; instead, they are created when
 218 Ethernet interfaces are attached or when the KLD is first loaded.
 219 Therefore, if the KLD is not statically compiled into the kernel,
 220 it is necessary to load the KLD manually in order to bring the
 221 .Nm
 222 nodes into existence.