mysql_host_data_source.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279
  1. // Copyright (C) 2015-2016 Internet Systems Consortium, Inc. ("ISC")
  2. //
  3. // This Source Code Form is subject to the terms of the Mozilla Public
  4. // License, v. 2.0. If a copy of the MPL was not distributed with this
  5. // file, You can obtain one at http://mozilla.org/MPL/2.0/.
  6. #ifndef MYSQL_HOST_DATA_SOURCE_H
  7. #define MYSQL_HOST_DATA_SOURCE_H
  8. #include <dhcpsrv/base_host_data_source.h>
  9. #include <dhcpsrv/mysql_connection.h>
  10. namespace isc {
  11. namespace dhcp {
  12. /// Forward declaration to the implementation of the @ref MySqlHostDataSource.
  13. class MySqlHostDataSourceImpl;
  14. /// @brief MySQL Host Data Source
  15. ///
  16. /// This class implements the @ref isc::dhcp::BaseHostDataSource interface to
  17. /// the MySQL database. Use of this backend presupposes that a MySQL database
  18. /// is available and that the Kea schema has been created within it.
  19. class MySqlHostDataSource: public BaseHostDataSource {
  20. public:
  21. /// @brief Constructor
  22. ///
  23. /// Uses the following keywords in the parameters passed to it to
  24. /// connect to the database:
  25. /// - name - Name of the database to which to connect (mandatory)
  26. /// - host - Host to which to connect (optional, defaults to "localhost")
  27. /// - user - Username under which to connect (optional)
  28. /// - password - Password for "user" on the database (optional)
  29. ///
  30. /// If the database is successfully opened, the version number in the
  31. /// schema_version table will be checked against hard-coded value in
  32. /// the implementation file.
  33. ///
  34. /// Finally, all the SQL commands are pre-compiled.
  35. ///
  36. /// @param parameters A data structure relating keywords and values
  37. /// concerned with the database.
  38. ///
  39. /// @throw isc::dhcp::NoDatabaseName Mandatory database name not given
  40. /// @throw isc::dhcp::DbOpenError Error opening the database
  41. /// @throw isc::dhcp::DbOperationError An operation on the open database has
  42. /// failed.
  43. MySqlHostDataSource(const DatabaseConnection::ParameterMap& parameters);
  44. /// @brief Virtual destructor.
  45. ///
  46. /// Releases prepared MySQL statements used by the backend.
  47. virtual ~MySqlHostDataSource();
  48. /// @brief Return all hosts for the specified HW address or DUID.
  49. ///
  50. /// This method returns all @c Host objects which represent reservations
  51. /// for the specified HW address or DUID. Note, that this method may
  52. /// return multiple reservations because a particular client may have
  53. /// reservations in multiple subnets and the same client may be identified
  54. /// by HW address or DUID. The server is unable to verify that the specific
  55. /// DUID and HW address belong to the same client, until the client sends
  56. /// a DHCP message.
  57. ///
  58. /// Specifying both hardware address and DUID is allowed for this method
  59. /// and results in returning all objects that are associated with hardware
  60. /// address OR duid. For example: if one host is associated with the
  61. /// specified hardware address and another host is associated with the
  62. /// specified DUID, two hosts will be returned.
  63. ///
  64. /// @param hwaddr HW address of the client or NULL if no HW address
  65. /// available.
  66. /// @param duid client id or NULL if not available, e.g. DHCPv4 client case.
  67. ///
  68. /// @return Collection of const @c Host objects.
  69. virtual ConstHostCollection
  70. getAll(const HWAddrPtr& hwaddr, const DuidPtr& duid = DuidPtr()) const;
  71. /// @brief Return all hosts connected to any subnet for which reservations
  72. /// have been made using a specified identifier.
  73. ///
  74. /// This method returns all @c Host objects which represent reservations
  75. /// for a specified identifier. This method may return multiple hosts
  76. /// because a particular client may have reservations in multiple subnets.
  77. ///
  78. /// @param identifier_begin Pointer to a begining of a buffer containing
  79. /// an identifier.
  80. /// @param identifier_len Identifier length.
  81. ///
  82. /// @return Collection of const @c Host objects.
  83. virtual ConstHostCollection
  84. getAll(const Host::IdentifierType& identifier_type,
  85. const uint8_t* identifier_begin, const size_t identifier_len) const;
  86. /// @brief Returns a collection of hosts using the specified IPv4 address.
  87. ///
  88. /// This method may return multiple @c Host objects if they are connected
  89. /// to different subnets.
  90. ///
  91. /// @param address IPv4 address for which the @c Host object is searched.
  92. ///
  93. /// @return Collection of const @c Host objects.
  94. virtual ConstHostCollection
  95. getAll4(const asiolink::IOAddress& address) const;
  96. /// @brief Returns a host connected to the IPv4 subnet.
  97. ///
  98. /// Implementations of this method should guard against the case when
  99. /// mutliple instances of the @c Host are present, e.g. when two
  100. /// @c Host objects are found, one for the DUID, another one for the
  101. /// HW address. In such case, an implementation of this method
  102. /// should throw an MultipleRecords exception.
  103. ///
  104. /// @param subnet_id Subnet identifier.
  105. /// @param hwaddr HW address of the client or NULL if no HW address
  106. /// available.
  107. /// @param duid client id or NULL if not available.
  108. ///
  109. /// @return Const @c Host object using a specified HW address or DUID.
  110. virtual ConstHostPtr
  111. get4(const SubnetID& subnet_id, const HWAddrPtr& hwaddr,
  112. const DuidPtr& duid = DuidPtr()) const;
  113. /// @brief Returns a host connected to the IPv4 subnet.
  114. ///
  115. /// @param subnet_id Subnet identifier.
  116. /// @param identifier_type Identifier type.
  117. /// @param identifier_begin Pointer to a begining of a buffer containing
  118. /// an identifier.
  119. /// @param identifier_len Identifier length.
  120. ///
  121. /// @return Const @c Host object for which reservation has been made using
  122. /// the specified identifier.
  123. virtual ConstHostPtr
  124. get4(const SubnetID& subnet_id, const Host::IdentifierType& identifier_type,
  125. const uint8_t* identifier_begin, const size_t identifier_len) const;
  126. /// @brief Returns a host connected to the IPv4 subnet and having
  127. /// a reservation for a specified IPv4 address.
  128. ///
  129. /// One of the use cases for this method is to detect collisions between
  130. /// dynamically allocated addresses and reserved addresses. When the new
  131. /// address is assigned to a client, the allocation mechanism should check
  132. /// if this address is not reserved for some other host and do not allocate
  133. /// this address if reservation is present.
  134. ///
  135. /// Implementations of this method should guard against invalid addresses,
  136. /// such as IPv6 address.
  137. ///
  138. /// @param subnet_id Subnet identifier.
  139. /// @param address reserved IPv4 address.
  140. ///
  141. /// @return Const @c Host object using a specified IPv4 address.
  142. virtual ConstHostPtr
  143. get4(const SubnetID& subnet_id, const asiolink::IOAddress& address) const;
  144. /// @brief Returns a host connected to the IPv6 subnet.
  145. ///
  146. /// Implementations of this method should guard against the case when
  147. /// mutliple instances of the @c Host are present, e.g. when two
  148. /// @c Host objects are found, one for the DUID, another one for the
  149. /// HW address. In such case, an implementation of this method
  150. /// should throw an MultipleRecords exception.
  151. ///
  152. /// @param subnet_id Subnet identifier.
  153. /// @param hwaddr HW address of the client or NULL if no HW address
  154. /// available.
  155. /// @param duid DUID or NULL if not available.
  156. ///
  157. /// @return Const @c Host object using a specified HW address or DUID.
  158. virtual ConstHostPtr
  159. get6(const SubnetID& subnet_id, const DuidPtr& duid,
  160. const HWAddrPtr& hwaddr = HWAddrPtr()) const;
  161. /// @brief Returns a host connected to the IPv6 subnet.
  162. ///
  163. /// @param subnet_id Subnet identifier.
  164. /// @param identifier_type Identifier type.
  165. /// @param identifier_begin Pointer to a begining of a buffer containing
  166. /// an identifier.
  167. /// @param identifier_len Identifier length.
  168. ///
  169. /// @return Const @c Host object for which reservation has been made using
  170. /// the specified identifier.
  171. virtual ConstHostPtr
  172. get6(const SubnetID& subnet_id, const Host::IdentifierType& identifier_type,
  173. const uint8_t* identifier_begin, const size_t identifier_len) const;
  174. /// @brief Returns a host using the specified IPv6 prefix.
  175. ///
  176. /// @param prefix IPv6 prefix for which the @c Host object is searched.
  177. /// @param prefix_len IPv6 prefix length.
  178. ///
  179. /// @return Const @c Host object using a specified HW address or DUID.
  180. virtual ConstHostPtr
  181. get6(const asiolink::IOAddress& prefix, const uint8_t prefix_len) const;
  182. /// @brief Adds a new host to the collection.
  183. ///
  184. /// The implementations of this method should guard against duplicate
  185. /// reservations for the same host, where possible. For example, when the
  186. /// reservation for the same HW address and subnet id is added twice, the
  187. /// addHost method should throw an DuplicateEntry exception. Note, that
  188. /// usually it is impossible to guard against adding duplicated host, where
  189. /// one instance is identified by HW address, another one by DUID.
  190. ///
  191. /// @param host Pointer to the new @c Host object being added.
  192. virtual void add(const HostPtr& host);
  193. /// @brief Return backend type
  194. ///
  195. /// Returns the type of the backend (e.g. "mysql", "memfile" etc.)
  196. ///
  197. /// @return Type of the backend.
  198. virtual std::string getType() const {
  199. return (std::string("mysql"));
  200. }
  201. /// @brief Returns backend name.
  202. ///
  203. /// Each backend have specific name.
  204. ///
  205. /// @return "mysql".
  206. virtual std::string getName() const;
  207. /// @brief Returns description of the backend.
  208. ///
  209. /// This description may be multiline text that describes the backend.
  210. ///
  211. /// @return Description of the backend.
  212. virtual std::string getDescription() const;
  213. /// @brief Returns backend version.
  214. ///
  215. /// @return Version number stored in the database, as a pair of unsigned
  216. /// integers. "first" is the major version number, "second" the
  217. /// minor number.
  218. ///
  219. /// @throw isc::dhcp::DbOperationError An operation on the open database
  220. /// has failed.
  221. virtual std::pair<uint32_t, uint32_t> getVersion() const;
  222. /// @brief Commit Transactions
  223. ///
  224. /// Commits all pending database operations.
  225. virtual void commit();
  226. /// @brief Rollback Transactions
  227. ///
  228. /// Rolls back all pending database operations.
  229. virtual void rollback();
  230. /// @brief Statement Tags
  231. ///
  232. /// The contents of the enum are indexes into the list of SQL statements
  233. enum StatementIndex {
  234. INSERT_HOST, // Insert new host to collection
  235. INSERT_V6_RESRV, // Insert v6 reservation
  236. GET_HOST_DHCPID, // Gets hosts by host identifier
  237. GET_HOST_ADDR, // Gets hosts by IPv4 address
  238. GET_HOST_SUBID4_DHCPID, // Gets host by IPv4 SubnetID, HW address/DUID
  239. GET_HOST_SUBID6_DHCPID, // Gets host by IPv6 SubnetID, HW address/DUID
  240. GET_HOST_SUBID_ADDR, // Gets host by IPv4 SubnetID and IPv4 address
  241. GET_HOST_PREFIX, // Gets host by IPv6 prefix
  242. GET_VERSION, // Obtain version number
  243. NUM_STATEMENTS // Number of statements
  244. };
  245. private:
  246. /// @brief Pointer to the implementation of the @ref MySqlHostDataSource.
  247. MySqlHostDataSourceImpl* impl_;
  248. };
  249. }
  250. }
  251. #endif // MYSQL_HOST_DATA_SOURCE_H