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