1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
|
// Copyright (C) 2011-2023 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
#ifndef IFACE_MGR_H
#define IFACE_MGR_H
#include <asiolink/io_address.h>
#include <dhcp/dhcp4.h>
#include <dhcp/dhcp6.h>
#include <dhcp/pkt4.h>
#include <dhcp/pkt6.h>
#include <dhcp/packet_queue_mgr4.h>
#include <dhcp/packet_queue_mgr6.h>
#include <dhcp/pkt_filter.h>
#include <dhcp/pkt_filter6.h>
#include <util/optional.h>
#include <util/watch_socket.h>
#include <util/watched_thread.h>
#include <boost/multi_index/hashed_index.hpp>
#include <boost/multi_index/mem_fun.hpp>
#include <boost/multi_index/sequenced_index.hpp>
#include <boost/multi_index_container.hpp>
#include <boost/noncopyable.hpp>
#include <boost/scoped_array.hpp>
#include <boost/shared_ptr.hpp>
#include <functional>
#include <list>
#include <vector>
#include <mutex>
namespace isc {
namespace dhcp {
/// @brief IfaceMgr exception thrown thrown when interface detection fails.
class IfaceDetectError : public Exception {
public:
IfaceDetectError(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief Exception thrown when it is not allowed to set new Packet Filter.
class PacketFilterChangeDenied : public Exception {
public:
PacketFilterChangeDenied(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief Exception thrown when a call to select is interrupted by a signal.
class SignalInterruptOnSelect : public Exception {
public:
SignalInterruptOnSelect(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief IfaceMgr exception thrown thrown when socket opening
/// or configuration failed.
class SocketConfigError : public Exception {
public:
SocketConfigError(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief IfaceMgr exception thrown thrown when error occurred during
/// reading data from socket.
class SocketReadError : public Exception {
public:
SocketReadError(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief IfaceMgr exception thrown thrown when error occurred during
/// sending data through socket.
class SocketWriteError : public Exception {
public:
SocketWriteError(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief IfaceMgr exception thrown when there is no suitable interface.
class IfaceNotFound : public Exception {
public:
IfaceNotFound(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief IfaceMgr exception thrown when there is no suitable socket found.
class SocketNotFound : public Exception {
public:
SocketNotFound(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) { };
};
/// @brief Represents a single network interface
///
/// Iface structure represents network interface with all useful
/// information, like name, interface index, MAC address and
/// list of assigned addresses
///
/// This class also holds the pointer to the socket read buffer.
/// Functions reading from the socket may utilize this buffer to store the
/// data being read from the socket. The advantage of using the
/// pre-allocated buffer is that the buffer is allocated only once, rather
/// than on every read. In addition, some OS specific code (e.g. BPF)
/// may require use of fixed-size buffers. The size of such a buffer is
/// returned by the OS kernel when the socket is opened. Hence, it is
/// convenient to allocate the buffer when the socket is being opened and
/// utilize it throughout the lifetime of the socket.
///
/// In order to avoid potentially expensive copies of the @c Iface objects
/// holding pre-allocated buffers and multiple containers, this class is
/// noncopyable.
class Iface : public boost::noncopyable {
public:
/// Maximum MAC address length (Infiniband uses 20 bytes)
static const unsigned int MAX_MAC_LEN = 20;
/// @brief Address type.
typedef util::Optional<asiolink::IOAddress> Address;
/// Type that defines list of addresses
typedef std::list<Address> AddressCollection;
/// @brief Type that holds a list of socket information.
///
/// @warning The type of the container used here must guarantee
/// that the iterators do not invalidate when erase() is called.
/// This is because, the \ref closeSockets function removes
/// elements selectively by calling erase on the element to be
/// removed and further iterates through remaining elements.
///
/// @todo: Add SocketCollectionConstIter type
typedef std::list<SocketInfo> SocketCollection;
/// @brief Type definition for a list of error messages
using ErrorBuffer = std::vector<std::string>;
/// @brief Iface constructor.
///
/// Creates Iface object that represents network interface.
///
/// @param name name of the interface
/// @param ifindex interface index (unique integer identifier)
/// @throw BadValue when name is empty.
Iface(const std::string& name, unsigned int ifindex);
/// @brief Destructor.
~Iface() { }
/// @brief Closes all open sockets on interface.
void closeSockets();
/// @brief Closes all IPv4 or IPv6 sockets.
///
/// This function closes sockets of the specific 'type' and closes them.
/// The 'type' of the socket indicates whether it is used to send IPv4
/// or IPv6 packets. The allowed values of the parameter are AF_INET and
/// AF_INET6 for IPv4 and IPv6 packets respectively. It is important
/// to realize that the actual types of sockets may be different than
/// AF_INET for IPv4 packets. This is because, historically the IfaceMgr
/// always used AF_INET sockets for IPv4 traffic. This is no longer the
/// case when the Direct IPv4 traffic must be supported. In order to support
/// direct traffic, the IfaceMgr operates on raw sockets, e.g. AF_PACKET
/// family sockets on Linux.
///
/// @todo Replace the AF_INET and AF_INET6 values with an enum
/// which will not be confused with the actual socket type.
///
/// @param family type of the sockets to be closed (AF_INET or AF_INET6)
///
/// @throw BadValue if family value is different than AF_INET or AF_INET6.
void closeSockets(const uint16_t family);
/// @brief Returns full interface name as "ifname/ifindex" string.
///
/// @return string with interface name
std::string getFullName() const;
/// @brief Returns link-layer address a plain text.
///
/// @return MAC address as a plain text (string)
std::string getPlainMac() const;
/// @brief Sets MAC address of the interface.
///
/// @param mac pointer to MAC address buffer
/// @param macLen length of mac address
void setMac(const uint8_t* mac, size_t macLen);
/// @brief Returns MAC length.
///
/// @return length of MAC address
size_t getMacLen() const { return mac_len_; }
/// @brief Returns pointer to MAC address.
///
/// Note: Returned pointer is only valid as long as the interface object
/// that returned it.
const uint8_t* getMac() const { return mac_; }
/// @brief Sets flag_*_ fields based on bitmask value returned by OS
///
/// @note Implementation of this method is OS-dependent as bits have
/// different meaning on each OS.
/// We need to make it 64 bits, because Solaris uses 64, not 32 bits.
///
/// @param flags bitmask value returned by OS in interface detection
void setFlags(uint64_t flags);
/// @brief Returns interface index.
///
/// @return interface index
unsigned int getIndex() const { return ifindex_; }
/// @brief Returns interface name.
///
/// @return interface name
std::string getName() const { return name_; };
/// @brief Sets up hardware type of the interface.
///
/// @param type hardware type
void setHWType(uint16_t type ) { hardware_type_ = type; }
/// @brief Returns hardware type of the interface.
///
/// @return hardware type
uint16_t getHWType() const { return hardware_type_; }
/// @brief Returns all addresses available on an interface.
///
/// The returned addresses are encapsulated in the @c util::Optional
/// class to be able to selectively flag some of the addresses as active
/// (when optional value is specified) or inactive (when optional value
/// is specified). If the address is marked as active, the
/// @c IfaceMgr::openSockets4 method will open socket and bind to this
/// address. Otherwise, it will not bind any socket to this address.
/// This is useful when an interface has multiple IPv4 addresses assigned.
///
/// Care should be taken to not use this collection after Iface object
/// ceases to exist. That is easy in most cases as Iface objects are
/// created by IfaceMgr that is a singleton an is expected to be
/// available at all time. We may revisit this if we ever decide to
/// implement dynamic interface detection, but such fancy feature would
/// mostly be useful for clients with wifi/vpn/virtual interfaces.
///
/// @return collection of addresses
const AddressCollection& getAddresses() const { return addrs_; }
/// @brief Returns IPv4 address assigned to the interface.
///
/// This function looks for an IPv4 address assigned to the interface
/// and returns it through the argument.
///
/// @param [out] address IPv4 address assigned to the interface.
///
/// @return Boolean value which informs whether IPv4 address has been found
/// for the interface (if true), or not (false).
bool getAddress4(isc::asiolink::IOAddress& address) const;
/// @brief Check if the interface has the specified address assigned.
///
/// @param address Address to be checked.
/// @return true if address is assigned to the interface, false otherwise.
bool hasAddress(const isc::asiolink::IOAddress& address) const;
/// @brief Adds an address to an interface.
///
/// This only adds an address to collection, it does not physically
/// configure address on actual network interface.
///
/// @param addr address to be added
void addAddress(const isc::asiolink::IOAddress& addr);
/// @brief Activates or deactivates address for the interface.
///
/// This method marks a specified address on the interface active or
/// inactive. If the address is marked inactive, the
/// @c IfaceMgr::openSockets4 method will NOT open socket for this address.
///
/// @param address An address which should be activated, deactivated.
/// @param active A boolean flag which indicates that the specified address
/// should be active (if true) or inactive (if false).
///
/// @throw BadValue if specified address doesn't exist for the interface.
void setActive(const isc::asiolink::IOAddress& address, const bool active);
/// @brief Activates or deactivates all addresses for the interface.
///
/// This method marks all addresses on the interface active or inactive.
/// If the address is marked inactive, the @c IfaceMgr::openSockets4
/// method will NOT open socket for this address.
///
/// @param active A boolean flag which indicates that the addresses
/// should be active (if true) or inactive (if false).
void setActive(const bool active);
/// @brief Returns a number of activated IPv4 addresses on the interface.
unsigned int countActive4() const;
/// @brief Deletes an address from an interface.
///
/// This only deletes address from collection, it does not physically
/// remove address configuration from actual network interface.
///
/// @param addr address to be removed.
///
/// @return true if removal was successful (address was in collection),
/// false otherwise
bool delAddress(const isc::asiolink::IOAddress& addr);
/// @brief Adds socket descriptor to an interface.
///
/// @param sock SocketInfo structure that describes socket.
void addSocket(const SocketInfo& sock) {
sockets_.push_back(sock);
}
/// @brief Closes socket.
///
/// Closes socket and removes corresponding SocketInfo structure
/// from an interface.
///
/// @param sockfd socket descriptor to be closed/removed.
/// @return true if there was such socket, false otherwise
bool delSocket(uint16_t sockfd);
/// @brief Returns collection of all sockets added to interface.
///
/// When new socket is created with @ref IfaceMgr::openSocket
/// it is added to sockets collection on particular interface.
/// If socket is opened by other means (e.g. function that does
/// not use @ref IfaceMgr::openSocket) it will not be available
/// in this collection. Note that functions like
/// @ref IfaceMgr::openSocketFromIface use
/// @ref IfaceMgr::openSocket internally.
/// The returned reference is only valid during the lifetime of
/// the IfaceMgr object that returned it.
///
/// @return collection of sockets added to interface
const SocketCollection& getSockets() const { return sockets_; }
/// @brief Removes any unicast addresses
///
/// Removes any unicast addresses that the server was configured to
/// listen on
void clearUnicasts() {
unicasts_.clear();
}
/// @brief Adds unicast the server should listen on
///
/// @throw BadValue if specified address is already defined on interface
/// @param addr unicast address to listen on
void addUnicast(const isc::asiolink::IOAddress& addr);
/// @brief Returns a container of addresses the server should listen on
///
/// @return address collection (may be empty)
const AddressCollection& getUnicasts() const {
return unicasts_;
}
/// @brief Returns the pointer to the buffer used for data reading.
///
/// The returned pointer is only valid during the lifetime of the
/// object which returns it or until the buffer is resized.
/// This function is meant to be used with socket API to gather
/// data from the socket.
///
/// @return Pointer to the first element of the read buffer or
/// NULL if the buffer is empty.
uint8_t* getReadBuffer() {
if (read_buffer_.empty()) {
return (0);
}
return (&read_buffer_[0]);
}
/// @brief Returns the current size of the socket read buffer.
size_t getReadBufferSize() const {
return (read_buffer_.size());
}
/// @brief Reallocates the socket read buffer.
///
/// @param new_size New size of the buffer.
void resizeReadBuffer(const size_t new_size) {
read_buffer_.resize(new_size);
}
/// @brief Add an error to the list of messages.
///
/// @param message the error message
void addError(std::string const& message);
/// @brief Clears all errors.
void clearErrors();
/// @brief Get the consistent list of error messages.
///
/// @return the list of messages
ErrorBuffer const& getErrors() const;
protected:
/// Socket used to send data.
SocketCollection sockets_;
/// Network interface name.
std::string name_;
/// Interface index (a value that uniquely identifies an interface).
unsigned int ifindex_;
/// List of assigned addresses.
AddressCollection addrs_;
/// List of unicast addresses the server should listen on
AddressCollection unicasts_;
/// Link-layer address.
uint8_t mac_[MAX_MAC_LEN];
/// Length of link-layer address (usually 6).
size_t mac_len_;
/// Hardware type.
uint16_t hardware_type_;
public:
/// @todo: Make those fields protected once we start supporting more
/// than just Linux
/// Specifies if selected interface is loopback.
bool flag_loopback_;
/// Specifies if selected interface is up.
bool flag_up_;
/// Flag specifies if selected interface is running
/// (e.g. cable plugged in, wifi associated).
bool flag_running_;
/// Flag specifies if selected interface is multicast capable.
bool flag_multicast_;
/// Flag specifies if selected interface is broadcast capable.
bool flag_broadcast_;
/// Interface flags (this value is as is returned by OS,
/// it may mean different things on different OSes).
/// Solaris based os have unsigned long flags field (64 bits).
/// It is usually 32 bits, though.
uint64_t flags_;
/// Indicates that IPv4 sockets should (true) or should not (false)
/// be opened on this interface.
bool inactive4_;
/// Indicates that IPv6 sockets should (true) or should not (false)
/// be opened on this interface.
bool inactive6_;
private:
/// @brief The buffer holding the data read from the socket.
///
/// See @c Iface manager description for details.
std::vector<uint8_t> read_buffer_;
/// @brief List of errors that occurred since the last attempt to open sockets
///
/// This list needs to always have a consistent view of the errors. They should all belong to
/// the same session of socket opening i.e. the same call to openSockets[46]. This is currently
/// ensured by openSockets[46] and all the places where these errors are being used i.e. the
/// status-get handler, being sequential.
ErrorBuffer errors_;
};
/// @brief Type definition for the pointer to an @c Iface object.
typedef boost::shared_ptr<Iface> IfacePtr;
/// @brief Collection of pointers to network interfaces.
class IfaceCollection {
public:
/// @brief Multi index container for network interfaces.
///
/// This container allows to search for a network interfaces using
/// three indexes:
/// - sequenced: used to access elements in the order they have
/// been added to the container.
/// - interface index: used to access an interface using its index.
/// - interface name: used to access an interface using its name.
/// Note that indexes and names are unique.
typedef boost::multi_index_container<
// Container comprises elements of IfacePtr type.
IfacePtr,
// Here we start enumerating various indexes.
boost::multi_index::indexed_by<
// Sequenced index allows accessing elements in the same way
// as elements in std::list. Sequenced is the index #0.
boost::multi_index::sequenced<>,
// Start definition of index #1.
boost::multi_index::hashed_unique<
// Use the interface index as the key.
boost::multi_index::const_mem_fun<
Iface, unsigned int, &Iface::getIndex
>
>,
// Start definition of index #2.
boost::multi_index::hashed_unique<
// Use the interface name as the key.
boost::multi_index::const_mem_fun<
Iface, std::string, &Iface::getName
>
>
>
> IfaceContainer;
/// @brief Begin iterator.
///
/// @return The container sequence begin iterator.
IfaceContainer::const_iterator begin() const {
return (ifaces_container_.begin());
}
/// @brief End iterator.
///
/// @return The container sequence end iterator.
IfaceContainer::const_iterator end() const {
return (ifaces_container_.end());
}
/// @brief Empty predicate.
///
/// @return If the container is empty true else false.
bool empty() const {
return (ifaces_container_.empty());
}
/// @brief Return the number of interfaces.
///
/// @return The container size.
size_t size() const {
return (ifaces_container_.size());
}
/// @brief Clear the collection.
void clear() {
cache_.reset();
ifaces_container_.clear();
}
/// @brief Adds an interface to the collection.
///
/// The interface is added at the end of sequence.
///
/// @param iface reference to Iface object.
void push_back(const IfacePtr& iface) {
ifaces_container_.push_back(iface);
}
/// @brief Lookup by interface index.
///
/// @param ifindex The index of the interface to find.
/// @return The interface with the index or null.
IfacePtr getIface(const unsigned int ifindex);
/// @brief Lookup by interface name.
///
/// @param ifname The name of the interface to find.
/// @return The interface with the name or null.
IfacePtr getIface(const std::string& ifname);
private:
/// @brief Lookup by interface index.
///
/// @param ifindex The index of the interface to find.
/// @param need_lock True when the cache operation needs to hold the mutex.
/// @return The interface with the index or null.
IfacePtr getIfaceInternal(const unsigned int ifindex, const bool need_lock);
/// @brief Lookup by interface name.
///
/// The mutex must be held when called from a packet processing thread.
///
/// @param ifname The name of the interface to find.
/// @param need_lock True when the cache operation needs to hold the mutex.
/// @return The interface with the name or null.
IfacePtr getIfaceInternal(const std::string& ifname, const bool need_lock);
/// @brief The mutex for protecting the cache from concurrent
/// access from packet processing threads.
std::mutex mutex_;
/// @brief The last interface returned by a lookup method.
///
/// A lookup method first tries the cache: if it matches the cache is
/// returned without an expensive lookup in the container. If it does
/// not match and a value is found in the container the cache is
/// updated with this value.
/// The cache should perform well when active interfaces are a small
/// subset of the whole interface set, or when consecutive packets
/// come from the same interface.
IfacePtr cache_;
/// @brief The container.
IfaceContainer ifaces_container_;
};
/// @brief Type definition for the unordered set of IPv4 bound addresses.
///
/// In order to make @c hasOpenSocket with an IPv4 address faster bound
/// addresses should be collected after calling @c CfgIface::openSockets.
typedef boost::multi_index_container<
/// Container comprises elements of asiolink::IOAddress type.
asiolink::IOAddress,
// Here we start enumerating the only index.
boost::multi_index::indexed_by<
// Start definition of index #0.
boost::multi_index::hashed_unique<
// Use the address in its network order integer form as the key.
boost::multi_index::const_mem_fun<
asiolink::IOAddress, uint32_t, &asiolink::IOAddress::toUint32
>
>
>
> BoundAddresses;
/// @brief Forward declaration to the @c IfaceMgr.
class IfaceMgr;
/// @brief Type definition for the pointer to the @c IfaceMgr.
typedef boost::shared_ptr<IfaceMgr> IfaceMgrPtr;
/// @brief This type describes the callback function invoked when error occurs
/// in the IfaceMgr.
///
/// @param errmsg An error message.
typedef
std::function<void(const std::string& errmsg)> IfaceMgrErrorMsgCallback;
/// @brief Handles network interfaces, transmission and reception.
///
/// IfaceMgr is an interface manager class that detects available network
/// interfaces, configured addresses, link-local addresses, and provides
/// API for using sockets.
///
class IfaceMgr : public boost::noncopyable {
public:
/// @brief Defines callback used when data is received over external sockets.
///
/// @param fd socket descriptor of the ready socket
typedef std::function<void (int fd)> SocketCallback;
/// @brief Defines callback used when detecting interfaces.
///
/// @param update_only Only add interfaces that do not exist and update
/// existing interfaces.
///
/// @return true if callback exited with no issue and @ref detectIfaces
/// should continue with specific system calls, false otherwise.
typedef std::function<bool (bool)> DetectCallback;
/// Keeps callback information for external sockets.
struct SocketCallbackInfo {
/// Socket descriptor of the external socket.
int socket_;
/// A callback that will be called when data arrives over socket_.
SocketCallback callback_;
};
/// Defines storage container for callbacks for external sockets
typedef std::list<SocketCallbackInfo> SocketCallbackInfoContainer;
/// @brief Packet reception buffer size
///
/// RFC 8415 states that server responses may be
/// fragmented if they are over MTU. There is no
/// text whether client's packets may be larger
/// than 1500. For now, we can assume that
/// we don't support packets larger than 1500.
static const uint32_t RCVBUFSIZE = 1500;
/// IfaceMgr is a singleton class. This method returns reference
/// to its sole instance.
///
/// @return the only existing instance of interface manager
static IfaceMgr& instance();
/// @brief Returns pointer to the sole instance of the interface manager.
///
/// This method returns the pointer to the instance of the interface manager
/// which can be held in singleton objects that depend on it. This will
/// eliminate issues with the static deinitialization fiasco between this
/// object and dependent singleton objects.
///
/// The @c IfaceMgr::instance method should be considered deprecated.
///
/// @return Shared pointer to the @c IfaceMgr instance.
static const IfaceMgrPtr& instancePtr();
/// @brief Destructor.
///
/// Closes open sockets.
virtual ~IfaceMgr();
/// @brief Sets or clears the test mode for @c IfaceMgr.
///
/// Various unit test may set this flag to true, to indicate that the
/// @c IfaceMgr is in the test mode. There are places in the code that
/// modify the behavior depending if the @c IfaceMgr is in the test
/// mode or not.
///
/// @param test_mode A flag which indicates that the @c IfaceMgr is in the
/// test mode (if true), or not (if false).
void setTestMode(const bool test_mode) {
test_mode_ = test_mode;
}
/// @brief Checks if the @c IfaceMgr is in the test mode.
///
/// @return true if the @c IfaceMgr is in the test mode, false otherwise.
bool isTestMode() const {
return (test_mode_);
}
/// @brief Allows or disallows the loopback interface
///
/// By default the loopback interface is not considered when opening
/// sockets. This flag provides a way to relax this constraint.
///
void setAllowLoopBack(const bool allow_loopback) {
allow_loopback_ = allow_loopback;
}
/// @brief Check if packet be sent directly to the client having no address.
///
/// Checks if IfaceMgr can send DHCPv4 packet to the client
/// who hasn't got address assigned. If this is not supported
/// broadcast address should be used to send response to
/// the client.
///
/// @return true if direct response is supported.
bool isDirectResponseSupported() const;
/// @brief Returns interface specified interface index
///
/// @param ifindex index of searched interface
///
/// @return interface with requested index (or null if no such
/// interface is present)
///
IfacePtr getIface(const unsigned int ifindex);
/// @brief Returns interface with specified interface name
///
/// @param ifname name of searched interface
///
/// @return interface with requested name (or null if no such
/// interface is present)
IfacePtr getIface(const std::string& ifname);
/// @brief Returns interface with specified packet
///
/// @note When the interface index is set (@c Pkt::indexSet
/// returns true) it is searched for, if it is not set
/// the name instead is searched for.
///
/// @param pkt packet with interface index and name
///
/// @return interface with packet interface index or name
/// (or null if no such interface is present)
IfacePtr getIface(const PktPtr& pkt);
/// @brief Returns container with all interfaces.
///
/// This reference is only valid as long as IfaceMgr is valid. However,
/// since IfaceMgr is a singleton and is expected to be destroyed after
/// main() function completes, you should not worry much about this.
///
/// @return container with all interfaces.
const IfaceCollection& getIfaces() { return (ifaces_); }
/// @brief Removes detected interfaces.
///
/// This method removes all detected interfaces. This method should be
/// used by unit tests to supply a custom set of interfaces. For example:
/// a unit test may create a pool of fake interfaces and use the custom
/// @c PktFilter class to mimic socket operation on these interfaces.
void clearIfaces();
/// @brief Set a callback to perform operations before executing specific
/// system calls.
///
/// @param cb The callback used before executing specific system calls.
void setDetectCallback(const DetectCallback& cb) {
detect_callback_ = cb;
}
/// @brief Check if the specific system calls used to detect interfaces
/// should be executed.
///
/// @param update_only Only add interfaces that do not exist and update
/// existing interfaces.
///
/// @return true if the specific system calls should be executed, false
/// otherwise causing the @ref detectIfaces to return immediately.
bool checkDetectIfaces(bool update_only);
/// @brief Detects network interfaces.
///
/// If the @ref detect_callback_ returns true, the specific system calls are
/// executed, otherwise the @ref detectIfaces will return immediately.
///
/// @param update_only Only add interfaces that do not exist and update
/// existing interfaces.
void detectIfaces(bool update_only = false);
/// @brief Clears unicast addresses on all interfaces.
void clearUnicasts();
/// @brief Clears the addresses all sockets are bound to.
void clearBoundAddresses();
/// @brief Collect the addresses all sockets are bound to.
void collectBoundAddresses();
/// @brief Return most suitable socket for transmitting specified IPv6 packet.
///
/// This method takes Pkt6Ptr (see overloaded implementation that takes
/// Pkt4Ptr) and chooses appropriate socket to send it. This method
/// may throw if specified packet does not have outbound interface specified,
/// no such interface exists, or specified interface does not have any
/// appropriate sockets open.
///
/// @param pkt a packet to be transmitted
///
/// @return a socket descriptor
/// @throw SocketNotFound If no suitable socket found.
/// @throw IfaceNotFound If interface is not set for the packet.
uint16_t getSocket(const isc::dhcp::Pkt6Ptr& pkt);
/// @brief Return most suitable socket for transmitting specified IPv4 packet.
///
/// This method uses the local address assigned to the packet and tries
/// to match it with addresses to which sockets are bound for the particular
/// interface. If the match is not found, the method returns the first IPv4
/// socket found for the particular interface. In case, there are no IPv4
/// sockets assigned to the interface the exception is thrown.
///
/// @param pkt A packet to be transmitted. It must hold a local address and
/// a valid pointer to the interface.
///
/// @return A structure describing a socket.
/// @throw SocketNotFound if no suitable socket found.
SocketInfo getSocket(const isc::dhcp::Pkt4Ptr& pkt);
/// Debugging method that prints out all available interfaces.
///
/// @param out specifies stream to print list of interfaces to
void printIfaces(std::ostream& out = std::cout);
/// @brief Sends an IPv6 packet.
///
/// Sends an IPv6 packet. All parameters for actual transmission are specified in
/// Pkt6 structure itself. That includes destination address, src/dst port
/// and interface over which data will be sent.
///
/// @param pkt packet to be sent
///
/// @throw isc::BadValue if invalid interface specified in the packet.
/// @throw isc::dhcp::SocketWriteError if sendmsg() failed to send packet.
/// @return true if sending was successful
bool send(const Pkt6Ptr& pkt);
/// @brief Sends an IPv4 packet.
///
/// Sends an IPv4 packet. All parameters for actual transmission are specified
/// in Pkt4 structure itself. That includes destination address, src/dst
/// port and interface over which data will be sent.
///
/// @param pkt a packet to be sent
///
/// @throw isc::BadValue if invalid interface specified in the packet.
/// @throw isc::dhcp::SocketWriteError if sendmsg() failed to send packet.
/// @return true if sending was successful
bool send(const Pkt4Ptr& pkt);
/// @brief Receive IPv4 packets or data from external sockets
///
/// Wrapper around calls to either @c receive4Direct or @c
/// receive4Indirect. The former is called when packet queueing is
/// disabled, the latter when it is enabled.
///
/// @param timeout_sec specifies integral part of the timeout (in seconds)
/// @param timeout_usec specifies fractional part of the timeout
/// (in microseconds)
///
/// @return Pkt4 object representing received packet (or null)
Pkt6Ptr receive6(uint32_t timeout_sec, uint32_t timeout_usec = 0);
/// @brief Receive IPv4 packets or data from external sockets
///
/// Wrapper around calls to either @c receive4Direct or @c
/// receive4Indirect. The former is called when packet queueing is
/// disabled, the latter when it is enabled.
///
/// @param timeout_sec specifies integral part of the timeout (in seconds)
/// @param timeout_usec specifies fractional part of the timeout
/// (in microseconds)
///
/// @return Pkt4 object representing received packet (or null)
Pkt4Ptr receive4(uint32_t timeout_sec, uint32_t timeout_usec = 0);
/// Opens UDP/IP socket and binds it to address, interface and port.
///
/// Specific type of socket (UDP/IPv4 or UDP/IPv6) depends on passed addr
/// family.
///
/// @param ifname name of the interface
/// @param addr address to be bound.
/// @param port UDP port.
/// @param receive_bcast configure IPv4 socket to receive broadcast
/// messages or IPv6 socket to join multicast group.
/// @param send_bcast configure IPv4 socket to send broadcast messages.
/// This parameter is ignored for IPv6 sockets.
///
/// Method will throw if socket creation, socket binding or multicast
/// join fails.
///
/// @return socket descriptor, if socket creation, binding and multicast
/// group join were all successful.
int openSocket(const std::string& ifname,
const isc::asiolink::IOAddress& addr,
const uint16_t port,
const bool receive_bcast = false,
const bool send_bcast = false);
/// @brief Opens UDP/IP socket and binds it to interface specified.
///
/// This method differs from \ref openSocket in that it does not require
/// the specification of a local address to which socket will be bound.
/// Instead, the method searches through the addresses on the specified
/// interface and selects one that matches the address family.
///
/// @note This method does not join the socket to the multicast group.
///
/// @param ifname name of the interface
/// @param port UDP port
/// @param family address family (AF_INET or AF_INET6)
/// @return socket descriptor, if socket creation and binding was
/// successful.
/// @throw isc::Unexpected if failed to create and bind socket.
/// @throw isc::BadValue if there is no address on specified interface
/// that belongs to given family.
int openSocketFromIface(const std::string& ifname,
const uint16_t port,
const uint8_t family);
/// @brief Opens UDP/IP socket and binds to address specified
///
/// This methods differs from \ref openSocket in that it does not require
/// the specification of the interface to which the socket will be bound.
///
/// @note This method does not join the socket to the multicast group.
///
/// @param addr address to be bound
/// @param port UDP port
/// @return socket descriptor, if socket creation and binding was
/// successful.
/// @throw isc::Unexpected if failed to create and bind socket
/// @throw isc::BadValue if specified address is not available on
/// any interface
int openSocketFromAddress(const isc::asiolink::IOAddress& addr,
const uint16_t port);
/// @brief Opens UDP/IP socket to be used to connect to remote address
///
/// This method identifies the local address to be used to connect to the
/// remote address specified as argument. Once the local address is
/// identified, \ref openSocket is called to open a socket and bind it to
/// the interface, address and port.
///
/// @note This method does not join the socket to a multicast group.
///
/// @param remote_addr remote address to connect to
/// @param port UDP port
/// @return socket descriptor, if socket creation and binding was
/// successful.
/// @throw isc::Unexpected if failed to create and bind socket
int openSocketFromRemoteAddress(const isc::asiolink::IOAddress& remote_addr,
const uint16_t port);
/// @brief Opens IPv6 sockets on detected interfaces.
///
/// This method opens sockets only on interfaces which have the
/// @c inactive6_ field set to false (are active). If the interface is active
/// but it is not running, it is down, or is a loopback interface when
/// loopback is not allowed, an error is reported.
///
/// If sockets were successfully opened, it calls @ startDHCPReceiver to
/// start the receiver thread (if packet queueing is enabled).
///
/// On the systems with multiple interfaces, it is often desired that the
/// failure to open a socket on a particular interface doesn't cause a
/// fatal error and sockets should be opened on remaining interfaces.
/// However, the warning about the failure for the particular socket should
/// be communicated to the caller. The libdhcp++ is a common library with
/// no logger associated with it. Most of the functions in this library
/// communicate errors via exceptions. In case of openSockets6 function
/// exception must not be thrown if the function is supposed to continue
/// opening sockets, despite an error. Therefore, if such a behavior is
/// desired, the error handler function can be passed as a parameter.
/// This error handler is called (if present) with an error string.
/// Typically, error handler will simply log an error using an application
/// logger, but it can do more sophisticated error handling too.
///
/// @todo It is possible that additional parameters will have to be added
/// to the error handler, e.g. Iface if it was really supposed to do
/// some more sophisticated error handling.
///
/// If the error handler is not installed (is null), the exception is thrown
/// for each failure (default behavior).
///
/// @warning This function does not check if there has been any sockets
/// already open by the @c IfaceMgr. Therefore a caller should call
/// @c IfaceMgr::closeSockets() before calling this function.
/// If there are any sockets open, the function may either throw an
/// exception or invoke an error handler on attempt to bind the new socket
/// to the same address and port.
///
/// @param port specifies port number (usually DHCP6_SERVER_PORT)
/// @param error_handler a pointer to an error handler function which is
/// called by the openSockets6 when it fails to open a socket. This
/// parameter can be null to indicate that the callback should not be used.
/// @param skip_opened skip the addresses that already have the opened port
///
/// @throw SocketOpenFailure if tried and failed to open socket.
/// @return true if any sockets were open
bool openSockets6(const uint16_t port = DHCP6_SERVER_PORT,
IfaceMgrErrorMsgCallback error_handler = 0,
const bool skip_opened = false);
/// @brief Opens IPv4 sockets on detected interfaces.
///
/// This method opens sockets only on interfaces which have the
/// @c inactive4_ field set to false (are active). If the interface is active
/// but it is not running, it is down, or is a loopback interface when
/// loopback is not allowed, an error is reported.
///
/// The type of the socket being open depends on the selected Packet Filter
/// represented by a class derived from @c isc::dhcp::PktFilter abstract
/// class.
///
/// If sockets were successfully opened, it calls @ startDHCPReceiver to
/// start the receiver thread (if packet queueing is enabled).
///
/// It is possible to specify whether sockets should be broadcast capable.
/// In most of the cases, the sockets should support broadcast traffic, e.g.
/// DHCPv4 server and relay need to listen to broadcast messages sent by
/// clients. If the socket has to be open on the particular interface, this
/// interface must have broadcast flag set. If this condition is not met,
/// the socket will be created in the unicast-only mode. If there are
/// multiple broadcast-capable interfaces present, they may be all open
/// in a broadcast mode only if the OS supports SO_BINDTODEVICE (bind socket
/// to a device) socket option. If this option is not supported, only the
/// first broadcast-capable socket will be opened in the broadcast mode.
/// The error will be reported for sockets being opened on other interfaces.
/// If the socket is bound to a device (interface), the broadcast traffic
/// sent to this interface will be received on this interface only.
/// This allows the DHCPv4 server or relay to detect the interface on which
/// the broadcast message has been received. This interface is later used
/// to send a response.
///
/// On the systems with multiple interfaces, it is often desired that the
/// failure to open a socket on a particular interface doesn't cause a
/// fatal error and sockets should be opened on remaining interfaces.
/// However, the warning about the failure for the particular socket should
/// be communicated to the caller. The libdhcp++ is a common library with
/// no logger associated with it. Most of the functions in this library
/// communicate errors via exceptions. In case of openSockets4 function
/// exception must not be thrown if the function is supposed to continue
/// opening sockets, despite an error. Therefore, if such a behavior is
/// desired, the error handler function can be passed as a parameter.
/// This error handler is called (if present) with an error string.
/// Typically, error handler will simply log an error using an application
/// logger, but it can do more sophisticated error handling too.
///
/// @todo It is possible that additional parameters will have to be added
/// to the error handler, e.g. Iface if it was really supposed to do
/// some more sophisticated error handling.
///
/// If the error handler is not installed (is null), the exception is thrown
/// for each failure (default behavior).
///
/// @warning This function does not check if there has been any sockets
/// already open by the @c IfaceMgr. Therefore a caller should call
/// @c IfaceMgr::closeSockets() before calling this function.
/// If there are any sockets open, the function may either throw an
/// exception or invoke an error handler on attempt to bind the new socket
/// to the same address and port.
///
/// @param port specifies port number (usually DHCP4_SERVER_PORT)
/// @param use_bcast configure sockets to support broadcast messages.
/// @param error_handler a pointer to an error handler function which is
/// called by the openSockets4 when it fails to open a socket. This
/// parameter can be null to indicate that the callback should not be used.
/// @param skip_opened skip the addresses that already have the opened port
///
/// @throw SocketOpenFailure if tried and failed to open socket and callback
/// function hasn't been specified.
/// @return true if any sockets were open
bool openSockets4(const uint16_t port = DHCP4_SERVER_PORT,
const bool use_bcast = true,
IfaceMgrErrorMsgCallback error_handler = 0,
const bool skip_opened = false);
/// @brief Closes all open sockets.
///
/// It calls @c stopDHCPReceiver to stop the receiver thread and then
/// it closes all open interface sockets.
///
/// Is used in destructor, but also from Dhcpv4Srv and Dhcpv6Srv classes.
void closeSockets();
/// @brief Returns number of detected interfaces.
///
/// @return number of detected interfaces
uint16_t countIfaces() { return ifaces_.size(); }
/// @brief Adds external socket and a callback
///
/// Specifies external socket and a callback that will be called
/// when data will be received over that socket.
///
/// @param socketfd socket descriptor
/// @param callback callback function
void addExternalSocket(int socketfd, SocketCallback callback);
/// @brief Deletes external socket
///
/// @param socketfd socket descriptor
void deleteExternalSocket(int socketfd);
/// @brief Scans registered socket set and removes any that are invalid.
///
/// Walks the list of registered external sockets and tests each for
/// validity. If any are found to be invalid they are removed. This is
/// primarily a self-defense mechanism against hook libs or other users
/// of external sockets that may leave a closed socket registered by
/// mistake.
///
/// @return A count of the sockets purged.
int purgeBadSockets();
/// @brief Deletes all external sockets.
void deleteAllExternalSockets();
/// @brief Set packet filter object to handle sending and receiving DHCPv4
/// messages.
///
/// Packet filter objects provide means for the @c IfaceMgr to open sockets
/// for IPv4 packets reception and sending. This function sets custom packet
/// filter (represented by a class derived from PktFilter) to be used by
/// @c IfaceMgr. Note that there must be no IPv4 sockets open when this
/// function is called. Call closeSockets(AF_INET) to close all hanging IPv4
/// sockets opened by the current packet filter object.
///
/// @param packet_filter a pointer to the new packet filter object to be
/// used by @c IfaceMgr.
///
/// @throw InvalidPacketFilter if provided packet filter object is null.
/// @throw PacketFilterChangeDenied if there are open IPv4 sockets.
void setPacketFilter(const PktFilterPtr& packet_filter);
/// @brief Set packet filter object to handle sending and receiving DHCPv6
/// messages.
///
/// Packet filter objects provide means for the @c IfaceMgr to open sockets
/// for IPv6 packets reception and sending. This function sets the new
/// instance of the packet filter which will be used by @c IfaceMgr to send
/// and receive DHCPv6 messages, until replaced by another packet filter.
///
/// It is required that DHCPv6 messages are send and received using methods
/// of the same object that was used to open socket. Therefore, it is
/// required that all IPv6 sockets are closed prior to calling this
/// function. Call closeSockets(AF_INET6) to close all hanging IPv6 sockets
/// opened by the current packet filter object.
///
/// @param packet_filter a pointer to the new packet filter object to be
/// used by @c IfaceMgr.
///
/// @throw isc::dhcp::InvalidPacketFilter if specified object is null.
/// @throw isc::dhcp::PacketFilterChangeDenied if there are open IPv6
/// sockets.
void setPacketFilter(const PktFilter6Ptr& packet_filter);
/// @brief Set Packet Filter object to handle send/receive packets.
///
/// This function sets Packet Filter object to be used by IfaceMgr,
/// appropriate for the current OS. Setting the argument to 'true'
/// indicates that function should set a packet filter class
/// which supports direct responses to clients having no address
/// assigned yet. Filters picked by this function will vary, depending
/// on the OS being used. There is no guarantee that there is an
/// implementation that supports this feature on a particular OS.
/// If there isn't, the PktFilterInet object will be set. If the
/// argument is set to 'false', PktFilterInet object instance will
/// be set as the Packet Filter regardless of the OS type.
///
/// @param direct_response_desired specifies whether the Packet Filter
/// object being set should support direct traffic to the host
/// not having address assigned.
void setMatchingPacketFilter(const bool direct_response_desired = false);
/// @brief Adds an interface to list of known interfaces.
///
/// @param iface reference to Iface object.
/// @note This function must be public because it has to be callable
/// from unit tests.
/// @throw Unexpected when name or index already exists.
void addInterface(const IfacePtr& iface);
/// @brief Checks if there is at least one socket of the specified family
/// open.
///
/// @param family A socket family.
///
/// @return true if there is at least one socket open, false otherwise.
bool hasOpenSocket(const uint16_t family) const;
/// @brief Checks if there is a socket open and bound to an address.
///
/// This function checks if one of the sockets opened by the IfaceMgr is
/// bound to the IP address specified as the method parameter. If the
/// socket is bound to the port (and address is unspecified), the
/// method will check if the address passed in the argument is configured
/// on an interface.
/// Note: On BSD and Solaris the socket is opened for "::" address instead
/// of the link-local address or the "ff02::1:2" address. If there are
/// multiple interfaces joining the multicast group, this function matches
/// the "::" address bound by any interface, not necessary the one with the
/// specified link-local address and returns true.
///
/// @param addr Address of the socket being searched.
///
/// @return true if there is a socket bound to the specified address.
bool hasOpenSocket(const isc::asiolink::IOAddress& addr) const;
/// @brief Fetches the DHCPv4 packet queue manager
///
/// @return pointer to the packet queue mgr
PacketQueueMgr4Ptr getPacketQueueMgr4() {
return (packet_queue_mgr4_);
}
/// @brief Fetches the DHCPv4 receiver packet queue.
///
/// Incoming packets are read by the receiver thread and
/// added to this queue. @c receive4() dequeues and
/// returns them.
/// @return pointer to the packet queue
PacketQueue4Ptr getPacketQueue4() {
return (packet_queue_mgr4_->getPacketQueue());
}
/// @brief Fetches the DHCPv6 packet queue manager
///
/// @return pointer to the packet queue mgr
PacketQueueMgr6Ptr getPacketQueueMgr6() {
return (packet_queue_mgr6_);
}
/// @brief Fetches the DHCPv6 receiver packet queue.
///
/// Incoming packets are read by the receiver thread and
/// added to this queue. @c receive6() dequeues and
/// returns them.
/// @return pointer to the packet queue
PacketQueue6Ptr getPacketQueue6() {
return (packet_queue_mgr6_->getPacketQueue());
}
/// @brief Starts DHCP packet receiver.
///
/// Starts the DHCP packet receiver thread for the given.
/// protocol, AF_NET or AF_INET6, if the packet queue
/// exists, otherwise it simply returns.
///
/// @param family indicates which receiver to start,
/// (AF_INET or AF_INET6)
///
/// @throw Unexpected if the thread already exists.
void startDHCPReceiver(const uint16_t family);
/// @brief Stops the DHCP packet receiver.
///
/// If the thread exists, it is stopped, deleted, and
/// the packet queue is flushed.
void stopDHCPReceiver();
/// @brief Returns true if there is a receiver exists and its
/// thread is currently running.
bool isDHCPReceiverRunning() const {
return (dhcp_receiver_ != 0 && dhcp_receiver_->isRunning());
}
/// @brief Configures DHCP packet queue
///
/// If the given configuration enables packet queueing, then the
/// appropriate queue is created. Otherwise, the existing queue is
/// destroyed. If the receiver thread is running when this function
/// is invoked, it will throw.
///
/// @param family indicates which receiver to start,
/// (AF_INET or AF_INET6)
/// @param queue_control configuration containing "dhcp-queue-control"
/// content
/// @return true if packet queueing has been enabled, false otherwise
/// @throw InvalidOperation if the receiver thread is currently running.
bool configureDHCPPacketQueue(const uint16_t family,
data::ConstElementPtr queue_control);
/// @brief Convenience method for adding an descriptor to a set
///
/// @param fd descriptor to add
/// @param[out] maxfd maximum fd value in the set. If the new fd is
/// larger than it's current value, it will be updated to new fd value
/// @param sockets pointer to the set of sockets
/// @throw BadValue if sockets is null
static void addFDtoSet(int fd, int& maxfd, fd_set* sockets);
// don't use private, we need derived classes in tests
protected:
/// @brief Protected constructor.
///
/// Protected constructor. This is a singleton class. We don't want
/// anyone to create instances of IfaceMgr. Use instance() method instead.
IfaceMgr();
/// @brief Opens IPv4 socket.
///
/// Please do not use this method directly. Use openSocket instead.
///
/// This method may throw exception if socket creation fails.
///
/// @param iface reference to interface structure.
/// @param addr an address the created socket should be bound to
/// @param port a port that created socket should be bound to
/// @param receive_bcast configure socket to receive broadcast messages
/// @param send_bcast configure socket to send broadcast messages.
///
/// @return socket descriptor
int openSocket4(Iface& iface, const isc::asiolink::IOAddress& addr,
const uint16_t port, const bool receive_bcast = false,
const bool send_bcast = false);
/// @brief Receive IPv4 packets directly or data from external sockets.
///
/// Attempts to receive a single DHCPv4 message over any of the open
/// IPv4 sockets. If reception is successful and all information about
/// its sender is obtained, an Pkt4 object is created and returned.
///
/// This method also checks if data arrived over registered external socket.
/// This data may be of a different protocol family than AF_INET.
///
/// @param timeout_sec specifies integral part of the timeout (in seconds)
/// @param timeout_usec specifies fractional part of the timeout
/// (in microseconds)
///
/// @throw isc::BadValue if timeout_usec is greater than one million
/// @throw isc::dhcp::SocketReadError if error occurred when receiving a
/// packet.
/// @throw isc::dhcp::SignalInterruptOnSelect when a call to select() is
/// interrupted by a signal.
///
/// @return Pkt4 object representing received packet (or null)
Pkt4Ptr receive4Direct(uint32_t timeout_sec, uint32_t timeout_usec = 0);
/// @brief Receive IPv4 packets indirectly or data from external sockets.
///
/// Attempts to receive a single DHCPv4 message from the packet queue.
/// The queue is populated by the receiver thread. If a packet is waiting
/// in the queue, a Pkt4 returned.
///
/// This method also checks if data arrived over registered external socket.
/// This data may be of a different protocol family than AF_INET.
///
/// @param timeout_sec specifies integral part of the timeout (in seconds)
/// @param timeout_usec specifies fractional part of the timeout
/// (in microseconds)
///
/// @throw isc::BadValue if timeout_usec is greater than one million
/// @throw isc::dhcp::SocketReadError if error occurred when receiving a
/// packet.
/// @throw isc::dhcp::SignalInterruptOnSelect when a call to select() is
/// interrupted by a signal.
///
/// @return Pkt4 object representing received packet (or null)
Pkt4Ptr receive4Indirect(uint32_t timeout_sec, uint32_t timeout_usec = 0);
/// @brief Opens IPv6 socket.
///
/// Please do not use this method directly. Use openSocket instead.
///
/// This method may throw exception if socket creation fails.
///
/// @param iface reference to interface structure.
/// @param addr an address the created socket should be bound to
/// @param port a port that created socket should be bound to
/// @param join_multicast A boolean parameter which indicates whether
/// socket should join All_DHCP_Relay_Agents_and_servers multicast
/// group.
///
/// @return socket descriptor
int openSocket6(Iface& iface, const isc::asiolink::IOAddress& addr,
uint16_t port, const bool join_multicast);
/// @brief Receive IPv6 packets directly or data from external sockets.
///
/// Attempts to receive a single DHCPv6 message over any of the open
/// IPv6 sockets. If reception is successful and all information about
/// its sender is obtained, an Pkt6 object is created and returned.
///
/// This method also checks if data arrived over registered external socket.
/// This data may be of a different protocol family than AF_INET.
///
/// @param timeout_sec specifies integral part of the timeout (in seconds)
/// @param timeout_usec specifies fractional part of the timeout
/// (in microseconds)
///
/// @throw isc::BadValue if timeout_usec is greater than one million
/// @throw isc::dhcp::SocketReadError if error occurred when receiving a
/// packet.
/// @throw isc::dhcp::SignalInterruptOnSelect when a call to select() is
/// interrupted by a signal.
///
/// @return Pkt6 object representing received packet (or null)
Pkt6Ptr receive6Direct(uint32_t timeout_sec, uint32_t timeout_usec = 0);
/// @brief Receive IPv6 packets indirectly or data from external sockets.
///
/// Attempts to receive a single DHCPv6 message from the packet queue.
/// The queue is populated by the receiver thread. If a packet is waiting
/// in the queue, a Pkt6 returned.
///
/// This method also checks if data arrived over registered external socket.
/// This data may be of a different protocol family than AF_INET.
///
/// @param timeout_sec specifies integral part of the timeout (in seconds)
/// @param timeout_usec specifies fractional part of the timeout
/// (in microseconds)
///
/// @throw isc::BadValue if timeout_usec is greater than one million
/// @throw isc::dhcp::SocketReadError if error occurred when receiving a
/// packet.
/// @throw isc::dhcp::SignalInterruptOnSelect when a call to select() is
/// interrupted by a signal.
///
/// @return Pkt6 object representing received packet (or null)
Pkt6Ptr receive6Indirect(uint32_t timeout_sec, uint32_t timeout_usec = 0);
/// @brief List of available interfaces
IfaceCollection ifaces_;
/// @brief Unordered set of IPv4 bound addresses.
BoundAddresses bound_address_;
// TODO: Also keep this interface on Iface once interface detection
// is implemented. We may need it e.g. to close all sockets on
// specific interface
//int recvsock_; // TODO: should be fd_set eventually, but we have only
//int sendsock_; // 2 sockets for now. Will do for until next release
// We can't use the same socket, as receiving socket
// is bound to multicast address. And we all know what happens
// to people who try to use multicast as source address.
private:
/// @brief Identifies local network address to be used to
/// connect to remote address.
///
/// This method identifies local network address that can be used
/// to connect to remote address specified.
/// It first creates socket and makes attempt to connect
/// to remote location via this socket. If connection
/// is established successfully, the local address to which
/// socket is bound is returned.
///
/// @param remote_addr remote address to connect to
/// @param port port to be used
/// @return local address to be used to connect to remote address
/// @throw isc::Unexpected if unable to identify local address
isc::asiolink::IOAddress
getLocalAddress(const isc::asiolink::IOAddress& remote_addr,
const uint16_t port);
/// @brief Open an IPv6 socket with multicast support.
///
/// This function opens a socket capable of receiving messages sent to
/// the All_DHCP_Relay_Agents_and_Servers (ff02::1:2) multicast address.
/// The socket is bound to the in6addr_any address and the IPV6_JOIN_GROUP
/// option is set to point to the ff02::1:2 multicast address.
///
/// @note This function is intended to be called internally by the
/// @c IfaceMgr::openSockets6. It is not intended to be called from any
/// other function.
///
/// @param iface Interface on which socket should be open.
/// @param addr Link-local address to bind the socket to.
/// @param port Port number to bind socket to.
/// @param error_handler Error handler function to be called when an
/// error occurs during opening a socket, or null if exception should
/// be thrown upon error.
bool openMulticastSocket(Iface& iface,
const isc::asiolink::IOAddress& addr,
const uint16_t port,
IfaceMgrErrorMsgCallback error_handler = 0);
/// @brief DHCPv4 receiver method.
///
/// Loops forever reading DHCPv4 packets from the interface sockets
/// and adds them to the packet queue. It monitors the "terminate"
/// watch socket, and exits if it is marked ready. This is method
/// is used as the worker function in the thread created by @c
/// startDHCP4Receiver(). It currently uses select() to monitor
/// socket readiness. If the select errors out (other than EINTR),
/// it marks the "error" watch socket as ready.
void receiveDHCP4Packets();
/// @brief Receives a single DHCPv4 packet from an interface socket
///
/// Called by @c receiveDHPC4Packets when a socket fd is flagged as
/// ready. It uses the DHCPv4 packet filter to receive a single packet
/// from the given interface socket, adds it to the packet queue, and
/// marks the "receive" watch socket ready. If an error occurs during
/// the read, the "error" watch socket is marked ready.
///
/// @param iface interface
/// @param socket_info structure holding socket information
void receiveDHCP4Packet(Iface& iface, const SocketInfo& socket_info);
/// @brief DHCPv6 receiver method.
///
/// Loops forever reading DHCPv6 packets from the interface sockets
/// and adds them to the packet queue. It monitors the "terminate"
/// watch socket, and exits if it is marked ready. This is method
/// is used as the worker function in the thread created by @c
/// startDHCP6Receiver(). It currently uses select() to monitor
/// socket readiness. If the select errors out (other than EINTR),
/// it marks the "error" watch socket as ready.
void receiveDHCP6Packets();
/// @brief Receives a single DHCPv6 packet from an interface socket
///
/// Called by @c receiveDHPC6Packets when a socket fd is flagged as
/// ready. It uses the DHCPv6 packet filter to receive a single packet
/// from the given interface socket, adds it to the packet queue, and
/// marks the "receive" watch socket ready. If an error occurs during
/// the read, the "error" watch socket is marked ready.
///
/// @param socket_info structure holding socket information
void receiveDHCP6Packet(const SocketInfo& socket_info);
/// @brief Deletes external socket with the callbacks_mutex_ taken
///
/// @param socketfd socket descriptor
void deleteExternalSocketInternal(int socketfd);
/// Holds instance of a class derived from PktFilter, used by the
/// IfaceMgr to open sockets and send/receive packets through these
/// sockets. It is possible to supply custom object using
/// setPacketFilter method. Various Packet Filters differ mainly by using
/// different types of sockets, e.g. SOCK_DGRAM, SOCK_RAW and different
/// families, e.g. AF_INET, AF_PACKET etc. Another possible type of
/// Packet Filter is the one used for unit testing, which doesn't
/// open sockets but rather mimics their behavior (mock object).
PktFilterPtr packet_filter_;
/// Holds instance of a class derived from PktFilter6, used by the
/// IfaceMgr to manage sockets used to send and receive DHCPv6
/// messages. It is possible to supply a custom object using
/// setPacketFilter method.
PktFilter6Ptr packet_filter6_;
/// @brief Contains list of callbacks for external sockets
SocketCallbackInfoContainer callbacks_;
/// @brief Mutex to protect callbacks_ against concurrent access
std::mutex callbacks_mutex_;
/// @brief Indicates if the IfaceMgr is in the test mode.
bool test_mode_;
/// @brief Detect callback used to perform actions before system dependent
/// function calls.
///
/// If the @ref detect_callback_ returns true, the specific system calls are
/// executed, otherwise the @ref detectIfaces will return immediately.
DetectCallback detect_callback_;
/// @brief Allows to use loopback
bool allow_loopback_;
/// @brief Manager for DHCPv4 packet implementations and queues
PacketQueueMgr4Ptr packet_queue_mgr4_;
/// @brief Manager for DHCPv6 packet implementations and queues
PacketQueueMgr6Ptr packet_queue_mgr6_;
/// @brief DHCP packet receiver.
isc::util::WatchedThreadPtr dhcp_receiver_;
};
} // namespace isc::dhcp
} // namespace isc
#endif // IFACE_MGR_H
|