- Uniformly use .In for header file references.
[dragonfly.git] / share / man / man4 / netgraph.4
CommitLineData
984263bc
MD
1.\" Copyright (c) 1996-1999 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.\" Authors: Julian Elischer <julian@FreeBSD.org>
34.\" Archie Cobbs <archie@FreeBSD.org>
35.\"
36.\" $FreeBSD: src/share/man/man4/netgraph.4,v 1.39.2.1 2001/12/21 09:00:50 ru Exp $
44cb301e 37.\" $DragonFly: src/share/man/man4/netgraph.4,v 1.6 2006/05/26 19:39:39 swildner Exp $
984263bc
MD
38.\" $Whistle: netgraph.4,v 1.7 1999/01/28 23:54:52 julian Exp $
39.\"
40.Dd January 19, 1999
41.Dt NETGRAPH 4
42.Os
43.Sh NAME
44.Nm netgraph
45.Nd graph based kernel networking subsystem
46.Sh DESCRIPTION
47The
48.Nm
49system provides a uniform and modular system for the implementation
50of kernel objects which perform various networking functions. The objects,
51known as
52.Em nodes ,
53can be arranged into arbitrarily complicated graphs. Nodes have
54.Em hooks
55which are used to connect two nodes together, forming the edges in the graph.
56Nodes communicate along the edges to process data, implement protocols, etc.
57.Pp
58The aim of
59.Nm
60is to supplement rather than replace the existing kernel networking
61infrastructure. It provides:
62.Pp
63.Bl -bullet -compact -offset 2n
64.It
65A flexible way of combining protocol and link level drivers
66.It
67A modular way to implement new protocols
68.It
69A common framework for kernel entities to inter-communicate
70.It
71A reasonably fast, kernel-based implementation
72.El
73.Sh Nodes and Types
74The most fundamental concept in
75.Nm
76is that of a
77.Em node .
78All nodes implement a number of predefined methods which allow them
79to interact with other nodes in a well defined manner.
80.Pp
81Each node has a
82.Em type ,
83which is a static property of the node determined at node creation time.
84A node's type is described by a unique
85.Tn ASCII
86type name.
87The type implies what the node does and how it may be connected
88to other nodes.
89.Pp
90In object-oriented language, types are classes and nodes are instances
91of their respective class. All node types are subclasses of the generic node
92type, and hence inherit certain common functionality and capabilities
93(e.g., the ability to have an
94.Tn ASCII
95name).
96.Pp
97Nodes may be assigned a globally unique
98.Tn ASCII
99name which can be
100used to refer to the node.
101The name must not contain the characters
102.Dq .\&
103or
104.Dq \&:
105and is limited to
106.Dv "NG_NODELEN + 1"
107characters (including NUL byte).
108.Pp
109Each node instance has a unique
110.Em ID number
111which is expressed as a 32-bit hex value. This value may be used to
112refer to a node when there is no
113.Tn ASCII
114name assigned to it.
115.Sh Hooks
116Nodes are connected to other nodes by connecting a pair of
117.Em hooks ,
118one from each node. Data flows bidirectionally between nodes along
119connected pairs of hooks. A node may have as many hooks as it
120needs, and may assign whatever meaning it wants to a hook.
121.Pp
122Hooks have these properties:
123.Pp
124.Bl -bullet -compact -offset 2n
125.It
126A hook has an
127.Tn ASCII
128name which is unique among all hooks
129on that node (other hooks on other nodes may have the same name).
130The name must not contain a
131.Dq .\&
132or a
133.Dq \&:
134and is
135limited to
136.Dv "NG_HOOKLEN + 1"
137characters (including NUL byte).
138.It
139A hook is always connected to another hook. That is, hooks are
140created at the time they are connected, and breaking an edge by
141removing either hook destroys both hooks.
142.El
143.Pp
144A node may decide to assign special meaning to some hooks.
145For example, connecting to the hook named
146.Dq debug
147might trigger
148the node to start sending debugging information to that hook.
149.Sh Data Flow
150Two types of information flow between nodes: data messages and
151control messages. Data messages are passed in mbuf chains along the edges
152in the graph, one edge at a time. The first mbuf in a chain must have the
153.Dv M_PKTHDR
154flag set. Each node decides how to handle data coming in on its hooks.
155.Pp
156Control messages are type-specific C structures sent from one node
157directly to some arbitrary other node. Control messages have a common
158header format, followed by type-specific data, and are binary structures
159for efficiency. However, node types also may support conversion of the
160type specific data between binary and
161.Tn ASCII
162for debugging and human interface purposes (see the
163.Dv NGM_ASCII2BINARY
164and
165.Dv NGM_BINARY2ASCII
166generic control messages below). Nodes are not required to support
167these conversions.
168.Pp
169There are two ways to address a control message. If
170there is a sequence of edges connecting the two nodes, the message
171may be
172.Dq source routed
173by specifying the corresponding sequence
174of hooks as the destination address for the message (relative
175addressing). Otherwise, the recipient node global
176.Tn ASCII
177name
178(or equivalent ID based name) is used as the destination address
179for the message (absolute addressing). The two types of addressing
180may be combined, by specifying an absolute start node and a sequence
181of hooks.
182.Pp
183Messages often represent commands that are followed by a reply message
184in the reverse direction. To facilitate this, the recipient of a
185control message is supplied with a
186.Dq return address
187that is suitable for addressing a reply.
188.Pp
189Each control message contains a 32 bit value called a
190.Em typecookie
191indicating the type of the message, i.e., how to interpret it.
192Typically each type defines a unique typecookie for the messages
193that it understands. However, a node may choose to recognize and
194implement more than one type of message.
195.Sh Netgraph is Functional
196In order to minimize latency, most
197.Nm
198operations are functional.
199That is, data and control messages are delivered by making function
200calls rather than by using queues and mailboxes. For example, if node
201A wishes to send a data mbuf to neighboring node B, it calls the
202generic
203.Nm
204data delivery function. This function in turn locates
205node B and calls B's
206.Dq receive data
207method. While this mode of operation
208results in good performance, it has a few implications for node
209developers:
210.Pp
211.Bl -bullet -compact -offset 2n
212.It
213Whenever a node delivers a data or control message, the node
214may need to allow for the possibility of receiving a returning
215message before the original delivery function call returns.
216.It
9298ddf3
SW
217Netgraph nodes and support routines generally run inside critical
218sections.
984263bc
MD
219However, some nodes may want to send data and control messages
220from a different priority level. Netgraph supplies queueing routines which
0ee6c762
SW
221utilize the NETISR system to move message delivery inside a critical
222section.
223Note that messages are always received from inside a critical section.
984263bc
MD
224.It
225It's possible for an infinite loop to occur if the graph contains cycles.
226.El
227.Pp
228So far, these issues have not proven problematical in practice.
229.Sh Interaction With Other Parts of the Kernel
230A node may have a hidden interaction with other components of the
231kernel outside of the
232.Nm
233subsystem, such as device hardware,
234kernel protocol stacks, etc. In fact, one of the benefits of
235.Nm
236is the ability to join disparate kernel networking entities together in a
237consistent communication framework.
238.Pp
239An example is the node type
240.Em socket
241which is both a netgraph node and a
242.Xr socket 2
243.Bx
244socket in the protocol family
245.Dv PF_NETGRAPH .
246Socket nodes allow user processes to participate in
247.Nm .
248Other nodes communicate with socket nodes using the usual methods, and the
249node hides the fact that it is also passing information to and from a
250cooperating user process.
251.Pp
252Another example is a device driver that presents
253a node interface to the hardware.
254.Sh Node Methods
255Nodes are notified of the following actions via function calls
0ee6c762 256to the following node methods (all from inside critical sections)
984263bc
MD
257and may accept or reject that action (by returning the appropriate
258error code):
259.Bl -tag -width xxx
260.It Creation of a new node
261The constructor for the type is called. If creation of a new node is
262allowed, the constructor must call the generic node creation
263function (in object-oriented terms, the superclass constructor)
264and then allocate any special resources it needs. For nodes that
265correspond to hardware, this is typically done during the device
266attach routine. Often a global
267.Tn ASCII
268name corresponding to the
269device name is assigned here as well.
270.It Creation of a new hook
271The hook is created and tentatively
272linked to the node, and the node is told about the name that will be
273used to describe this hook. The node sets up any special data structures
274it needs, or may reject the connection, based on the name of the hook.
275.It Successful connection of two hooks
276After both ends have accepted their
277hooks, and the links have been made, the nodes get a chance to
278find out who their peer is across the link and can then decide to reject
279the connection. Tear-down is automatic.
280.It Destruction of a hook
281The node is notified of a broken connection. The node may consider some hooks
282to be critical to operation and others to be expendable: the disconnection
283of one hook may be an acceptable event while for another it
284may affect a total shutdown for the node.
285.It Shutdown of a node
286This method allows a node to clean up
287and to ensure that any actions that need to be performed
288at this time are taken. The method must call the generic (i.e., superclass)
289node destructor to get rid of the generic components of the node.
290Some nodes (usually associated with a piece of hardware) may be
291.Em persistent
292in that a shutdown breaks all edges and resets the node,
293but doesn't remove it, in which case the generic destructor is not called.
294.El
295.Sh Sending and Receiving Data
296Three other methods are also supported by all nodes:
297.Bl -tag -width xxx
298.It Receive data message
299An mbuf chain is passed to the node.
300The node is notified on which hook the data arrived,
301and can use this information in its processing decision.
302The node must must always
303.Fn m_freem
304the mbuf chain on completion or error, or pass it on to another node
305(or kernel module) which will then be responsible for freeing it.
306.Pp
307In addition to the mbuf chain itself there is also a pointer to a
308structure describing meta-data about the message
309(e.g. priority information). This pointer may be
310.Dv NULL
311if there is no additional information. The format for this information is
312described in
44cb301e 313.In netgraph/netgraph.h .
984263bc
MD
314The memory for meta-data must allocated via
315.Fn malloc
316with type
317.Dv M_NETGRAPH .
318As with the data itself, it is the receiver's responsibility to
319.Fn free
320the meta-data. If the mbuf chain is freed the meta-data must
321be freed at the same time. If the meta-data is freed but the
322real data on is passed on, then a
323.Dv NULL
324pointer must be substituted.
325.Pp
326The receiving node may decide to defer the data by queueing it in the
327.Nm
328NETISR system (see below).
329.Pp
330The structure and use of meta-data is still experimental, but is
331presently used in frame-relay to indicate that management packets
332should be queued for transmission
333at a higher priority than data packets. This is required for
334conformance with Frame Relay standards.
335.Pp
336.It Receive queued data message
337Usually this will be the same function as
338.Em Receive data message.
339This is the entry point called when a data message is being handed to
340the node after having been queued in the NETISR system.
341This allows a node to decide in the
342.Em Receive data message
343method that a message should be deferred and queued,
344and be sure that when it is processed from the queue,
345it will not be queued again.
346.It Receive control message
347This method is called when a control message is addressed to the node.
348A return address is always supplied, giving the address of the node
349that originated the message so a reply message can be sent anytime later.
350.Pp
351It is possible for a synchronous reply to be made, and in fact this
352is more common in practice.
353This is done by setting a pointer (supplied as an extra function parameter)
354to point to the reply.
355Then when the control message delivery function returns,
356the caller can check if this pointer has been made non-NULL,
357and if so then it points to the reply message allocated via
358.Fn malloc
359and containing the synchronous response. In both directions,
360(request and response) it is up to the
361receiver of that message to
362.Fn free
363the control message buffer. All control messages and replies are
364allocated with
365.Fn malloc
366type
367.Dv M_NETGRAPH .
368.El
369.Pp
370Much use has been made of reference counts, so that nodes being
371free'd of all references are automatically freed, and this behaviour
372has been tested and debugged to present a consistent and trustworthy
373framework for the
374.Dq type module
375writer to use.
376.Sh Addressing
377The
378.Nm
379framework provides an unambiguous and simple to use method of specifically
380addressing any single node in the graph. The naming of a node is
381independent of its type, in that another node, or external component
382need not know anything about the node's type in order to address it so as
383to send it a generic message type. Node and hook names should be
384chosen so as to make addresses meaningful.
385.Pp
386Addresses are either absolute or relative. An absolute address begins
387with a node name, (or ID), followed by a colon, followed by a sequence of hook
388names separated by periods. This addresses the node reached by starting
389at the named node and following the specified sequence of hooks.
390A relative address includes only the sequence of hook names, implicitly
391starting hook traversal at the local node.
392.Pp
393There are a couple of special possibilities for the node name.
394The name
395.Dq .\&
396(referred to as
397.Dq \&.: )
398always refers to the local node.
399Also, nodes that have no global name may be addressed by their ID numbers,
400by enclosing the hex representation of the ID number within square brackets.
401Here are some examples of valid netgraph addresses:
402.Bd -literal -offset 4n -compact
403
404 .:
405 foo:
406 .:hook1
407 foo:hook1.hook2
408 [f057cd80]:hook1
409.Ed
410.Pp
411Consider the following set of nodes might be created for a site with
412a single physical frame relay line having two active logical DLCI channels,
413with RFC-1490 frames on DLCI 16 and PPP frames over DLCI 20:
414.Pp
415.Bd -literal
416[type SYNC ] [type FRAME] [type RFC1490]
417[ "Frame1" ](uplink)<-->(data)[<un-named>](dlci16)<-->(mux)[<un-named> ]
418[ A ] [ B ](dlci20)<---+ [ C ]
419 |
420 | [ type PPP ]
421 +>(mux)[<un-named>]
422 [ D ]
423.Ed
424.Pp
425One could always send a control message to node C from anywhere
426by using the name
427.Em "Frame1:uplink.dlci16" .
428Similarly,
429.Em "Frame1:uplink.dlci20"
430could reliably be used to reach node D, and node A could refer
431to node B as
432.Em ".:uplink" ,
433or simply
434.Em "uplink" .
435Conversely, B can refer to A as
436.Em "data" .
437The address
438.Em "mux.data"
439could be used by both nodes C and D to address a message to node A.
440.Pp
441Note that this is only for
442.Em control messages .
443Data messages are routed one hop at a time, by specifying the departing
444hook, with each node making the next routing decision. So when B
445receives a frame on hook
446.Em data
447it decodes the frame relay header to determine the DLCI,
448and then forwards the unwrapped frame to either C or D.
449.Pp
450A similar graph might be used to represent multi-link PPP running
451over an ISDN line:
452.Pp
453.Bd -literal
454[ type BRI ](B1)<--->(link1)[ type MPP ]
455[ "ISDN1" ](B2)<--->(link2)[ (no name) ]
456[ ](D) <-+
457 |
458 +----------------+
459 |
460 +->(switch)[ type Q.921 ](term1)<---->(datalink)[ type Q.931 ]
461 [ (no name) ] [ (no name) ]
462.Ed
463.Sh Netgraph Structures
464Interesting members of the node and hook structures are shown below:
465.Bd -literal
466struct ng_node {
467 char *name; /* Optional globally unique name */
468 void *private; /* Node implementation private info */
469 struct ng_type *type; /* The type of this node */
470 int refs; /* Number of references to this struct */
471 int numhooks; /* Number of connected hooks */
472 hook_p hooks; /* Linked list of (connected) hooks */
473};
474typedef struct ng_node *node_p;
475
476struct ng_hook {
477 char *name; /* This node's name for this hook */
478 void *private; /* Node implementation private info */
479 int refs; /* Number of references to this struct */
480 struct ng_node *node; /* The node this hook is attached to */
481 struct ng_hook *peer; /* The other hook in this connected pair */
482 struct ng_hook *next; /* Next in list of hooks for this node */
483};
484typedef struct ng_hook *hook_p;
485.Ed
486.Pp
487The maintenance of the name pointers, reference counts, and linked list
488of hooks for each node is handled automatically by the
489.Nm
490subsystem.
491Typically a node's private info contains a back-pointer to the node or hook
492structure, which counts as a new reference that must be registered by
493incrementing
494.Dv "node->refs" .
495.Pp
496From a hook you can obtain the corresponding node, and from
497a node the list of all active hooks.
498.Pp
499Node types are described by these structures:
500.Bd -literal
501/** How to convert a control message from binary <-> ASCII */
502struct ng_cmdlist {
503 u_int32_t cookie; /* typecookie */
504 int cmd; /* command number */
505 const char *name; /* command name */
506 const struct ng_parse_type *mesgType; /* args if !NGF_RESP */
507 const struct ng_parse_type *respType; /* args if NGF_RESP */
508};
509
510struct ng_type {
511 u_int32_t version; /* Must equal NG_VERSION */
512 const char *name; /* Unique type name */
513
514 /* Module event handler */
515 modeventhand_t mod_event; /* Handle load/unload (optional) */
516
517 /* Constructor */
518 int (*constructor)(node_p *node); /* Create a new node */
519
520 /** Methods using the node **/
521 int (*rcvmsg)(node_p node, /* Receive control message */
522 struct ng_mesg *msg, /* The message */
523 const char *retaddr, /* Return address */
524 struct ng_mesg **resp); /* Synchronous response */
525 int (*shutdown)(node_p node); /* Shutdown this node */
526 int (*newhook)(node_p node, /* create a new hook */
527 hook_p hook, /* Pre-allocated struct */
528 const char *name); /* Name for new hook */
529
530 /** Methods using the hook **/
531 int (*connect)(hook_p hook); /* Confirm new hook attachment */
532 int (*rcvdata)(hook_p hook, /* Receive data on a hook */
533 struct mbuf *m, /* The data in an mbuf */
534 meta_p meta); /* Meta-data, if any */
535 int (*disconnect)(hook_p hook); /* Notify disconnection of hook */
536
537 /** How to convert control messages binary <-> ASCII */
538 const struct ng_cmdlist *cmdlist; /* Optional; may be NULL */
539};
540.Ed
541.Pp
542Control messages have the following structure:
543.Bd -literal
544#define NG_CMDSTRLEN 15 /* Max command string (16 with null) */
545
546struct ng_mesg {
547 struct ng_msghdr {
548 u_char version; /* Must equal NG_VERSION */
549 u_char spare; /* Pad to 2 bytes */
550 u_short arglen; /* Length of cmd/resp data */
551 u_long flags; /* Message status flags */
552 u_long token; /* Reply should have the same token */
553 u_long typecookie; /* Node type understanding this message */
554 u_long cmd; /* Command identifier */
555 u_char cmdstr[NG_CMDSTRLEN+1]; /* Cmd string (for debug) */
556 } header;
557 char data[0]; /* Start of cmd/resp data */
558};
559
560#define NG_VERSION 1 /* Netgraph version */
561#define NGF_ORIG 0x0000 /* Command */
562#define NGF_RESP 0x0001 /* Response */
563.Ed
564.Pp
565Control messages have the fixed header shown above, followed by a
566variable length data section which depends on the type cookie
567and the command. Each field is explained below:
568.Bl -tag -width xxx
569.It Dv version
570Indicates the version of netgraph itself. The current version is
571.Dv NG_VERSION .
572.It Dv arglen
573This is the length of any extra arguments, which begin at
574.Dv data .
575.It Dv flags
576Indicates whether this is a command or a response control message.
577.It Dv token
578The
579.Dv token
580is a means by which a sender can match a reply message to the
581corresponding command message; the reply always has the same token.
582.Pp
583.It Dv typecookie
584The corresponding node type's unique 32-bit value.
585If a node doesn't recognize the type cookie it must reject the message
586by returning
587.Er EINVAL .
588.Pp
589Each type should have an include file that defines the commands,
590argument format, and cookie for its own messages.
591The typecookie
592insures that the same header file was included by both sender and
593receiver; when an incompatible change in the header file is made,
594the typecookie
595.Em must
596be changed.
597The de facto method for generating unique type cookies is to take the
598seconds from the epoch at the time the header file is written
599(i.e., the output of
600.Dv "date -u +'%s'" ) .
601.Pp
602There is a predefined typecookie
603.Dv NGM_GENERIC_COOKIE
604for the
605.Dq generic
606node type, and
607a corresponding set of generic messages which all nodes understand.
608The handling of these messages is automatic.
609.It Dv command
610The identifier for the message command. This is type specific,
611and is defined in the same header file as the typecookie.
612.It Dv cmdstr
613Room for a short human readable version of
614.Dq command
615(for debugging purposes only).
616.El
617.Pp
618Some modules may choose to implement messages from more than one
619of the header files and thus recognize more than one type cookie.
620.Sh Control Message ASCII Form
621Control messages are in binary format for efficiency. However, for
622debugging and human interface purposes, and if the node type supports
623it, control messages may be converted to and from an equivalent
624.Tn ASCII
625form. The
626.Tn ASCII
627form is similar to the binary form, with two exceptions:
628.Pp
629.Bl -tag -compact -width xxx
630.It o
631The
632.Dv cmdstr
633header field must contain the
634.Tn ASCII
635name of the command, corresponding to the
636.Dv cmd
637header field.
638.It o
639The
640.Dv args
641field contains a NUL-terminated
642.Tn ASCII
643string version of the message arguments.
644.El
645.Pp
646In general, the arguments field of a control messgage can be any
647arbitrary C data type. Netgraph includes parsing routines to support
648some pre-defined datatypes in
649.Tn ASCII
650with this simple syntax:
651.Pp
652.Bl -tag -compact -width xxx
653.It o
654Integer types are represented by base 8, 10, or 16 numbers.
655.It o
656Strings are enclosed in double quotes and respect the normal
657C language backslash escapes.
658.It o
659IP addresses have the obvious form.
660.It o
661Arrays are enclosed in square brackets, with the elements listed
662consecutively starting at index zero. An element may have an optional
663index and equals sign preceding it. Whenever an element
664does not have an explicit index, the index is implicitly the previous
665element's index plus one.
666.It o
667Structures are enclosed in curly braces, and each field is specified
668in the form
669.Dq fieldname=value .
670.It o
671Any array element or structure field whose value is equal to its
672.Dq default value
673may be omitted. For integer types, the default value
674is usually zero; for string types, the empty string.
675.It o
676Array elements and structure fields may be specified in any order.
677.El
678.Pp
679Each node type may define its own arbitrary types by providing
680the necessary routines to parse and unparse.
681.Tn ASCII
682forms defined
683for a specific node type are documented in the documentation for
684that node type.
685.Sh Generic Control Messages
686There are a number of standard predefined messages that will work
687for any node, as they are supported directly by the framework itself.
688These are defined in
44cb301e 689.In netgraph/ng_message.h
984263bc
MD
690along with the basic layout of messages and other similar information.
691.Bl -tag -width xxx
692.It Dv NGM_CONNECT
693Connect to another node, using the supplied hook names on either end.
694.It Dv NGM_MKPEER
695Construct a node of the given type and then connect to it using the
696supplied hook names.
697.It Dv NGM_SHUTDOWN
698The target node should disconnect from all its neighbours and shut down.
699Persistent nodes such as those representing physical hardware
700might not disappear from the node namespace, but only reset themselves.
701The node must disconnect all of its hooks.
702This may result in neighbors shutting themselves down, and possibly a
703cascading shutdown of the entire connected graph.
704.It Dv NGM_NAME
705Assign a name to a node. Nodes can exist without having a name, and this
706is the default for nodes created using the
707.Dv NGM_MKPEER
708method. Such nodes can only be addressed relatively or by their ID number.
709.It Dv NGM_RMHOOK
710Ask the node to break a hook connection to one of its neighbours.
711Both nodes will have their
712.Dq disconnect
713method invoked.
714Either node may elect to totally shut down as a result.
715.It Dv NGM_NODEINFO
716Asks the target node to describe itself. The four returned fields
717are the node name (if named), the node type, the node ID and the
718number of hooks attached. The ID is an internal number unique to that node.
719.It Dv NGM_LISTHOOKS
720This returns the information given by
721.Dv NGM_NODEINFO ,
722but in addition
723includes an array of fields describing each link, and the description for
724the node at the far end of that link.
725.It Dv NGM_LISTNAMES
726This returns an array of node descriptions (as for
727.Dv NGM_NODEINFO ")"
728where each entry of the array describes a named node.
729All named nodes will be described.
730.It Dv NGM_LISTNODES
731This is the same as
732.Dv NGM_LISTNAMES
733except that all nodes are listed regardless of whether they have a name or not.
734.It Dv NGM_LISTTYPES
735This returns a list of all currently installed netgraph types.
736.It Dv NGM_TEXT_STATUS
737The node may return a text formatted status message.
738The status information is determined entirely by the node type.
739It is the only "generic" message
740that requires any support within the node itself and as such the node may
741elect to not support this message. The text response must be less than
742.Dv NG_TEXTRESPONSE
743bytes in length (presently 1024). This can be used to return general
744status information in human readable form.
745.It Dv NGM_BINARY2ASCII
746This message converts a binary control message to its
747.Tn ASCII
748form.
749The entire control message to be converted is contained within the
750arguments field of the
751.Dv NGM_BINARY2ASCII
752message itself. If successful, the reply will contain the same control
753message in
754.Tn ASCII
755form.
756A node will typically only know how to translate messages that it
757itself understands, so the target node of the
758.Dv NGM_BINARY2ASCII
759is often the same node that would actually receive that message.
760.It Dv NGM_ASCII2BINARY
761The opposite of
762.Dv NGM_BINARY2ASCII .
763The entire control message to be converted, in
764.Tn ASCII
765form, is contained
766in the arguments section of the
767.Dv NGM_ASCII2BINARY
768and need only have the
769.Dv flags ,
770.Dv cmdstr ,
771and
772.Dv arglen
773header fields filled in, plus the NUL-terminated string version of
774the arguments in the arguments field. If successful, the reply
775contains the binary version of the control message.
776.El
777.Sh Metadata
778Data moving through the
779.Nm
780system can be accompanied by meta-data that describes some
781aspect of that data. The form of the meta-data is a fixed header,
782which contains enough information for most uses, and can optionally
783be supplemented by trailing
784.Em option
785structures, which contain a
786.Em cookie
787(see the section on control messages), an identifier, a length and optional
788data. If a node does not recognize the cookie associated with an option,
789it should ignore that option.
790.Pp
791Meta data might include such things as priority, discard eligibility,
792or special processing requirements. It might also mark a packet for
793debug status, etc. The use of meta-data is still experimental.
794.Sh INITIALIZATION
795The base
796.Nm
797code may either be statically compiled
798into the kernel or else loaded dynamically as a KLD via
799.Xr kldload 8 .
800In the former case, include
801.Pp
a156c807 802.D1 Cd options NETGRAPH
984263bc
MD
803.Pp
804in your kernel configuration file. You may also include selected
805node types in the kernel compilation, for example:
a156c807
SW
806.Bd -unfilled -offset indent
807.Cd options NETGRAPH
808.Cd options NETGRAPH_SOCKET
809.Cd options NETGRAPH_ECHO
984263bc
MD
810.Ed
811.Pp
812Once the
813.Nm
814subsystem is loaded, individual node types may be loaded at any time
815as KLD modules via
816.Xr kldload 8 .
817Moreover,
818.Nm
819knows how to automatically do this; when a request to create a new
820node of unknown type
821.Em type
822is made,
823.Nm
824will attempt to load the KLD module
825.Pa ng_type.ko .
826.Pp
827Types can also be installed at boot time, as certain device drivers
828may want to export each instance of the device as a netgraph node.
829.Pp
830In general, new types can be installed at any time from within the
831kernel by calling
832.Fn ng_newtype ,
833supplying a pointer to the type's
834.Dv struct ng_type
835structure.
836.Pp
837The
838.Fn NETGRAPH_INIT
839macro automates this process by using a linker set.
840.Sh EXISTING NODE TYPES
841Several node types currently exist. Each is fully documented
842in its own man page:
843.Bl -tag -width xxx
844.It SOCKET
845The socket type implements two new sockets in the new protocol domain
846.Dv PF_NETGRAPH .
847The new sockets protocols are
848.Dv NG_DATA
849and
850.Dv NG_CONTROL ,
851both of type
852.Dv SOCK_DGRAM .
853Typically one of each is associated with a socket node.
854When both sockets have closed, the node will shut down. The
855.Dv NG_DATA
856socket is used for sending and receiving data, while the
857.Dv NG_CONTROL
858socket is used for sending and receiving control messages.
859Data and control messages are passed using the
860.Xr sendto 2
861and
862.Xr recvfrom 2
863calls, using a
864.Dv struct sockaddr_ng
865socket address.
866.Pp
867.It HOLE
868Responds only to generic messages and is a
869.Dq black hole
870for data, Useful for testing. Always accepts new hooks.
871.Pp
872.It ECHO
873Responds only to generic messages and always echoes data back through the
874hook from which it arrived. Returns any non generic messages as their
875own response. Useful for testing. Always accepts new hooks.
876.Pp
877.It TEE
878This node is useful for
879.Dq snooping .
880It has 4 hooks:
881.Dv left ,
882.Dv right ,
883.Dv left2right ,
884and
885.Dv right2left .
886Data entering from the right is passed to the left and duplicated on
887.Dv right2left ,
888and data entering from the left is passed to the right and
889duplicated on
890.Dv left2right .
891Data entering from
892.Dv left2right
893is sent to the right and data from
894.Dv right2left
895to left.
896.Pp
897.It RFC1490 MUX
898Encapsulates/de-encapsulates frames encoded according to RFC 1490.
899Has a hook for the encapsulated packets
900.Pq Dq downstream
901and one hook
902for each protocol (i.e., IP, PPP, etc.).
903.Pp
904.It FRAME RELAY MUX
905Encapsulates/de-encapsulates Frame Relay frames.
906Has a hook for the encapsulated packets
907.Pq Dq downstream
908and one hook
909for each DLCI.
910.Pp
911.It FRAME RELAY LMI
912Automatically handles frame relay
913.Dq LMI
914(link management interface) operations and packets.
915Automatically probes and detects which of several LMI standards
916is in use at the exchange.
917.Pp
918.It TTY
919This node is also a line discipline. It simply converts between mbuf
920frames and sequential serial data, allowing a tty to appear as a netgraph
921node. It has a programmable
922.Dq hotkey
923character.
924.Pp
925.It ASYNC
926This node encapsulates and de-encapsulates asynchronous frames
927according to RFC 1662. This is used in conjunction with the TTY node
928type for supporting PPP links over asynchronous serial lines.
929.Pp
930.It INTERFACE
931This node is also a system networking interface. It has hooks representing
932each protocol family (IP, AppleTalk, IPX, etc.) and appears in the output of
933.Xr ifconfig 8 .
934The interfaces are named
935.Em ng0 ,
936.Em ng1 ,
937etc.
938.El
939.Sh NOTES
940Whether a named node exists can be checked by trying to send a control message
941to it (e.g.,
942.Dv NGM_NODEINFO ) .
943If it does not exist,
944.Er ENOENT
945will be returned.
946.Pp
947All data messages are mbuf chains with the M_PKTHDR flag set.
948.Pp
949Nodes are responsible for freeing what they allocate.
950There are three exceptions:
951.Bl -tag -width xxxx
952.It 1
953Mbufs sent across a data link are never to be freed by the sender.
954.It 2
955Any meta-data information traveling with the data has the same restriction.
956It might be freed by any node the data passes through, and a
957.Dv NULL
958passed onwards, but the caller will never free it.
959Two macros
960.Fn NG_FREE_META "meta"
961and
962.Fn NG_FREE_DATA "m" "meta"
963should be used if possible to free data and meta data (see
44cb301e 964.In netgraph/netgraph.h ) .
984263bc
MD
965.It 3
966Messages sent using
967.Fn ng_send_message
968are freed by the callee. As in the case above, the addresses
969associated with the message are freed by whatever allocated them so the
970recipient should copy them if it wants to keep that information.
971.El
972.Sh FILES
973.Bl -tag -width xxxxx -compact
44cb301e 974.It In netgraph/netgraph.h
984263bc
MD
975Definitions for use solely within the kernel by
976.Nm
977nodes.
44cb301e 978.It In netgraph/ng_message.h
984263bc
MD
979Definitions needed by any file that needs to deal with
980.Nm
981messages.
44cb301e 982.It In netgraph/socket/ng_socket.h
984263bc
MD
983Definitions needed to use
984.Nm
985socket type nodes.
44cb301e 986.It In netgraph/{type}/ng_{type}.h
984263bc
MD
987Definitions needed to use
988.Nm
989{type}
990nodes, including the type cookie definition.
991.It Pa /modules/netgraph.ko
992Netgraph subsystem loadable KLD module.
993.It Pa /modules/ng_{type}.ko
994Loadable KLD module for node type {type}.
995.El
996.Sh USER MODE SUPPORT
997There is a library for supporting user-mode programs that wish
998to interact with the netgraph system. See
999.Xr netgraph 3
1000for details.
1001.Pp
1002Two user-mode support programs,
1003.Xr ngctl 8
1004and
1005.Xr nghook 8 ,
1006are available to assist manual configuration and debugging.
1007.Pp
1008There are a few useful techniques for debugging new node types.
1009First, implementing new node types in user-mode first
1010makes debugging easier.
1011The
1012.Em tee
1013node type is also useful for debugging, especially in conjunction with
1014.Xr ngctl 8
1015and
1016.Xr nghook 8 .
1017.Sh SEE ALSO
1018.Xr socket 2 ,
1019.Xr netgraph 3 ,
1020.Xr ng_async 4 ,
1021.Xr ng_bpf 4 ,
1022.Xr ng_cisco 4 ,
1023.Xr ng_echo 4 ,
1024.Xr ng_ether 4 ,
1025.Xr ng_frame_relay 4 ,
1026.Xr ng_hole 4 ,
1027.Xr ng_iface 4 ,
1028.Xr ng_ksocket 4 ,
1029.Xr ng_lmi 4 ,
1030.Xr ng_mppc 4 ,
1031.Xr ng_ppp 4 ,
1032.Xr ng_pppoe 4 ,
1033.Xr ng_rfc1490 4 ,
1034.Xr ng_socket 4 ,
1035.Xr ng_tee 4 ,
1036.Xr ng_tty 4 ,
1037.Xr ng_UI 4 ,
1038.Xr ng_vjc 4 ,
1039.Xr ngctl 8 ,
1040.Xr nghook 8
1041.Sh HISTORY
1042The
1043.Nm
1044system was designed and first implemented at Whistle Communications, Inc.\&
1045in a version of
1046.Fx 2.2
1047customized for the Whistle InterJet.
1048It first made its debut in the main tree in
1049.Fx 3.4 .
1050.Sh AUTHORS
1051.An -nosplit
1052.An Julian Elischer Aq julian@FreeBSD.org ,
1053with contributions by
1054.An Archie Cobbs Aq archie@FreeBSD.org .