New man page ng_ether(8) describing the netgraph capabilities of

Ethernet interfaces.

3 files changed, 229 insertions, 1 deletions

diff --git a/share/man/man4/ng_ether.4 b/share/man/man4/ng_ether.4
new file mode 100644
index 0000000..165c348
--- /dev/null
+++ b/share/man/man4/ng_ether.4
@@ -0,0 +1,114 @@
+.\" Copyright (c) 2000 Whistle Communications, Inc.
+.\" All rights reserved.
+.\" 
+.\" Subject to the following obligations and disclaimer of warranty, use and
+.\" redistribution of this software, in source or object code forms, with or
+.\" without modifications are expressly permitted by Whistle Communications;
+.\" provided, however, that:
+.\" 1. Any and all reproductions of the source or object code must include the
+.\"    copyright notice above and the following disclaimer of warranties; and
+.\" 2. No rights are granted, in any manner or form, to use Whistle
+.\"    Communications, Inc. trademarks, including the mark "WHISTLE
+.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
+.\"    such appears in the above copyright notice or in the software.
+.\" 
+.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
+.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
+.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
+.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
+.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
+.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
+.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
+.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
+.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
+.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
+.\" OF SUCH DAMAGE.
+.\" 
+.\" Author: Archie Cobbs <archie@whistle.com>
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 25, 2000
+.Dt NG_ETHER 8
+.Os FreeBSD
+.Sh NAME
+.Nm ng_ether
+.Nd Ethernet netgraph node type
+.Sh SYNOPSIS
+.Fd #include <netgraph/ng_ether.h>
+.Sh DESCRIPTION
+The
+.Nm ether
+netgraph node type allows Ethernet interfaces to interact with
+the
+.Xr netgraph 4 
+networking subsystem.  The kernel must be compiled with
+.Bd -literal
+    options NETGRAPH
+.Ed
+.Pp
+for this functionality to be enabled.
+This causes a netgraph node to be automatically created for each Ethernet
+interface in the system.  The node will have a name equal to
+the name of the interface, and it will be persistent.
+.Pp
+The Ethernet interface continues to function normally until a connection
+is made to one of the two supported hooks,
+.Dv orphans
+or
+.Dv divert .
+The
+.Dv orphans
+hook is used to receive Ethernet frames received by the device and
+having an unknown or unsupported Ethertype.
+The
+.Dv divert
+hook is used to divert
+.Em all
+Ethernet frames received by the device; the interface will otherwise
+appear to go silent until this hook is disconnected.
+.Pp
+Either hook may be used to transmit Ethernet frames by transmitting packets
+to the hook.  In all cases, frames are raw Ethernet frames with the standard
+14 byte Ethernet header (but no checksum).
+.Sh HOOKS
+This node type supports the following hooks:
+.Pp
+.Bl -tag -width orphans
+.It Dv orphans
+This hook transmits Ethernet frames received by the device and
+having an unknown or unsupported Ethertype.  Frames received on
+this hook are written as-is out on the wire.
+.It Dv divert
+When connected, this hook transmits all Ethernet frames received by the device.
+Frames received on this hook are written as-is out on the wire.
+.El
+.Sh CONTROL MESSAGES
+This node type supports only the generic control messages.
+.Sh SHUTDOWN
+This node is persistent.  Upon receipt of a
+.Dv NGM_SHUTDOWN
+control message, all hooks are disconnected.
+.Sh EXAMPLE
+This command will dump all packets received by the
+.Dv fxp0
+interface to standard output as decoded hex and ASCII:
+.Bl -literal
+
+    nghook -a fxp0: divert
+.El
+.Sh SEE ALSO
+.Xr arp 4 ,
+.Xr netgraph 4 ,
+.Xr netintro 4 ,
+.Xr ifconfig 8 ,
+.Xr nghook 8 ,
+.Xr ngctl 8
+.Sh AUTHOR
+.An Julian Elischer Aq julian@freebsd.org
diff --git a/share/man/man8/Makefile b/share/man/man8/Makefile
index 09ce927..abfa46b 100644
--- a/share/man/man8/Makefile
+++ b/share/man/man8/Makefile
@@ -1,7 +1,7 @@
 #	@(#)Makefile	8.1 (Berkeley) 6/5/93
 # $FreeBSD$
 
