docs: convert vpp doc md->rst

Type: improvement

Change-Id: If453321785b04f9c16e8cea36fb1910efaeb2c59
Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>

1 files changed, 0 insertions, 374 deletions

diff --git a/src/vnet/bfd/bfd_doc.md b/src/vnet/bfd/bfd_doc.md
deleted file mode 100644
index 7d7606e4dd1..00000000000
--- a/src/vnet/bfd/bfd_doc.md
+++ /dev/null
@@ -1,374 +0,0 @@
-# BFD module    {#bfd_doc}
-
-## Overview
-
-Bidirectional Forwarding Detection in VPP currently supports single-hop UDP
-transport based on RFC 5880 and RFC 5881.
-
-## Usage
-
-### General usage
-
-BFD sessions are created using APIs only. The following CLIs are implemented,
-which call the APIs to manipulate the BFD:
-
-#### Show commands:
-
-> show bfd [keys|sessions|echo-source]
-
-Show the existing keys, sessions or echo-source.
-
-#### Key manipulation
-
-##### Create a new key or modify an existing key
-
-> bfd key set conf-key-id <id> type <keyed-sha1|meticulous-keyed-sha1> secret <secret>
-
-Parameters:
-
-* conf-key-id     - local configuration key ID, used to uniquely identify this key
-* type            - type of the key
-* secret          - shared secret (hex data)
-
-Example:
-
-> bfd key set conf-key-id 2368880803 type meticulous-keyed-sha1 secret 69d685b0d990cdba46872706dc
-
-Notes:
-
-* in-use key cannot be modified
-
-##### Delete an existing key
-
-> bfd key del conf-key-id <id>
-
-Parameters:
-
-* conf-key-id     - local configuration key ID, used to uniquely identify this key
-
-Example:
-
-> bfd key del conf-key-id 2368880803
-
-Notes:
-
-*  in-use key cannot be deleted
-
-##### Create a new (plain or authenticated) BFD session
-
-> bfd udp session add interface <interface> local-addr <address> peer-addr <address> desired-min-tx <interval> required-min-rx <interval> detect-mult <multiplier> [ conf-key-id <ID> bfd-key-id <ID> ]
-
-Parameters:
-
-* interface       - interface to which this session is tied to
-* local-addr      - local address (ipv4 or ipv6)
-* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
-* desired-min-tx  - desired minimum tx interval (microseconds)
-* required-min-rx - required minimum rx interval (microseconds)
-* detect-mult     - detect multiplier (must be non-zero)
-* conf-key-id     - local configuration key ID
-* bfd-key-id      - BFD key ID, as carried in BFD control frames
-
-Example:
-
-> bfd udp session add interface pg0 local-addr fd01:1::1 peer-addr fd01:1::2 desired-min-tx 100000 required-min-rx 100000 detect-mult 3 conf-key-id 1029559112 bfd-key-id 13
-
-Notes:
-
-* if conf-key-id and bfd-key-id are not specified, session is non-authenticated
-* desired-min-tx controls desired transmission rate of both control frames and echo packets
-
-##### Modify BFD session
-
-> bfd udp session mod interface <interface> local-addr <address> peer-addr <address> desired-min-tx <interval> required-min-rx <interval> detect-mult <multiplier>
-
-Parameters:
-
-* interface       - interface to which this session is tied to
-* local-addr      - local address (ipv4 or ipv6)
-* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
-* desired-min-tx  - desired minimum tx interval (microseconds)
-* required-min-rx - required minimum rx interval (microseconds)
-* detect-mult     - detect multiplier (must be non-zero)
-
-Example:
-
-> bfd udp session mod interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 desired-min-tx 300000 required-min-rx 200000 detect-mult 12
-
-Notes:
-
-* desired-min-tx controls desired transmission rate of both control frames and echo packets
-
-##### Delete an existing BFD session
-
-> bfd udp session del interface <interface> local-addr <address> peer-addr<address>
-
-Parameters:
-
-* interface       - interface to which this session is tied to
-* local-addr      - local address (ipv4 or ipv6)
-* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
-
-Example:
-
-> bfd udp session del interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2
-
-##### Set session admin-up or admin-down
-
-> bfd udp session set-flags interface <interface> local-addr <address> peer-addr <address> admin <up|down>
-
-Parameters:
-
-* interface       - interface to which this session is tied to
-* local-addr      - local address (ipv4 or ipv6)
-* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
-* admin           - up/down based on desired action
-
-Example:
-
-> bfd udp session set-flags admin down interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2
-
-##### Activate/change authentication for existing session
-
-> bfd udp session auth activate interface <interface> local-addr <address> peer-addr <address> conf-key-id <ID> bfd-key-id <ID> [ delayed <yes|no> ]
-
-Parameters:
-
-* interface       - interface to which this session is tied to
-* local-addr      - local address (ipv4 or ipv6)
-* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
-* conf-key-id     - local configuration key ID
-* bfd-key-id      - BFD key ID, as carried in BFD control frames
-* delayed         - is yes then this action is delayed until the peer performs the same action
-
-Example:
-
-> bfd udp session auth activate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2 conf-key-id 540928695 bfd-key-id 239 delayed yes
-
-Notes:
-
-* see [Delayed option] for more information
-
-##### Deactivate authentication for existing session
-
-> bfd udp session auth deactivate interface <interface> local-addr <address> peer-addr <address> [ delayed <yes|no> ]
-
-Parameters:
-
-* interface       - interface to which this session is tied to
-* local-addr      - local address (ipv4 or ipv6)
-* peer-addr       - peer address (ipv4 or ipv6, must match local-addr family)
-* delayed         - is yes then this action is delayed until the peer performs the same action
-
-Example:
-
-> bfd udp session auth deactivate interface pg0 local-addr 172.16.1.1 peer-addr 172.16.1.2
-
-Notes:
-
-* see [Delayed option] for more information
-
-##### Set echo-source interface
-
-> bfd udp echo-source set interface <interface>
-
-Parameters:
-
-* interface       - interface used for getting source address for echo packets
-
-Example:
-
-> bfd udp echo-source set interface loop0
-
-##### Delete echo-source interface
-
-> bfd udp echo-source del
-
-Example:
-
-> bfd udp echo-source del
-
-### Authentication
-
-BFD sessions should be authenticated for security purposes. SHA1 and meticulous
-SHA1 authentication is supported by VPP. First, authentication keys are
-configured in VPP and afterwards they can be used by sessions.
-
-There are two key IDs in the scope of BFD session:
-
-* configuration key ID is the internal unique key ID inside VPP and is never
-  communicated to any peer, it serves only the purpose of identifying the key
-* BFD key ID is the key ID carried in BFD control frames and is used for
-  verifying authentication
-
-#### Turning auth on/off
-
-Authentication can be turned on or off at any time. Care must be taken however,
-to either synchronize the authentication manipulation with peer's actions
-to avoid the session going down.
-
-##### Delayed option
-
-Delayed option is useful for synchronizing authentication changes with a peer.
-If it's specified, then authentication change is not performed immediately.
-In this case, VPP continues to transmit packets using the old authentication
-method (unauthenticated or using old sha1 key). If a packet is received, which
-does not pass the current authentication, then VPP tries to authenticate it
-using the new method (which might be none, if deactivating authentication)
-and if it passes, then the new authentication method is put in use.
-
-The recommended procedure for enabling/changing/disabling session 
-authentication is:
-
-1. perform authentication change on vpp's side with delayed option set to yes
-2. perform authentication change on peer's side (without delayed option)
-
-Notes:
-
-* if both peers use delayed option at the same time, the change will never
-  be carried out, since none of the peers will see any packet with the new
-  authentication which could trigger the change
-* remote peer does not need to support or even be aware of this mechanism
-  for it to work properly
-
-
-### Echo function
-
-Echo function is used by VPP whenever a peer declares the willingness
-to support it, echo-source is set and it contains a usable subnet (see below).
-When echo function is switched on, the required min rx interval advertised
-to peer is set to 1 second (or the configured value, if its higher).
-
-#### Echo source address
-
-Because echo packets are only looped back (and not processed in any way)
-by a peer, it's necessary to set the source address in a way which avoids
-packet drop due to spoofing protection by VPP. Per RFC, the source address
-should not be in the subnet set on the interface over which the echo packets
-are sent. Also, it must not be any VPP-local address, otherwise the packet
-gets dropped on receipt by VPP. The solution is to create a loopback interface
-with a (private) IPv4/IPv6 subnet assigned as echo-source. The BFD then picks
-an unused address from the subnet by flipping the last bit and uses that as
-source address in the echo packets, thus meeting RFC recommendation while
-avoiding spoofing protection.
-
-Example: if 10.10.10.3/31 is the subnet, then 10.10.10.2 will be used as
-         source address in (IPv4) echo packets
-
-### Demand mode
-
-Demand mode is respected by VPP, but not used locally. The only scenario when
-demand mode could make sense currently is when echo is active. Because echo
-packets are inherently insecure against an adversary looping them back a poll
-sequence would be required for slow periodic connectivity verification anyway.
-It's more efficient to just ask the remote peer to send slow periodic control
-frames without VPP initiating periodic poll sequences.
-
-### Admin-down
-
-Session may be put admin-down at any time. This immediately causes the state
-to be changed to AdminDown and remain so unless the session is put admin-up.
-
-## BFD implementation notes
-
-Because BFD can work over different transport layers, the BFD code is separated
-into core BFD functionality - main module implemented in bfd_main.c
-and transport-specific code implemented in bfd_udp.c.
-
-### Main module
-
-Main module is responsible for handling all the BFD functionality defined
-in RFC 5880.
-
-#### Internal API
-
-Internal APIs defined in bfd_main.h are called from transport-specific code
-to create/modify/delete
-
-#### Packet receipt
-
-When a packet is received by the transport layer, it is forwarded to main
-module (to main thread) via an RPC call. At this point, the authentication has
-been verified, so the packet is consumed, session parameters are updated
-accordingly and state change (if applicable). Based on these, the timeouts
-are adjusted if required and an event is sent to the process node to wake up
-and recalculate sleep time.
-
-#### Packet transmit
-
-Main module allocates a vlib_buffer_t, creates the required BFD frame (control
-or echo in it), then calls the transport layer to add the transport layer.
-Then a frame containing the buffer to the aprropriate node is created
-and enqueued.
-
-#### Process node
-
-Main module implements one process node which is a simple loop. The process
-node gets next timeout from the timer wheel, sleeps until the timeout expires
-and then calls a timeout routine which drives the state machine for each
-session which timed out. The sleep is interrupted externally via vlib event,
-when a session is added or modified in a way which might require timer wheel
-manipulation. In this case the caller inserts the necessary timeout to timer
-wheel and then signals the process node to wake up early, handle possible
-timeouts and recalculate the sleep time again.
-
-#### State machine
-
-Default state of BFD session when created is Down, per RFC 5880. State changes
-to Init, Up or Down based on events like received state from peer and timeouts.
-The session state can be set AdminDown using a binary API, which prevents it
-from going to any other state, until this limitation is removed. This state
-is advertised to peers in slow periodic control frames.
-
-For each session, the following timeouts are maintained:
-
-1. tx timeout - used for sending out control frames
-2. rx timeout - used for detecting session timeout
-3. echo tx timeout - used for sending out echo frames
-3. echo rx timeout - used for detecting session timeout based on echo
-
-These timeouts are maintained in cpu clocks and recalculated when appropriate
-(e.g. rx timeout is bumped when a packet is received, keeping the session
-alive). Only the earliest timeout is inserted into the timer wheel at a time
-and timer wheel events are never deleted, rather spurious events are ignored.
-This allows efficient operation, like not inserting events into timing wheel
-for each packet received or ignoring left-over events in case a bfd session
-gets removed and a new one is recreated with the same session index.
-
-#### Authentication keys management
-
-Authentication keys are managed internally in a pool, with each key tracking
-it's use count. The removal/modification is only allowed if the key is not in
-use.
-
-### UDP module
-
-UDP module is responsible for:
-
-1. public APIs/CLIs to configure BFD over UDP.
-2. support code called by main module to encapsulate/decapsulate BFD packets
-
-This module implements two graph nodes - for consuming ipv4 and ipv6 packets
-target at BFD ports 3874 and 3875.
-
-#### Packet receipt
-
-BFD packet receipt receipt starts in the bfd udp graph nodes. Since the code
-needs to verify IP/UDP header data, it relies on ip4-local (and ip6-local)
-nodes to store pointers to the appropriate headers. First, your discriminator
-is extracted from BFD packet and used to lookup the existing session. In case
-it's zero, the pair of IP addresses and sw_if_index is used to lookup session.
-Then, main module is called to verify the authentication, if present.
-Afterwards a check is made if the IP/UDP headers are correct. If yes, then
-an RPC call is made to the main thread to consume the packet and take action
-upon it.
-
-#### Packet transmission
-
-When process node decides that there is a need to transmit the packet, it
-creates a buffer, fills the BFD frame data in and calls the UDP module to
-add the transport layer. This is a simple operation for the control frames
-consisting of just adding UDP/IP headers based on session data. For echo
-frames, an additional step, looking at the echo-source interface and picking
-and address is performed and if this fails, then the packet cannot be
-transmitted and an error is returned to main thread.