The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/modules/netgraph/netgraph/netgraph.4

Version: -  FREEBSD  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-2  -  FREEBSD-11-1  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-4  -  FREEBSD-10-3  -  FREEBSD-10-2  -  FREEBSD-10-1  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-3  -  FREEBSD-9-2  -  FREEBSD-9-1  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-4  -  FREEBSD-8-3  -  FREEBSD-8-2  -  FREEBSD-8-1  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-4  -  FREEBSD-7-3  -  FREEBSD-7-2  -  FREEBSD-7-1  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-4  -  FREEBSD-6-3  -  FREEBSD-6-2  -  FREEBSD-6-1  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-5  -  FREEBSD-5-4  -  FREEBSD-5-3  -  FREEBSD-5-2  -  FREEBSD-5-1  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1 
SearchContext: -  none  -  3  -  10 

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

Cache object: b4776f9d00cca6a75fd6c57f2585dac0


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.