-MAN8=	adding_user.8 crash.8 diskless.8 intro.8 rc.8 sticky.8
+MAN8=	adding_user.8 crash.8 diskless.8 intro.8 ng_ether.8 rc.8 sticky.8
 
 # XXX NOT IMPORTED:	man8.hp300 man8.tahoe man8.vax
 .if ${MACHINE_ARCH} == "i386"
diff --git a/share/man/man8/ng_ether.8 b/share/man/man8/ng_ether.8
new file mode 100644
index 0000000..165c348
--- /dev/null
+++ b/share/man/man8/ng_ether.8
@@ -0,0 +1,114 @@
+.\" Copyright (c) 2000 Whistle Communications, Inc.
+.\" All rights reserved.
+.\" 
+.\" Subject to the following obligations and disclaimer of warranty, use and
+.\" redistribution of this software, in source or object code forms, with or
+.\" without modifications are expressly permitted by Whistle Communications;
+.\" provided, however, that:
+.\" 1. Any and all reproductions of the source or object code must include the
+.\"    copyright notice above and the following disclaimer of warranties; and
+.\" 2. No rights are granted, in any manner or form, to use Whistle
+.\"    Communications, Inc. trademarks, including the mark "WHISTLE
+.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
+.\"    such appears in the above copyright notice or in the software.
+.\" 
+.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
+.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
+.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
+.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
+.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
+.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
+.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
+.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
+.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
+.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
+.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
+.\" OF SUCH DAMAGE.
+.\" 
+.\" Author: Archie Cobbs <archie@whistle.com>
+.\"
+.\" $FreeBSD$
+.\"
+.Dd January 25, 2000
+.Dt NG_ETHER 8
+.Os FreeBSD
+.Sh NAME
+.Nm ng_ether
+.Nd Ethernet netgraph node type
+.Sh SYNOPSIS
+.Fd #include <netgraph/ng_ether.h>
+.Sh DESCRIPTION
+The
+.Nm ether
+netgraph node type allows Ethernet interfaces to interact with
+the
+.Xr netgraph 4 
+networking subsystem.  The kernel must be compiled with
+.Bd -literal
+    options NETGRAPH
+.Ed
+.Pp
+for this functionality to be enabled.
+This causes a netgraph node to be automatically created for each Ethernet
+interface in the system.  The node will have a name equal to
+the name of the interface, and it will be persistent.
+.Pp
+The Ethernet interface continues to function normally until a connection
+is made to one of the two supported hooks,
+.Dv orphans
+or
+.Dv divert .
+The
+.Dv orphans
+hook is used to receive Ethernet frames received by the device and
+having an unknown or unsupported Ethertype.
+The
+.Dv divert
+hook is used to divert
+.Em all
+Ethernet frames received by the device; the interface will otherwise
+appear to go silent until this hook is disconnected.
+.Pp
+Either hook may be used to transmit Ethernet frames by transmitting packets
+to the hook.  In all cases, frames are raw Ethernet frames with the standard
+14 byte Ethernet header (but no checksum).
+.Sh HOOKS
+This node type supports the following hooks:
+.Pp
+.Bl -tag -width orphans
+.It Dv orphans
+This hook transmits Ethernet frames received by the device and
+having an unknown or unsupported Ethertype.  Frames received on
+this hook are written as-is out on the wire.
+.It Dv divert
+When connected, this hook transmits all Ethernet frames received by the device.
+Frames received on this hook are written as-is out on the wire.
+.El
+.Sh CONTROL MESSAGES
+This node type supports only the generic control messages.
+.Sh SHUTDOWN
+This node is persistent.  Upon receipt of a
+.Dv NGM_SHUTDOWN
+control message, all hooks are disconnected.
+.Sh EXAMPLE
+This command will dump all packets received by the
+.Dv fxp0
+interface to standard output as decoded hex and ASCII:
+.Bl -literal
+
+    nghook -a fxp0: divert
+.El
+.Sh SEE ALSO
+.Xr arp 4 ,
+.Xr netgraph 4 ,
+.Xr netintro 4 ,
+.Xr ifconfig 8 ,
+.Xr nghook 8 ,
+.Xr ngctl 8
+.Sh AUTHOR
+.An Julian Elischer Aq julian@freebsd.org