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>
42 .Nd Ethernet netgraph node type
44 .In netgraph/ng_ether.h
48 netgraph node type allows Ethernet interfaces to interact with
54 module is loaded into 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.
59 Three hooks are supported:
65 may be used as an alias for
67 and is provided for backward compatibility.
68 In reality, the two names represent the same hook.
72 hook is a connection to the raw Ethernet device.
73 When connected, all incoming packets are forwarded to this hook,
74 instead of being passed to the kernel for upper layer processing.
75 Writing to this hook results in a raw Ethernet frame being transmitted
77 Normal outgoing packets are not affected by
83 hook is a connection to the upper protocol layers.
84 When connected, all outgoing packets are forwarded to this hook,
85 instead of being transmitted by the device.
86 Writing to this hook results in a raw Ethernet frame being received by
87 the kernel just as if it had come in over the wire.
88 Normal incoming packets are not affected by
96 except that only unrecognized packets (that would otherwise be discarded)
97 are written to the hook, while other normal incoming traffic is unaffected.
98 Unrecognized packets written to
100 will be forwarded back out to
104 In all cases, frames are raw Ethernet frames with the standard
105 14 byte Ethernet header (but no checksum).
107 When no hooks are connected,
111 are in effect connected together,
112 so that packets flow normally upwards and downwards.
114 This node type supports the following hooks:
115 .Bl -tag -width ".Va orphans"
117 Connection to the lower device link layer.
119 Connection to the upper protocol layers.
123 but only receives unrecognized packets.
126 This node type supports the generic control messages, plus the following:
128 .It Dv NGM_ETHER_GET_IFNAME Pq Ic getifname
129 Returns the name of the associated interface as a
130 .Dv NUL Ns -terminated
133 Normally this is the same as the name of the node.
134 .It Dv NGM_ETHER_GET_IFINDEX Pq Ic getifindex
135 Returns the global index of the associated interface as a 32 bit integer.
136 .It Dv NGM_ETHER_GET_ENADDR Pq Ic getenaddr
137 Returns the device's unique six byte Ethernet address.
138 .It Dv NGM_ETHER_SET_ENADDR Pq Ic setenaddr
139 Sets the device's unique six byte Ethernet address.
140 This control message is equivalent to using the
144 .It Dv NGM_ETHER_SET_PROMISC Pq Ic setpromisc
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 Any non-zero value enables promiscuous mode.
149 .It Dv NGM_ETHER_GET_PROMISC Pq Ic getpromisc
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 Pq Ic setautosrc
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 disabled.
164 .It Dv NGM_ETHER_GET_AUTOSRC Pq Ic getautosrc
165 Get the current value of the node's source address override flag.
166 The returned value is always either one or zero.
167 .It Dv NGM_ETHER_ADD_MULTI Pq Ic addmulti
168 Join Ethernet multicast group.
169 This control message is equivalent to using the
173 .It Dv NGM_ETHER_DEL_MULTI Pq Ic delmulti
174 Leave Ethernet multicast group.
175 This control message is equivalent to using the
179 .It Dv NGM_ETHER_DETACH Pq Ic detach
180 Detach from underlying Ethernet interface and shut down node.
185 control message, all hooks are disconnected, promiscuous mode is disabled,
186 but the node is not removed.
187 Node can be shut down only using
190 If the interface itself is detached (e.g., because of PC Card removal), the
191 node disappears as well.
193 This command dumps all unrecognized packets received by the
195 interface to standard output decoded in hex and
198 .Dl "nghook -a fxp0: orphans"
200 This command sends the contents of
205 .Dl "cat sample.pkt | nghook fxp0: orphans"
207 These commands insert an
213 protocol layers, which can be used for
214 tracing packet flow, statistics, etc.:
215 .Bd -literal -offset indent
216 ngctl mkpeer fxp0: tee lower right
217 ngctl connect fxp0: lower upper left
227 .An Julian Elischer Aq julian@FreeBSD.org
228 .An Archie Cobbs Aq archie@FreeBSD.org
230 The automatic KLD module loading mechanism that works for most
231 other Netgraph node types does not work for the
236 nodes are not created on demand; instead, they are created when
237 Ethernet interfaces are attached or when the KLD is first loaded.
238 Therefore, if the KLD is not statically compiled into the kernel,
239 it is necessary to load the KLD manually in order to bring the
241 nodes into existence.