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