blob: ac24ff1552410454383cc1f96e8fbbab7cc0ae84 [file] [log] [blame]
Wailok Shumbb7408b2021-09-30 22:41:32 +08001DHCP Relay
2==========
3
4.. tip::
5 We strongly recommend you to setup DHCP relay and configure the hosts to
6 **obtain address via DHCP**.
7
8 See `Alternative: Configure static IP`_ if you want to statically configure
9 IP address on each host.
10
11Overview
12--------
13The DHCP relay app used in SD-Fabric is an L3 relay.
14
15That is, it support relaying DHCP packets from/to a server that's not in the
16same subnet of the client.
17
18Here's a list of features supported:
19
20- DHCPv4 and DHCPv6
21
22- DHCP server directly attached to fabric leaves, or indirectly connected via
23 upstream router
24
25- DHCP client directly attached to fabric leaves, or indirectly connected via
26 `LDRA (Light-weight DHCP Relay Agent) <https://tools.ietf.org/html/rfc6221>`_
27
28- Multiple DHCP servers for HA
29
30.. note::
31 Please pay attention to the definition of **direct/indirect server/client**.
32 You will find them many times later in this section.
33
34Configure DHCP Relay
35--------------------
36
37Server directly connected to fabric
38^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
39
40.. image:: ../../images/config-dhcp.png
41
42In this case, the configuration involves first configuring the switch interface
43with the VLAN/subnet the DHCP service is part of.
44
45For example, if I have a switch ``of:205`` with a DHCP server on port 24 on
46VLAN 20, the port config looks like:
47
48.. code-block:: json
49
50 {
51 "ports": {
52 "of:0000000000000205/24" : {
53 "interfaces" : [ {
54 "name" : "dhcp-server-intf",
55 "ips" : [ "10.0.2.254/24", "2001:db8:1::254/64" ],
56 "vlan-tagged" : [ 20 ]
57 } ]
58 }
59 }
60 }
61
62A second part of the configuration for the DHCP relay app requires a json
63configuration under the key apps:
64
65.. code-block:: json
66
67 {
68 "apps" : {
69 "org.onosproject.dhcp-relay" : {
70 "default" : [
71 {
72 "dhcpServerConnectPoint": "of:0000000000000205/24",
73 "serverIps": ["10.0.2.253", "2001:db8:2::2"]
74 }
75 ]
76 }
77 }
78 }
79
80Note that the ``dhcprelay`` app is configured with location of the DHCP server (the
81switch port to which it is connected to the fabric).
82
83It is also configured with the DHCP server IP, but it is no longer necessary to
84configure the MAC address of the server.
85
86ONOS will automatically learn the MAC and VLAN corresponding to the ``serverIP``.
87
88
89Server reachable via external router
90^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
91In this case, it is actually the external router that is directly connected to
92the fabric.
93
94This external router is already configured in the ports section of
95network-config (for vRouter functionality).
96
97For example, if the external router is connected to switch ``of:205`` on port 1
98
99.. code-block:: json
100
101 {
102 "ports": {
103 "of:0000000000000205/1" : {
104 "interfaces" : [ {
105 "ips" : [ "192.168.101.2/30", "2000::c0a8:6402/120" ],
106 "mac" : "a2:9b:32:9d:7f:b3",
107 "name" : "internet-router"
108 } ]
109 }
110 }
111 }
112
113As before the ``ips`` and ``mac`` configured on port 1, actually correspond to
114the addresses configured in Quagga.
115
116The app config in this case, includes an additional field necessary to inform
117the ``dhcprelay`` app of the ``gatewayIP`` through which the DHCP server can be
118reached.
119
120.. code-block:: json
121
122 {
123 "apps" : {
124 "org.onosproject.dhcp-relay" : {
125 "default" : [
126 {
127 "dhcpServerConnectPoint": "of:0000000000000205/1",
128 "serverIps": ["10.0.2.253", "2001:db8:2::2"],
129 "gatewayIps": ["192.168.101.1", "1000::100:1"]
130 }
131 ]
132 }
133 }
134 }
135
136.. note::
137 Note that the ``dhcpserverConnectPoint`` should now be the switch port to
138 which the external router is connected to the fabric.
139
140Setup DHCP server
141-----------------
142
143Install DHCP server
144^^^^^^^^^^^^^^^^^^^
145
146Modern DHCP servers should support relayed DHCP request.
147However, the way to configure them are probably different case to case.
148Here we use **isc-dhcp-server** on Ubuntu as an example.
149To install the DHCP server, simply run:
150
151.. code-block:: console
152
153 $ sudo apt-get install isc-dhcp-server
154
155
156Configure DHCP Server
157^^^^^^^^^^^^^^^^^^^^^
158
159Two configuration files are required by DHCP server.
160
161First, we need to specify which network interface the DHCP server should listen on.
162To do that, we need to modify ``/etc/default/isc-dhcp-server`` and change the following line.
163
164.. code-block:: text
165
166 INTERFACES="eth1"
167
168Next, we need to specify the subnet we want to lease.
169To do that, we need to modify ``/etc/dhcp/dhcpd.conf`` and add the following lines.
170
171Note that the subnet of ``eth1`` needs to be included.
172
173Otherwise, the DHCP server will not listen to the interface even though we have
174specified that in ``/etc/default/isc-dhcp-server``.
175
176.. code-block:: text
177
178 subnet 10.0.1.0 netmask 255.255.255.0 {
179 range 10.0.1.1 10.0.1.240;
180 option routers 10.0.1.254;
181 }
182
183 # A subnet that matches the interface IP address is required by isc-dhcp-server
184 subnet 10.0.2.0 netmask 255.255.255.0 {
185 range 10.0.2.1 10.0.2.240;
186 option routers 10.0.2.254;
187 }
188
189It's similar to configure DHCPv6.
190
191.. code-block:: text
192
193 subnet6 2001:db8:1::/64 {
194 # Range for clients
195 range6 2001:db8:1::129 2001:db8:1::250;
196
197 # Range for clients requesting a temporary address
198 range6 2001:db8:1::/64 temporary;
199 }
200 # A subnet that matches the interface IP address is required by isc-dhcp-server
201 subnet6 2001:db8:2::/64 {
202 # Range for clients
203 range6 2001:db8:2::129 2001:db8:2::254;
204
205 # Range for clients requesting a temporary address
206 range6 2001:db8:2::/64 temporary;
207
208 # Prefix range for delegation to sub-routers
209 prefix6 2001:db8:1:: 2001:db8:10:: /56;
210
211 }
212
213Finally, restart the DHCP server.
214
215.. code-block:: console
216
217 $ sudo service isc-dhcp-server restart
218
219Testing
220-------
221
222The host should be able to obtain an IP address from the pool we specified.
223Try to run ``dhclient`` and see if the host can get an IP address.
224
225.. code-block:: console
226
227 sudo dhclient eth1
228
229It's similar to test DHCPv6
230
231.. code-block:: console
232
233 sudo dhclient -6 -N eth1 # for obtaining ip address
234 sudo dhclient -6 -P -N eth1 # for obtaining ip address and prefix together
235
236 sudo dhclient -6 -r eth1 # for releasing ip address
237 sudo dhclient -6 -P -r eth1 # for releasing prefix
238
239
240If something goes wrong, check ``/var/log/syslog`` for DHCP server log and run
241``tcpdump`` on DHCP server to see if the DHCP packets from the host reach the
242server correctly.
243
244Additional Features
245-------------------
246
247DHCP Relay store
248^^^^^^^^^^^^^^^^
249
250DHCP relay application stores information from DHCP packet which processed by
251the app, administrator can use CLI command ``dhcp-relay`` to query these
252information.
253
254The store provides these functionality:
255
256- Latest state of DHCP client (e.g. client location, last seen time, DHCP
257 type...), for debugging purpose
258
259- For direct host, ONOS can find location and VLAN from relay agent option,
260 however, for indirect host, ONOS need to query last state from the store to
261 find correct destination.
262
263
264DHCPv6 Relay counter
265^^^^^^^^^^^^^^^^^^^^
266There are two DHCPv6 packet counters which are Host basis counters and Global counters.
267
268Host basis counters count and record DHCPv6 packets received on this host.
269
270It can be displayed by ``dhcp-relay counter``. These counters can be reset by
271typing ``dhcp-relay counter reset``.
272
273.. code-block:: console
274
275 onos> dhcp-relay counter
276 DHCP Relay Counters :
277 Counters for id=00:AA:BB:00:00:01/None, locations=[of:0000000000000204/3]
278 SOLICIT ............................ 4 packets
279 REQUEST ............................ 4 packets
280 ADVERTISE ............................ 4 packets
281 RENEW ............................ 1000 packets
282 REPLY ............................ 1004 packets
283 Counters for id=00:AA:00:00:00:01/None, locations=[of:0000000000000205/3][D]
284 SOLICIT ............................ 2 packets
285 REQUEST ............................ 2 packets
286 ADVERTISE ............................ 2 packets
287 RENEW ............................ 500 packets
288 CONFIRM ............................ 2 packets
289 REPLY ............................ 500 packets
290
291 onos> dhcp-relay counter reset
292
293Global counters counts and records all DHCPv6 packets received in ONOS.
294
295It can be displayed by ``dhcp-relay-agg-counters``. These counters can be reset
296by typing ``dhcp-relay-agg-counters reset``.
297
298.. code-block:: console
299
300 onos> dhcp-relay-agg-counters
301 DHCP Relay Aggregate Counters :
302 SOLICIT ............................ 12 packets
303 REQUEST ............................ 12 packets
304 ADVERTISE ............................ 12 packets
305 REBIND ............................ 4 packets
306 RENEW ............................ 3026 packets
307 CONFIRM ............................ 4 packets
308 REPLY ............................ 3044 packets
309
310 onos> dhcp-relay-agg-counters reset
311
312
313Indirect client support
314^^^^^^^^^^^^^^^^^^^^^^^
315DHCP relay can support hosts which do not directly connect to SD-Fabric.
316
317These hosts usually connected to another LDRA, the LDRA will forward DHCP
318packet to/from SD-Fabric.
319
320For **DHCPv4**, packets from the LDRA includes a valid DHCP relay agent option
321(option 82).
322
323DHCP Relay application checks relay agent option and determine the DHCP packet
324comes from direct or indirect host.
325
326.. image:: ../../images/config-dhcp-indirect.jpg
327
328ONOS uses circuit id option in relay agent option with specific format if DHCP
329packet comes without relay agent option, the format of circuit will be:
330``ConnectPoint:VlanId``
331
332For example, the DHCP request/discover packet comes from
333``of:000000000000001/1`` with ``VLAN 100``, the circuit ONOS put will be
334``of:000000000000001/1:100`` and send DHCP packet to DHCP server.
335
336Indirect host won't put into host store. DHCP relay app will put IP address of
337indirect host to the route store, and use IP address of relay agent as next
338hop.
339
340**DHCPv6** clients will be handled similar to DHCPv4.
341
342One major difference is that DHCPv6 supports ``RELAY-FORWARD`` message type and
343``InterfaceId`` option natively, so we utilize those fields to encode
344information.
345
346Overwrite relay agent IP
347^^^^^^^^^^^^^^^^^^^^^^^^
348
349The DHCP relay can overwrite the relay agent address (``giaddr`` in **DHCPv4**,
350``link-addr`` in **DHCPv6**) in DHCP message for different device.
351
352If ``relayAgentIps`` is configured, the app will overwrite ``giaddr`` or
353``link-addr`` before it forward the DHCP message to the server.
354
355Otherwise, it will retain the original relay agent IP.
356
357An example configuration is shown below:
358
359.. code-block:: json
360
361 {
362 "apps" : {
363 "org.onosproject.dhcprelay" : {
364 "default": [{
365 "dhcpServerConnectPoint": "of:0000000000000002/2",
366 "serverIps": ["172.168.10.2", "2000::200:1"],
367 "gatewayIps": ["192.168.10.254", "1000::100:1"],
368 "relayAgentIps": {
369 "of:0000000000000001": {
370 "ipv4": "10.0.0.10",
371 "ipv6": "2000::10"
372 },
373 "of:0000000000000002": {
374 "ipv4": "10.0.1.10",
375 "ipv6": "2000::1:10"
376 }
377 }
378 }]
379 }
380 }
381 }
382
383
384Configure multiple servers
385^^^^^^^^^^^^^^^^^^^^^^^^^^
386
387DHCP server HA can be achieved by specifying additional server configuration
388objects.
389
390Client initiated packets like ``SOLICIT`` or ``REBIND`` shall be replicated and
391sent to all server objects.
392
393Below is an example of multiple server configuration:
394
395.. code-block:: json
396
397 {
398 "apps" : {
399 "org.onosproject.dhcprelay" : {
400 "default": [
401 {
402 "dhcpServerConnectPoint": "of:0000000000000205/5",
403 "serverIps": ["10.0.3.252", "2002:4::253"],
404 "gatewayIps": ["10.0.3.100","2001:3::100"],
405 "relayAgentIps": {
406 "of:0000000000000204": {
407 "ipv4": "10.0.2.254",
408 "ipv6": "2001:2::254"
409 }
410 }
411 },
412 {
413 "dhcpServerConnectPoint": "of:0000000000000206/3",
414 "serverIps": ["2002:5::253"],
415 "gatewayIps": ["2001:4::100"],
416 "relayAgentIps": {
417 "of:0000000000000204": {
418 "ipv4": "10.0.2.254",
419 "ipv6": "2001:2::254"
420 }
421 }
422 }
423 ],
424 "indirect": [
425 {
426 "dhcpServerConnectPoint": "of:0000000000000205/5",
427 "serverIps": ["10.0.3.252", "2002:4::253"],
428 "gatewayIps": ["10.0.3.100", "2001:3::100"],
429 "relayAgentIps": {
430 "of:0000000000000204": {
431 "ipv4": "10.0.2.254",
432 "ipv6": "2001:2::254"
433 }
434 }
435 },
436 {
437 "dhcpServerConnectPoint": "of:0000000000000205/5",
438 "serverIps": ["10.0.3.252", "2002:5::253"],
439 "gatewayIps": ["10.0.3.100", "2001:3::100"],
440 "relayAgentIps": {
441 "of:0000000000000204": {
442 "ipv4": "10.0.2.254",
443 "ipv6": "2001:2::254"
444 }
445 }
446 },
447 {
448 "dhcpServerConnectPoint": "of:0000000000000206/3",
449 "serverIps": ["2002:5::253"],
450 "gatewayIps": ["2001:4::100"],
451 "relayAgentIps": {
452 "of:0000000000000204": {
453 "ipv4": "10.0.2.254",
454 "ipv6": "2001:2::254"
455 }
456 }
457 },
458 {
459 "dhcpServerConnectPoint": "of:0000000000000206/3",
460 "serverIps": ["2002:4::253"],
461 "gatewayIps": ["2001:4::100"],
462 "relayAgentIps": {
463 "of:0000000000000204": {
464 "ipv4": "10.0.2.254",
465 "ipv6": "2001:2::254"
466 }
467 }
468 }
469 ]
470 }
471 }
472 }
473
474- ``dhcpServerConnectPoint``: represent the location of DHCP server
475
476- ``serverIps``: IP address of the DHCP server, contains at least one IP address of DHCP server.
477 IP address can be IPv4 or IPv6 for different version of DHCP.
478 Will use first address if multiple IPv4 or IPv6 address configured.
479
480- ``gatewayIps``: Optional. Should be configured if the DHCP server is not
481 directly connected to the SD-Fabric. It tells which gateway we need to
482 send to reach the server.
483
484.. note::
485 - If ``indirect`` server configuration is not configured, the app will use
486 ``default`` configuration for all cases.
487
488
489Ignoring DHCP relay on a particular VLAN
490^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
491
492In some cases, it may be necessary to avoid punting DHCP packets to the
493controller, and letting them be forwarded normally through the data plane.
494
495In such cases, the DHCP relay application can be configured to avoid punting
496DHCP packets on a particular VLAN on a particular switch.
497
498.. code-block:: json
499
500 {
501 "apps" : {
502 "org.onosproject.dhcprelay" : {
503 "ignoreDhcp" : [
504 { "deviceId": "of:0000000000000205", "vlan":24 },
505 { "deviceId": "of:0000000000000206", "vlan":24 }
506 ]
507 }
508 }
509 }
510
511In the example shown above, DHCP packets on VLAAN 24 are not punted to the
512controller from switches of:205 and of:206
513
514DHCPv6 Prefix Delegation (PD) Pushing
515^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
516
517.. note::
518 This feature requires both ``dhcprelay`` and ``fpm`` apps to be activated
519
520PD pushing allows IPv6 prefixes from DhcpRelay to be sent over the FPM
521connection to Quagga where they will be configured as a static route.
522
523Prior to PD Pushing, the FPM connection was only used by Quagga in one
524direction to push routes to FPM. PD pushing is disabled by default in DHCP
525Relay and FPM.
526
527To enable in DHCP relay:
528
529.. code-block:: console
530
531 onos> cfg set org.onosproject.dhcprelay.DhcpRelayManager DhcpFpmEnabled true
532
533To display PD's stored in DHCP relay, execute the following CLI command:
534
535.. code-block:: console
536
537 onos> dhcp-fpm-routes
538
539When PD pushing is enabled in FPM, by default the next-hop to be used for all
540prefixes pushed to Quagga will be retrieved from the first interface with
541``RUR`` in the name in ONOS.
542
543Next-hop may also be configured using FPM component config. This will override
544a ``RUR`` interface if present.
545
546If there is no interface with ``RUR`` in the name and the next-hop is not
547configured, no prefixes can be pushed to Quagga even if PD pushing is enabled.
548For DhcpRelay, only the IPv6 next-hop is needed.
549
550To enable in FPM:
551
552.. code-block:: console
553
554 onos> cfg set org.onosproject.routing.fpm.FpmManager pdPushNextHopIPv4 124.200.1.60
555 onos> cfg set org.onosproject.routing.fpm.FpmManager pdPushNextHopIPv6 2001:a08::2
556 onos> cfg set org.onosproject.routing.fpm.FpmManager pdPushEnabled true
557
558
559To verify that PD pushing is enabled:
560
561.. code-block:: console
562
563 onos> fpm-connections
564 PD Pushing is enabled.
565 peer 124.200.3.42:48640 connected to 127.0.0.1 since 2m23s ago * (2 routes locally)
566
567
568Prefixes pushed to Quagga can be displayed in ``vtysh`` using ``show ip route`` and ``show ipv6 route``.
569If the output is not as expected, check the Quagga log to see if it was received from FPM.
570
571.. note::
572 Quagga requires a patch to be able to receive Netlink Messages from FPM.
573
574Clean up expired address and PD prefix
575^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
576
577DHCPv6 relay cleans up stale IP address and pd prefix based on timer whose
578default interval is 24 hours (24 * 3600 secs = 86400 secs).
579
580If the preferred life time of ip address or pd prefix exceeds 1/2 of poll
581interval, they will be removed from ONOS.
582
583The poll interval can be modified by ``cfg set
584org.onosproject.dhcprelay.DhcpRelayManager dhcpPollInterval <newVal>``
585
586.. code-block:: console
587
588 onos> cfg get org.onosproject.dhcprelay.DhcpRelayManager
589 org.onosproject.dhcprelay.DhcpRelayManager
590 name=dhcpPollInterval, type=integer, value=86400, defaultValue=86400, description=dhcp relay poll interval
591
592 onos> cfg set org.onosproject.dhcprelay.DhcpRelayManager dhcpPollInterval 60
593
594 onos> cfg get org.onosproject.dhcprelay.DhcpRelayManager
595 org.onosproject.dhcprelay.DhcpRelayManager
596 name=dhcpPollInterval, type=integer, value=60, defaultValue=86400, description=dhcp relay poll interval
597
598
599Alternative: Configure static IP
600--------------------------------
601
602Although we strongly recommend to use `DHCP Relay`_ for IP assignment, it is
603also possible to statically configure the IP address and route on the host.
604
6051. **Configure the IP address and subnet mask**
606
607 Make sure the IP address and the subnet mask on the fabric network interface
608 of the host is consistent with the information in the Network Configuration
609 section. For example, you can run
610
611 .. code-block:: console
612
613 # ip addr add 10.0.0.1/24 dev mlx0
614
6152. **Configure the default route**
616
617 Make sure you change the default route of the host to the interface IP of
618 the leaf switch it connects to. For example, you can run
619
620 .. code-block:: console
621
622 # ip route add default via 10.0.0.254
623
624 .. note::
625 In the case that you want to keep default route through the management network,
626 you need to add routes to all other subnets in the network one by one.
627
6283. **Trigger host learning**
629
630 We need to let ONOS learn the host in order to program corresponding flows
631 and groups.
632
633 This is automatically done as part of the DHCP process.
634
635 However, we need to manually triggers it by sending an ARP or ND packet if
636 the host is configured to use static IP.
637
638 .. code-block:: console
639
640 # arping -c 1 ${GATEWAY_IP}
641
642 .. code-block:: console
643
644 # ndsend ${HOST_IP} ${INTF}
645
646Reference
647---------
648- https://www.cisco.com/c/en/us/support/docs/security/adaptive-security-appliance-asa-software/116265-configure-product-00.html