diff options
Diffstat (limited to 'static/freebsd/man4/netgraph.4 3.html')
| -rw-r--r-- | static/freebsd/man4/netgraph.4 3.html | 1023 |
1 files changed, 0 insertions, 1023 deletions
diff --git a/static/freebsd/man4/netgraph.4 3.html b/static/freebsd/man4/netgraph.4 3.html deleted file mode 100644 index c3d615fa..00000000 --- a/static/freebsd/man4/netgraph.4 3.html +++ /dev/null @@ -1,1023 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">NETGRAPH(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">NETGRAPH(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">netgraph</code> — <span class="Nd">graph - based kernel networking subsystem</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">netgraph</code> system provides a uniform and - modular system for the implementation of kernel objects which perform - various networking functions. The objects, known as <i class="Em">nodes</i>, - can be arranged into arbitrarily complicated graphs. Nodes have - <i class="Em">hooks</i> which are used to connect two nodes together, - forming the edges in the graph. Nodes communicate along the edges to process - data, implement protocols, etc.</p> -<p class="Pp">The aim of <code class="Nm">netgraph</code> is to supplement - rather than replace the existing kernel networking infrastructure. It - provides:</p> -<p class="Pp"></p> -<ul class="Bl-bullet Bl-compact"> - <li>A flexible way of combining protocol and link level drivers.</li> - <li>A modular way to implement new protocols.</li> - <li>A common framework for kernel entities to inter-communicate.</li> - <li>A reasonably fast, kernel-based implementation.</li> -</ul> -<section class="Ss"> -<h2 class="Ss" id="Nodes_and_Types"><a class="permalink" href="#Nodes_and_Types">Nodes - and Types</a></h2> -<p class="Pp">The most fundamental concept in <code class="Nm">netgraph</code> - is that of a - <a class="permalink" href="#node"><i class="Em" id="node">node</i></a>. All - nodes implement a number of predefined methods which allow them to interact - with other nodes in a well defined manner.</p> -<p class="Pp" id="type">Each node has a - <a class="permalink" href="#type"><i class="Em">type</i></a>, which is a - static property of the node determined at node creation time. A node's type - is described by a unique ASCII type name. The type implies what the node - does and how it may be connected to other nodes.</p> -<p class="Pp">In object-oriented language, types are classes, and nodes are - instances of their respective class. All node types are subclasses of the - generic node type, and hence inherit certain common functionality and - capabilities (e.g., the ability to have an ASCII name).</p> -<p class="Pp">Nodes may be assigned a globally unique ASCII name which can be - used to refer to the node. The name must not contain the characters - ‘<code class="Li">.</code>’ or - ‘<code class="Li">:</code>’, and is limited to - <code class="Dv">NG_NODESIZ</code> characters (including the terminating - <code class="Dv">NUL</code> character).</p> -<p class="Pp" id="ID">Each node instance has a unique - <a class="permalink" href="#ID"><i class="Em">ID number</i></a> which is - expressed as a 32-bit hexadecimal value. This value may be used to refer to - a node when there is no ASCII name assigned to it.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Hooks"><a class="permalink" href="#Hooks">Hooks</a></h2> -<p class="Pp">Nodes are connected to other nodes by connecting a pair of - <i class="Em">hooks</i>, one from each node. Data flows bidirectionally - between nodes along connected pairs of hooks. A node may have as many hooks - as it needs, and may assign whatever meaning it wants to a hook.</p> -<p class="Pp">Hooks have these properties:</p> -<ul class="Bl-bullet"> - <li>A hook has an ASCII name which is unique among all hooks on that node - (other hooks on other nodes may have the same name). The name must not - contain the characters ‘<code class="Li">.</code>’ or - ‘<code class="Li">:</code>’, and is limited to - <code class="Dv">NG_HOOKSIZ</code> characters (including the terminating - <code class="Dv">NUL</code> character).</li> - <li>A hook is always connected to another hook. That is, hooks are created at - the time they are connected, and breaking an edge by removing either hook - destroys both hooks.</li> - <li>A hook can be set into a state where incoming packets are always queued by - the input queueing system, rather than being delivered directly. This can - be used when the data is sent from an interrupt handler, and processing - must be quick so as not to block other interrupts.</li> - <li>A hook may supply overriding receive data and receive message functions, - which should be used for data and messages received through that hook in - preference to the general node-wide methods.</li> -</ul> -<p class="Pp">A node may decide to assign special meaning to some hooks. For - example, connecting to the hook named <var class="Va">debug</var> might - trigger the node to start sending debugging information to that hook.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Data_Flow"><a class="permalink" href="#Data_Flow">Data - Flow</a></h2> -<p class="Pp">Two types of information flow between nodes: data messages and - control messages. Data messages are passed in <var class="Vt">mbuf - chains</var> along the edges in the graph, one edge at a time. The first - <var class="Vt">mbuf</var> in a chain must have the - <code class="Dv">M_PKTHDR</code> flag set. Each node decides how to handle - data received through one of its hooks.</p> -<p class="Pp">Along with data, nodes can also receive control messages. There - are generic and type-specific control messages. Control messages have a - common header format, followed by type-specific data, and are binary - structures for efficiency. However, node types may also support conversion - of the type-specific data between binary and ASCII formats, for debugging - and human interface purposes (see the - <code class="Dv">NGM_ASCII2BINARY</code> and - <code class="Dv">NGM_BINARY2ASCII</code> generic control messages below). - Nodes are not required to support these conversions.</p> -<p class="Pp">There are three ways to address a control message. If there is a - sequence of edges connecting the two nodes, the message may be - “source routed” by specifying the corresponding sequence of - ASCII hook names as the destination address for the message (relative - addressing). If the destination is adjacent to the source, then the source - node may simply specify (as a pointer in the code) the hook across which the - message should be sent. Otherwise, the recipient node's global ASCII name - (or equivalent ID-based name) is used as the destination address for the - message (absolute addressing). The two types of ASCII addressing may be - combined, by specifying an absolute start node and a sequence of hooks. Only - the ASCII addressing modes are available to control programs outside the - kernel; use of direct pointers is limited to kernel modules.</p> -<p class="Pp">Messages often represent commands that are followed by a reply - message in the reverse direction. To facilitate this, the recipient of a - control message is supplied with a “return address” that is - suitable for addressing a reply.</p> -<p class="Pp">Each control message contains a 32-bit value, called a - “typecookie”, indicating the type of the message, i.e. how to - interpret it. Typically each type defines a unique typecookie for the - messages that it understands. However, a node may choose to recognize and - implement more than one type of messages.</p> -<p class="Pp">If a message is delivered to an address that implies that it - arrived at that node through a particular hook (as opposed to having been - directly addressed using its ID or global name) then that hook is identified - to the receiving node. This allows a message to be re-routed or passed on, - should a node decide that this is required, in much the same way that data - packets are passed around between nodes. A set of standard messages for flow - control and link management purposes are defined by the base system that are - usually passed around in this manner. Flow control message would usually - travel in the opposite direction to the data to which they pertain.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Netgraph_is_(Usually)_Functional"><a class="permalink" href="#Netgraph_is_(Usually)_Functional">Netgraph - is (Usually) Functional</a></h2> -<p class="Pp">In order to minimize latency, most - <code class="Nm">netgraph</code> operations are functional. That is, data - and control messages are delivered by making function calls rather than by - using queues and mailboxes. For example, if node A wishes to send a data - <var class="Vt">mbuf</var> to neighboring node B, it calls the generic - <code class="Nm">netgraph</code> data delivery function. This function in - turn locates node B and calls B's “receive data” method. There - are exceptions to this.</p> -<p class="Pp" id="writers">Each node has an input queue, and some operations can - be considered to be - <a class="permalink" href="#writers"><i class="Em">writers</i></a> in that - they alter the state of the node. Obviously, in an SMP world it would be bad - if the state of a node were changed while another data packet were - transiting the node. For this purpose, the input queue implements a - <a class="permalink" href="#reader/writer"><i class="Em" id="reader/writer">reader/writer</i></a> - semantic so that when there is a writer in the node, all other requests are - queued, and while there are readers, a writer, and any following packets are - queued. In the case where there is no reason to queue the data, the input - method is called directly, as mentioned above.</p> -<p class="Pp">A node may declare that all requests should be considered as - writers, or that requests coming in over a particular hook should be - considered to be a writer, or even that packets leaving or entering across a - particular hook should always be queued, rather than delivered directly - (often useful for interrupt routines who want to get back to the hardware - quickly). By default, all control message packets are considered to be - writers unless specifically declared to be a reader in their definition. - (See <code class="Dv">NGM_READONLY</code> in - <code class="In"><<a class="In">netgraph/ng_message.h</a>></code>.)</p> -<p class="Pp">While this mode of operation results in good performance, it has a - few implications for node developers:</p> -<ul class="Bl-bullet"> - <li>Whenever a node delivers a data or control message, the node may need to - allow for the possibility of receiving a returning message before the - original delivery function call returns.</li> - <li><code class="Nm">Netgraph</code> provides internal synchronization between - nodes. Data always enters a “graph” at an <i class="Em">edge - node</i>. An <i class="Em">edge node</i> is a node that interfaces between - <code class="Nm">netgraph</code> and some other part of the system. - Examples of “edge nodes” include device drivers, the - <var class="Vt">socket</var>, <var class="Vt">ether</var>, - <var class="Vt">tty</var>, and <var class="Vt">ksocket</var> node type. In - these <i class="Em">edge nodes</i>, the calling thread directly executes - code in the node, and from that code calls upon the - <code class="Nm">netgraph</code> framework to deliver data across some - edge in the graph. From an execution point of view, the calling thread - will execute the <code class="Nm">netgraph</code> framework methods, and - if it can acquire a lock to do so, the input methods of the next node. - This continues until either the data is discarded or queued for some - device or system entity, or the thread is unable to acquire a lock on the - next node. In that case, the data is queued for the node, and execution - rewinds back to the original calling entity. The queued data will be - picked up and processed by either the current holder of the lock when they - have completed their operations, or by a special - <code class="Nm">netgraph</code> thread that is activated when there are - such items queued.</li> - <li>It is possible for an infinite loop to occur if the graph contains - cycles.</li> -</ul> -<p class="Pp">So far, these issues have not proven problematical in - practice.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Interaction_with_Other_Parts_of_the_Kernel"><a class="permalink" href="#Interaction_with_Other_Parts_of_the_Kernel">Interaction - with Other Parts of the Kernel</a></h2> -<p class="Pp">A node may have a hidden interaction with other components of the - kernel outside of the <code class="Nm">netgraph</code> subsystem, such as - device hardware, kernel protocol stacks, etc. In fact, one of the benefits - of <code class="Nm">netgraph</code> is the ability to join disparate kernel - networking entities together in a consistent communication framework.</p> -<p class="Pp">An example is the <var class="Vt">socket</var> node type which is - both a <code class="Nm">netgraph</code> node and a - <a class="Xr">socket(2)</a> in the protocol family - <code class="Dv">PF_NETGRAPH</code>. Socket nodes allow user processes to - participate in <code class="Nm">netgraph</code>. Other nodes communicate - with socket nodes using the usual methods, and the node hides the fact that - it is also passing information to and from a cooperating user process.</p> -<p class="Pp">Another example is a device driver that presents a node interface - to the hardware.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Node_Methods"><a class="permalink" href="#Node_Methods">Node - Methods</a></h2> -<p class="Pp">Nodes are notified of the following actions via function calls to - the following node methods, and may accept or reject that action (by - returning the appropriate error code):</p> -<dl class="Bl-tag"> - <dt>Creation of a new node</dt> - <dd>The constructor for the type is called. If creation of a new node is - allowed, constructor method may allocate any special resources it needs. - For nodes that correspond to hardware, this is typically done during the - device attach routine. Often a global ASCII name corresponding to the - device name is assigned here as well.</dd> - <dt>Creation of a new hook</dt> - <dd>The hook is created and tentatively linked to the node, and the node is - told about the name that will be used to describe this hook. The node sets - up any special data structures it needs, or may reject the connection, - based on the name of the hook.</dd> - <dt id="queueing">Successful connection of two hooks</dt> - <dd>After both ends have accepted their hooks, and the links have been made, - the nodes get a chance to find out who their peer is across the link, and - can then decide to reject the connection. Tear-down is automatic. This is - also the time at which a node may decide whether to set a particular hook - (or its peer) into the - <a class="permalink" href="#queueing"><i class="Em">queueing</i></a> - mode.</dd> - <dt>Destruction of a hook</dt> - <dd>The node is notified of a broken connection. The node may consider some - hooks to be critical to operation and others to be expendable: the - disconnection of one hook may be an acceptable event while for another it - may effect a total shutdown for the node.</dd> - <dt>Preshutdown of a node</dt> - <dd>This method is called before real shutdown, which is discussed below. - While in this method, the node is fully operational and can send a - “goodbye” message to its peers, or it can exclude itself - from the chain and reconnect its peers together, like the - <a class="Xr">ng_tee(4)</a> node type does.</dd> - <dt id="persistent">Shutdown of a node</dt> - <dd>This method allows a node to clean up and to ensure that any actions that - need to be performed at this time are taken. The method is called by the - generic (i.e., superclass) node destructor which will get rid of the - generic components of the node. Some nodes (usually associated with a - piece of hardware) may be - <a class="permalink" href="#persistent"><i class="Em">persistent</i></a> - in that a shutdown breaks all edges and resets the node, but does not - remove it. In this case, the shutdown method should not free its - resources, but rather, clean up and then call the - <a class="permalink" href="#NG_NODE_REVIVE"><code class="Fn" id="NG_NODE_REVIVE">NG_NODE_REVIVE</code></a>() - macro to signal the generic code that the shutdown is aborted. In the case - where the shutdown is started by the node itself due to hardware removal - or unloading (via - <a class="permalink" href="#ng_rmnode_self"><code class="Fn" id="ng_rmnode_self">ng_rmnode_self</code></a>()), - it should set the <code class="Dv">NGF_REALLY_DIE</code> flag to signal to - its own shutdown method that it is not to persist.</dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="Sending_and_Receiving_Data"><a class="permalink" href="#Sending_and_Receiving_Data">Sending - and Receiving Data</a></h2> -<p class="Pp">Two other methods are also supported by all nodes:</p> -<dl class="Bl-tag"> - <dt id="queueable">Receive data message</dt> - <dd>A <code class="Nm">netgraph</code> - <a class="permalink" href="#queueable"><i class="Em">queueable request - item</i></a>, usually referred to as an <i class="Em">item</i>, is - received by this function. The item contains a pointer to an - <var class="Vt">mbuf</var>. - <p class="Pp" id="NG_FREE_M">The node is notified on which hook the item has - arrived, and can use this information in its processing decision. The - receiving node must always - <a class="permalink" href="#NG_FREE_M"><code class="Fn">NG_FREE_M</code></a>() - the <var class="Vt">mbuf chain</var> on completion or error, or pass it - on to another node (or kernel module) which will then be responsible for - freeing it. Similarly, the <i class="Em">item</i> must be freed if it is - not to be passed on to another node, by using the - <a class="permalink" href="#NG_FREE_ITEM"><code class="Fn" id="NG_FREE_ITEM">NG_FREE_ITEM</code></a>() - macro. If the item still holds references to <var class="Vt">mbufs</var> - at the time of freeing then they will also be appropriately freed. - Therefore, if there is any chance that the <var class="Vt">mbuf</var> - will be changed or freed separately from the item, it is very important - that it be retrieved using the - <a class="permalink" href="#NGI_GET_M"><code class="Fn" id="NGI_GET_M">NGI_GET_M</code></a>() - macro that also removes the reference within the item. (Or multiple - frees of the same object will occur.)</p> - <p class="Pp" id="NGI_M">If it is only required to examine the contents of - the <var class="Vt">mbufs</var>, then it is possible to use the - <a class="permalink" href="#NGI_M"><code class="Fn">NGI_M</code></a>() - macro to both read and rewrite <var class="Vt">mbuf</var> pointer inside - the item.</p> - <p class="Pp">If developer needs to pass any meta information along with the - <var class="Vt">mbuf chain</var>, he should use - <a class="Xr">mbuf_tags(9)</a> framework.</p> - <div class="Bf Sy">Note that old <code class="Nm">netgraph</code> specific - meta-data format is obsoleted now.</div> - <p class="Pp" id="peer">The receiving node may decide to defer the data by - queueing it in the <code class="Nm">netgraph</code> NETISR system (see - below). It achieves this by setting the <code class="Dv">HK_QUEUE</code> - flag in the flags word of the hook on which that data will arrive. The - infrastructure will respect that bit and queue the data for delivery at - a later time, rather than deliver it directly. A node may decide to set - the bit on the - <a class="permalink" href="#peer"><i class="Em">peer</i></a> node, so - that its own output packets are queued.</p> - <p class="Pp" id="NG_HOOK_SET_RCVDATA">The node may elect to nominate a - different receive data function for data received on a particular hook, - to simplify coding. It uses the - <a class="permalink" href="#NG_HOOK_SET_RCVDATA"><code class="Fn">NG_HOOK_SET_RCVDATA</code></a>(<var class="Fa">hook</var>, - <var class="Fa">fn</var>) macro to do this. The function receives the - same arguments in every way other than it will receive all (and only) - packets from that hook.</p> - </dd> - <dt id="NGI_MSG">Receive control message</dt> - <dd>This method is called when a control message is addressed to the node. As - with the received data, an <i class="Em">item</i> is received, with a - pointer to the control message. The message can be examined using the - <a class="permalink" href="#NGI_MSG"><code class="Fn">NGI_MSG</code></a>() - macro, or completely extracted from the item using the - <a class="permalink" href="#NGI_GET_MSG"><code class="Fn" id="NGI_GET_MSG">NGI_GET_MSG</code></a>() - which also removes the reference within the item. If the item still holds - a reference to the message when it is freed (using the - <code class="Fn">NG_FREE_ITEM</code>() macro), then the message will also - be freed appropriately. If the reference has been removed, the node must - free the message itself using the - <a class="permalink" href="#NG_FREE_MSG"><code class="Fn" id="NG_FREE_MSG">NG_FREE_MSG</code></a>() - macro. A return address is always supplied, giving the address of the node - that originated the message so a reply message can be sent anytime later. - The return address is retrieved from the <i class="Em">item</i> using the - <a class="permalink" href="#NGI_RETADDR"><code class="Fn" id="NGI_RETADDR">NGI_RETADDR</code></a>() - macro and is of type <var class="Vt">ng_ID_t</var>. All control messages - and replies are allocated with the <a class="Xr">malloc(9)</a> type - <code class="Dv">M_NETGRAPH_MSG</code>, however it is more convenient to - use the - <a class="permalink" href="#NG_MKMESSAGE"><code class="Fn" id="NG_MKMESSAGE">NG_MKMESSAGE</code></a>() - and - <a class="permalink" href="#NG_MKRESPONSE"><code class="Fn" id="NG_MKRESPONSE">NG_MKRESPONSE</code></a>() - macros to allocate and fill out a message. Messages must be freed using - the <code class="Fn">NG_FREE_MSG</code>() macro. - <p class="Pp">If the message was delivered via a specific hook, that hook - will also be made known, which allows the use of such things as - flow-control messages, and status change messages, where the node may - want to forward the message out another hook to that on which it - arrived.</p> - <p class="Pp" id="NG_HOOK_SET_RCVMSG">The node may elect to nominate a - different receive message function for messages received on a particular - hook, to simplify coding. It uses the - <a class="permalink" href="#NG_HOOK_SET_RCVMSG"><code class="Fn">NG_HOOK_SET_RCVMSG</code></a>(<var class="Fa">hook</var>, - <var class="Fa">fn</var>) macro to do this. The function receives the - same arguments in every way other than it will receive all (and only) - messages from that hook.</p> - </dd> -</dl> -<p class="Pp">Much use has been made of reference counts, so that nodes being - freed of all references are automatically freed, and this behaviour has been - tested and debugged to present a consistent and trustworthy framework for - the “type module” writer to use.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Addressing"><a class="permalink" href="#Addressing">Addressing</a></h2> -<p class="Pp">The <code class="Nm">netgraph</code> framework provides an - unambiguous and simple to use method of specifically addressing any single - node in the graph. The naming of a node is independent of its type, in that - another node, or external component need not know anything about the node's - type in order to address it so as to send it a generic message type. Node - and hook names should be chosen so as to make addresses meaningful.</p> -<p class="Pp">Addresses are either absolute or relative. An absolute address - begins with a node name or ID, followed by a colon, followed by a sequence - of hook names separated by periods. This addresses the node reached by - starting at the named node and following the specified sequence of hooks. A - relative address includes only the sequence of hook names, implicitly - starting hook traversal at the local node.</p> -<p class="Pp">There are a couple of special possibilities for the node name. The - name ‘<code class="Li">.</code>’ (referred to as - ‘<code class="Li">.:</code>’) always refers to the local node. - Also, nodes that have no global name may be addressed by their ID numbers, - by enclosing the hexadecimal representation of the ID number within the - square brackets. Here are some examples of valid - <code class="Nm">netgraph</code> addresses:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>.: -[3f]: -foo: -.:hook1 -foo:hook1.hook2 -[d80]:hook1</pre> -</div> -<p class="Pp">The following set of nodes might be created for a site with a - single physical frame relay line having two active logical DLCI channels, - with RFC 1490 frames on DLCI 16 and PPP frames over DLCI 20:</p> -<div class="Bd Pp Li"> -<pre>[type SYNC ] [type FRAME] [type RFC1490] -[ "Frame1" ](uplink)<-->(data)[<un-named>](dlci16)<-->(mux)[<un-named> ] -[ A ] [ B ](dlci20)<---+ [ C ] - | - | [ type PPP ] - +>(mux)[<un-named>] - [ D ]</pre> -</div> -<p class="Pp">One could always send a control message to node C from anywhere by - using the name “<code class="Li">Frame1:uplink.dlci16</code>”. - In this case, node C would also be notified that the message reached it via - its hook <var class="Va">mux</var>. Similarly, - “<code class="Li">Frame1:uplink.dlci20</code>” could reliably - be used to reach node D, and node A could refer to node B as - “<code class="Li">.:uplink</code>”, or simply - “<code class="Li">uplink</code>”. Conversely, B can refer to A - as “<code class="Li">data</code>”. The address - “<code class="Li">mux.data</code>” could be used by both nodes - C and D to address a message to node A.</p> -<p class="Pp" id="control">Note that this is only for - <a class="permalink" href="#control"><i class="Em">control messages</i></a>. - In each of these cases, where a relative addressing mode is used, the - recipient is notified of the hook on which the message arrived, as well as - the originating node. This allows the option of hop-by-hop distribution of - messages and state information. Data messages are - <a class="permalink" href="#only"><i class="Em" id="only">only</i></a> - routed one hop at a time, by specifying the departing hook, with each node - making the next routing decision. So when B receives a frame on hook - <var class="Va">data</var>, it decodes the frame relay header to determine - the DLCI, and then forwards the unwrapped frame to either C or D.</p> -<p class="Pp" id="direct">In a similar way, flow control messages may be routed - in the reverse direction to outgoing data. For example a “buffer - nearly full” message from - “<code class="Li">Frame1:</code>” would be passed to node B - which might decide to send similar messages to both nodes C and D. The nodes - would use <a class="permalink" href="#direct"><i class="Em">direct hook - pointer</i></a> addressing to route the messages. The message may have - travelled from “<code class="Li">Frame1:</code>” to B as a - synchronous reply, saving time and cycles.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Netgraph_Structures"><a class="permalink" href="#Netgraph_Structures">Netgraph - Structures</a></h2> -<p class="Pp">Structures are defined in - <code class="In"><<a class="In">netgraph/netgraph.h</a>></code> (for - kernel structures only of interest to nodes) and - <code class="In"><<a class="In">netgraph/ng_message.h</a>></code> (for - message definitions also of interest to user programs).</p> -<p class="Pp">The two basic object types that are of interest to node authors - are <i class="Em">nodes</i> and <i class="Em">hooks</i>. These two objects - have the following properties that are also of interest to the node - writers.</p> -<dl class="Bl-tag"> - <dt><var class="Vt">struct ng_node</var></dt> - <dd>Node authors should always use the following - <code class="Ic">typedef</code> to declare their pointers, and should - never actually declare the structure. - <p class="Pp"><code class="Fd">typedef struct ng_node *node_p;</code></p> - <p class="Pp">The following properties are associated with a node, and can - be accessed in the following manner:</p> - <dl class="Bl-tag"> - <dt id="NG_NODE_IS_VALID">Validity</dt> - <dd>A driver or interrupt routine may want to check whether the node is - still valid. It is assumed that the caller holds a reference on the - node so it will not have been freed, however it may have been disabled - or otherwise shut down. Using the - <a class="permalink" href="#NG_NODE_IS_VALID"><code class="Fn">NG_NODE_IS_VALID</code></a>(<var class="Fa">node</var>) - macro will return this state. Eventually it should be almost - impossible for code to run in an invalid node but at this time that - work has not been completed.</dd> - <dt id="NG_NODE_ID">Node ID (<var class="Vt">ng_ID_t</var>)</dt> - <dd>This property can be retrieved using the macro - <a class="permalink" href="#NG_NODE_ID"><code class="Fn">NG_NODE_ID</code></a>(<var class="Fa">node</var>).</dd> - <dt>Node name</dt> - <dd>Optional globally unique name, <code class="Dv">NUL</code> terminated - string. If there is a value in here, it is the name of the node. - <div class="Bd Pp Bd-indent Li"> - <pre>if (NG_NODE_NAME(node)[0] != '\0') ... - -if (strcmp(NG_NODE_NAME(node), "fred") == 0) ...</pre> - </div> - </dd> - <dt id="NG_NODE_SET_PRIVATE">A node dependent opaque cookie</dt> - <dd>Anything of the pointer type can be placed here. The macros - <a class="permalink" href="#NG_NODE_SET_PRIVATE"><code class="Fn">NG_NODE_SET_PRIVATE</code></a>(<var class="Fa">node</var>, - <var class="Fa">value</var>) and - <a class="permalink" href="#NG_NODE_PRIVATE"><code class="Fn" id="NG_NODE_PRIVATE">NG_NODE_PRIVATE</code></a>(<var class="Fa">node</var>) - set and retrieve this property, respectively.</dd> - <dt id="NG_NODE_NUMHOOKS">Number of hooks</dt> - <dd>The - <a class="permalink" href="#NG_NODE_NUMHOOKS"><code class="Fn">NG_NODE_NUMHOOKS</code></a>(<var class="Fa">node</var>) - macro is used to retrieve this value.</dd> - <dt id="NG_NODE_FOREACH_HOOK">Hooks</dt> - <dd>The node may have a number of hooks. A traversal method is provided to - allow all the hooks to be tested for some condition. - <a class="permalink" href="#NG_NODE_FOREACH_HOOK"><code class="Fn">NG_NODE_FOREACH_HOOK</code></a>(<var class="Fa">node</var>, - <var class="Fa">fn</var>, <var class="Fa">arg</var>, - <var class="Fa">rethook</var>) where <var class="Fa">fn</var> is a - function that will be called for each hook with the form - <a class="permalink" href="#fn"><code class="Fn" id="fn">fn</code></a>(<var class="Fa">hook</var>, - <var class="Fa">arg</var>) and returning 0 to terminate the search. If - the search is terminated, then <var class="Fa">rethook</var> will be - set to the hook at which the search was terminated.</dd> - </dl> - </dd> - <dt><var class="Vt">struct ng_hook</var></dt> - <dd>Node authors should always use the following - <code class="Ic">typedef</code> to declare their hook pointers. - <p class="Pp"><code class="Fd">typedef struct ng_hook *hook_p;</code></p> - <p class="Pp">The following properties are associated with a hook, and can - be accessed in the following manner:</p> - <dl class="Bl-tag"> - <dt id="NG_HOOK_SET_PRIVATE">A hook dependent opaque cookie</dt> - <dd>Anything of the pointer type can be placed here. The macros - <a class="permalink" href="#NG_HOOK_SET_PRIVATE"><code class="Fn">NG_HOOK_SET_PRIVATE</code></a>(<var class="Fa">hook</var>, - <var class="Fa">value</var>) and - <a class="permalink" href="#NG_HOOK_PRIVATE"><code class="Fn" id="NG_HOOK_PRIVATE">NG_HOOK_PRIVATE</code></a>(<var class="Fa">hook</var>) - set and retrieve this property, respectively.</dd> - <dt id="NG_HOOK_NODE">An associate node</dt> - <dd>The macro - <a class="permalink" href="#NG_HOOK_NODE"><code class="Fn">NG_HOOK_NODE</code></a>(<var class="Fa">hook</var>) - finds the associated node.</dd> - <dt id="NG_HOOK_PEER">A peer hook (<var class="Vt">hook_p</var>)</dt> - <dd>The other hook in this connected pair. The - <a class="permalink" href="#NG_HOOK_PEER"><code class="Fn">NG_HOOK_PEER</code></a>(<var class="Fa">hook</var>) - macro finds the peer.</dd> - <dt id="NG_HOOK_REF">References</dt> - <dd>The - <a class="permalink" href="#NG_HOOK_REF"><code class="Fn">NG_HOOK_REF</code></a>(<var class="Fa">hook</var>) - and - <a class="permalink" href="#NG_HOOK_UNREF"><code class="Fn" id="NG_HOOK_UNREF">NG_HOOK_UNREF</code></a>(<var class="Fa">hook</var>) - macros increment and decrement the hook reference count accordingly. - After decrement you should always assume the hook has been freed - unless you have another reference still valid.</dd> - <dt>Override receive functions</dt> - <dd>The - <code class="Fn">NG_HOOK_SET_RCVDATA</code>(<var class="Fa">hook</var>, - <var class="Fa">fn</var>) and - <code class="Fn">NG_HOOK_SET_RCVMSG</code>(<var class="Fa">hook</var>, - <var class="Fa">fn</var>) macros can be used to set override methods - that will be used in preference to the generic receive data and - receive message functions. To unset these, use the macros to set them - to <code class="Dv">NULL</code>. They will only be used for data and - messages received on the hook on which they are set.</dd> - </dl> - <p class="Pp" id="NG_NODE_UNREF">The maintenance of the names, reference - counts, and linked list of hooks for each node is handled automatically - by the <code class="Nm">netgraph</code> subsystem. Typically a node's - private info contains a back-pointer to the node or hook structure, - which counts as a new reference that must be included in the reference - count for the node. When the node constructor is called, there is - already a reference for this calculated in, so that when the node is - destroyed, it should remember to do a - <a class="permalink" href="#NG_NODE_UNREF"><code class="Fn">NG_NODE_UNREF</code></a>() - on the node.</p> - <p class="Pp">From a hook you can obtain the corresponding node, and from a - node, it is possible to traverse all the active hooks.</p> - <p class="Pp">A current example of how to define a node can always be seen - in <span class="Pa">src/sys/netgraph/ng_sample.c</span> and should be - used as a starting point for new node writers.</p> - </dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="Netgraph_Message_Structure"><a class="permalink" href="#Netgraph_Message_Structure">Netgraph - Message Structure</a></h2> -<p class="Pp">Control messages have the following structure:</p> -<div class="Bd Pp Li"> -<pre>#define NG_CMDSTRSIZ 32 /* Max command string (including null) */ - -struct ng_mesg { - struct ng_msghdr { - u_char version; /* Must equal NG_VERSION */ - u_char spare; /* Pad to 4 bytes */ - uint16_t spare2; - uint32_t arglen; /* Length of cmd/resp data */ - uint32_t cmd; /* Command identifier */ - uint32_t flags; /* Message status flags */ - uint32_t token; /* Reply should have the same token */ - uint32_t typecookie; /* Node type understanding this message */ - u_char cmdstr[NG_CMDSTRSIZ]; /* cmd string +   */ - } header; - char data[]; /* placeholder for actual data */ -}; - -#define NG_ABI_VERSION 12 /* Netgraph kernel ABI version */ -#define NG_VERSION 8 /* Netgraph message version */ -#define NGF_ORIG 0x00000000 /* The msg is the original request */ -#define NGF_RESP 0x00000001 /* The message is a response */</pre> -</div> -<p class="Pp">Control messages have the fixed header shown above, followed by a - variable length data section which depends on the type cookie and the - command. Each field is explained below:</p> -<dl class="Bl-tag"> - <dt id="version"><var class="Va">version</var></dt> - <dd>Indicates the version of the <code class="Nm">netgraph</code> message - protocol itself. The current version is - <code class="Dv">NG_VERSION</code>.</dd> - <dt id="arglen"><var class="Va">arglen</var></dt> - <dd>This is the length of any extra arguments, which begin at - <var class="Va">data</var>.</dd> - <dt id="flags"><var class="Va">flags</var></dt> - <dd>Indicates whether this is a command or a response control message.</dd> - <dt id="token"><var class="Va">token</var></dt> - <dd>The <var class="Va">token</var> is a means by which a sender can match a - reply message to the corresponding command message; the reply always has - the same token.</dd> - <dt id="typecookie"><var class="Va">typecookie</var></dt> - <dd>The corresponding node type's unique 32-bit value. If a node does not - recognize the type cookie it must reject the message by returning - <code class="Er">EINVAL</code>. - <p class="Pp" id="must">Each type should have an include file that defines - the commands, argument format, and cookie for its own messages. The - typecookie ensures that the same header file was included by both sender - and receiver; when an incompatible change in the header file is made, - the typecookie - <a class="permalink" href="#must"><i class="Em">must</i></a> be changed. - The de-facto method for generating unique type cookies is to take the - seconds from the Epoch at the time the header file is written (i.e., the - output of “<code class="Nm">date</code> - <code class="Fl">-u</code> <code class="Li">+%s</code>”).</p> - <p class="Pp">There is a predefined typecookie - <code class="Dv">NGM_GENERIC_COOKIE</code> for the - <var class="Vt">generic</var> node type, and a corresponding set of - generic messages which all nodes understand. The handling of these - messages is automatic.</p> - </dd> - <dt id="cmd"><var class="Va">cmd</var></dt> - <dd>The identifier for the message command. This is type specific, and is - defined in the same header file as the typecookie.</dd> - <dt id="cmdstr"><var class="Va">cmdstr</var></dt> - <dd>Room for a short human readable version of <var class="Va">command</var> - (for debugging purposes only).</dd> -</dl> -<p class="Pp">Some modules may choose to implement messages from more than one - of the header files and thus recognize more than one type cookie.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Control_Message_ASCII_Form"><a class="permalink" href="#Control_Message_ASCII_Form">Control - Message ASCII Form</a></h2> -<p class="Pp">Control messages are in binary format for efficiency. However, for - debugging and human interface purposes, and if the node type supports it, - control messages may be converted to and from an equivalent ASCII form. The - ASCII form is similar to the binary form, with two exceptions:</p> -<ol class="Bl-enum"> - <li>The <var class="Va">cmdstr</var> header field must contain the ASCII name - of the command, corresponding to the <var class="Va">cmd</var> header - field.</li> - <li>The arguments field contains a <code class="Dv">NUL</code>-terminated - ASCII string version of the message arguments.</li> -</ol> -<p class="Pp">In general, the arguments field of a control message can be any - arbitrary C data type. <code class="Nm">Netgraph</code> includes parsing - routines to support some pre-defined datatypes in ASCII with this simple - syntax:</p> -<ul class="Bl-bullet"> - <li>Integer types are represented by base 8, 10, or 16 numbers.</li> - <li>Strings are enclosed in double quotes and respect the normal C language - backslash escapes.</li> - <li>IP addresses have the obvious form.</li> - <li>Arrays are enclosed in square brackets, with the elements listed - consecutively starting at index zero. An element may have an optional - index and equals sign (‘<code class="Li">=</code>’) - preceding it. Whenever an element does not have an explicit index, the - index is implicitly the previous element's index plus one.</li> - <li>Structures are enclosed in curly braces, and each field is specified in - the form <var class="Ar">fieldname</var>=<var class="Ar">value</var>.</li> - <li>Any array element or structure field whose value is equal to its - “default value” may be omitted. For integer types, the - default value is usually zero; for string types, the empty string.</li> - <li>Array elements and structure fields may be specified in any order.</li> -</ul> -<p class="Pp">Each node type may define its own arbitrary types by providing the - necessary routines to parse and unparse. ASCII forms defined for a specific - node type are documented in the corresponding man page.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Generic_Control_Messages"><a class="permalink" href="#Generic_Control_Messages">Generic - Control Messages</a></h2> -<p class="Pp">There are a number of standard predefined messages that will work - for any node, as they are supported directly by the framework itself. These - are defined in - <code class="In"><<a class="In">netgraph/ng_message.h</a>></code> - along with the basic layout of messages and other similar information.</p> -<dl class="Bl-tag"> - <dt id="NGM_CONNECT"><a class="permalink" href="#NGM_CONNECT"><code class="Dv">NGM_CONNECT</code></a></dt> - <dd>Connect to another node, using the supplied hook names on either end.</dd> - <dt id="NGM_MKPEER"><a class="permalink" href="#NGM_MKPEER"><code class="Dv">NGM_MKPEER</code></a></dt> - <dd>Construct a node of the given type and then connect to it using the - supplied hook names.</dd> - <dt id="NGM_SHUTDOWN"><a class="permalink" href="#NGM_SHUTDOWN"><code class="Dv">NGM_SHUTDOWN</code></a></dt> - <dd>The target node should disconnect from all its neighbours and shut down. - Persistent nodes such as those representing physical hardware might not - disappear from the node namespace, but only reset themselves. The node - must disconnect all of its hooks. This may result in neighbors shutting - themselves down, and possibly a cascading shutdown of the entire connected - graph.</dd> - <dt id="NGM_NAME"><a class="permalink" href="#NGM_NAME"><code class="Dv">NGM_NAME</code></a></dt> - <dd>Assign a name to a node. Nodes can exist without having a name, and this - is the default for nodes created using the - <code class="Dv">NGM_MKPEER</code> method. Such nodes can only be - addressed relatively or by their ID number.</dd> - <dt id="NGM_RMHOOK"><a class="permalink" href="#NGM_RMHOOK"><code class="Dv">NGM_RMHOOK</code></a></dt> - <dd>Ask the node to break a hook connection to one of its neighbours. Both - nodes will have their “disconnect” method invoked. Either - node may elect to totally shut down as a result.</dd> - <dt id="NGM_NODEINFO"><a class="permalink" href="#NGM_NODEINFO"><code class="Dv">NGM_NODEINFO</code></a></dt> - <dd>Asks the target node to describe itself. The four returned fields are the - node name (if named), the node type, the node ID and the number of hooks - attached. The ID is an internal number unique to that node.</dd> - <dt id="NGM_LISTHOOKS"><a class="permalink" href="#NGM_LISTHOOKS"><code class="Dv">NGM_LISTHOOKS</code></a></dt> - <dd>This returns the information given by - <code class="Dv">NGM_NODEINFO</code>, but in addition includes an array of - fields describing each link, and the description for the node at the far - end of that link.</dd> - <dt id="NGM_LISTNAMES"><a class="permalink" href="#NGM_LISTNAMES"><code class="Dv">NGM_LISTNAMES</code></a></dt> - <dd>This returns an array of node descriptions (as for - <code class="Dv">NGM_NODEINFO</code>) where each entry of the array - describes a named node. All named nodes will be described.</dd> - <dt id="NGM_LISTNODES"><a class="permalink" href="#NGM_LISTNODES"><code class="Dv">NGM_LISTNODES</code></a></dt> - <dd>This is the same as <code class="Dv">NGM_LISTNAMES</code> except that all - nodes are listed regardless of whether they have a name or not.</dd> - <dt id="NGM_LISTTYPES"><a class="permalink" href="#NGM_LISTTYPES"><code class="Dv">NGM_LISTTYPES</code></a></dt> - <dd>This returns a list of all currently installed - <code class="Nm">netgraph</code> types.</dd> - <dt id="NGM_TEXT_STATUS"><a class="permalink" href="#NGM_TEXT_STATUS"><code class="Dv">NGM_TEXT_STATUS</code></a></dt> - <dd>The node may return a text formatted status message. The status - information is determined entirely by the node type. It is the only - “generic” message that requires any support within the node - itself and as such the node may elect to not support this message. The - text response must be less than <code class="Dv">NG_TEXTRESPONSE</code> - bytes in length (presently 1024). This can be used to return general - status information in human readable form.</dd> - <dt id="NGM_BINARY2ASCII"><a class="permalink" href="#NGM_BINARY2ASCII"><code class="Dv">NGM_BINARY2ASCII</code></a></dt> - <dd>This message converts a binary control message to its ASCII form. The - entire control message to be converted is contained within the arguments - field of the <code class="Dv">NGM_BINARY2ASCII</code> message itself. If - successful, the reply will contain the same control message in ASCII form. - A node will typically only know how to translate messages that it itself - understands, so the target node of the - <code class="Dv">NGM_BINARY2ASCII</code> is often the same node that would - actually receive that message.</dd> - <dt id="NGM_ASCII2BINARY"><a class="permalink" href="#NGM_ASCII2BINARY"><code class="Dv">NGM_ASCII2BINARY</code></a></dt> - <dd>The opposite of <code class="Dv">NGM_BINARY2ASCII</code>. The entire - control message to be converted, in ASCII form, is contained in the - arguments section of the <code class="Dv">NGM_ASCII2BINARY</code> and need - only have the <var class="Va">flags</var>, <var class="Va">cmdstr</var>, - and <var class="Va">arglen</var> header fields filled in, plus the - <code class="Dv">NUL</code>-terminated string version of the arguments in - the arguments field. If successful, the reply contains the binary version - of the control message.</dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="Flow_Control_Messages"><a class="permalink" href="#Flow_Control_Messages">Flow - Control Messages</a></h2> -<p class="Pp">In addition to the control messages that affect nodes with respect - to the graph, there are also a number of - <a class="permalink" href="#flow"><i class="Em" id="flow">flow - control</i></a> messages defined. At present these are - <a class="permalink" href="#not"><i class="Em" id="not">not</i></a> handled - automatically by the system, so nodes need to handle them if they are going - to be used in a graph utilising flow control, and will be in the likely path - of these messages. The default action of a node that does not understand - these messages should be to pass them onto the next node. Hopefully some - helper functions will assist in this eventually. These messages are also - defined in - <code class="In"><<a class="In">netgraph/ng_message.h</a>></code> and - have a separate cookie <code class="Dv">NG_FLOW_COOKIE</code> to help - identify them. They will not be covered in depth here.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="INITIALIZATION"><a class="permalink" href="#INITIALIZATION">INITIALIZATION</a></h1> -<p class="Pp">The base <code class="Nm">netgraph</code> code may either be - statically compiled into the kernel or else loaded dynamically as a KLD via - <a class="Xr">kldload(8)</a>. In the former case, include</p> -<p class="Pp"></p> -<div class="Bd Bd-indent"><code class="Cd">options NETGRAPH</code></div> -<p class="Pp">in your kernel configuration file. You may also include selected - node types in the kernel compilation, for example:</p> -<p class="Pp"></p> -<div class="Bd Bd-indent"><code class="Cd">options NETGRAPH</code></div> -<div class="Bd Bd-indent"><code class="Cd">options NETGRAPH_SOCKET</code></div> -<div class="Bd Bd-indent"><code class="Cd">options NETGRAPH_ECHO</code></div> -<p class="Pp">Once the <code class="Nm">netgraph</code> subsystem is loaded, - individual node types may be loaded at any time as KLD modules via - <a class="Xr">kldload(8)</a>. Moreover, <code class="Nm">netgraph</code> - knows how to automatically do this; when a request to create a new node of - unknown type <var class="Ar">type</var> is made, - <code class="Nm">netgraph</code> will attempt to load the KLD module - <span class="Pa">ng_</span>⟨<var class="Ar">type</var>⟩<span class="Pa">.ko</span>.</p> -<p class="Pp">Types can also be installed at boot time, as certain device - drivers may want to export each instance of the device as a - <code class="Nm">netgraph</code> node.</p> -<p class="Pp" id="ng_newtype">In general, new types can be installed at any time - from within the kernel by calling - <a class="permalink" href="#ng_newtype"><code class="Fn">ng_newtype</code></a>(), - supplying a pointer to the type's <var class="Vt">struct ng_type</var> - structure.</p> -<p class="Pp" id="NETGRAPH_INIT">The - <a class="permalink" href="#NETGRAPH_INIT"><code class="Fn">NETGRAPH_INIT</code></a>() - macro automates this process by using a linker set.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXISTING_NODE_TYPES"><a class="permalink" href="#EXISTING_NODE_TYPES">EXISTING - NODE TYPES</a></h1> -<p class="Pp">Several node types currently exist. Each is fully documented in - its own man page:</p> -<dl class="Bl-tag"> - <dt>SOCKET</dt> - <dd>The socket type implements two new sockets in the new protocol domain - <code class="Dv">PF_NETGRAPH</code>. The new sockets protocols are - <code class="Dv">NG_DATA</code> and <code class="Dv">NG_CONTROL</code>, - both of type <code class="Dv">SOCK_DGRAM</code>. Typically one of each is - associated with a socket node. When both sockets have closed, the node - will shut down. The <code class="Dv">NG_DATA</code> socket is used for - sending and receiving data, while the <code class="Dv">NG_CONTROL</code> - socket is used for sending and receiving control messages. Data and - control messages are passed using the <a class="Xr">sendto(2)</a> and - <a class="Xr">recvfrom(2)</a> system calls, using a <var class="Vt">struct - sockaddr_ng</var> socket address.</dd> - <dt>HOLE</dt> - <dd>Responds only to generic messages and is a “black hole” for - data. Useful for testing. Always accepts new hooks.</dd> - <dt>ECHO</dt> - <dd>Responds only to generic messages and always echoes data back through the - hook from which it arrived. Returns any non-generic messages as their own - response. Useful for testing. Always accepts new hooks.</dd> - <dt>TEE</dt> - <dd>This node is useful for “snooping”. It has 4 hooks: - <var class="Va">left</var>, <var class="Va">right</var>, - <var class="Va">left2right</var>, and <var class="Va">right2left</var>. - Data entering from the <var class="Va">right</var> is passed to the - <var class="Va">left</var> and duplicated on - <var class="Va">right2left</var>, and data entering from the - <var class="Va">left</var> is passed to the <var class="Va">right</var> - and duplicated on <var class="Va">left2right</var>. Data entering from - <var class="Va">left2right</var> is sent to the - <var class="Va">right</var> and data from <var class="Va">right2left</var> - to <var class="Va">left</var>.</dd> - <dt>RFC1490 MUX</dt> - <dd>Encapsulates/de-encapsulates frames encoded according to RFC 1490. Has a - hook for the encapsulated packets (<var class="Va">downstream</var>) and - one hook for each protocol (i.e., IP, PPP, etc.).</dd> - <dt>FRAME RELAY MUX</dt> - <dd>Encapsulates/de-encapsulates Frame Relay frames. Has a hook for the - encapsulated packets (<var class="Va">downstream</var>) and one hook for - each DLCI.</dd> - <dt>FRAME RELAY LMI</dt> - <dd>Automatically handles frame relay “LMI” (link management - interface) operations and packets. Automatically probes and detects which - of several LMI standards is in use at the exchange.</dd> - <dt>TTY</dt> - <dd>This node is also a line discipline. It simply converts between - <var class="Vt">mbuf</var> frames and sequential serial data, allowing a - TTY to appear as a <code class="Nm">netgraph</code> node. It has a - programmable “hotkey” character.</dd> - <dt>ASYNC</dt> - <dd>This node encapsulates and de-encapsulates asynchronous frames according - to RFC 1662. This is used in conjunction with the TTY node type for - supporting PPP links over asynchronous serial lines.</dd> - <dt>ETHERNET</dt> - <dd>This node is attached to every Ethernet interface in the system. It allows - capturing raw Ethernet frames from the network, as well as sending frames - out of the interface.</dd> - <dt>INTERFACE</dt> - <dd>This node is also a system networking interface. It has hooks representing - each protocol family (IP, IPv6) and appears in the output of - <a class="Xr">ifconfig(8)</a>. The interfaces are named - “<code class="Li">ng0</code>”, - “<code class="Li">ng1</code>”, etc.</dd> - <dt>ONE2MANY</dt> - <dd>This node implements a simple round-robin multiplexer. It can be used for - example to make several LAN ports act together to get a higher speed link - between two machines.</dd> - <dt>Various PPP related nodes</dt> - <dd>There is a full multilink PPP implementation that runs in - <code class="Nm">netgraph</code>. The <span class="Pa">net/mpd5</span> - port can use these modules to make a very low latency high capacity PPP - system. It also supports PPTP VPNs using the PPTP node.</dd> - <dt>PPPOE</dt> - <dd>A server and client side implementation of PPPoE. Used in conjunction with - either <a class="Xr">ppp(8)</a> or the <span class="Pa">net/mpd5</span> - port.</dd> - <dt>BRIDGE</dt> - <dd>This node, together with the Ethernet nodes, allows a very flexible - bridging system to be implemented.</dd> - <dt>KSOCKET</dt> - <dd>This intriguing node looks like a socket to the system but diverts all - data to and from the <code class="Nm">netgraph</code> system for further - processing. This allows such things as UDP tunnels to be almost trivially - implemented from the command line.</dd> -</dl> -<p class="Pp">Refer to the section at the end of this man page for more nodes - types.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> -<p class="Pp">Whether a named node exists can be checked by trying to send a - control message to it (e.g., <code class="Dv">NGM_NODEINFO</code>). If it - does not exist, <code class="Er">ENOENT</code> will be returned.</p> -<p class="Pp">All data messages are <var class="Vt">mbuf chains</var> with the - <code class="Dv">M_PKTHDR</code> flag set.</p> -<p class="Pp">Nodes are responsible for freeing what they allocate. There are - three exceptions:</p> -<ol class="Bl-enum"> - <li><var class="Vt">Mbufs</var> sent across a data link are never to be freed - by the sender. In the case of error, they should be considered freed.</li> - <li id="NG_SEND_MSG_*">Messages sent using one of - <a class="permalink" href="#NG_SEND_MSG_*"><code class="Fn">NG_SEND_MSG_*</code></a>() - family macros are freed by the recipient. As in the case above, the - addresses associated with the message are freed by whatever allocated them - so the recipient should copy them if it wants to keep that - information.</li> - <li id="NG_FREE_ITEM~2">Both control messages and data are delivered and - queued with a <code class="Nm">netgraph</code> <i class="Em">item</i>. The - item must be freed using - <a class="permalink" href="#NG_FREE_ITEM~2"><code class="Fn">NG_FREE_ITEM</code></a>(<var class="Fa">item</var>) - or passed on to another node.</li> -</ol> -</section> -<section class="Sh"> -<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> -<dl class="Bl-tag"> - <dt><code class="In"><<a class="In">netgraph/netgraph.h</a>></code></dt> - <dd>Definitions for use solely within the kernel by - <code class="Nm">netgraph</code> nodes.</dd> - <dt><code class="In"><<a class="In">netgraph/ng_message.h</a>></code></dt> - <dd>Definitions needed by any file that needs to deal with - <code class="Nm">netgraph</code> messages.</dd> - <dt><code class="In"><<a class="In">netgraph/ng_socket.h</a>></code></dt> - <dd>Definitions needed to use <code class="Nm">netgraph</code> - <var class="Vt">socket</var> type nodes.</dd> - <dt><code class="In"><<a class="In">netgraph/ng_</a>></code>⟨<var class="Ar">type</var>⟩<span class="Pa">.h</span></dt> - <dd>Definitions needed to use <code class="Nm">netgraph</code> - <var class="Ar">type</var> nodes, including the type cookie - definition.</dd> - <dt><span class="Pa">/boot/kernel/netgraph.ko</span></dt> - <dd>The <code class="Nm">netgraph</code> subsystem loadable KLD module.</dd> - <dt><span class="Pa">/boot/kernel/ng_</span>⟨<var class="Ar">type</var>⟩<span class="Pa">.ko</span></dt> - <dd>Loadable KLD module for node type <var class="Ar">type</var>.</dd> - <dt><span class="Pa">src/sys/netgraph/ng_sample.c</span></dt> - <dd>Skeleton <code class="Nm">netgraph</code> node. Use this as a starting - point for new node types.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="USER_MODE_SUPPORT"><a class="permalink" href="#USER_MODE_SUPPORT">USER - MODE SUPPORT</a></h1> -<p class="Pp">There is a library for supporting user-mode programs that wish to - interact with the <code class="Nm">netgraph</code> system. See - <a class="Xr">netgraph(3)</a> for details.</p> -<p class="Pp">Two user-mode support programs, <a class="Xr">ngctl(8)</a> and - <a class="Xr">nghook(8)</a>, are available to assist manual configuration - and debugging.</p> -<p class="Pp">There are a few useful techniques for debugging new node types. - First, implementing new node types in user-mode first makes debugging - easier. The <var class="Vt">tee</var> node type is also useful for - debugging, especially in conjunction with <a class="Xr">ngctl(8)</a> and - <a class="Xr">nghook(8)</a>.</p> -<p class="Pp">Also look in <span class="Pa">/usr/share/examples/netgraph</span> - for solutions to several common networking problems, solved using - <code class="Nm">netgraph</code>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">socket(2)</a>, <a class="Xr">netgraph(3)</a>, - <a class="Xr">ng_async(4)</a>, <a class="Xr">ng_bluetooth(4)</a>, - <a class="Xr">ng_bpf(4)</a>, <a class="Xr">ng_bridge(4)</a>, - <a class="Xr">ng_btsocket(4)</a>, <a class="Xr">ng_car(4)</a>, - <a class="Xr">ng_cisco(4)</a>, <a class="Xr">ng_device(4)</a>, - <a class="Xr">ng_echo(4)</a>, <a class="Xr">ng_eiface(4)</a>, - <a class="Xr">ng_etf(4)</a>, <a class="Xr">ng_ether(4)</a>, - <a class="Xr">ng_frame_relay(4)</a>, <a class="Xr">ng_gif(4)</a>, - <a class="Xr">ng_gif_demux(4)</a>, <a class="Xr">ng_hci(4)</a>, - <a class="Xr">ng_hole(4)</a>, <a class="Xr">ng_hub(4)</a>, - <a class="Xr">ng_iface(4)</a>, <a class="Xr">ng_ip_input(4)</a>, - <a class="Xr">ng_ipfw(4)</a>, <a class="Xr">ng_ksocket(4)</a>, - <a class="Xr">ng_l2cap(4)</a>, <a class="Xr">ng_l2tp(4)</a>, - <a class="Xr">ng_lmi(4)</a>, <a class="Xr">ng_mppc(4)</a>, - <a class="Xr">ng_nat(4)</a>, <a class="Xr">ng_netflow(4)</a>, - <a class="Xr">ng_one2many(4)</a>, <a class="Xr">ng_patch(4)</a>, - <a class="Xr">ng_ppp(4)</a>, <a class="Xr">ng_pppoe(4)</a>, - <a class="Xr">ng_pptpgre(4)</a>, <a class="Xr">ng_rfc1490(4)</a>, - <a class="Xr">ng_socket(4)</a>, <a class="Xr">ng_split(4)</a>, - <a class="Xr">ng_tee(4)</a>, <a class="Xr">ng_tty(4)</a>, - <a class="Xr">ng_ubt(4)</a>, <a class="Xr">ng_UI(4)</a>, - <a class="Xr">ng_vjc(4)</a>, <a class="Xr">ng_vlan(4)</a>, - <a class="Xr">ngctl(8)</a>, <a class="Xr">nghook(8)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">netgraph</code> system was designed and first - implemented at Whistle Communications, Inc. in a version of - <span class="Ux">FreeBSD 2.2</span> customized for the Whistle InterJet. It - first made its debut in the main tree in <span class="Ux">FreeBSD - 3.4</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><span class="An">Julian Elischer</span> - <<a class="Mt" href="mailto:julian@FreeBSD.org">julian@FreeBSD.org</a>>, - with contributions by <span class="An">Archie Cobbs</span> - <<a class="Mt" href="mailto:archie@FreeBSD.org">archie@FreeBSD.org</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">September 29, 2021</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |