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 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_NODESIZ" 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_HOOKSIZ" 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 217Netgraph nodes and support routines generally run inside critical 218sections. 219However, some nodes may want to send data and control messages 220from a different priority level. Netgraph supplies queueing routines which 221utilize the NETISR system to move message delivery inside a critical 222section. 223Note that messages are always received from inside a critical section. 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 256to the following node methods (all from inside critical sections) 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 313.In netgraph/netgraph.h . 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.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 424One could always send a control message to node C from anywhere 425by using the name 426.Em "Frame1:uplink.dlci16" . 427Similarly, 428.Em "Frame1:uplink.dlci20" 429could reliably be used to reach node D, and node A could refer 430to node B as 431.Em ".:uplink" , 432or simply 433.Em "uplink" . 434Conversely, B can refer to A as 435.Em "data" . 436The address 437.Em "mux.data" 438could be used by both nodes C and D to address a message to node A. 439.Pp 440Note that this is only for 441.Em control messages . 442Data messages are routed one hop at a time, by specifying the departing 443hook, with each node making the next routing decision. So when B 444receives a frame on hook 445.Em data 446it decodes the frame relay header to determine the DLCI, 447and then forwards the unwrapped frame to either C or D. 448.Pp 449A similar graph might be used to represent multi-link PPP running 450over 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 462Interesting members of the node and hook structures are shown below: 463.Bd -literal 464struct 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}; 472typedef struct ng_node *node_p; 473 474struct 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}; 482typedef struct ng_hook *hook_p; 483.Ed 484.Pp 485The maintenance of the name pointers, reference counts, and linked list 486of hooks for each node is handled automatically by the 487.Nm 488subsystem. 489Typically a node's private info contains a back-pointer to the node or hook 490structure, which counts as a new reference that must be registered by 491incrementing 492.Dv "node->refs" . 493.Pp 494From a hook you can obtain the corresponding node, and from 495a node the list of all active hooks. 496.Pp 497Node types are described by these structures: 498.Bd -literal 499/** How to convert a control message from binary <-> ASCII */ 500struct 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}; 507 508struct ng_type { 509 u_int32_t version; /* Must equal NG_VERSION */ 510 const char *name; /* Unique type name */ 511 512 /* Module event handler */ 513 modeventhand_t mod_event; /* Handle load/unload (optional) */ 514 515 /* Constructor */ 516 int (*constructor)(node_p *node); /* Create a new node */ 517 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 */ 527 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 */ 534 535 /** How to convert control messages binary <-> ASCII */ 536 const struct ng_cmdlist *cmdlist; /* Optional; may be NULL */ 537}; 538.Ed 539.Pp 540Control messages have the following structure: 541.Bd -literal 542#define NG_CMDSTRSIZ 16 /* Max command string (including null) */ 543 544struct 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}; 557 558#define NG_VERSION 1 /* Netgraph version */ 559#define NGF_ORIG 0x0000 /* Command */ 560#define NGF_RESP 0x0001 /* Response */ 561.Ed 562.Pp 563Control messages have the fixed header shown above, followed by a 564variable length data section which depends on the type cookie 565and the command. Each field is explained below: 566.Bl -tag -width xxx 567.It Dv version 568Indicates the version of netgraph itself. The current version is 569.Dv NG_VERSION . 570.It Dv arglen 571This is the length of any extra arguments, which begin at 572.Dv data . 573.It Dv flags 574Indicates whether this is a command or a response control message. 575.It Dv token 576The 577.Dv token 578is a means by which a sender can match a reply message to the 579corresponding command message; the reply always has the same token. 580.Pp 581.It Dv typecookie 582The corresponding node type's unique 32-bit value. 583If a node doesn't recognize the type cookie it must reject the message 584by returning 585.Er EINVAL . 586.Pp 587Each type should have an include file that defines the commands, 588argument format, and cookie for its own messages. 589The typecookie 590insures that the same header file was included by both sender and 591receiver; when an incompatible change in the header file is made, 592the typecookie 593.Em must 594be changed. 595The de facto method for generating unique type cookies is to take the 596seconds from the epoch at the time the header file is written 597(i.e., the output of 598.Dv "date -u +'%s'" ) . 599.Pp 600There is a predefined typecookie 601.Dv NGM_GENERIC_COOKIE 602for the 603.Dq generic 604node type, and 605a corresponding set of generic messages which all nodes understand. 606The handling of these messages is automatic. 607.It Dv command 608The identifier for the message command. This is type specific, 609and is defined in the same header file as the typecookie. 610.It Dv cmdstr 611Room for a short human readable version of 612.Dq command 613(for debugging purposes only). 614.El 615.Pp 616Some modules may choose to implement messages from more than one 617of the header files and thus recognize more than one type cookie. 618.Sh Control Message ASCII Form 619Control messages are in binary format for efficiency. However, for 620debugging and human interface purposes, and if the node type supports 621it, control messages may be converted to and from an equivalent 622.Tn ASCII 623form. The 624.Tn ASCII 625form is similar to the binary form, with two exceptions: 626.Pp 627.Bl -tag -compact -width xxx 628.It o 629The 630.Dv cmdstr 631header field must contain the 632.Tn ASCII 633name of the command, corresponding to the 634.Dv cmd 635header field. 636.It o 637The 638.Dv args 639field contains a NUL-terminated 640.Tn ASCII 641string version of the message arguments. 642.El 643.Pp 644In general, the arguments field of a control message can be any 645arbitrary C data type. Netgraph includes parsing routines to support 646some pre-defined datatypes in 647.Tn ASCII 648with this simple syntax: 649.Pp 650.Bl -tag -compact -width xxx 651.It o 652Integer types are represented by base 8, 10, or 16 numbers. 653.It o 654Strings are enclosed in double quotes and respect the normal 655C language backslash escapes. 656.It o 657IP addresses have the obvious form. 658.It o 659Arrays are enclosed in square brackets, with the elements listed 660consecutively starting at index zero. An element may have an optional 661index and equals sign preceding it. Whenever an element 662does not have an explicit index, the index is implicitly the previous 663element's index plus one. 664.It o 665Structures are enclosed in curly braces, and each field is specified 666in the form 667.Dq fieldname=value . 668.It o 669Any array element or structure field whose value is equal to its 670.Dq default value 671may be omitted. For integer types, the default value 672is usually zero; for string types, the empty string. 673.It o 674Array elements and structure fields may be specified in any order. 675.El 676.Pp 677Each node type may define its own arbitrary types by providing 678the necessary routines to parse and unparse. 679.Tn ASCII 680forms defined 681for a specific node type are documented in the documentation for 682that node type. 683.Sh Generic Control Messages 684There are a number of standard predefined messages that will work 685for any node, as they are supported directly by the framework itself. 686These are defined in 687.In netgraph/ng_message.h 688along with the basic layout of messages and other similar information. 689.Bl -tag -width xxx 690.It Dv NGM_CONNECT 691Connect to another node, using the supplied hook names on either end. 692.It Dv NGM_MKPEER 693Construct a node of the given type and then connect to it using the 694supplied hook names. 695.It Dv NGM_SHUTDOWN 696The target node should disconnect from all its neighbours and shut down. 697Persistent nodes such as those representing physical hardware 698might not disappear from the node namespace, but only reset themselves. 699The node must disconnect all of its hooks. 700This may result in neighbors shutting themselves down, and possibly a 701cascading shutdown of the entire connected graph. 702.It Dv NGM_NAME 703Assign a name to a node. Nodes can exist without having a name, and this 704is the default for nodes created using the 705.Dv NGM_MKPEER 706method. Such nodes can only be addressed relatively or by their ID number. 707.It Dv NGM_RMHOOK 708Ask the node to break a hook connection to one of its neighbours. 709Both nodes will have their 710.Dq disconnect 711method invoked. 712Either node may elect to totally shut down as a result. 713.It Dv NGM_NODEINFO 714Asks the target node to describe itself. The four returned fields 715are the node name (if named), the node type, the node ID and the 716number of hooks attached. The ID is an internal number unique to that node. 717.It Dv NGM_LISTHOOKS 718This returns the information given by 719.Dv NGM_NODEINFO , 720but in addition 721includes an array of fields describing each link, and the description for 722the node at the far end of that link. 723.It Dv NGM_LISTNAMES 724This returns an array of node descriptions (as for 725.Dv NGM_NODEINFO ")" 726where each entry of the array describes a named node. 727All named nodes will be described. 728.It Dv NGM_LISTNODES 729This is the same as 730.Dv NGM_LISTNAMES 731except that all nodes are listed regardless of whether they have a name or not. 732.It Dv NGM_LISTTYPES 733This returns a list of all currently installed netgraph types. 734.It Dv NGM_TEXT_STATUS 735The node may return a text formatted status message. 736The status information is determined entirely by the node type. 737It is the only "generic" message 738that requires any support within the node itself and as such the node may 739elect to not support this message. The text response must be less than 740.Dv NG_TEXTRESPONSE 741bytes in length (presently 1024). This can be used to return general 742status information in human readable form. 743.It Dv NGM_BINARY2ASCII 744This message converts a binary control message to its 745.Tn ASCII 746form. 747The entire control message to be converted is contained within the 748arguments field of the 749.Dv NGM_BINARY2ASCII 750message itself. If successful, the reply will contain the same control 751message in 752.Tn ASCII 753form. 754A node will typically only know how to translate messages that it 755itself understands, so the target node of the 756.Dv NGM_BINARY2ASCII 757is often the same node that would actually receive that message. 758.It Dv NGM_ASCII2BINARY 759The opposite of 760.Dv NGM_BINARY2ASCII . 761The entire control message to be converted, in 762.Tn ASCII 763form, is contained 764in the arguments section of the 765.Dv NGM_ASCII2BINARY 766and need only have the 767.Dv flags , 768.Dv cmdstr , 769and 770.Dv arglen 771header fields filled in, plus the NUL-terminated string version of 772the arguments in the arguments field. If successful, the reply 773contains the binary version of the control message. 774.El 775.Sh Metadata 776Data moving through the 777.Nm 778system can be accompanied by meta-data that describes some 779aspect of that data. The form of the meta-data is a fixed header, 780which contains enough information for most uses, and can optionally 781be supplemented by trailing 782.Em option 783structures, which contain a 784.Em cookie 785(see the section on control messages), an identifier, a length and optional 786data. If a node does not recognize the cookie associated with an option, 787it should ignore that option. 788.Pp 789Meta data might include such things as priority, discard eligibility, 790or special processing requirements. It might also mark a packet for 791debug status, etc. The use of meta-data is still experimental. 792.Sh INITIALIZATION 793The base 794.Nm 795code may either be statically compiled 796into the kernel or else loaded dynamically as a KLD via 797.Xr kldload 8 . 798In the former case, include 799.Pp 800.D1 Cd options NETGRAPH 801.Pp 802in your kernel configuration file. You may also include selected 803node 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 810Once the 811.Nm 812subsystem is loaded, individual node types may be loaded at any time 813as KLD modules via 814.Xr kldload 8 . 815Moreover, 816.Nm 817knows how to automatically do this; when a request to create a new 818node of unknown type 819.Em type 820is made, 821.Nm 822will attempt to load the KLD module 823.Pa ng_type.ko . 824.Pp 825Types can also be installed at boot time, as certain device drivers 826may want to export each instance of the device as a netgraph node. 827.Pp 828In general, new types can be installed at any time from within the 829kernel by calling 830.Fn ng_newtype , 831supplying a pointer to the type's 832.Dv struct ng_type 833structure. 834.Pp 835The 836.Fn NETGRAPH_INIT 837macro automates this process by using a linker set. 838.Sh EXISTING NODE TYPES 839Several node types currently exist. Each is fully documented 840in its own man page: 841.Bl -tag -width xxx 842.It SOCKET 843The socket type implements two new sockets in the new protocol domain 844.Dv PF_NETGRAPH . 845The new sockets protocols are 846.Dv NG_DATA 847and 848.Dv NG_CONTROL , 849both of type 850.Dv SOCK_DGRAM . 851Typically one of each is associated with a socket node. 852When both sockets have closed, the node will shut down. The 853.Dv NG_DATA 854socket is used for sending and receiving data, while the 855.Dv NG_CONTROL 856socket is used for sending and receiving control messages. 857Data and control messages are passed using the 858.Xr sendto 2 859and 860.Xr recvfrom 2 861calls, using a 862.Dv struct sockaddr_ng 863socket address. 864.Pp 865.It HOLE 866Responds only to generic messages and is a 867.Dq black hole 868for data, Useful for testing. Always accepts new hooks. 869.Pp 870.It ECHO 871Responds only to generic messages and always echoes data back through the 872hook from which it arrived. Returns any non generic messages as their 873own response. Useful for testing. Always accepts new hooks. 874.Pp 875.It TEE 876This node is useful for 877.Dq snooping . 878It has 4 hooks: 879.Dv left , 880.Dv right , 881.Dv left2right , 882and 883.Dv right2left . 884Data entering from the right is passed to the left and duplicated on 885.Dv right2left , 886and data entering from the left is passed to the right and 887duplicated on 888.Dv left2right . 889Data entering from 890.Dv left2right 891is sent to the right and data from 892.Dv right2left 893to left. 894.Pp 895.It RFC1490 MUX 896Encapsulates/de-encapsulates frames encoded according to RFC 1490. 897Has a hook for the encapsulated packets 898.Pq Dq downstream 899and one hook 900for each protocol (i.e., IP, PPP, etc.). 901.Pp 902.It FRAME RELAY MUX 903Encapsulates/de-encapsulates Frame Relay frames. 904Has a hook for the encapsulated packets 905.Pq Dq downstream 906and one hook 907for each DLCI. 908.Pp 909.It FRAME RELAY LMI 910Automatically handles frame relay 911.Dq LMI 912(link management interface) operations and packets. 913Automatically probes and detects which of several LMI standards 914is in use at the exchange. 915.Pp 916.It TTY 917This node is also a line discipline. It simply converts between mbuf 918frames and sequential serial data, allowing a tty to appear as a netgraph 919node. It has a programmable 920.Dq hotkey 921character. 922.Pp 923.It ASYNC 924This node encapsulates and de-encapsulates asynchronous frames 925according to RFC 1662. This is used in conjunction with the TTY node 926type for supporting PPP links over asynchronous serial lines. 927.Pp 928.It INTERFACE 929This node is also a system networking interface. It has hooks representing 930each protocol family (IP, AppleTalk, IPX, etc.) and appears in the output of 931.Xr ifconfig 8 . 932The interfaces are named 933.Em ng0 , 934.Em ng1 , 935etc. 936.El 937.Sh NOTES 938Whether a named node exists can be checked by trying to send a control message 939to it (e.g., 940.Dv NGM_NODEINFO ) . 941If it does not exist, 942.Er ENOENT 943will be returned. 944.Pp 945All data messages are mbuf chains with the M_PKTHDR flag set. 946.Pp 947Nodes are responsible for freeing what they allocate. 948There are three exceptions: 949.Bl -tag -width xxxx 950.It 1 951Mbufs sent across a data link are never to be freed by the sender. 952.It 2 953Any meta-data information traveling with the data has the same restriction. 954It might be freed by any node the data passes through, and a 955.Dv NULL 956passed onwards, but the caller will never free it. 957Two macros 958.Fn NG_FREE_META "meta" 959and 960.Fn NG_FREE_DATA "m" "meta" 961should be used if possible to free data and meta data (see 962.In netgraph/netgraph.h ) . 963.It 3 964Messages sent using 965.Fn ng_send_msg 966are freed by the callee. As in the case above, the addresses 967associated with the message are freed by whatever allocated them so the 968recipient 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 973Definitions for use solely within the kernel by 974.Nm 975nodes. 976.It In netgraph/ng_message.h 977Definitions needed by any file that needs to deal with 978.Nm 979messages. 980.It In netgraph/socket/ng_socket.h 981Definitions needed to use 982.Nm 983socket type nodes. 984.It In netgraph/{type}/ng_{type}.h 985Definitions needed to use 986.Nm 987{type} 988nodes, including the type cookie definition. 989.It Pa /boot/modules/netgraph.ko 990Netgraph subsystem loadable KLD module. 991.It Pa /boot/modules/ng_{type}.ko 992Loadable KLD module for node type {type}. 993.El 994.Sh USER MODE SUPPORT 995There is a library for supporting user-mode programs that wish 996to interact with the netgraph system. See 997.Xr netgraph 3 998for details. 999.Pp 1000Two user-mode support programs, 1001.Xr ngctl 8 1002and 1003.Xr nghook 8 , 1004are available to assist manual configuration and debugging. 1005.Pp 1006There are a few useful techniques for debugging new node types. 1007First, implementing new node types in user-mode first 1008makes debugging easier. 1009The 1010.Em tee 1011node type is also useful for debugging, especially in conjunction with 1012.Xr ngctl 8 1013and 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 1045The 1046.Nm 1047system was designed and first implemented at Whistle Communications, Inc.\& 1048in a version of 1049.Fx 2.2 1050customized for the Whistle InterJet. 1051It 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 , 1056with contributions by 1057.An Archie Cobbs Aq archie@FreeBSD.org . 1058