1 .\" Copyright (c) 2000 Whistle Communications, Inc.
2 .\" All rights reserved.
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.
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
33 .\" Author: Archie Cobbs <archie@FreeBSD.org>
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.4 2006/05/26 21:39:39 swildner Exp $
43 .Nd Ethernet netgraph node type
45 .In netgraph/ether/ng_ether.h
49 netgraph node type allows Ethernet interfaces to interact with
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.
61 nodes are persistent for as long as the interface itself exists.
63 Three hooks are supported:
70 may be used as an alias for
72 and is provided for backward compatibility.
73 In reality the two names represent the same hook.
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
81 Normal outgoing packets are not affected by
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
99 except that only unrecognized packets (that would otherwise be discarded)
100 are written to the hook, and normal incoming traffic is unaffected.
105 may be connected at any time.
107 In all cases, frames are raw Ethernet frames with the standard
108 14 byte Ethernet header (but no checksum).
110 When no hooks are connected,
114 are in effect connected together,
115 so that packets flow normally upwards and downwards.
117 This node type supports the following hooks:
119 .Bl -tag -width orphans
121 Connection to the lower device link layer.
123 Connection to the upper protocol layers.
127 but only receives unrecognized packets.
130 This node type supports the generic control messages, plus the following:
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
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.,
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
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.
169 This node is persistent for as long as the interface exists.
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.
178 This command dumps all unrecognized packets received by the
180 interface to standard output decoded in hex and ASCII:
181 .Bd -literal -offset indent
182 nghook -a fxp0: orphans
185 This command sends the contents of
189 .Bd -literal -offset indent
190 cat foo.pkt | nghook fxp0: orphans
193 These commands insert an
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
209 .An Julian Elischer Aq julian@FreeBSD.org
210 .An Archie Cobbs Aq archie@FreeBSD.org
212 The automatic KLD module loading mechanism that works for most
213 other netgraph node types does not work for the
218 nodes are not created on demand; instead, they are created when
219 Ethernet interfaces are attached or when the KLD is first loaded.
220 Therefore, if the KLD is not statically compiled into the kernel,
221 it is necessary to load the KLD manually in order to bring the
223 nodes into existence.