On Thu, Oct 24, 2013 at 09:49:33AM -0700, Ben Pfaff wrote:
> This update improves the BFD documentation in a few ways:
>
> - Demand mode is now supported.
>
> - Wordsmithing, spelling, etc.
>
> - Attempt to better explain decay_min_rx, forwarding_if_rx, and
> cpath_down.
>
> - Break into subgroups for configuration and status, to better explain
> which party sets which fields.
>
> - Reindents to match the rest of vswitch.xml.
>
> Because of the reindentation, this patch may be easier to view with spacing
> changes suppressed.
>
> Signed-off-by: Ben Pfaff <[email protected]>
Here is the patch with the spacing changes suppressed:
diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index c12fd8f..6c7d861 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -1844,9 +1844,9 @@
<group title="Bidirectional Forwarding Detection (BFD)">
<p>
- BFD, defined in RFC 5880 and RFC 5881, allows point to point
+ BFD, defined in RFC 5880 and RFC 5881, allows point-to-point
detection of connectivity failures by occasional transmission of
- BFD control messages. It is implemented in Open vSwitch to serve
+ BFD control messages. Open vSwitch implements BFD to serve
as a more popular and standards compliant alternative to CFM.
</p>
@@ -1854,118 +1854,128 @@
BFD operates by regularly transmitting BFD control messages at a
rate negotiated independently in each direction. Each endpoint
specifies the rate at which it expects to receive control messages,
- and the rate at which it's willing to transmit them. Open vSwitch
+ and the rate at which it is willing to transmit them. Open vSwitch
uses a detection multiplier of three, meaning that an endpoint
- which fails to receive BFD control messages for a period of three
- times the expected reception rate, will signal a connectivity
- fault. In the case of a unidirectional connectivity issue, the
- system not receiving BFD control messages will signal the problem
- to its peer in the messages it transmits.
+ signals a connectivity fault if it fails to receive BFD consecutive
+ control messages at the expected rate. In the case of a
+ unidirectional connectivity issue, the system not receiving BFD
+ control messages signals the problem to its peer in the messages it
+ transmits.
</p>
<p>
The Open vSwitch implementation of BFD aims to comply faithfully
- with the requirements put forth in RFC 5880. Currently, the only
- known omission is ``Demand Mode'', which we hope to include in
- future. Open vSwitch does not implement the optional
- Authentication or ``Echo Mode'' features.
+ with RFC 5880 requirements. Open vSwitch does not implement the
+ optional Authentication or ``Echo Mode'' features.
</p>
- <column name="bfd" key="enable">
- When <code>true</code> BFD is enabled on this
- <ref table="Interface"/>, otherwise it's disabled. Defaults to
- <code>false</code>.
+ <group title="BFD Configuration">
+ <p>
+ A controller sets up key-value pairs in the <ref column="bfd"/>
+ column to enable and configure BFD.
+ </p>
+
+ <column name="bfd" key="enable" type='{"type": "boolean"}'>
+ True to enable BFD on this <ref table="Interface"/>.
</column>
<column name="bfd" key="min_rx"
type='{"type": "integer", "minInteger": 1}'>
- The fastest rate, in milliseconds, at which this BFD session is
- willing to receive BFD control messages. The actual rate may be
- slower if the remote endpoint isn't willing to transmit as quickly as
- specified. Defaults to <code>1000</code>.
+ The shortest interval, in milliseconds, at which this BFD session
+ offers to receive BFD control messages. The remote endpoint may
+ choose to send messages at a slower rate. Defaults to
+ <code>1000</code>.
</column>
<column name="bfd" key="min_tx"
type='{"type": "integer", "minInteger": 1}'>
- The fastest rate, in milliseconds, at which this BFD session is
- willing to transmit BFD control messages. The actual rate may be
- slower if the remote endpoint isn't willing to receive as quickly as
- specified. Defaults to <code>100</code>.
+ The shortest interval, in milliseconds, at which this BFD session is
+ willing to transmit BFD control messages. Messages will actually be
+ transmitted at a slower rate if the remote endpoint is not willing to
+ receive as quickly as specified. Defaults to <code>100</code>.
</column>
<column name="bfd" key="decay_min_rx" type='{"type": "integer"}'>
- <code>decay_min_rx</code> is used to set the <code>min_rx</code>,
- when there is no obvious incoming data traffic at the interface.
- It cannot be set less than the <code>min_rx</code>. The decay feature
- is disabled by setting the <code>decay_min_rx</code> to 0. And the
- feature is reset everytime itself or <code>min_rx</code> is
- reconfigured.
+ An alternate receive interval, in milliseconds, that must be greater
+ than or equal to <ref column="bfd" key="min_rx"/>. The
+ implementation switches from <ref column="bfd" key="min_rx"/> to <ref
+ column="bfd" key="decay_min_rx"/> when there is no obvious incoming
+ data traffic at the interface, to reduce the CPU and bandwidth cost
+ of monitoring an idle interface. This feature may be disabled by
+ setting a value of 0. This feature is reset whenever <ref
+ column="bfd" key="decay_min_rx"/> or <ref column="bfd" key="min_rx"/>
+ changes.
</column>
<column name="bfd" key="forwarding_if_rx" type='{"type": "boolean"}'>
- When <code>forwarding_if_rx</code> is true the interface will be
- considered capable of packet I/O as long as there is packet
- received at interface. This is important in that when link becomes
- temporarily conjested, consecutive BFD control packets can be lost.
- And the <code>forwarding_if_rx</code> can prevent link failover by
- detecting non-control packets received at interface.
+ True to consider the interface capable of packet I/O as long as it
+ continues to receive any packets (not just BFD packets). This
+ prevents link congestion that causes BFD consecutive control packets
+ to be lost from marking the interface down.
</column>
<column name="bfd" key="cpath_down" type='{"type": "boolean"}'>
- Concatenated path down may be used when the local system should not
- have traffic forwarded to it for some reason other than a connectivty
- failure on the interface being monitored. When a controller thinks
- this may be the case, it may set <code>cpath_down</code> to
- <code>true</code> which may cause the remote BFD session not to
- forward traffic to this <ref table="Interface"/>. Defaults to
- <code>false</code>.
+ Set to true to notify the remote endpoint that traffic should not be
+ forwarded to this system for some reason other than a connectivty
+ failure on the interface being monitored. The typical underlying
+ reason is ``concatenated path down,'' that is, that connectivity
+ beyond the local system is down. Defaults to false.
</column>
<column name="bfd" key="check_tnl_key" type='{"type": "boolean"}'>
- When set to true, Check Tunnel Key will make BFD only accept control
- messages with an <code>in_key</code> of zero. Defaults to
- <code>false</code>.
+ Set to true to make BFD accept only control messages with an tunnel
+ key of zero. By default, BFD accepts control messages with any
+ tunnel key.
</column>
<column name="bfd" key="bfd_dst_mac">
- An Ethernet address in the form
+ Set to an Ethernet address in the form
<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
- to set the destination mac address of the bfd packet. If this
- field is set, it is assumed that all the bfd packets destined to this
- interface also has the same destination mac address. If not set, a
- default value of <code>00:23:20:00:00:01</code> is used.
+ to set the MAC used as destination for transmitted BFD packet and
+ expected as destination for received BFD packets. The default is
+ <code>00:23:20:00:00:01</code>.
</column>
+ </group>
+
+ <group title="BFD Status">
+ <p>
+ The switch sets key-value pairs in the <ref column="bfd_status"/>
+ column to report the status of BFD on this interface. When BFD is
+ not enabled, with <ref column="bfd" key="enable"/>, the switch clears
+ all key-value pairs from <ref column="bfd_status"/>.
+ </p>
<column name="bfd_status" key="state"
type='{"type": "string",
"enum": ["set", ["admin_down", "down", "init", "up"]]}'>
- State of the BFD session. The BFD session is fully healthy and
- negotiated if <code>UP</code>.
+ Reports the state of the BFD session. The BFD session is fully
+ healthy and negotiated if <code>UP</code>.
</column>
<column name="bfd_status" key="forwarding" type='{"type": "boolean"}'>
- True if the BFD session believes this <ref table="Interface"/> may be
- used to forward traffic. Typically this means the local session is
- signaling <code>UP</code>, and the remote system isn't signaling a
- problem such as concatenated path down.
+ Reports whether the BFD session believes this <ref
+ table="Interface"/> may be used to forward traffic. Typically this
+ means the local session is signaling <code>UP</code>, and the remote
+ system isn't signaling a problem such as concatenated path down.
</column>
<column name="bfd_status" key="diagnostic">
- A short message indicating what the BFD session thinks is wrong in
- case of a problem.
+ In case of a problem, set to a short message that reports what the
+ local BFD session thinks is wrong.
</column>
<column name="bfd_status" key="remote_state"
type='{"type": "string",
"enum": ["set", ["admin_down", "down", "init", "up"]]}'>
- State of the remote endpoint's BFD session.
+ Reports the state of the remote endpoint's BFD session.
</column>
<column name="bfd_status" key="remote_diagnostic">
- A short message indicating what the remote endpoint's BFD session
- thinks is wrong in case of a problem.
+ In case of a problem, set to a short message that reports what the
+ remote endpoint's BFD session thinks is wrong
</column>
</group>
+ </group>
<group title="Connectivity Fault Management">
<p>
_______________________________________________
dev mailing list
[email protected]
http://openvswitch.org/mailman/listinfo/dev
