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/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 .Pp
 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 BUGS
 201 The automatic KLD module loading mechanism that works for most
 202 other netgraph node types does not work for the
 203 .Nm
 204 node type,
 205 because
 206 .Nm
 207 nodes are not created on demand; instead, they are created when
 208 Ethernet interfaces are attached or when the KLD is first loaded.
 209 Therefore, if the KLD is not statically compiled into the kernel,
 210 it is necessary to load the KLD manually in order to bring the
 211 .Nm
 212 nodes into existence.
 213 .Sh SEE ALSO
 214 .Xr arp 4 ,
 215 .Xr netgraph 4 ,
 216 .Xr netintro 4 ,
 217 .Xr ifconfig 8 ,
 218 .Xr ngctl 8 ,
 219 .Xr nghook 8
 220 .Sh AUTHORS
 221 .An Julian Elischer Aq julian@FreeBSD.org
 222 .An Archie Cobbs Aq archie@FreeBSD.org