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, 1023 insertions, 0 deletions
diff --git a/static/freebsd/man4/netgraph.4 3.html b/static/freebsd/man4/netgraph.4 3.html new file mode 100644 index 00000000..c3d615fa --- /dev/null +++ b/static/freebsd/man4/netgraph.4 3.html @@ -0,0 +1,1023 @@ +<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> |