/share/man/man4/ng_bridge.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 213 lines · 213 code · 0 blank · 0 comment · 4 complexity · 336289ba0151ae4f7ad8fc7a1710bb65 MD5 · raw file

  1. .\" Copyright (c) 2000 Whistle Communications, Inc.
  2. .\" All rights reserved.
  3. .\"
  4. .\" Subject to the following obligations and disclaimer of warranty, use and
  5. .\" redistribution of this software, in source or object code forms, with or
  6. .\" without modifications are expressly permitted by Whistle Communications;
  7. .\" provided, however, that:
  8. .\" 1. Any and all reproductions of the source or object code must include the
  9. .\" copyright notice above and the following disclaimer of warranties; and
  10. .\" 2. No rights are granted, in any manner or form, to use Whistle
  11. .\" Communications, Inc. trademarks, including the mark "WHISTLE
  12. .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as
  13. .\" such appears in the above copyright notice or in the software.
  14. .\"
  15. .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
  16. .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
  17. .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
  18. .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
  19. .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
  20. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
  21. .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
  22. .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
  23. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
  24. .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
  25. .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  26. .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
  27. .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
  28. .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29. .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30. .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
  31. .\" OF SUCH DAMAGE.
  32. .\"
  33. .\" Author: Archie Cobbs <archie@FreeBSD.org>
  34. .\"
  35. .\" $FreeBSD$
  36. .\"
  37. .Dd May 5, 2010
  38. .Dt NG_BRIDGE 4
  39. .Os
  40. .Sh NAME
  41. .Nm ng_bridge
  42. .Nd Ethernet bridging netgraph node type
  43. .Sh SYNOPSIS
  44. .In sys/types.h
  45. .In netgraph/ng_bridge.h
  46. .Sh DESCRIPTION
  47. The
  48. .Nm bridge
  49. node type performs Ethernet bridging over one or more links.
  50. Each link (represented by a connected hook) is used to transmit
  51. and receive raw Ethernet frames.
  52. As packets are received, the node learns which link each
  53. host resides on.
  54. Packets unicast to a known host are directed out the appropriate
  55. link only, and other links are spared the traffic.
  56. This behavior is in contrast to a hub, which always forwards
  57. every received packet to every other link.
  58. .Sh LOOP DETECTION
  59. The
  60. .Nm bridge
  61. node incorporates a simple loop detection algorithm.
  62. A loop is when two ports are connected to the same physical medium.
  63. Loops are important to avoid because of packet storms, which severely
  64. degrade performance.
  65. A packet storm results when the same packet is sent and received
  66. over and over again.
  67. If a host is detected on link A, and is then detected on link B
  68. within a certain time period after first being detected on link A,
  69. then link B is considered to be a looped back link.
  70. The time period is called the minimum stable time.
  71. .Pp
  72. A looped back link will be temporarily muted, i.e., all traffic
  73. received on that link is ignored.
  74. .Sh IPFW PROCESSING
  75. Processing of IP packets via the
  76. .Xr ipfirewall 4
  77. mechanism on a per-link basis is not yet implemented.
  78. .Sh HOOKS
  79. This node type supports up to
  80. .Dv NG_BRIDGE_MAX_LINKS
  81. hooks.
  82. Each connected hook represents a bridged link.
  83. The hooks are named
  84. .Dv link0 ,
  85. .Dv link1 ,
  86. etc.
  87. Typically these hooks are connected to the
  88. .Dv lower
  89. hooks of one or more
  90. .Xr ng_ether 4
  91. nodes.
  92. To connect the host machine to a bridged network, simply connect the
  93. .Dv upper
  94. hook of an
  95. .Xr ng_ether 4
  96. node to the bridge node.
  97. .Sh CONTROL MESSAGES
  98. This node type supports the generic control messages, plus the
  99. following:
  100. .Bl -tag -width foo
  101. .It Dv NGM_BRIDGE_SET_CONFIG
  102. Set the node configuration.
  103. This command takes a
  104. .Dv "struct ng_bridge_config"
  105. as an argument:
  106. .Bd -literal -offset 0n
  107. /* Node configuration structure */
  108. struct ng_bridge_config {
  109. u_char ipfw[NG_BRIDGE_MAX_LINKS]; /* enable ipfw */
  110. u_char debugLevel; /* debug level */
  111. uint32_t loopTimeout; /* link loopback mute time */
  112. uint32_t maxStaleness; /* max host age before nuking */
  113. uint32_t minStableAge; /* min time for a stable host */
  114. };
  115. .Ed
  116. .Pp
  117. The
  118. .Dv ipfw
  119. array enables
  120. .Xr ipfirewall 4
  121. processing of IP packets received on the corresponding links.
  122. The
  123. .Dv debugLevel
  124. field sets the debug level on the node.
  125. At level of 2 or greater, detected loops are logged.
  126. The default level is 1.
  127. .Pp
  128. The
  129. .Dv loopTimeout
  130. determines how long (in seconds) a looped link is muted.
  131. The default is 60 seconds.
  132. The
  133. .Dv maxStaleness
  134. parameter determines how long a period of inactivity before
  135. a host's entry is forgotten.
  136. The default is 15 minutes.
  137. The
  138. .Dv minStableAge
  139. determines how quickly a host must jump from one link to another
  140. before we declare a loopback condition.
  141. The default is one second.
  142. .Pp
  143. .It Dv NGM_BRIDGE_GET_CONFIG
  144. Returns the current configuration as a
  145. .Dv "struct ng_bridge_config" .
  146. .It Dv NGM_BRIDGE_RESET
  147. Causes the node to forget all hosts and unmute all links.
  148. The node configuration is not changed.
  149. .It Dv NGM_BRIDGE_GET_STATS
  150. This command takes a four byte link number as an argument and
  151. returns a
  152. .Dv "struct ng_bridge_link_stats"
  153. containing statistics for the corresponding link, which must be
  154. currently connected:
  155. .Bd -literal -offset 0n
  156. /* Statistics structure (one for each link) */
  157. struct ng_bridge_link_stats {
  158. uint64_t recvOctets; /* total octets rec'd on link */
  159. uint64_t recvPackets; /* total pkts rec'd on link */
  160. uint64_t recvMulticasts; /* multicast pkts rec'd on link */
  161. uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */
  162. uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */
  163. uint64_t recvRunts; /* pkts rec'd less than 14 bytes */
  164. uint64_t recvInvalid; /* pkts rec'd with bogus source addr */
  165. uint64_t xmitOctets; /* total octets xmit'd on link */
  166. uint64_t xmitPackets; /* total pkts xmit'd on link */
  167. uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */
  168. uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */
  169. uint64_t loopDrops; /* pkts dropped due to loopback */
  170. uint64_t loopDetects; /* number of loop detections */
  171. uint64_t memoryFailures; /* times couldn't get mem or mbuf */
  172. };
  173. .Ed
  174. .It Dv NGM_BRIDGE_CLR_STATS
  175. This command takes a four byte link number as an argument and
  176. clears the statistics for that link.
  177. .It Dv NGM_BRIDGE_GETCLR_STATS
  178. Same as
  179. .Dv NGM_BRIDGE_GET_STATS ,
  180. but also atomically clears the statistics as well.
  181. .It Dv NGM_BRIDGE_GET_TABLE
  182. Returns the current host mapping table used to direct packets, in a
  183. .Dv "struct ng_bridge_host_ary" .
  184. .It Dv NGM_BRIDGE_SET_PERSISTENT
  185. This command sets the persistent flag on the node, and takes no arguments.
  186. .El
  187. .Sh SHUTDOWN
  188. This node shuts down upon receipt of a
  189. .Dv NGM_SHUTDOWN
  190. control message, or when all hooks have been disconnected. Setting the
  191. persistent flag via a
  192. .Dv NGM_BRIDGE_SET_PERSISTENT
  193. control message disables automatic node shutdown when the last hook gets
  194. disconnected.
  195. .Sh FILES
  196. .Bl -tag -width XXXXXXXX -compact
  197. .It Pa /usr/share/examples/netgraph/ether.bridge
  198. Example script showing how to set up a bridging network
  199. .El
  200. .Sh SEE ALSO
  201. .Xr if_bridge 4 ,
  202. .Xr netgraph 4 ,
  203. .Xr ng_ether 4 ,
  204. .Xr ng_hub 4 ,
  205. .Xr ng_one2many 4 ,
  206. .Xr ngctl 8
  207. .Sh HISTORY
  208. The
  209. .Nm
  210. node type was implemented in
  211. .Fx 4.2 .
  212. .Sh AUTHORS
  213. .An Archie Cobbs Aq archie@FreeBSD.org