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