MANUAL.TXT

   1 NDPROXY(4)             FreeBSD Kernel Interfaces Manual             NDPROXY(4)
   2
   3 NAME
   4      ndproxy -- Neighbor Discovery Proxy
   5
   6 SYNOPSIS
   7      ndproxy is a kernel module that implements IPv6 Neighbor Discovery proxy-
   8      ing over Ethernet-like access networks, with many options to handle sev-
   9      eral use-cases.
  10
  11      ndproxy replies to a neighbor solicitation with a specific neighbor ad-
  12      vertisement, in order to let the PE uplink router send further packets to
  13      a CPE downlink router, that may or may not be the same node that run nd-
  14      proxy.
  15
  16      The hook-based pfil(9) framework is used to let ndproxy be invoked for
  17      every IPv6 incoming packet, in order to specifically handle and filter
  18      neighbor solicitations and reply with appropriate neighbor advertise-
  19      ments.
  20
  21      ND (Neighbor Discovery) packets are mainly targeted at solicited-node
  22      multicast addresses, but ndproxy has no information about the hosts to
  23      proxy, then it can not join the corresponding groups. Thus, the interface
  24      on which ndproxy listen to solicitations must be put into permanently
  25      promiscuous mode: add "promisc" to the ifconfig_<interface> variable in
  26      rc.conf(5).
  27
  28      For the same reason, MLD snooping must be disabled on the switches that
  29      share the PE/CPE interconnect (the layer-2 link the listening interface
  30      is attached to). Note that MLD snooping must not be disabled entirely on
  31      each switch, but only on the corresponding vlan.
  32
  33      The interface on which ndproxy listen to solicitations only need to be
  34      assigned a link-local address. No information about the delegated prefix
  35      and no global address are needed on this interface. It is sufficient to
  36      add "inet6 -ifdisabled -accept_rtadv auto_linklocal" to the ifconfig_<in-
  37      terface>_ipv6 variable in rc.conf(5).
  38
  39 DIFFERENCES WITH NDP
  40      The target address to proxy must be given when using the ndp(8) command-
  41      line tool with the proxy option. On the contrary, ndproxy does not rely
  42      on a list of target addresses to proxy. Thus, RFC-4941 temporary ad-
  43      dresses can be proxyfied. For security reasons, many operating systems
  44      use a temporary address when establishing outbound connections.
  45
  46      When using ndp(8) command-line tool with the proxy option, the proxyfied
  47      packets are redirected to the node that run ndp. With ndproxy, the host
  48      that run ndp can be used only to redirect packets to another IPv6 inter-
  49      nal router, for instance a dedicated router with hardware support of IPv6
  50      routing process.
  51
  52 PREFIX SUBNETTING
  53      Connecting a flat IPv6 network to the Internet is easily done with the
  54      RFC-4861 ND protocol. But connecting a subnetted IPv6 prefix is more com-
  55      plicated, depending on the ISP network design choices.  ndproxy can help
  56      subscribers to achieve this goal.
  57
  58      Here are some protocols or mechanisms the ISP need to support, when the
  59      delegated prefix must be subnetted and assigned to multiple links within
  60      the subscriber's network.  For instance, the ISP could learn routes from
  61      the subscriber router using an IGP routing protocol, but the ISP and the
  62      subscriber must agree with a common routing protocol.  The ISP could also
  63      feed the PE with a static route to the CPE router, but the ISP must be
  64      informed about the subscriber router address.  Finally, the ISP could use
  65      the RFC-3633 IPv6 Prefix Options with DHCPv6 to delegate the prefix from
  66      its PE router to a requesting subscriber's router: in such a case, the
  67      ISP must support the DHCPv6 option.
  68
  69      ndproxy has been written for subscribers to ISP that do not support any
  70      of those mechanisms or protocols, thus not being able to natively subnet
  71      their IPv6 delegated prefix.
  72
  73 NETWORK DESIGN
  74      Here is a generic network design using ndproxy to solve such situations:
  75         ______________________                 \
  76        /                      \                 \
  77        |   ISP core network   |                  \
  78        \__________ ___________/                   |
  79                   |                               | ISP network
  80                   | dsl to subscriber premises    |
  81                   |                              /
  82               +---+---------------------+       /
  83               |  PE or triple-play box  |      /
  84               +-----------+-------------+
  85                           |
  86       PE/CPE interconnect | /48 prefix         \
  87               --+---------+---------+--         \
  88                 |  no mld snooping  |            \
  89                 |                   |             |
  90            +----+--------+     +----+-----+       |
  91            |     CPE     |     | ndproxy  |       |
  92            | IPv6 router |     | BSD host |       |
  93            +----+---+----+     +----------+       |
  94        subnet1  |   |  subnet2                    | Subscriber
  95       ----+-----+- -+-----+------                 | network
  96           | /60           | /60                   |
  97       +---+------+   +----+-----+                 |
  98       |Subscriber|   |Subscriber|                /
  99       |  host    |   |  host    |               /
 100       +----------+   +----------+              /
 101
 102      Note that many other use-cases can be handled with ndproxy: the BSD host
 103      and the CPE router can be the same node, the delegated-prefix length can
 104      be /64, the PE router can have several interfaces on the ISP/Subscriber
 105      layer-2 boundary, there can be multiple PE routers, etc.
 106
 107 PREFIX LENGTH
 108      Even if the IESG and the IAB first recommended the allocations of /48
 109      prefixes in the general case, for the boundary between the public and the
 110      private topology (see RFC-3177), and that some Regional Internet Reg-
 111      istries (APNIC, ARIN and RIPE) have subsequently revised the end site as-
 112      signment policy to encourage the assignment of /56 blocks to end sites,
 113      and that RFC-6177 finally recommended giving home sites significantly
 114      more than a single /64, in order for home sites to be given multiple sub-
 115      nets, some ISP currently only delegate /64 prefixes.
 116
 117      In such a case, the subscriber should subnet a RFC-4193 Unique Local IPv6
 118      Unicast Addresses prefix to the internal subnetworks, for internal-to-in-
 119      ternal communications. The /64 global prefix should be routed to the only
 120      internal subnet in which RFC-4941 temporary addresses are used by hosts
 121      when establishing outbound connections. Static routes on the CPE router
 122      should be set to let hosts on other internal subnets be able to communi-
 123      cate with the Internet. Using temporary addresses for outbound connec-
 124      tions to the Internet must be disabled on hosts on those other internal
 125      subnets.
 126
 127 IPv6 EXTENSION HEADERS
 128      For security reasons, ndproxy explicitely rejects neighbor solicitation
 129      packets containing any extension header.  Such a packet is mainly unat-
 130      tended:
 131
 132      Fragmentation:
 133
 134                    According to RFC-6980, IPv6 fragmentation header is forbid-
 135                    den in all neighbor discovery messages.
 136
 137      Hop-by-hop header:
 138
 139                    commonly used for jumbograms or for MLD. Should not involve
 140                    neighbor solicitation packets.
 141
 142      Destination mobility headers:
 143
 144                    commonly used for mobility, ndproxy does not support these
 145                    headers.
 146
 147      Routing header:
 148
 149                    commonly used for mobility or source routing, ndproxy does
 150                    not support these headers.
 151
 152      AH & ESP headers:
 153
 154                    securing the neighbor discovery process is not done with
 155                    IPsec but with the SEcure Neighbor Discovery protocol
 156                    (RFC-3971). ndproxy can not support RFC-3971, since proxi-
 157                    fying ND packets is some kind of a spoofing process.
 158
 159 EXCEPTION ADDRESSES
 160      Some neigbhor solicitations sent on the PE/CPE interconnect must not be
 161      proxyfied:
 162
 163      1.   solicitations sent by other nodes than the PE;
 164
 165      2.   solicitations sent by the PE to reach any on-link address (the ad-
 166           dress filled in the target address option) owned by nodes attached
 167           to the PE/CPE interconnect, for instance to reach the CPE, the nd-
 168           proxy host or other hosts attached to this layer-2 interconnect.
 169
 170      The target addresses filled in those solicitations that ndproxy must ig-
 171      nore have to be declared via sysctl (net.inet6.ndproxyconf_excep-
 172      tion_ipv6_addresses). This list must contain the link-local and global-
 173      scoped unicast and anycast addresses of the CPE, of the ndproxy host and
 174      of any other host than the PE attached to the PE/CPE interconnect.
 175
 176      Failing to maintain this list correctly could lead to badly redirect some
 177      packets to the CPE, but with a simple network design, this list can be
 178      let empty.
 179
 180 UPLINK ROUTER ADDRESSES
 181      ndproxy only handles packets originating from one of the PE addresses.
 182      During its address resolution process, different source addresses can be
 183      choosen by the PE, depending on the packet that triggered the process or
 184      depending on other external constraints.
 185
 186      Here are some cases when it can occur:
 187
 188      1.   The PE may have multiple interfaces;
 189
 190      2.   There may be multiple PE;
 191
 192      3.   Many routers choose to use a link-local address when sending neigh-
 193           bor solicitations, but when an administrator of such a router, also
 194           having a global address assigned on the same link, tries to send
 195           packets (echo request, for instance) to an on-link destination
 196           global address, the source address of the echo request packet
 197           prompting the solicitation may be global-scoped according to the se-
 198           lection algorithm described in RFC-6724. Therefore, the source ad-
 199           dress of the Neighbor Solicitation packet should also be selected in
 200           the same global scope, according to RFC-4861;
 201
 202      4.   When the uplink router does not yet know its own address, it must
 203           use the unspecified address, according to RFC-4861.
 204
 205      So, it can not be assumed that an uplink router will always use the same
 206      IPv6 address to send neighbor solicitations. Each assigned address that
 207      can be used as a source address by the PE on its downlink interface must
 208      then be declared to ndproxy via sysctl (net.inet6.ndproxyconf_up-
 209      link_ipv6_addresses).
 210
 211      ndproxy will only handle packets that come from one of these addresses.
 212
 213      A special care must be taken about the unsolicited address. It may be
 214      used by the PE, then it is part of the list of PE addresses and should
 215      therefore be added to the list of PE addresses. Since this address can
 216      also be used by other nodes during some initialization steps (for in-
 217      stance when hot-swapping an Ethernet board), another node could use this
 218      address to send neighbor solicitations that ndproxy should not handle,
 219      because they are not sent by the PE. In fact, this is not a problem be-
 220      cause the target address option contained in a solicitation from this
 221      other node should be in the exception list. So, adding the unsolicited
 222      address in the PE addresses list should be safe.
 223
 224      Failing to maintain this list correctly could lead the PE not to be able
 225      to establish outbound connections to nodes on the PE/CPE interconnect,
 226      but if this list contains at least the PE link-local address, IPv6 con-
 227      nectivity should be correctly established between the Internet and the
 228      internal subscriber's subnets.
 229
 230 CONFIGURATION
 231      An IPv6 address can be any valid textual representation according to
 232      RFC-4291 and RFC-5952 (this means that transitional textual representa-
 233      tion is fully supported).  Other representations will trigger an error
 234      event. IPv6 address lists must be formated as series of IPv6 adresses
 235      separated by semi-colons.
 236
 237      The sysctl utility or rc.conf(5) are used to set ndproxy configuration
 238      parameters.
 239
 240      If you have installed ndproxy as a port or as a package, set the follow-
 241      ing variables in rc.conf(5) and load the module at boot time by placing
 242      the following line in rc.conf(5):
 243
 244            ndproxy_enable="YES"
 245
 246      On the contrary, if you have NOT installed ndproxy as a port or as a
 247      package but as a standalone distribution, place the sysctl entries in
 248      sysctl.conf(5) and load the module at boot time by placing the following
 249      line in loader.conf(5):
 250
 251            ndproxy_load="YES"
 252
 253      net.inet6.ndproxyconf_uplink_interface sysctl entry or
 254                    ndproxy_uplink_interface rc.conf variable:
 255
 256                    Name of the interface talking to the broadcast multi-access
 257                    network connecting the PE and CPE routers.
 258
 259                    Example: "vlan2".
 260
 261      net.inet6.ndproxyconf_downlink_mac_address sysctl entry or
 262                    ndproxy_downlink_mac_address rc.conf variable:
 263
 264                    MAC address of the CPE router. Neighbor advertisements sent
 265                    by ndproxy will be filled with this address in the target
 266                    link-layer address option. The format of this parameter is
 267                    the hexadecimal representation made of 6 groups of 2 hexa-
 268                    decimal numbers separated by colons.
 269
 270                    Example: "00:0C:29:B6:43:D5".
 271
 272      net.inet6.ndproxyconf_exception_ipv6_addresses sysctl entry or
 273                    ndproxy_exception_ipv6_addresses rc.conf variable:
 274
 275                    Target addresses not to proxy. In a simple network design,
 276                    this list can be let empty. See section "EXCEPTION AD-
 277                    DRESSES".
 278
 279                    Example:
 280                    "fe80::20d:edff:fe7b:68b7;fe80::222:15ff:fe3b:59a".
 281
 282      net.inet6.ndproxyconf_uplink_ipv6_addresses sysctl entry or
 283                    ndproxy_uplink_ipv6_addresses rc.conf variable:
 284
 285                    Addresses of the PE. This list should at least contain the
 286                    PE link-local address. See section "UPLINK ROUTER AD-
 287                    DRESSES".
 288
 289                    Example:
 290                    "fe80::207:cbff:fe4b:2d20;2a01:e35:8aae:bc60::1;::".
 291
 292      net.inet6.ndproxycount sysctl entry:
 293
 294                    Number of advertisements sent.
 295
 296 SEE ALSO
 297      inet6(4), rc.conf(5), loader.conf(5), sysctl.conf(5), sysctl(8),
 298      loader(8), pfil(9)
 299
 300 AUTHOR
 301      Alexandre Fenyo <alex@fenyo.net> - www.fenyo.net
 302
 303 FreeBSD 13.0                     May 27, 2017                     FreeBSD 13.0