summaryrefslogtreecommitdiffstats
path: root/src/plugins/dhcp
diff options
context:
space:
mode:
authorNathan Skrzypczak <nathan.skrzypczak@gmail.com>2021-10-08 14:05:35 +0200
committerDave Wallace <dwallacelf@gmail.com>2021-10-13 23:22:20 +0000
commitf47122e07e1ecd0151902a3cabe46c60a99bee8e (patch)
tree0c28c0eca2cb17050d6f31fd8f0ca8f78299bf0d /src/plugins/dhcp
parent1e4281223ab4d655b54496ae13fbdb68f867e351 (diff)
docs: convert plugins doc md->rst
Type: improvement Change-Id: I7e821cce1feae229e1be4baeed249b9cca658135 Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com>
Diffstat (limited to 'src/plugins/dhcp')
-rw-r--r--src/plugins/dhcp/dhcp6_pd_doc.md86
-rw-r--r--src/plugins/dhcp/dhcp6_pd_doc.rst113
2 files changed, 113 insertions, 86 deletions
diff --git a/src/plugins/dhcp/dhcp6_pd_doc.md b/src/plugins/dhcp/dhcp6_pd_doc.md
deleted file mode 100644
index 0d0e0865f1b..00000000000
--- a/src/plugins/dhcp/dhcp6_pd_doc.md
+++ /dev/null
@@ -1,86 +0,0 @@
-# DHCPv6 prefix delegation {#dhcp6_pd_doc}
-
-DHCPv6 prefix delegation client implementation is split between Control Plane and Data Plane.
-Data Plane can also be used alone by external application (external Control Plane) using Data Plane Binary API.
-
-Number of different IA\_PDs managed by VPP is currently limited to 1 (and corresponding IAID has value 1).
-Client ID is of type DUID-LLT (Link Layer address plus time) and is created on VPP startup from avaliable interfaces (or chosen at random for debugging purposes).
-Server ID is only visible to Data Plane. Control Plane identifies servers by a 32-bit handle (server\_index) mapped to Server ID by Data Plane.
-
-## Control Plane
-
-DHCPv6 PD clients are configured per interface.
-When configuring a PD client we have to choose a name of a prefix group for that client.
-Each prefix obtained through this client will be flagged as belonging to specified prefix group.
-The prefix groups are used as a filter by prefix consumers.
-
-To enable client on particular interface call Binary API function dhcp6\_pd\_client\_enable\_disable with param 'sw\_if\_index' set to that interface,
-'prefix\_group' set to prefix group name and 'enable' set to true.
-Format of corresponding Debug CLI command is: "dhcp6 pd client <interface> [disable]"
-
-To add/delete IPv6 address potentially using available prefix from specified prefix group call Binary API command ip6\_add\_del\_address\_using\_prefix with parameters:
-> sw\_if\_index - software interface index of interface to add/delete address to/from
-> prefix\_group - name of prefix group, prefix\_group[0] == '\0' means no prefix should be used
-> address - address or suffix to be used with a prefix from selected group
-> prefix\_length - subnet prefix for the address
-> is\_add - 1 for add, 0 for remove
-or Debug CLI command with format: "set ip6 addresses <interface> [prefix group <n>] <address> [del]"
-
-When no prefix is avaliable, no address is physically added, but is added once a prefix becomes avaliable.
-Address is removed when all available prefixes are removed.
-When a used prefix is removed and there is other available prefix, the address that used the prefix is reconfigured using the available prefix.
-
-There are three debug CLI commands (with no parameters) used to show the state of clients, prefixes and addresses:
- show ip6 pd clients
- show ip6 prefixes
- show ip6 addresses
-
-### Example configuration
-
-set int state GigabitEthernet0/8/0 up
-dhcp6 pd client GigabitEthernet0/8/0 prefix group my-dhcp6-pd-group
-set ip6 address GigabitEthernet0/8/0 prefix group my-dhcp6-pd-group ::7/64
-
-## Data Plane
-
-First API message to be called is dhcp6\_clients\_enable\_disable with enable parameter set to 1.
-It enables DHCPv6 client subsystem to receive UDP messages containing DHCPv6 client port (sets the router to DHCPv6 client mode).
-This is to ensure client subsystem gets the messages instead of DHCPv6 proxy subsystem.
-
-There is one common Binary API call for sending DHCPv6 client messages (dhcp6\_pd\_send\_client\_message) with these fields:
-> msg\_type - message type (e.g. Solicit)
-> sw\_if\_index - index of TX interface
-> server\_index - used to dentify DHCPv6 server,
- unique for each DHCPv6 server on the link,
- value obrtained from dhcp6\_pd\_reply\_event API message,
- use ~0 to send message to all DHCPv6 servers
-> param irt - initial retransmission time
-> param mrt - maximum retransmission time
-> param mrc - maximum retransmission count
-> param mrd - maximum retransmission duration for sending the message
-> stop - if non-zero then stop resending the message, otherwise start sending the message
-> T1 - value of T1 in IA\_PD option
-> T2 - value of T2 in IA\_PD option
-> prefixes - list of prefixes in IA\_PD option
-
-The message is automatically resent by Data Plane based on parameters 'irt', 'mrt', 'mrc' and 'mrd'.
-To stop the resending call the same function (same msg\_type is sufficient) with 'stop' set to 1.
-
-To subscribe for notifications of DHCPv6 messages from server call Binary API function
-want\_dhcp6\_pd\_reply\_events with enable\_disable set to 1
-Notification (dhcp6\_pd\_reply\_event) fileds are:
-> sw\_if\_index - index of RX interface
-> server\_index - used to dentify DHCPv6 server, unique for each DHCPv6 server on the link
-> msg\_type - message type
-> T1 - value of T1 in IA\_PD option
-> T2 - value of T2 in IA\_PD option
-> inner\_status\_code - value of status code inside IA\_PD option
-> status\_code - value of status code
-> preference - value of preference option in reply message
-> prefixes - list of prefixes in IA\_PD option
-
-Prefix is a struct with with these fields:
-> prefix - prefix bytes
-> prefix\_length - prefix length
-> valid\_time - valid lifetime
-> preferred\_time - preferred lifetime
diff --git a/src/plugins/dhcp/dhcp6_pd_doc.rst b/src/plugins/dhcp/dhcp6_pd_doc.rst
new file mode 100644
index 00000000000..349abe215e1
--- /dev/null
+++ b/src/plugins/dhcp/dhcp6_pd_doc.rst
@@ -0,0 +1,113 @@
+DHCPv6 prefix delegation
+========================
+
+| DHCPv6 prefix delegation client implementation is split between
+ Control Plane and Data Plane.
+| Data Plane can also be used alone by external application (external
+ Control Plane) using Data Plane Binary API.
+
+| Number of different IA_PDs managed by VPP is currently limited to 1
+ (and corresponding IAID has value 1).
+| Client ID is of type DUID-LLT (Link Layer address plus time) and is
+ created on VPP startup from avaliable interfaces (or chosen at random
+ for debugging purposes).
+| Server ID is only visible to Data Plane. Control Plane identifies
+ servers by a 32-bit handle (server_index) mapped to Server ID by Data
+ Plane.
+
+Control Plane
+-------------
+
+| DHCPv6 PD clients are configured per interface.
+| When configuring a PD client we have to choose a name of a prefix
+ group for that client.
+| Each prefix obtained through this client will be flagged as belonging
+ to specified prefix group.
+| The prefix groups are used as a filter by prefix consumers.
+
+| To enable client on particular interface call Binary API function
+ dhcp6_pd_client_enable_disable with param ‘sw_if_index’ set to that
+ interface, ‘prefix_group’ set to prefix group name and ‘enable’ set to
+ true.
+| Format of corresponding Debug CLI command is: “dhcp6 pd client
+ [disable]”
+
+To add/delete IPv6 address potentially using available prefix from
+specified prefix group call Binary API command
+ip6_add_del_address_using_prefix with parameters:
+> sw_if_index - software interface index of interface to add/delete
+address to/from > prefix_group - name of prefix group, prefix_group[0]
+== ‘\\0’ means no prefix should be used > address - address or suffix to
+be used with a prefix from selected group > prefix_length - subnet
+prefix for the address > is_add - 1 for add, 0 for remove or Debug CLI
+command with format: “set ip6 addresses [prefix group ]
+
+.. raw:: html
+
+ <address>
+
+[del]”
+
+| When no prefix is avaliable, no address is physically added, but is
+ added once a prefix becomes avaliable.
+| Address is removed when all available prefixes are removed.
+| When a used prefix is removed and there is other available prefix, the
+ address that used the prefix is reconfigured using the available
+ prefix.
+
+| There are three debug CLI commands (with no parameters) used to show
+ the state of clients, prefixes and addresses:
+| show ip6 pd clients
+| show ip6 prefixes
+| show ip6 addresses
+
+Example configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+set int state GigabitEthernet0/8/0 up dhcp6 pd client
+GigabitEthernet0/8/0 prefix group my-dhcp6-pd-group set ip6 address
+GigabitEthernet0/8/0 prefix group my-dhcp6-pd-group ::7/64
+
+Data Plane
+----------
+
+| First API message to be called is dhcp6_clients_enable_disable with
+ enable parameter set to 1.
+| It enables DHCPv6 client subsystem to receive UDP messages containing
+ DHCPv6 client port (sets the router to DHCPv6 client mode).
+| This is to ensure client subsystem gets the messages instead of DHCPv6
+ proxy subsystem.
+
+| There is one common Binary API call for sending DHCPv6 client messages
+ (dhcp6_pd_send_client_message) with these fields:
+| > msg_type - message type (e.g. Solicit) > sw_if_index - index of TX
+ interface > server_index - used to dentify DHCPv6 server, unique for
+ each DHCPv6 server on the link, value obrtained from
+ dhcp6_pd_reply_event API message, use ~0 to send message to all DHCPv6
+ servers > param irt - initial retransmission time > param mrt -
+ maximum retransmission time > param mrc - maximum retransmission count
+ > param mrd - maximum retransmission duration for sending the message
+ > stop - if non-zero then stop resending the message, otherwise start
+ sending the message > T1 - value of T1 in IA_PD option > T2 - value of
+ T2 in IA_PD option > prefixes - list of prefixes in IA_PD option
+
+| The message is automatically resent by Data Plane based on parameters
+ ‘irt’, ‘mrt’, ‘mrc’ and ‘mrd’.
+| To stop the resending call the same function (same msg_type is
+ sufficient) with ‘stop’ set to 1.
+
+| To subscribe for notifications of DHCPv6 messages from server call
+ Binary API function
+| want_dhcp6_pd_reply_events with enable_disable set to 1
+| Notification (dhcp6_pd_reply_event) fileds are:
+| > sw_if_index - index of RX interface > server_index - used to dentify
+ DHCPv6 server, unique for each DHCPv6 server on the link > msg_type -
+ message type > T1 - value of T1 in IA_PD option > T2 - value of T2 in
+ IA_PD option > inner_status_code - value of status code inside IA_PD
+ option > status_code - value of status code > preference - value of
+ preference option in reply message > prefixes - list of prefixes in
+ IA_PD option
+
+| Prefix is a struct with with these fields:
+| > prefix - prefix bytes > prefix_length - prefix length > valid_time -
+ valid lifetime > preferred_time - preferred lifetime