1 .\" Copyright (c) 1996-1999 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 .\" Authors: Julian Elischer <julian@FreeBSD.org>
34 .\" Archie Cobbs <archie@FreeBSD.org>
36 .\" $FreeBSD: src/share/man/man4/netgraph.4,v 1.39.2.1 2001/12/21 09:00:50 ru Exp $
37 .\" $Whistle: netgraph.4,v 1.7 1999/01/28 23:54:52 julian Exp $
44 .Nd graph based kernel networking subsystem
48 system provides a uniform and modular system for the implementation
49 of kernel objects which perform various networking functions.
52 can be arranged into arbitrarily complicated graphs.
55 which are used to connect two nodes together, forming the edges in the graph.
56 Nodes communicate along the edges to process data, implement protocols, etc.
60 is to supplement rather than replace the existing kernel networking
64 .Bl -bullet -compact -offset 2n
66 A flexible way of combining protocol and link level drivers
68 A modular way to implement new protocols
70 A common framework for kernel entities to inter-communicate
72 A reasonably fast, kernel-based implementation
75 The most fundamental concept in
79 All nodes implement a number of predefined methods which allow them
80 to interact with other nodes in a well defined manner.
84 which is a static property of the node determined at node creation time.
85 A node's type is described by a unique
88 The type implies what the node does and how it may be connected
91 In object-oriented language, types are classes and nodes are instances
92 of their respective class.
93 All node types are subclasses of the generic node
94 type, and hence inherit certain common functionality and capabilities
95 (e.g., the ability to have an
99 Nodes may be assigned a globally unique
102 used to refer to the node.
103 The name must not contain the characters
109 characters (including NUL byte).
111 Each node instance has a unique
113 which is expressed as a 32-bit hex value.
114 This value may be used to refer to a node when there is no
118 Nodes are connected to other nodes by connecting a pair of
121 Data flows bidirectionally between nodes along connected pairs of hooks.
122 A node may have as many hooks as it needs,
123 and may assign whatever meaning it wants to a hook.
125 Hooks have these properties:
127 .Bl -bullet -compact -offset 2n
131 name which is unique among all hooks
132 on that node (other hooks on other nodes may have the same name).
133 The name must not contain a
140 characters (including NUL byte).
142 A hook is always connected to another hook.
143 That is, hooks are created at the time they are connected,
144 and breaking an edge by removing either hook destroys both hooks.
147 A node may decide to assign special meaning to some hooks.
148 For example, connecting to the hook named
151 the node to start sending debugging information to that hook.
153 Two types of information flow between nodes: data messages and
155 Data messages are passed in mbuf chains along the edges
156 in the graph, one edge at a time.
157 The first mbuf in a chain must have the
160 Each node decides how to handle data coming in on its hooks.
162 Control messages are type-specific C structures sent from one node
163 directly to some arbitrary other node.
164 Control messages have a common header format,
165 followed by type-specific data, and are binary structures
167 However, node types also may support conversion of the
168 type specific data between binary and
170 for debugging and human interface purposes (see the
174 generic control messages below).
175 Nodes are not required to support these conversions.
177 There are two ways to address a control message.
178 If there is a sequence of edges connecting the two nodes,
181 by specifying the corresponding sequence
182 of hooks as the destination address for the message (relative
184 Otherwise, the recipient node global
187 (or equivalent ID based name) is used as the destination address
188 for the message (absolute addressing).
189 The two types of addressing may be combined,
190 by specifying an absolute start node and a sequence of hooks.
192 Messages often represent commands that are followed by a reply message
193 in the reverse direction.
194 To facilitate this, the recipient of a
195 control message is supplied with a
197 that is suitable for addressing a reply.
199 Each control message contains a 32 bit value called a
201 indicating the type of the message, i.e. how to interpret it.
202 Typically each type defines a unique typecookie for the messages
204 However, a node may choose to recognize and
205 implement more than one type of message.
206 .Sh Netgraph is Functional
207 In order to minimize latency, most
209 operations are functional.
210 That is, data and control messages are delivered by making function
211 calls rather than by using queues and mailboxes.
212 For example, if node A wishes to send a data mbuf to neighboring node B,
215 data delivery function.
216 This function in turn locates node B and calls B's
219 While this mode of operation results in good performance,
220 it has a few implications for node developers:
222 .Bl -bullet -compact -offset 2n
224 Whenever a node delivers a data or control message, the node
225 may need to allow for the possibility of receiving a returning
226 message before the original delivery function call returns.
228 Netgraph nodes and support routines generally run inside critical
230 However, some nodes may want to send data and control messages
231 from a different priority level.
232 Netgraph supplies queueing routines which utilize the NETISR system to
233 move message delivery inside a critical section.
234 Note that messages are always received from inside a critical section.
236 It's possible for an infinite loop to occur if the graph contains cycles.
239 So far, these issues have not proven problematical in practice.
240 .Sh Interaction With Other Parts of the Kernel
241 A node may have a hidden interaction with other components of the
242 kernel outside of the
244 subsystem, such as device hardware, kernel protocol stacks, etc.
245 In fact, one of the benefits of
247 is the ability to join disparate kernel networking entities together in a
248 consistent communication framework.
250 An example is the node type
252 which is both a netgraph node and a
255 socket in the protocol family
257 Socket nodes allow user processes to participate in
259 Other nodes communicate with socket nodes using the usual methods, and the
260 node hides the fact that it is also passing information to and from a
261 cooperating user process.
263 Another example is a device driver that presents
264 a node interface to the hardware.
266 Nodes are notified of the following actions via function calls
267 to the following node methods (all from inside critical sections)
268 and may accept or reject that action (by returning the appropriate
271 .It Creation of a new node
272 The constructor for the type is called.
273 If creation of a new node is allowed,
274 the constructor must call the generic node creation
275 function (in object-oriented terms, the superclass constructor)
276 and then allocate any special resources it needs.
277 For nodes that correspond to hardware, this is typically done during
278 the device attach routine.
281 name corresponding to the
282 device name is assigned here as well.
283 .It Creation of a new hook
284 The hook is created and tentatively
285 linked to the node, and the node is told about the name that will be
286 used to describe this hook.
287 The node sets up any special data structures it needs,
288 or may reject the connection, based on the name of the hook.
289 .It Successful connection of two hooks
290 After both ends have accepted their
291 hooks, and the links have been made, the nodes get a chance to
292 find out who their peer is across the link and can then decide to reject
294 Tear-down is automatic.
295 .It Destruction of a hook
296 The node is notified of a broken connection.
297 The node may consider some hooks to be critical to operation and others
298 to be expendable: the disconnection of one hook may be an acceptable
299 event while for another it may affect a total shutdown for the node.
300 .It Shutdown of a node
301 This method allows a node to clean up
302 and to ensure that any actions that need to be performed
303 at this time are taken.
304 The method must call the generic (i.e. superclass)
305 node destructor to get rid of the generic components of the node.
306 Some nodes (usually associated with a piece of hardware) may be
308 in that a shutdown breaks all edges and resets the node,
309 but doesn't remove it, in which case the generic destructor is not called.
311 .Sh Sending and Receiving Data
312 Three other methods are also supported by all nodes:
314 .It Receive data message
315 An mbuf chain is passed to the node.
316 The node is notified on which hook the data arrived,
317 and can use this information in its processing decision.
320 the mbuf chain on completion or error, or pass it on to another node
321 (or kernel module) which will then be responsible for freeing it.
323 In addition to the mbuf chain itself there is also a pointer to a
324 structure describing meta-data about the message
325 (e.g. priority information).
328 if there is no additional information.
329 The format for this information is described in
330 .In netgraph/netgraph.h .
331 The memory for meta-data must allocated via
335 As with the data itself, it is the receiver's responsibility to
338 If the mbuf chain is freed the meta-data must be freed at the same time.
339 If the meta-data is freed but the real data on is passed on, then a
341 pointer must be substituted.
343 The receiving node may decide to defer the data by queueing it in the
345 NETISR system (see below).
347 The structure and use of meta-data is still experimental, but is
348 presently used in frame-relay to indicate that management packets
349 should be queued for transmission
350 at a higher priority than data packets.
351 This is required for conformance with Frame Relay standards.
352 .It Receive queued data message
353 Usually this will be the same function as
354 .Em Receive data message.
355 This is the entry point called when a data message is being handed to
356 the node after having been queued in the NETISR system.
357 This allows a node to decide in the
358 .Em Receive data message
359 method that a message should be deferred and queued,
360 and be sure that when it is processed from the queue,
361 it will not be queued again.
362 .It Receive control message
363 This method is called when a control message is addressed to the node.
364 A return address is always supplied, giving the address of the node
365 that originated the message so a reply message can be sent anytime later.
367 It is possible for a synchronous reply to be made, and in fact this
368 is more common in practice.
369 This is done by setting a pointer (supplied as an extra function parameter)
370 to point to the reply.
371 Then when the control message delivery function returns,
372 the caller can check if this pointer has been made non-NULL,
373 and if so then it points to the reply message allocated via
375 and containing the synchronous response.
376 In both directions, (request and response) it is up to the
377 receiver of that message to
379 the control message buffer.
380 All control messages and replies are allocated with
386 Much use has been made of reference counts, so that nodes being
387 free'd of all references are automatically freed, and this behaviour
388 has been tested and debugged to present a consistent and trustworthy
395 framework provides an unambiguous and simple to use method of specifically
396 addressing any single node in the graph.
397 The naming of a node is independent of its type, in that another node,
398 or external component need not know anything about the node's type in
399 order to address it so as to send it a generic message type.
400 Node and hook names should be chosen so as to make addresses meaningful.
402 Addresses are either absolute or relative.
403 An absolute address begins with a node name (or ID), followed by a colon,
404 followed by a sequence of hook names separated by periods.
405 This addresses the node reached by starting
406 at the named node and following the specified sequence of hooks.
407 A relative address includes only the sequence of hook names, implicitly
408 starting hook traversal at the local node.
410 There are a couple of special possibilities for the node name.
415 always refers to the local node.
416 Also, nodes that have no global name may be addressed by their ID numbers,
417 by enclosing the hex representation of the ID number within square brackets.
418 Here are some examples of valid netgraph addresses:
419 .Bd -literal -offset 4n -compact
428 Consider the following set of nodes might be created for a site with
429 a single physical frame relay line having two active logical DLCI channels,
430 with RFC 1490 frames on DLCI 16 and PPP frames over DLCI 20:
432 [type SYNC ] [type FRAME] [type RFC1490]
433 [ "Frame1" ](uplink)<-->(data)[<un-named>](dlci16)<-->(mux)[<un-named> ]
434 [ A ] [ B ](dlci20)<---+ [ C ]
441 One could always send a control message to node C from anywhere
443 .Em "Frame1:uplink.dlci16" .
445 .Em "Frame1:uplink.dlci20"
446 could reliably be used to reach node D, and node A could refer
451 Conversely, B can refer to A as
455 could be used by both nodes C and D to address a message to node A.
457 Note that this is only for
458 .Em control messages .
459 Data messages are routed one hop at a time, by specifying the departing
460 hook, with each node making the next routing decision.
461 So when B receives a frame on hook
463 it decodes the frame relay header to determine the DLCI,
464 and then forwards the unwrapped frame to either C or D.
465 .Sh Netgraph Structures
466 Interesting members of the node and hook structures are shown below:
469 char *name; /* Optional globally unique name */
470 void *private; /* Node implementation private info */
471 struct ng_type *type; /* The type of this node */
472 int refs; /* Number of references to this struct */
473 int numhooks; /* Number of connected hooks */
474 hook_p hooks; /* Linked list of (connected) hooks */
476 typedef struct ng_node *node_p;
479 char *name; /* This node's name for this hook */
480 void *private; /* Node implementation private info */
481 int refs; /* Number of references to this struct */
482 struct ng_node *node; /* The node this hook is attached to */
483 struct ng_hook *peer; /* The other hook in this connected pair */
484 struct ng_hook *next; /* Next in list of hooks for this node */
486 typedef struct ng_hook *hook_p;
489 The maintenance of the name pointers, reference counts, and linked list
490 of hooks for each node is handled automatically by the
493 Typically a node's private info contains a back-pointer to the node or hook
494 structure, which counts as a new reference that must be registered by
498 From a hook you can obtain the corresponding node, and from
499 a node the list of all active hooks.
501 Node types are described by these structures:
503 /** How to convert a control message from binary <-> ASCII */
505 u_int32_t cookie; /* typecookie */
506 int cmd; /* command number */
507 const char *name; /* command name */
508 const struct ng_parse_type *mesgType; /* args if !NGF_RESP */
509 const struct ng_parse_type *respType; /* args if NGF_RESP */
513 u_int32_t version; /* Must equal NG_VERSION */
514 const char *name; /* Unique type name */
516 /* Module event handler */
517 modeventhand_t mod_event; /* Handle load/unload (optional) */
520 int (*constructor)(node_p *node); /* Create a new node */
522 /** Methods using the node **/
523 int (*rcvmsg)(node_p node, /* Receive control message */
524 struct ng_mesg *msg, /* The message */
525 const char *retaddr, /* Return address */
526 struct ng_mesg **resp); /* Synchronous response */
527 int (*shutdown)(node_p node); /* Shutdown this node */
528 int (*newhook)(node_p node, /* create a new hook */
529 hook_p hook, /* Pre-allocated struct */
530 const char *name); /* Name for new hook */
532 /** Methods using the hook **/
533 int (*connect)(hook_p hook); /* Confirm new hook attachment */
534 int (*rcvdata)(hook_p hook, /* Receive data on a hook */
535 struct mbuf *m, /* The data in an mbuf */
536 meta_p meta); /* Meta-data, if any */
537 int (*disconnect)(hook_p hook); /* Notify disconnection of hook */
539 /** How to convert control messages binary <-> ASCII */
540 const struct ng_cmdlist *cmdlist; /* Optional; may be NULL */
544 Control messages have the following structure:
546 #define NG_CMDSTRSIZ 16 /* Max command string (including null) */
550 u_char version; /* Must equal NG_VERSION */
551 u_char spare; /* Pad to 2 bytes */
552 u_short arglen; /* Length of cmd/resp data */
553 u_long flags; /* Message status flags */
554 u_long token; /* Reply should have the same token */
555 u_long typecookie; /* Node type understanding this message */
556 u_long cmd; /* Command identifier */
557 u_char cmdstr[NG_CMDSTRSIZ]; /* Cmd string (for debug) */
559 char data[0]; /* Start of cmd/resp data */
562 #define NG_VERSION 1 /* Netgraph version */
563 #define NGF_ORIG 0x0000 /* Command */
564 #define NGF_RESP 0x0001 /* Response */
567 Control messages have the fixed header shown above, followed by a
568 variable length data section which depends on the type cookie
570 Each field is explained below:
573 Indicates the version of netgraph itself.
574 The current version is
577 This is the length of any extra arguments, which begin at
580 Indicates whether this is a command or a response control message.
584 is a means by which a sender can match a reply message to the
585 corresponding command message; the reply always has the same token.
587 The corresponding node type's unique 32-bit value.
588 If a node doesn't recognize the type cookie it must reject the message
592 Each type should have an include file that defines the commands,
593 argument format, and cookie for its own messages.
595 insures that the same header file was included by both sender and
596 receiver; when an incompatible change in the header file is made,
600 The de facto method for generating unique type cookies is to take the
601 seconds from the epoch at the time the header file is written
603 .Dv "date -u +'%s'" ) .
605 There is a predefined typecookie
606 .Dv NGM_GENERIC_COOKIE
610 a corresponding set of generic messages which all nodes understand.
611 The handling of these messages is automatic.
613 The identifier for the message command.
614 This is type specific,
615 and is defined in the same header file as the typecookie.
617 Room for a short human readable version of
619 (for debugging purposes only).
622 Some modules may choose to implement messages from more than one
623 of the header files and thus recognize more than one type cookie.
624 .Sh Control Message ASCII Form
625 Control messages are in binary format for efficiency.
626 However, for debugging and human interface purposes,
627 and if the node type supports it,
628 control messages may be converted to and from an equivalent
633 form is similar to the binary form, with two exceptions:
635 .Bl -tag -compact -width xxx
639 header field must contain the
641 name of the command, corresponding to the
647 field contains a NUL-terminated
649 string version of the message arguments.
652 In general, the arguments field of a control message can be any
653 arbitrary C data type.
654 Netgraph includes parsing routines to support
655 some pre-defined datatypes in
657 with this simple syntax:
659 .Bl -tag -compact -width xxx
661 Integer types are represented by base 8, 10, or 16 numbers.
663 Strings are enclosed in double quotes and respect the normal
664 C language backslash escapes.
666 IP addresses have the obvious form.
668 Arrays are enclosed in square brackets, with the elements listed
669 consecutively starting at index zero.
670 An element may have an optional index and equals sign preceding it.
671 Whenever an element does not have an explicit index, the index is
672 implicitly the previous element's index plus one.
674 Structures are enclosed in curly braces, and each field is specified
676 .Dq fieldname=value .
678 Any array element or structure field whose value is equal to its
681 For integer types, the default value is usually zero;
682 for string types, the empty string.
684 Array elements and structure fields may be specified in any order.
687 Each node type may define its own arbitrary types by providing
688 the necessary routines to parse and unparse.
691 for a specific node type are documented in the documentation for
693 .Sh Generic Control Messages
694 There are a number of standard predefined messages that will work
695 for any node, as they are supported directly by the framework itself.
697 .In netgraph/ng_message.h
698 along with the basic layout of messages and other similar information.
701 Connect to another node, using the supplied hook names on either end.
703 Construct a node of the given type and then connect to it using the
706 The target node should disconnect from all its neighbours and shut down.
707 Persistent nodes such as those representing physical hardware
708 might not disappear from the node namespace, but only reset themselves.
709 The node must disconnect all of its hooks.
710 This may result in neighbors shutting themselves down, and possibly a
711 cascading shutdown of the entire connected graph.
713 Assign a name to a node.
714 Nodes can exist without having a name, and this
715 is the default for nodes created using the
718 Such nodes can only be addressed relatively or by their ID number.
720 Ask the node to break a hook connection to one of its neighbours.
721 Both nodes will have their
724 Either node may elect to totally shut down as a result.
726 Asks the target node to describe itself.
727 The four returned fields are the node name (if named), the node type,
728 the node ID and the number of hooks attached.
729 The ID is an internal number unique to that node.
731 This returns the information given by
734 includes an array of fields describing each link, and the description for
735 the node at the far end of that link.
737 This returns an array of node descriptions (as for
739 where each entry of the array describes a named node.
740 All named nodes will be described.
744 except that all nodes are listed regardless of whether they have a name or not.
746 This returns a list of all currently installed netgraph types.
747 .It Dv NGM_TEXT_STATUS
748 The node may return a text formatted status message.
749 The status information is determined entirely by the node type.
750 It is the only "generic" message
751 that requires any support within the node itself and as such the node may
752 elect to not support this message.
753 The text response must be less than
755 bytes in length (presently 1024).
756 This can be used to return general
757 status information in human readable form.
758 .It Dv NGM_BINARY2ASCII
759 This message converts a binary control message to its
762 The entire control message to be converted is contained within the
763 arguments field of the
766 If successful, the reply will contain the same control message in
769 A node will typically only know how to translate messages that it
770 itself understands, so the target node of the
772 is often the same node that would actually receive that message.
773 .It Dv NGM_ASCII2BINARY
775 .Dv NGM_BINARY2ASCII .
776 The entire control message to be converted, in
779 in the arguments section of the
781 and need only have the
786 header fields filled in, plus the NUL-terminated string version of
787 the arguments in the arguments field.
788 If successful, the reply
789 contains the binary version of the control message.
792 Data moving through the
794 system can be accompanied by meta-data that describes some
796 The form of the meta-data is a fixed header,
797 which contains enough information for most uses, and can optionally
798 be supplemented by trailing
800 structures, which contain a
802 (see the section on control messages), an identifier, a length and optional
804 If a node does not recognize the cookie associated with an option,
805 it should ignore that option.
807 Meta data might include such things as priority, discard eligibility,
808 or special processing requirements.
809 It might also mark a packet for debug status, etc.
810 The use of meta-data is still experimental.
814 code may either be statically compiled
815 into the kernel or else loaded dynamically as a KLD via
817 In the former case, include
819 .D1 Cd options NETGRAPH
821 in your kernel configuration file.
822 You may also include selected
823 node types in the kernel compilation, for example:
824 .Bd -unfilled -offset indent
826 .Cd options NETGRAPH_SOCKET
827 .Cd options NETGRAPH_ECHO
832 subsystem is loaded, individual node types may be loaded at any time
837 knows how to automatically do this; when a request to create a new
842 will attempt to load the KLD module
845 Types can also be installed at boot time, as certain device drivers
846 may want to export each instance of the device as a netgraph node.
848 In general, new types can be installed at any time from within the
851 supplying a pointer to the type's
857 macro automates this process by using a linker set.
858 .Sh EXISTING NODE TYPES
859 Several node types currently exist.
860 Each is fully documented in its own man page:
863 The socket type implements two new sockets in the new protocol domain
865 The new sockets protocols are
871 Typically one of each is associated with a socket node.
872 When both sockets have closed, the node will shut down.
875 socket is used for sending and receiving data, while the
877 socket is used for sending and receiving control messages.
878 Data and control messages are passed using the
883 .Dv struct sockaddr_ng
886 Responds only to generic messages and is a
888 for data, Useful for testing.
889 Always accepts new hooks.
891 Responds only to generic messages and always echoes data back through the
892 hook from which it arrived.
893 Returns any non generic messages as their own response.
895 Always accepts new hooks.
897 This node is useful for
905 Data entering from the right is passed to the left and duplicated on
907 and data entering from the left is passed to the right and
912 is sent to the right and data from
916 Encapsulates/de-encapsulates frames encoded according to RFC 1490.
917 Has a hook for the encapsulated packets
920 for each protocol (i.e. IP, PPP, etc.).
922 Encapsulates/de-encapsulates Frame Relay frames.
923 Has a hook for the encapsulated packets
928 Automatically handles frame relay
930 (link management interface) operations and packets.
931 Automatically probes and detects which of several LMI standards
932 is in use at the exchange.
934 This node is also a line discipline.
935 It simply converts between mbuf frames and sequential serial data,
936 allowing a tty to appear as a netgraph node.
937 It has a programmable
941 This node encapsulates and de-encapsulates asynchronous frames
942 according to RFC 1662.
943 This is used in conjunction with the TTY node
944 type for supporting PPP links over asynchronous serial lines.
946 This node is also a system networking interface.
947 It has hooks representing each protocol family (IP, AppleTalk, etc.)
948 and appears in the output of
950 The interfaces are named
956 Whether a named node exists can be checked by trying to send a control message
959 If it does not exist,
963 All data messages are mbuf chains with the M_PKTHDR flag set.
965 Nodes are responsible for freeing what they allocate.
966 There are three exceptions:
969 Mbufs sent across a data link are never to be freed by the sender.
971 Any meta-data information traveling with the data has the same restriction.
972 It might be freed by any node the data passes through, and a
974 passed onwards, but the caller will never free it.
976 .Fn NG_FREE_META "meta"
978 .Fn NG_FREE_DATA "m" "meta"
979 should be used if possible to free data and meta data (see
980 .In netgraph/netgraph.h ) .
984 are freed by the callee.
985 As in the case above, the addresses
986 associated with the message are freed by whatever allocated them so the
987 recipient should copy them if it wants to keep that information.
990 .Bl -tag -width xxxxx -compact
991 .It In netgraph/netgraph.h
992 Definitions for use solely within the kernel by
995 .It In netgraph/ng_message.h
996 Definitions needed by any file that needs to deal with
999 .It In netgraph/socket/ng_socket.h
1000 Definitions needed to use
1003 .It In netgraph/{type}/ng_{type}.h
1004 Definitions needed to use
1007 nodes, including the type cookie definition.
1008 .It Pa /boot/kernel/netgraph.ko
1009 Netgraph subsystem loadable KLD module.
1010 .It Pa /boot/kernel/ng_{type}.ko
1011 Loadable KLD module for node type {type}.
1013 .Sh USER MODE SUPPORT
1014 There is a library for supporting user-mode programs that wish
1015 to interact with the netgraph system.
1020 Two user-mode support programs,
1024 are available to assist manual configuration and debugging.
1026 There are a few useful techniques for debugging new node types.
1027 First, implementing new node types in user-mode first
1028 makes debugging easier.
1031 node type is also useful for debugging, especially in conjunction with
1046 .Xr ng_frame_relay 4 ,
1067 system was designed and first implemented at Whistle Communications, Inc.\&
1070 customized for the Whistle InterJet.
1071 It first made its debut in the main tree in
1075 .An Julian Elischer Aq Mt julian@FreeBSD.org ,
1076 with contributions by
1077 .An Archie Cobbs Aq Mt archie@FreeBSD.org .