| netgraph.4 (69027) | netgraph.4 (69922) |
|---|---|
| 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 --- 19 unchanged lines hidden (view full) --- 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.\" | 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 --- 19 unchanged lines hidden (view full) --- 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: head/share/man/man4/netgraph.4 69027 2000-11-22 09:35:58Z ru $ | 36.\" $FreeBSD: head/share/man/man4/netgraph.4 69922 2000-12-12 18:52:14Z julian $ |
| 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 FreeBSD 42.Sh NAME 43.Nm netgraph 44.Nd graph based kernel networking subsystem --- 88 unchanged lines hidden (view full) --- 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. | 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 FreeBSD 42.Sh NAME 43.Nm netgraph 44.Nd graph based kernel networking subsystem --- 88 unchanged lines hidden (view full) --- 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.It 142A hook can be set into a state where incoming packets are always queued 143by the input queuing system, rather than being delivered directly. This 144is used when the two joined nodes need to be decoupled, e.g. if they are 145running at different processor priority levels. (spl) |
|
| 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 --- 11 unchanged lines hidden (view full) --- 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 | 146.El 147.Pp 148A node may decide to assign special meaning to some hooks. 149For example, connecting to the hook named 150.Dq debug 151might trigger 152the node to start sending debugging information to that hook. 153.Sh Data Flow --- 11 unchanged lines hidden (view full) --- 165.Tn ASCII 166for debugging and human interface purposes (see the 167.Dv NGM_ASCII2BINARY 168and 169.Dv NGM_BINARY2ASCII 170generic control messages below). Nodes are not required to support 171these conversions. 172.Pp |
| 168There are two ways to address a control message. If | 173There are three 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 | 174there is a sequence of edges connecting the two nodes, the message 175may be 176.Dq source routed 177by specifying the corresponding sequence |
| 173of hooks as the destination address for the message (relative 174addressing). Otherwise, the recipient node global | 178of |
| 175.Tn ASCII | 179.Tn ASCII |
| 180hook names as the destination address for the message (relative 181addressing). If the destination is adjacent to the source, then the source 182node may simply specify (as a pointer in the code) the hook across which the 183message should be sent. Otherwise, the recipient node global 184.Tn ASCII |
|
| 176name 177(or equivalent ID based name) is used as the destination address | 185name 186(or equivalent ID based name) is used as the destination address |
| 178for the message (absolute addressing). The two types of addressing | 187for the message (absolute addressing). The two types of 188.Tn ASCII 189addressing |
| 179may be combined, by specifying an absolute start node and a sequence | 190may be combined, by specifying an absolute start node and a sequence |
| 180of hooks. | 191of hooks. Only the 192.Tn ASCII 193addressing modes are available to control programs outside the kernel, 194as use of direct pointers is limited of course to kernel modules. |
| 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 | 195.Pp 196Messages often represent commands that are followed by a reply message 197in the reverse direction. To facilitate this, the recipient of a 198control message is supplied with a 199.Dq return address |
| 186that is suitable 187for addressing a reply. | 200that is suitable for addressing a reply. 201In addition, depending on the topology of 202the graph and whether the source has requested it, a pointer to a 203pointer that can be read by the source node may also be supplied. 204This allows the destination node to directly respond in a 205synchronous manner when control returns to the source node, by 206simply pointing the supplied pointer to the response message. 207Such synchronous message responses are more efficient but are not always possible. |
| 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.Pp | 208.Pp 209Each control message contains a 32 bit value called a 210.Em typecookie 211indicating the type of the message, i.e., how to interpret it. 212Typically each type defines a unique typecookie for the messages 213that it understands. However, a node may choose to recognize and 214implement more than one type of message. 215.Pp |
| 196If message is delivered to an address that implies that it arrived 197at that node through a particular hook, that hook is identified to the | 216If a message is delivered to an address that implies that it arrived 217at that node through a particular hook, (as opposed to having been directly 218addressed using its ID or global name), then that hook is identified to the |
| 198receiving node. This allows a message to be rerouted or passed on, should | 219receiving node. This allows a message to be rerouted or passed on, should |
| 199a node decide that this is required. | 220a node decide that this is required, in much the same way that data packets 221are passed around between nodes. A set of standard 222messages for flow control and link management purposes are 223defined by the base system that are usually 224passed around in this manner. Flow control message would usually travel 225in the opposite direction to the data to which they pertain. 226.Pp 227Since flow control packets can also result from data being sent, it is also 228possible to return a synchronous message response to a data packet being 229sent between nodes. (See later). |
| 200.Sh Netgraph is Functional 201In order to minimize latency, most 202.Nm 203operations are functional. 204That is, data and control messages are delivered by making function 205calls rather than by using queues and mailboxes. For example, if node 206A wishes to send a data mbuf to neighboring node B, it calls the 207generic 208.Nm 209data delivery function. This function in turn locates 210node B and calls B's 211.Dq receive data | 230.Sh Netgraph is Functional 231In order to minimize latency, most 232.Nm 233operations are functional. 234That is, data and control messages are delivered by making function 235calls rather than by using queues and mailboxes. For example, if node 236A wishes to send a data mbuf to neighboring node B, it calls the 237generic 238.Nm 239data delivery function. This function in turn locates 240node B and calls B's 241.Dq receive data |
| 212method. | 242method. There are exceptions to this. |
| 213.Pp 214It is allowable for nodes to reject a data packet, or to pass it back to the 215caller in a modified or completely replaced form. The caller can notify the 216node being called that it does not wish to receive any such packets 217by using the 218.Fn NG_SEND_DATA | 243.Pp 244It is allowable for nodes to reject a data packet, or to pass it back to the 245caller in a modified or completely replaced form. The caller can notify the 246node being called that it does not wish to receive any such packets 247by using the 248.Fn NG_SEND_DATA |
| 219macro, in which case, the second node should just discard rejected packets. | 249and 250.Fn NG_SEND_DATA_ONLY 251macros, in which case, the second node should just discard rejected packets. |
| 220If the sender knows how to handle returned packets, it must use the 221.Fn NG_SEND_DATA_RET 222macro, which will adjust the parameters to point to the returned data 223or NULL if no data was returned to the caller. No packet return is possible 224across a queuing link (though an explicitly sent return is of course possible, 225it doesn't mean quite the same thing). 226.Pp 227While this mode of operation --- 4 unchanged lines hidden (view full) --- 232.It 233Whenever a node delivers a data or control message, the node 234may need to allow for the possibility of receiving a returning 235message before the original delivery function call returns. 236.It 237Netgraph nodes and support routines generally run at 238.Fn splnet . 239However, some nodes may want to send data and control messages | 252If the sender knows how to handle returned packets, it must use the 253.Fn NG_SEND_DATA_RET 254macro, which will adjust the parameters to point to the returned data 255or NULL if no data was returned to the caller. No packet return is possible 256across a queuing link (though an explicitly sent return is of course possible, 257it doesn't mean quite the same thing). 258.Pp 259While this mode of operation --- 4 unchanged lines hidden (view full) --- 264.It 265Whenever a node delivers a data or control message, the node 266may need to allow for the possibility of receiving a returning 267message before the original delivery function call returns. 268.It 269Netgraph nodes and support routines generally run at 270.Fn splnet . 271However, some nodes may want to send data and control messages |
| 240from a different priority level. Netgraph supplies queueing routines which 241utilize the NETISR system to move message delivery to | 272from a different priority level. Netgraph supplies a mechanism which 273utilizes the NETISR system to move message and data delivery to |
| 242.Fn splnet . 243Nodes that run at other priorities (e.g. interfaces) can be directly 244linked to other nodes so that the combination runs at the other priority, | 274.Fn splnet . 275Nodes that run at other priorities (e.g. interfaces) can be directly 276linked to other nodes so that the combination runs at the other priority, |
| 245however any interaction with nodes running at splnet MUST be achievd via the | 277however any interaction with nodes running at splnet MUST be achieved via the |
| 246queueing functions, (which use the 247.Fn netisr 248feature of the kernel). 249Note that messages are always received at 250.Fn splnet . 251.It 252It's possible for an infinite loop to occur if the graph contains cycles. 253.El --- 44 unchanged lines hidden (view full) --- 298The hook is created and tentatively 299linked to the node, and the node is told about the name that will be 300used to describe this hook. The node sets up any special data structures 301it needs, or may reject the connection, based on the name of the hook. 302.It Successful connection of two hooks 303After both ends have accepted their 304hooks, and the links have been made, the nodes get a chance to 305find out who their peer is across the link and can then decide to reject | 278queueing functions, (which use the 279.Fn netisr 280feature of the kernel). 281Note that messages are always received at 282.Fn splnet . 283.It 284It's possible for an infinite loop to occur if the graph contains cycles. 285.El --- 44 unchanged lines hidden (view full) --- 330The hook is created and tentatively 331linked to the node, and the node is told about the name that will be 332used to describe this hook. The node sets up any special data structures 333it needs, or may reject the connection, based on the name of the hook. 334.It Successful connection of two hooks 335After both ends have accepted their 336hooks, and the links have been made, the nodes get a chance to 337find out who their peer is across the link and can then decide to reject |
| 306the connection. Tear-down is automatic. | 338the connection. Tear-down is automatic. This is also the time at which 339a node may decide whether to set a particular hook (or its peer) into 340.Em queuing 341mode. |
| 307.It Destruction of a hook 308The node is notified of a broken connection. The node may consider some hooks 309to be critical to operation and others to be expendable: the disconnection 310of one hook may be an acceptable event while for another it 311may effect a total shutdown for the node. 312.It Shutdown of a node 313This method allows a node to clean up 314and to ensure that any actions that need to be performed 315at this time are taken. The method must call the generic (i.e., superclass) 316node destructor to get rid of the generic components of the node. 317Some nodes (usually associated with a piece of hardware) may be 318.Em persistent 319in that a shutdown breaks all edges and resets the node, 320but doesn't remove it, in which case the generic destructor is not called. 321.El 322.Sh Sending and Receiving Data | 342.It Destruction of a hook 343The node is notified of a broken connection. The node may consider some hooks 344to be critical to operation and others to be expendable: the disconnection 345of one hook may be an acceptable event while for another it 346may effect a total shutdown for the node. 347.It Shutdown of a node 348This method allows a node to clean up 349and to ensure that any actions that need to be performed 350at this time are taken. The method must call the generic (i.e., superclass) 351node destructor to get rid of the generic components of the node. 352Some nodes (usually associated with a piece of hardware) may be 353.Em persistent 354in that a shutdown breaks all edges and resets the node, 355but doesn't remove it, in which case the generic destructor is not called. 356.El 357.Sh Sending and Receiving Data |
| 323Three other methods are also supported by all nodes: | 358Two other methods are also supported by all nodes: |
| 324.Bl -tag -width xxx 325.It Receive data message 326An mbuf chain is passed to the node. 327The node is notified on which hook the data arrived, 328and can use this information in its processing decision. 329The receiving node must always 330.Fn m_freem 331the mbuf chain on completion or error, pass it back (reject it), or pass --- 5 unchanged lines hidden (view full) --- 337or in some other way filter it (e.g. packet filtering). 338.Pp 339In addition to the mbuf chain itself there is also a pointer to a 340structure describing meta-data about the message 341(e.g. priority information). This pointer may be 342.Dv NULL 343if there is no additional information. The format for this information is 344described in | 359.Bl -tag -width xxx 360.It Receive data message 361An mbuf chain is passed to the node. 362The node is notified on which hook the data arrived, 363and can use this information in its processing decision. 364The receiving node must always 365.Fn m_freem 366the mbuf chain on completion or error, pass it back (reject it), or pass --- 5 unchanged lines hidden (view full) --- 372or in some other way filter it (e.g. packet filtering). 373.Pp 374In addition to the mbuf chain itself there is also a pointer to a 375structure describing meta-data about the message 376(e.g. priority information). This pointer may be 377.Dv NULL 378if there is no additional information. The format for this information is 379described in |
| 345.Pa netgraph.h . | 380.Pa sys/netgraph/netgraph.h . |
| 346The memory for meta-data must allocated via 347.Fn malloc 348with type 349.Dv M_NETGRAPH . 350As with the data itself, it is the receiver's responsibility to 351.Fn free 352the meta-data. If the mbuf chain is freed the meta-data must 353be freed at the same time. If the meta-data is freed but the 354real data on is passed on, then a 355.Dv NULL 356pointer must be substituted. 357Meta-data may be passed back in the same way that mbuf data may be passed back. 358As with mbuf data, the rejected or returned meta-data pointer may point to 359the same or different meta-data as that passed in, 360and if it is different, the original must be freed. 361.Pp 362The receiving node may decide to defer the data by queueing it in the 363.Nm | 381The memory for meta-data must allocated via 382.Fn malloc 383with type 384.Dv M_NETGRAPH . 385As with the data itself, it is the receiver's responsibility to 386.Fn free 387the meta-data. If the mbuf chain is freed the meta-data must 388be freed at the same time. If the meta-data is freed but the 389real data on is passed on, then a 390.Dv NULL 391pointer must be substituted. 392Meta-data may be passed back in the same way that mbuf data may be passed back. 393As with mbuf data, the rejected or returned meta-data pointer may point to 394the same or different meta-data as that passed in, 395and if it is different, the original must be freed. 396.Pp 397The receiving node may decide to defer the data by queueing it in the 398.Nm |
| 364NETISR system (see below). | 399NETISR system (see below). It achieves this by setting the 400.Dv HK_QUEUE 401flag in the flags word of the hook on which that data will arrive. 402The infrastructure will respect that bit and queue the data for delivery at 403a later time, rather than deliver it directly. A node may decide to set 404the bit on the 405.Em peer 406node, so that it's own output packets are queued. This is used 407by device drivers running at different processor priorities to transfer 408packet delivery to the splnet() level at which the bulk of 409.Nm 410runs. |
| 365.Pp | 411.Pp |
| 366The structure and use of meta-data is still experimental, but is presently used in 367frame-relay to indicate that management packets should be queued for transmission | 412The structure and use of meta-data is still experimental, but is 413presently used in frame-relay to indicate that management packets 414should be queued for transmission |
| 368at a higher priority than data packets. This is required for 369conformance with Frame Relay standards. 370.Pp | 415at a higher priority than data packets. This is required for 416conformance with Frame Relay standards. 417.Pp |
| 371.It Receive queued data message 372Usually this will be the same function as 373.Em Receive data message. 374This is the entry point called when a data message is being handed to 375the node after having been queued in the NETISR system. 376This allows a node to decide in the 377.Em Receive data message 378method that a message should be deferred and queued, 379and be sure that when it is processed from the queue, 380it will not be queued again. | 418The node may also receive information allowing it to send a synchronous 419message response to one of the originators of the data. it is envisionned 420that such a message would contain error or flow-control information. 421Standard messages for these purposes have been defined in 422.Pa sys/netgraph/netgraph.h . |
| 381.It Receive control message 382This method is called when a control message is addressed to the node. 383A return address is always supplied, giving the address of the node 384that originated the message so a reply message can be sent anytime later. 385.Pp 386It is possible for a synchronous reply to be made, and in fact this 387is more common in practice. 388This is done by setting a pointer (supplied as an extra function parameter) --- 51 unchanged lines hidden (view full) --- 440by enclosing the hex representation of the ID number within square brackets. 441Here are some examples of valid netgraph addresses: 442.Bd -literal -offset 4n -compact 443 444 .: 445 foo: 446 .:hook1 447 foo:hook1.hook2 | 423.It Receive control message 424This method is called when a control message is addressed to the node. 425A return address is always supplied, giving the address of the node 426that originated the message so a reply message can be sent anytime later. 427.Pp 428It is possible for a synchronous reply to be made, and in fact this 429is more common in practice. 430This is done by setting a pointer (supplied as an extra function parameter) --- 51 unchanged lines hidden (view full) --- 482by enclosing the hex representation of the ID number within square brackets. 483Here are some examples of valid netgraph addresses: 484.Bd -literal -offset 4n -compact 485 486 .: 487 foo: 488 .:hook1 489 foo:hook1.hook2 |
| 448 [f057cd80]:hook1 | 490 [d80]:hook1 |
| 449.Ed 450.Pp 451Consider the following set of nodes might be created for a site with 452a single physical frame relay line having two active logical DLCI channels, 453with RFC-1490 frames on DLCI 16 and PPP frames over DLCI 20: 454.Pp 455.Bd -literal 456[type SYNC ] [type FRAME] [type RFC1490] --- 36 unchanged lines hidden (view full) --- 493.Em only 494routed one hop at a time, by specifying the departing 495hook, with each node making 496the next routing decision. So when B receives a frame on hook 497.Dq data 498it decodes the frame relay header to determine the DLCI, 499and then forwards the unwrapped frame to either C or D. 500.Pp | 491.Ed 492.Pp 493Consider the following set of nodes might be created for a site with 494a single physical frame relay line having two active logical DLCI channels, 495with RFC-1490 frames on DLCI 16 and PPP frames over DLCI 20: 496.Pp 497.Bd -literal 498[type SYNC ] [type FRAME] [type RFC1490] --- 36 unchanged lines hidden (view full) --- 535.Em only 536routed one hop at a time, by specifying the departing 537hook, with each node making 538the next routing decision. So when B receives a frame on hook 539.Dq data 540it decodes the frame relay header to determine the DLCI, 541and then forwards the unwrapped frame to either C or D. 542.Pp |
| 543In a similar way, flow control messages may be routed in the reverse 544direction to outgoing data. For example a "buffer nearly full" message from 545.Em "Frame1: 546would be passed to node 547.Em B 548which might decide to send similar messages to both nodes 549.Em C 550and 551.Em D . 552The nodes would use 553.Em "Direct hook pointer" 554addressing to route the messages. The message may have travelled from 555.Em "Frame1: 556to 557.Em B 558as a synchronous reply, saving time and cycles. 559 560 561.Pp |
|
| 501A similar graph might be used to represent multi-link PPP running 502over an ISDN line: 503.Pp 504.Bd -literal 505[ type BRI ](B1)<--->(link1)[ type MPP ] 506[ "ISDN1" ](B2)<--->(link2)[ (no name) ] 507[ ](D) <-+ 508 | 509 +----------------+ 510 | 511 +->(switch)[ type Q.921 ](term1)<---->(datalink)[ type Q.931 ] 512 [ (no name) ] [ (no name) ] 513.Ed 514.Sh Netgraph Structures | 562A similar graph might be used to represent multi-link PPP running 563over an ISDN line: 564.Pp 565.Bd -literal 566[ type BRI ](B1)<--->(link1)[ type MPP ] 567[ "ISDN1" ](B2)<--->(link2)[ (no name) ] 568[ ](D) <-+ 569 | 570 +----------------+ 571 | 572 +->(switch)[ type Q.921 ](term1)<---->(datalink)[ type Q.931 ] 573 [ (no name) ] [ (no name) ] 574.Ed 575.Sh Netgraph Structures |
| 515Interesting members of the node and hook structures are shown below: | 576Interesting members of the node and hook structures are shown below 577however you should 578check 579.Pa sys/netgraph/netgraph.h 580on your system for more up-to-date versions. 581 |
| 516.Bd -literal 517struct ng_node { 518 char *name; /* Optional globally unique name */ 519 void *private; /* Node implementation private info */ 520 struct ng_type *type; /* The type of this node */ 521 int refs; /* Number of references to this struct */ 522 int numhooks; /* Number of connected hooks */ 523 hook_p hooks; /* Linked list of (connected) hooks */ --- 18 unchanged lines hidden (view full) --- 542Typically a node's private info contains a back-pointer to the node or hook 543structure, which counts as a new reference that must be registered by 544incrementing 545.Dv "node->refs" . 546.Pp 547From a hook you can obtain the corresponding node, and from 548a node the list of all active hooks. 549.Pp | 582.Bd -literal 583struct ng_node { 584 char *name; /* Optional globally unique name */ 585 void *private; /* Node implementation private info */ 586 struct ng_type *type; /* The type of this node */ 587 int refs; /* Number of references to this struct */ 588 int numhooks; /* Number of connected hooks */ 589 hook_p hooks; /* Linked list of (connected) hooks */ --- 18 unchanged lines hidden (view full) --- 608Typically a node's private info contains a back-pointer to the node or hook 609structure, which counts as a new reference that must be registered by 610incrementing 611.Dv "node->refs" . 612.Pp 613From a hook you can obtain the corresponding node, and from 614a node the list of all active hooks. 615.Pp |
| 550Node types are described by these structures: | 616Node types are described by the structures below: |
| 551.Bd -literal 552/** How to convert a control message from binary <-> ASCII */ 553struct ng_cmdlist { 554 u_int32_t cookie; /* typecookie */ 555 int cmd; /* command number */ 556 const char *name; /* command name */ 557 const struct ng_parse_type *mesgType; /* args if !NGF_RESP */ 558 const struct ng_parse_type *respType; /* args if NGF_RESP */ --- 6 unchanged lines hidden (view full) --- 565 /* Module event handler */ 566 modeventhand_t mod_event; /* Handle load/unload (optional) */ 567 568 /* Constructor */ 569 int (*constructor)(node_p *node); /* Create a new node */ 570 571 /** Methods using the node **/ 572 int (*rcvmsg)(node_p node, /* Receive control message */ | 617.Bd -literal 618/** How to convert a control message from binary <-> ASCII */ 619struct ng_cmdlist { 620 u_int32_t cookie; /* typecookie */ 621 int cmd; /* command number */ 622 const char *name; /* command name */ 623 const struct ng_parse_type *mesgType; /* args if !NGF_RESP */ 624 const struct ng_parse_type *respType; /* args if NGF_RESP */ --- 6 unchanged lines hidden (view full) --- 631 /* Module event handler */ 632 modeventhand_t mod_event; /* Handle load/unload (optional) */ 633 634 /* Constructor */ 635 int (*constructor)(node_p *node); /* Create a new node */ 636 637 /** Methods using the node **/ 638 int (*rcvmsg)(node_p node, /* Receive control message */ |
| 573 struct ng_mesg *msg, /* The message */ 574 const char *retaddr, /* Return address */ 575 struct ng_mesg **resp /* Synchronous response */ 576 hook_p lasthook); /* last hook traversed */ | 639 struct ng_mesg *msg, /* The message */ 640 const char *retaddr, /* Return address */ 641 struct ng_mesg **resp /* Synchronous response */ 642 hook_p lasthook); /* last hook traversed */ |
| 577 int (*shutdown)(node_p node); /* Shutdown this node */ 578 int (*newhook)(node_p node, /* create a new hook */ | 643 int (*shutdown)(node_p node); /* Shutdown this node */ 644 int (*newhook)(node_p node, /* create a new hook */ |
| 579 hook_p hook, /* Pre-allocated struct */ 580 const char *name); /* Name for new hook */ | 645 hook_p hook, /* Pre-allocated struct */ 646 const char *name); /* Name for new hook */ |
| 581 582 /** Methods using the hook **/ 583 int (*connect)(hook_p hook); /* Confirm new hook attachment */ 584 int (*rcvdata)(hook_p hook, /* Receive data on a hook */ | 647 648 /** Methods using the hook **/ 649 int (*connect)(hook_p hook); /* Confirm new hook attachment */ 650 int (*rcvdata)(hook_p hook, /* Receive data on a hook */ |
| 585 struct mbuf *m, /* The data in an mbuf */ 586 meta_p meta, /* Meta-data, if any */ 587 struct mbuf **ret_m, /* return data here */ 588 meta_p *ret_meta); /* return Meta-data here */ | 651 struct mbuf *m, /* The data in an mbuf */ 652 meta_p meta, /* Meta-data, if any */ 653 struct mbuf **ret_m, /* return data here */ 654 meta_p *ret_meta, /* return Meta-data here */ 655 struct ng_message **resp); /* Synchronous reply info */ |
| 589 int (*disconnect)(hook_p hook); /* Notify disconnection of hook */ 590 591 /** How to convert control messages binary <-> ASCII */ 592 const struct ng_cmdlist *cmdlist; /* Optional; may be NULL */ 593}; 594.Ed 595.Pp 596Control messages have the following structure: --- 9 unchanged lines hidden (view full) --- 606 u_long token; /* Reply should have the same token */ 607 u_long typecookie; /* Node type understanding this message */ 608 u_long cmd; /* Command identifier */ 609 u_char cmdstr[NG_CMDSTRLEN+1]; /* Cmd string (for debug) */ 610 } header; 611 char data[0]; /* Start of cmd/resp data */ 612}; 613 | 656 int (*disconnect)(hook_p hook); /* Notify disconnection of hook */ 657 658 /** How to convert control messages binary <-> ASCII */ 659 const struct ng_cmdlist *cmdlist; /* Optional; may be NULL */ 660}; 661.Ed 662.Pp 663Control messages have the following structure: --- 9 unchanged lines hidden (view full) --- 673 u_long token; /* Reply should have the same token */ 674 u_long typecookie; /* Node type understanding this message */ 675 u_long cmd; /* Command identifier */ 676 u_char cmdstr[NG_CMDSTRLEN+1]; /* Cmd string (for debug) */ 677 } header; 678 char data[0]; /* Start of cmd/resp data */ 679}; 680 |
| 614#define NG_VERSION 1 /* Netgraph version */ | 681#define NG_VERSION 3 /* Netgraph version */ |
| 615#define NGF_ORIG 0x0000 /* Command */ 616#define NGF_RESP 0x0001 /* Response */ 617.Ed 618.Pp 619Control messages have the fixed header shown above, followed by a 620variable length data section which depends on the type cookie 621and the command. Each field is explained below: 622.Bl -tag -width xxx --- 200 unchanged lines hidden (view full) --- 823.Dv flags , 824.Dv cmdstr , 825and 826.Dv arglen 827header fields filled in, plus the NUL-terminated string version of 828the arguments in the arguments field. If successful, the reply 829contains the binary version of the control message. 830.El | 682#define NGF_ORIG 0x0000 /* Command */ 683#define NGF_RESP 0x0001 /* Response */ 684.Ed 685.Pp 686Control messages have the fixed header shown above, followed by a 687variable length data section which depends on the type cookie 688and the command. Each field is explained below: 689.Bl -tag -width xxx --- 200 unchanged lines hidden (view full) --- 890.Dv flags , 891.Dv cmdstr , 892and 893.Dv arglen 894header fields filled in, plus the NUL-terminated string version of 895the arguments in the arguments field. If successful, the reply 896contains the binary version of the control message. 897.El |
| 898 899.Sh Flow Control Messages 900In addition to the control messages that affect nodes with respect to the 901graph, there are also a number of 902.Em Flow-control 903messages defined. At present these are 904.Em NOT 905handled automatically by the system, so 906nodes need to handle them if they are going to be used in a graph utilising 907flow control, and will be in the likely path of these messages. The 908default action of a node that doesn't understand these messages should 909be to pass them onto the next node. Hopefully some helper functions 910will assist in this eventually. These messages are also defined in 911.Pa sys/netgraph/ng_message.h 912and have a separate cookie 913.Em NG_FLOW_COOKIE 914to help identify them. They will not be covered in depth here. |
|
| 831.Sh Metadata 832Data moving through the 833.Nm 834system can be accompanied by meta-data that describes some 835aspect of that data. The form of the meta-data is a fixed header, 836which contains enough information for most uses, and can optionally 837be supplemented by trailing 838.Em option --- 149 unchanged lines hidden (view full) --- 988.It INTERFACE 989This node is also a system networking interface. It has hooks representing 990each protocol family (IP, AppleTalk, IPX, etc.) and appears in the output of 991.Xr ifconfig 8 . 992The interfaces are named 993.Em ng0 , 994.Em ng1 , 995etc. | 915.Sh Metadata 916Data moving through the 917.Nm 918system can be accompanied by meta-data that describes some 919aspect of that data. The form of the meta-data is a fixed header, 920which contains enough information for most uses, and can optionally 921be supplemented by trailing 922.Em option --- 149 unchanged lines hidden (view full) --- 1072.It INTERFACE 1073This node is also a system networking interface. It has hooks representing 1074each protocol family (IP, AppleTalk, IPX, etc.) and appears in the output of 1075.Xr ifconfig 8 . 1076The interfaces are named 1077.Em ng0 , 1078.Em ng1 , 1079etc. |
| 1080.It ONE2MANY 1081This node implements a simple round-robin multiplexer. It can be used 1082for example to make several LAN ports act together to get a higher speed 1083link between two machines. 1084.It Various PPP related nodes. 1085There is a full multilink PPP implementation that runs in Netgraph. 1086The 1087.Em Mpd 1088port can use these modules to make a very low latency high 1089capacity ppp system. It also supports 1090.Em PPTP 1091vpns using the 1092.Em PPTP 1093node. 1094.It PPPOE 1095A server and client side implememtation of PPPoE. Used in conjunction with 1096either 1097.Xr ppp 8 1098or the 1099.Em mpd port. 1100.It BRIDGE 1101This node, togther with the ethernet nodes allows a very flexible 1102bridging system to be implemented. 1103.It KSOCKET 1104This intriguing node looks like a socket to the system but diverts 1105all data to and from the netgraph system for further processing. This allows 1106such things as UDP tunnels to be almost trivially implemented from the 1107command line. 1108 |
|
| 996.El | 1109.El |
| 1110.Pp 1111Refer to the section at the end of this man page for more nodes types. |
|
| 997.Sh NOTES 998Whether a named node exists can be checked by trying to send a control message 999to it (e.g., 1000.Dv NGM_NODEINFO 1001). 1002If it does not exist, 1003.Er ENOENT 1004will be returned. --- 64 unchanged lines hidden (view full) --- 1069First, implementing new node types in user-mode first 1070makes debugging easier. 1071The 1072.Em tee 1073node type is also useful for debugging, especially in conjunction with 1074.Xr ngctl 8 1075and 1076.Xr nghook 8 . | 1112.Sh NOTES 1113Whether a named node exists can be checked by trying to send a control message 1114to it (e.g., 1115.Dv NGM_NODEINFO 1116). 1117If it does not exist, 1118.Er ENOENT 1119will be returned. --- 64 unchanged lines hidden (view full) --- 1184First, implementing new node types in user-mode first 1185makes debugging easier. 1186The 1187.Em tee 1188node type is also useful for debugging, especially in conjunction with 1189.Xr ngctl 8 1190and 1191.Xr nghook 8 . |
| 1192.Pp 1193Also look in /usr/share/examples/netgraph for solutions to several 1194common networking problems, solved using 1195.Nm . |
|
| 1077.Sh SEE ALSO 1078.Xr socket 2 , 1079.Xr netgraph 3 , 1080.Xr ng_async 4 , | 1196.Sh SEE ALSO 1197.Xr socket 2 , 1198.Xr netgraph 3 , 1199.Xr ng_async 4 , |
| 1200.Xr ng_bridge 4 , |
|
| 1081.Xr ng_bpf 4 , 1082.Xr ng_cisco 4 , 1083.Xr ng_ether 4 , 1084.Xr ng_echo 4 , | 1201.Xr ng_bpf 4 , 1202.Xr ng_cisco 4 , 1203.Xr ng_ether 4 , 1204.Xr ng_echo 4 , |
| 1205.Xr ng_ether 4 , |
|
| 1085.Xr ng_frame_relay 4 , 1086.Xr ng_hole 4 , 1087.Xr ng_iface 4 , 1088.Xr ng_ksocket 4 , 1089.Xr ng_lmi 4 , 1090.Xr ng_mppc 4 , 1091.Xr ng_ppp 4 , 1092.Xr ng_pppoe 4 , | 1206.Xr ng_frame_relay 4 , 1207.Xr ng_hole 4 , 1208.Xr ng_iface 4 , 1209.Xr ng_ksocket 4 , 1210.Xr ng_lmi 4 , 1211.Xr ng_mppc 4 , 1212.Xr ng_ppp 4 , 1213.Xr ng_pppoe 4 , |
| 1214.Xr ng_pptpgre 4 , |
|
| 1093.Xr ng_rfc1490 4 , 1094.Xr ng_socket 4 , 1095.Xr ng_tee 4 , 1096.Xr ng_tty 4 , 1097.Xr ng_UI 4 , 1098.Xr ng_vjc 4 , 1099.Xr ng_{type} 4 , 1100.Xr ngctl 8 , --- 15 unchanged lines hidden --- | 1215.Xr ng_rfc1490 4 , 1216.Xr ng_socket 4 , 1217.Xr ng_tee 4 , 1218.Xr ng_tty 4 , 1219.Xr ng_UI 4 , 1220.Xr ng_vjc 4 , 1221.Xr ng_{type} 4 , 1222.Xr ngctl 8 , --- 15 unchanged lines hidden --- |