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.2 2003/06/17 04:36:59 dillon 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/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 .Pp
 119 .Bl -tag -width orphans
 120 .It Dv lower
 121 Connection to the lower device link layer.
 122 .It Dv upper
 123 Connection to the upper protocol layers.
 124 .It Dv orphans
 125 Like
 126 .Dv lower ,
 127 but only receives unrecognized packets.
 128 .El
 129 .Sh CONTROL MESSAGES
 130 This node type supports the generic control messages, plus the following:
 131 .Bl -tag -width foo
 132 .It Dv NGM_ETHER_GET_IFNAME
 133 Returns the name of the associated interface as a NUL-terminated ASCII string.
 134 Normally this is the same as the name of the node.
 135 .It Dv NGM_ETHER_GET_IFINDEX
 136 Returns the global index of the associated interface as a 32 bit integer.
 137 .It Dv NGM_ETHER_GET_ENADDR
 138 Returns the device's unique six byte Ethernet address.
 139 .It Dv NGM_ETHER_SET_ENADDR
 140 Sets the device's unique six byte Ethernet address.
 141 This control message is equivalent to using the
 142 .Dv SIOCSIFLLADDR
 143 .Xr ioctl 2
 144 system call.
 145 .It Dv NGM_ETHER_SET_PROMISC
 146 Enable or disable promiscuous mode.
 147 This message includes a single 32 bit integer flag that enables or
 148 disables promiscuous mode on the interface.
 149 .It Dv NGM_ETHER_GET_PROMISC
 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
 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 enabled.
 164 .It Dv NGM_ETHER_GET_AUTOSRC
 165 Get the current value of the node's source address override flag.
 166 The returned value is always either one or zero.
 167 .El
 168 .Sh SHUTDOWN
 169 This node is persistent for as long as the interface exists.
 170 Upon receipt of a
 171 .Dv NGM_SHUTDOWN
 172 control message, all hooks are disconnected, promiscuous mode is disabled,
 173 and the source address override flag is reenabled,
 174 but the node is not removed.
 175 If the interface itself is detached (e.g., because of PCCARD removal), the
 176 node disappears as well.
 177 .Sh EXAMPLES
 178 This command dumps all unrecognized packets received by the
 179 .Dv fxp0
 180 interface to standard output decoded in hex and ASCII:
 181 .Bd -literal -offset indent
 182 nghook -a fxp0: orphans
 183 .Ed
 184 .Pp
 185 This command sends the contents of
 186 .Dv foo.pkt
 187 out the interface
 188 .Dv fxp0 :
 189 .Bd -literal -offset indent
 190 cat foo.pkt | nghook fxp0: orphans
 191 .Ed
 192 .Pp
 193 These commands insert an
 194 .Xr ng_tee 4
 195 node between the lower and upper protocol layers, which can be used for
 196 tracing packet flow, statistics, etc.:
 197 .Bd -literal -offset indent
 198 ngctl mkpeer fxp0: tee lower right
 199 ngctl connect fxp0: lower upper left
 200 .Ed
 201 .Sh BUGS
 202 The automatic KLD module loading mechanism that works for most
 203 other netgraph node types does not work for the
 204 .Nm
 205 node type,
 206 because
 207 .Nm
 208 nodes are not created on demand; instead, they are created when
 209 Ethernet interfaces are attached or when the KLD is first loaded.
 210 Therefore, if the KLD is not statically compiled into the kernel,
 211 it is necessary to load the KLD manually in order to bring the
 212 .Nm
 213 nodes into existence.
 214 .Sh SEE ALSO
 215 .Xr arp 4 ,
 216 .Xr netgraph 4 ,
 217 .Xr netintro 4 ,
 218 .Xr ifconfig 8 ,
 219 .Xr ngctl 8 ,
 220 .Xr nghook 8
 221 .Sh AUTHORS
 222 .An Julian Elischer Aq julian@FreeBSD.org
 223 .An Archie Cobbs Aq archie@FreeBSD.org