src/plugins/dhcp/dhcp6_pd_doc.rst

   1 DHCPv6 prefix delegation
   2 ========================
   3
   4 | DHCPv6 prefix delegation client implementation is split between
   5   Control Plane and Data Plane.
   6 | Data Plane can also be used alone by external application (external
   7   Control Plane) using Data Plane Binary API.
   8
   9 | Number of different IA_PDs managed by VPP is currently limited to 1
  10   (and corresponding IAID has value 1).
  11 | Client ID is of type DUID-LLT (Link Layer address plus time) and is
  12   created on VPP startup from avaliable interfaces (or chosen at random
  13   for debugging purposes).
  14 | Server ID is only visible to Data Plane. Control Plane identifies
  15   servers by a 32-bit handle (server_index) mapped to Server ID by Data
  16   Plane.
  17
  18 Control Plane
  19 -------------
  20
  21 | DHCPv6 PD clients are configured per interface.
  22 | When configuring a PD client we have to choose a name of a prefix
  23   group for that client.
  24 | Each prefix obtained through this client will be flagged as belonging
  25   to specified prefix group.
  26 | The prefix groups are used as a filter by prefix consumers.
  27
  28 | To enable client on particular interface call Binary API function
  29   dhcp6_pd_client_enable_disable with param ‘sw_if_index’ set to that
  30   interface, ‘prefix_group’ set to prefix group name and ‘enable’ set to
  31   true.
  32 | Format of corresponding Debug CLI command is: “dhcp6 pd client
  33   [disable]”
  34
  35 To add/delete IPv6 address potentially using available prefix from
  36 specified prefix group call Binary API command
  37 ip6_add_del_address_using_prefix with parameters:
  38 > sw_if_index - software interface index of interface to add/delete
  39 address to/from > prefix_group - name of prefix group, prefix_group[0]
  40 == ‘\\0’ means no prefix should be used > address - address or suffix to
  41 be used with a prefix from selected group > prefix_length - subnet
  42 prefix for the address > is_add - 1 for add, 0 for remove or Debug CLI
  43 command with format: “set ip6 addresses [prefix group ]
  44
  45 .. raw:: html
  46
  47    <address>
  48
  49 [del]”
  50
  51 | When no prefix is avaliable, no address is physically added, but is
  52   added once a prefix becomes avaliable.
  53 | Address is removed when all available prefixes are removed.
  54 | When a used prefix is removed and there is other available prefix, the
  55   address that used the prefix is reconfigured using the available
  56   prefix.
  57
  58 | There are three debug CLI commands (with no parameters) used to show
  59   the state of clients, prefixes and addresses:
  60 | show ip6 pd clients
  61 | show ip6 prefixes
  62 | show ip6 addresses
  63
  64 Example configuration
  65 ~~~~~~~~~~~~~~~~~~~~~
  66
  67 set int state GigabitEthernet0/8/0 up dhcp6 pd client
  68 GigabitEthernet0/8/0 prefix group my-dhcp6-pd-group set ip6 address
  69 GigabitEthernet0/8/0 prefix group my-dhcp6-pd-group ::7/64
  70
  71 Data Plane
  72 ----------
  73
  74 | First API message to be called is dhcp6_clients_enable_disable with
  75   enable parameter set to 1.
  76 | It enables DHCPv6 client subsystem to receive UDP messages containing
  77   DHCPv6 client port (sets the router to DHCPv6 client mode).
  78 | This is to ensure client subsystem gets the messages instead of DHCPv6
  79   proxy subsystem.
  80
  81 | There is one common Binary API call for sending DHCPv6 client messages
  82   (dhcp6_pd_send_client_message) with these fields:
  83 | > msg_type - message type (e.g. Solicit) > sw_if_index - index of TX
  84   interface > server_index - used to dentify DHCPv6 server, unique for
  85   each DHCPv6 server on the link, value obrtained from
  86   dhcp6_pd_reply_event API message, use ~0 to send message to all DHCPv6
  87   servers > param irt - initial retransmission time > param mrt -
  88   maximum retransmission time > param mrc - maximum retransmission count
  89   > param mrd - maximum retransmission duration for sending the message
  90   > stop - if non-zero then stop resending the message, otherwise start
  91   sending the message > T1 - value of T1 in IA_PD option > T2 - value of
  92   T2 in IA_PD option > prefixes - list of prefixes in IA_PD option
  93
  94 | The message is automatically resent by Data Plane based on parameters
  95   ‘irt’, ‘mrt’, ‘mrc’ and ‘mrd’.
  96 | To stop the resending call the same function (same msg_type is
  97   sufficient) with ‘stop’ set to 1.
  98
  99 | To subscribe for notifications of DHCPv6 messages from server call
 100   Binary API function
 101 | want_dhcp6_pd_reply_events with enable_disable set to 1
 102 | Notification (dhcp6_pd_reply_event) fileds are:
 103 | > sw_if_index - index of RX interface > server_index - used to dentify
 104   DHCPv6 server, unique for each DHCPv6 server on the link > msg_type -
 105   message type > T1 - value of T1 in IA_PD option > T2 - value of T2 in
 106   IA_PD option > inner_status_code - value of status code inside IA_PD
 107   option > status_code - value of status code > preference - value of
 108   preference option in reply message > prefixes - list of prefixes in
 109   IA_PD option
 110
 111 | Prefix is a struct with with these fields:
 112 | > prefix - prefix bytes > prefix_length - prefix length > valid_time -
 113   valid lifetime > preferred_time - preferred lifetime