lease_mgr.h 20.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

15 16
#ifndef LEASE_MGR_H
#define LEASE_MGR_H
17

18
#include <asiolink/io_address.h>
19
#include <dhcp/duid.h>
20
#include <dhcp/option.h>
21
#include <dhcp/subnet.h>
22 23 24 25 26
#include <exceptions/exceptions.h>

#include <boost/noncopyable.hpp>
#include <boost/shared_ptr.hpp>

27
#include <fstream>
28
#include <map>
29 30 31 32
#include <string>
#include <utility>
#include <vector>

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
/// @file dhcp/lease_mgr.h
/// @brief An abstract API for lease database
///
/// This file contains declarations of Lease4, Lease6 and LeaseMgr classes.
/// They are essential components of the interface to any database backend.
/// Each concrete database backend (e.g. MySQL) will define a class derived
/// from LeaseMgr class.
///
/// Failover considerations:
/// There are no intermediate plans to implement DHCPv4 failover
/// (draft-ietf-dhc-failover-12.txt). Currently (Oct. 2012) the DHCPv6 failover
/// is being defined in DHC WG in IETF (draft-ietf-dhcpv6-failover-requirements,
/// draft-ietf-dhcpv6-dailover-design), but the work is not advanced enough
/// for implementation plans yet. v4 failover requires additional parameters
/// to be kept with a lease. It is likely that v6 failover will require similar
/// fields. Such implementation will require database schema extension.
/// We have designed a way to expand/upgrade schemas during upgrades: a database
/// schema is versioned and sanity checks about required version will be done
/// upon start and/or upgrade. With this mechanism in place, we can add new
/// fields to the database. In particular we can use that capability to
/// introduce failover related fields.
///
/// However, there is another approach that can be reliably used to provide
/// failover, even without the actual failover protocol implemented. As the
/// first backend will use MySQL, we will be able to use Multi-Master capability
/// offered by MySQL and use two separatate Kea instances connecting to the
/// same database.
///
/// Nevertheless, we hope to have failover protocol eventually implemented in
/// the Kea.

64 65
#include <iostream>

66 67 68
namespace isc {
namespace dhcp {

69 70 71 72 73 74 75
/// @brief Exception thrown if name of database is not specified
class NoDatabaseName : public Exception {
public:
    NoDatabaseName(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

76 77
/// @brief Exception thrown on failure to open database
class DbOpenError : public Exception {
78
public:
79 80 81 82
    DbOpenError(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

83 84 85 86 87 88 89
/// @brief Exception thrown on failure to execute a database function
class DbOperationError : public Exception {
public:
    DbOperationError(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

90 91 92 93 94 95 96
/// @brief Attempt to update lease that was not there
class NoSuchLease : public Exception {
public:
    NoSuchLease(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

97 98 99 100 101 102 103
/// @brief Structure that holds a lease for IPv4 address
///
/// For performance reasons it is a simple structure, not a class. If we chose
/// make it a class, all fields would have to made private and getters/setters
/// would be required. As this is a critical part of the code that will be used
/// extensively, direct access is warranted.
struct Lease4 {
Tomek Mrugalski's avatar
Tomek Mrugalski committed
104 105
    /// IPv4 address
    isc::asiolink::IOAddress addr_;
106 107 108 109 110 111 112 113

    /// @brief Address extension
    ///
    /// It is envisaged that in some cases IPv4 address will be accompanied with some
    /// additional data. One example of such use are Address + Port solutions (or
    /// Port-restricted Addresses), where several clients may get the same address, but
    /// different port ranges. This feature is not expected to be widely used.
    /// Under normal circumstances, the value should be 0.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
114
    uint32_t ext_;
115 116

    /// @brief hardware address
117
    std::vector<uint8_t> hwaddr_;
118 119

    /// @brief client identifier
Tomek Mrugalski's avatar
Tomek Mrugalski committed
120
    boost::shared_ptr<ClientId> client_id_;
121

122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
    /// @brief renewal timer
    ///
    /// Specifies renewal time. Although technically it is a property of IA container,
    /// not the address itself, since our data model does not define separate IA
    /// entity, we are keeping it in the lease. In case of multiple addresses/prefixes
    /// for the same IA, each must have consistent T1 and T2 values. Specified in
    /// seconds since cltt.
    uint32_t t1_;

    /// @brief rebinding timer
    ///
    /// Specifies rebinding time. Although technically it is a property of IA container,
    /// not the address itself, since our data model does not define separate IA
    /// entity, we are keeping it in the lease. In case of multiple addresses/prefixes
    /// for the same IA, each must have consistent T1 and T2 values. Specified in
    /// seconds since cltt.
    uint32_t t2_;

140 141 142 143
    /// @brief valid lifetime
    ///
    /// Expressed as number of seconds since cltt
    uint32_t valid_lft_;
144 145 146 147

    /// @brief client last transmission time
    ///
    /// Specifies a timestamp, when last transmission from a client was received.
148
    time_t cltt_;
149

150
    /// @brief Subnet identifier
151
    ///
152 153
    /// Specifies subnet-id of the subnet that the lease belongs to
    SubnetID subnet_id_;
154 155 156 157

    /// @brief Is this a fixed lease?
    ///
    /// Fixed leases are kept after they are released/expired.
158
    bool fixed_;
159 160 161 162

    /// @brief client hostname
    ///
    /// This field may be empty
163
    std::string hostname_;
164 165

    /// @brief did we update AAAA record for this lease?
166
    bool fqdn_fwd_;
167

168 169
    /// @brief did we update PTR record for this lease?
    bool fqdn_rev_;
170 171 172 173 174

    /// @brief Lease comments.
    ///
    /// Currently not used. It may be used for keeping comments made by the
    /// system administrator.
175
    std::string comments_;
176 177

    /// @todo: Add DHCPv4 failover related fields here
178 179 180 181

    /// @brief Constructor
    ///
    /// Initialize fields that don't have a default constructor.
182
    /// @TODO Remove this
183
    Lease4() : addr_(0) {}
184 185 186 187 188
};

/// @brief Pointer to a Lease4 structure.
typedef boost::shared_ptr<Lease4> Lease4Ptr;

189 190
/// @brief A collection of IPv4 leases.
typedef std::vector< boost::shared_ptr<Lease4Ptr> > Lease4Collection;
191 192 193 194 195 196 197 198 199 200 201 202 203 204

/// @brief Structure that holds a lease for IPv6 address and/or prefix
///
/// For performance reasons it is a simple structure, not a class. Had we chose to
/// make it a class, all fields would have to be made private and getters/setters
/// would be required. As this is a critical part of the code that will be used
/// extensively, direct access rather than through getters/setters is warranted.
struct Lease6 {
    typedef enum {
        LEASE_IA_NA, /// the lease contains non-temporary IPv6 address
        LEASE_IA_TA, /// the lease contains temporary IPv6 address
        LEASE_IA_PD  /// the lease contains IPv6 prefix (for prefix delegation)
    } LeaseType;

205 206
    Lease6(LeaseType type, const isc::asiolink::IOAddress& addr, DuidPtr duid,
           uint32_t iaid, uint32_t preferred, uint32_t valid, uint32_t t1,
207
           uint32_t t2, SubnetID subnet_id, uint8_t prefixlen_ = 0);
208

209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
    /// @brief specifies lease type (normal addr, temporary addr, prefix)
    LeaseType type_;

    /// IPv6 address
    isc::asiolink::IOAddress addr_;

    /// IPv6 prefix length (used only for PD)
    uint8_t prefixlen_;

    /// @brief IAID
    ///
    /// Identity Association IDentifier. DHCPv6 stores all addresses and prefixes
    /// in IA containers (IA_NA, IA_TA, IA_PD). Most containers may appear more
    /// than once in a message. To differentiate between them, IAID field is present
    uint32_t iaid_;

    /// @brief client identifier
    boost::shared_ptr<DUID> duid_;

    /// @brief preferred lifetime
    ///
    /// This parameter specifies preferred lifetime since the lease was assigned/renewed
    /// (cltt), expressed in seconds.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
232
    uint32_t preferred_lft_;
233 234

    /// @brief valid lifetime
Tomek Mrugalski's avatar
Tomek Mrugalski committed
235 236 237 238
    ///
    /// This parameter specified valid lifetime since the lease was assigned/renewed
    /// (cltt), expressed in seconds.
    uint32_t valid_lft_;
239 240 241 242 243 244

    /// @brief T1 timer
    ///
    /// Specifies renewal time. Although technically it is a property of IA container,
    /// not the address itself, since our data model does not define separate IA
    /// entity, we are keeping it in the lease. In case of multiple addresses/prefixes
Tomek Mrugalski's avatar
Tomek Mrugalski committed
245 246
    /// for the same IA, each must have consistent T1 and T2 values. Specified in
    /// seconds since cltt.
247 248
    /// This value will also be useful for failover to calculate the next expected
    /// client transmission time.
249 250 251 252 253 254 255
    uint32_t t1_;

    /// @brief T2 timer
    ///
    /// Specifies rebinding time. Although technically it is a property of IA container,
    /// not the address itself, since our data model does not define separate IA
    /// entity, we are keeping it in the lease. In case of multiple addresses/prefixes
Tomek Mrugalski's avatar
Tomek Mrugalski committed
256 257
    /// for the same IA, each must have consistent T1 and T2 values. Specified in
    /// seconds since cltt.
258 259 260 261 262
    uint32_t t2_;

    /// @brief client last transmission time
    ///
    /// Specifies a timestamp, when last transmission from a client was received.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
263
    time_t cltt_;
264

265
    /// @brief Subnet identifier
266
    ///
267 268
    /// Specifies subnet-id of the subnet that the lease belongs to
    SubnetID subnet_id_;
269 270 271 272

    /// @brief Is this a fixed lease?
    ///
    /// Fixed leases are kept after they are released/expired.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
273
    bool fixed_;
274 275 276 277

    /// @brief client hostname
    ///
    /// This field may be empty
Tomek Mrugalski's avatar
Tomek Mrugalski committed
278
    std::string hostname_;
279 280

    /// @brief did we update AAAA record for this lease?
Tomek Mrugalski's avatar
Tomek Mrugalski committed
281
    bool fqdn_fwd_;
282

283
    /// @brief did we update PTR record for this lease?
Tomek Mrugalski's avatar
Tomek Mrugalski committed
284
    bool fqdn_rev_;
285

Tomek Mrugalski's avatar
Tomek Mrugalski committed
286
    /// @brief Lease comments
287
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
288 289
    /// This field is currently not used.
    std::string comments_;
290 291

    /// @todo: Add DHCPv6 failover related fields here
292 293 294 295

    /// @brief Constructor
    ///
    /// Initialize fields that don't have a default constructor.
296
    Lease6() : addr_("::") {}
297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314

    /// @brief Convert Lease6 to Printable Form
    ///
    /// @return String form of the lease
    std::string toText();

    /// @brief Compare two leases for equality
    ///
    /// @param other lease6 object with which to compare
    bool operator==(const Lease6& other) const;

    /// @brief Compare two leases for inequality
    ///
    /// @param other lease6 object with which to compare
    bool operator!=(const Lease6& other) const {
        return (!operator==(other));
    }

315 316 317 318 319 320 321 322
};

/// @brief Pointer to a Lease6 structure.
typedef boost::shared_ptr<Lease6> Lease6Ptr;

/// @brief Const pointer to a Lease6 structure.
typedef boost::shared_ptr<const Lease6> ConstLease6Ptr;

323
/// @brief A collection of IPv6 leases.
324
typedef std::vector<Lease6Ptr> Lease6Collection;
325

326
/// @brief Abstract Lease Manager
327
///
328 329 330 331
/// This is an abstract API for lease database backends. It provides unified
/// interface to all backends. As this is an abstract class, it should not
/// be used directly, but rather specialized derived class should be used
/// instead.
332 333 334 335
///
/// As all methods are virtual, this class throws no exceptions.  However,
/// methods in concrete implementations of this class may throw exceptions:
/// see the documentation of those classes for details.
336 337
class LeaseMgr {
public:
338 339 340
    /// Client Hardware address
    typedef std::vector<uint8_t> HWAddr;

341 342 343
    /// Database configuration parameter map
    typedef std::map<std::string, std::string> ParameterMap;

344
    /// @brief Constructor
345
    ///
346 347 348
    /// @param parameters A data structure relating keywords and values
    ///        concerned with the database.
    LeaseMgr(const ParameterMap& parameters);
349

350 351
    /// @brief Destructor
    ~LeaseMgr();
352

353
    /// @brief Adds an IPv4 lease.
354 355
    ///
    /// @param lease lease to be added
356 357 358 359
    ///
    /// @result true if the lease was added, false if not (because a lease
    ///         with the same address was already there).
    virtual bool addLease(const Lease4Ptr& lease) = 0;
360

361
    /// @brief Adds an IPv6 lease.
362 363
    ///
    /// @param lease lease to be added
364 365 366 367
    ///
    /// @result true if the lease was added, false if not (because a lease
    ///         with the same address was already there).
    virtual bool addLease(const Lease6Ptr& lease) = 0;
368

369
    /// @brief Returns IPv4 lease for specified IPv4 address and subnet_id
370 371 372 373 374 375 376 377 378
    ///
    /// This method is used to get a lease for specific subnet_id. There can be
    /// at most one lease for any given subnet, so this method returns a single
    /// pointer.
    ///
    /// @param addr address of the searched lease
    /// @param subnet_id ID of the subnet the lease must belong to
    ///
    /// @return smart pointer to the lease (or NULL if a lease is not found)
379
    virtual Lease4Ptr getLease4(const isc::asiolink::IOAddress& addr,
380 381 382 383 384 385 386 387 388 389
                                SubnetID subnet_id) const = 0;

    /// @brief Returns an IPv4 lease for specified IPv4 address
    ///
    /// This method return a lease that is associated with a given address.
    /// For other query types (by hardware addr, by client-id) there can be
    /// several leases in different subnets (e.g. for mobile clients that
    /// got address in different subnets). However, for a single address
    /// there can be only one lease, so this method returns a pointer to
    /// a single lease, not a container of leases.
390 391
    ///
    /// @param addr address of the searched lease
392
    /// @param subnet_id ID of the subnet the lease must belong to
393
    ///
394
    /// @return smart pointer to the lease (or NULL if a lease is not found)
395
    virtual Lease4Ptr getLease4(const isc::asiolink::IOAddress& addr) const = 0;
396

397 398 399 400 401 402
    /// @brief Returns existing IPv4 leases for specified hardware address.
    ///
    /// Although in the usual case there will be only one lease, for mobile
    /// clients or clients with multiple static/fixed/reserved leases there
    /// can be more than one. Thus return type is a container, not a single
    /// pointer.
403 404 405
    ///
    /// @param hwaddr hardware address of the client
    ///
406 407 408 409 410 411 412 413 414 415 416 417 418
    /// @return lease collection
    virtual Lease4Collection getLease4(const HWAddr& hwaddr) const = 0;

    /// @brief Returns existing IPv4 leases for specified hardware address
    ///        and a subnet
    ///
    /// There can be at most one lease for a given HW address in a single
    /// pool, so this method with either return a single lease or NULL.
    ///
    /// @param hwaddr hardware address of the client
    /// @param subnet_id identifier of the subnet that lease must belong to
    ///
    /// @return a pointer to the lease (or NULL if a lease is not found)
419
    virtual Lease4Ptr getLease4(const HWAddr& hwaddr,
420
                                SubnetID subnet_id) const = 0;
421

422 423
    /// @brief Returns existing IPv4 lease for specified client-id
    ///
424 425 426 427 428
    /// Although in the usual case there will be only one lease, for mobile
    /// clients or clients with multiple static/fixed/reserved leases there
    /// can be more than one. Thus return type is a container, not a single
    /// pointer.
    ///
429
    /// @param clientid client identifier
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444
    ///
    /// @return lease collection
    virtual Lease4Collection getLease4(const ClientId& clientid) const = 0;

    /// @brief Returns existing IPv4 lease for specified client-id
    ///
    /// There can be at most one lease for a given HW address in a single
    /// pool, so this method with either return a single lease or NULL.
    ///
    /// @param clientid client identifier
    /// @param subnet_id identifier of the subnet that lease must belong to
    ///
    /// @return a pointer to the lease (or NULL if a lease is not found)
    virtual Lease4Ptr getLease4(const ClientId& clientid,
                                SubnetID subnet_id) const = 0;
445

446
    /// @brief Returns existing IPv6 lease for a given IPv6 address.
447
    ///
448 449 450 451
    /// For a given address, we assume that there will be only one lease.
    /// The assumtion here is that there will not be site or link-local
    /// addresses used, so there is no way of having address duplication.
    ///
452 453
    /// @param addr address of the searched lease
    ///
454
    /// @return smart pointer to the lease (or NULL if a lease is not found)
455
    virtual Lease6Ptr getLease6(const isc::asiolink::IOAddress& addr) const = 0;
456

457 458 459 460 461 462 463 464 465 466 467
    /// @brief Returns existing IPv6 leases for a given DUID+IA combination
    ///
    /// Although in the usual case there will be only one lease, for mobile
    /// clients or clients with multiple static/fixed/reserved leases there
    /// can be more than one. Thus return type is a container, not a single
    /// pointer.
    ///
    /// @param duid client DUID
    /// @param iaid IA identifier
    ///
    /// @return smart pointer to the lease (or NULL if a lease is not found)
468
    virtual Lease6Collection getLease6(const DUID& duid,
469 470
                                       uint32_t iaid) const = 0;

471 472 473 474
    /// @brief Returns existing IPv6 lease for a given DUID+IA combination
    ///
    /// @param duid client DUID
    /// @param iaid IA identifier
475
    /// @param subnet_id subnet id of the subnet the lease belongs to
476 477
    ///
    /// @return smart pointer to the lease (or NULL if a lease is not found)
478 479
    virtual Lease6Ptr getLease6(const DUID& duid, uint32_t iaid,
                                SubnetID subnet_id) const = 0;
480

481 482 483 484 485
    /// @brief Updates IPv4 lease.
    ///
    /// @param lease4 The lease to be updated.
    ///
    /// If no such lease is present, an exception will be thrown.
486
    virtual void updateLease4(const Lease4Ptr& lease4) = 0;
487

Marcin Siodelski's avatar
Marcin Siodelski committed
488
    /// @brief Updates IPv6 lease.
489
    ///
Marcin Siodelski's avatar
Marcin Siodelski committed
490
    /// @param lease6 The lease to be updated.
491
    virtual void updateLease6(const Lease6Ptr& lease6) = 0;
492 493 494 495 496 497

    /// @brief Deletes a lease.
    ///
    /// @param addr IPv4 address of the lease to be deleted.
    ///
    /// @return true if deletion was successful, false if no such lease exists
498
    virtual bool deleteLease4(const isc::asiolink::IOAddress& addr) = 0;
499 500 501

    /// @brief Deletes a lease.
    ///
Marcin Siodelski's avatar
Marcin Siodelski committed
502
    /// @param addr IPv6 address of the lease to be deleted.
503 504
    ///
    /// @return true if deletion was successful, false if no such lease exists
505
    virtual bool deleteLease6(const isc::asiolink::IOAddress& addr) = 0;
506

507 508 509 510
    /// @brief Returns backend name.
    ///
    /// Each backend have specific name, e.g. "mysql" or "sqlite".
    virtual std::string getName() const = 0;
511

512 513 514 515
    /// @brief Returns description of the backend.
    ///
    /// This description may be multiline text that describes the backend.
    virtual std::string getDescription() const = 0;
516

517
    /// @brief Returns backend version.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
518
    ///
519 520 521
    /// @return Version number as a pair of unsigned integers.  "first" is the
    ///         major version number, "second" the minor number.
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
522 523 524 525 526 527 528 529
    /// @todo: We will need to implement 3 version functions eventually:
    /// A. abstract API version
    /// B. backend version
    /// C. database version (stored in the database scheme)
    ///
    /// and then check that:
    /// B>=A and B=C (it is ok to have newer backend, as it should be backward
    /// compatible)
530
    /// Also if B>C, some database upgrade procedure may be triggered
531
    virtual std::pair<uint32_t, uint32_t> getVersion() const = 0;
532

533 534 535 536 537 538 539 540 541 542 543 544
    /// @brief Commit Transactions
    ///
    /// Commits all pending database operations.  On databases that don't
    /// support transactions, this is a no-op.
    virtual void commit() = 0;

    /// @brief Rollback Transactions
    ///
    /// Rolls back all pending database operations.  On databases that don't
    /// support transactions, this is a no-op.
    virtual void rollback() = 0;

545
    /// @todo: Add host management here
Tomek Mrugalski's avatar
Tomek Mrugalski committed
546 547 548 549 550
    /// As host reservation is outside of scope for 2012, support for hosts
    /// is currently postponed.

    /// @brief returns value of the parameter
    std::string getParameter(const std::string& name) const;
551

552
private:
553
    /// @brief list of parameters passed in dbconfig
Tomek Mrugalski's avatar
Tomek Mrugalski committed
554 555 556 557
    ///
    /// That will be mostly used for storing database name, username,
    /// password and other parameters required for DB access. It is not
    /// intended to keep any DHCP-related parameters.
558
    ParameterMap parameters_;
559
};
560 561 562

}; // end of isc::dhcp namespace
}; // end of isc namespace
563

564
#endif // LEASE_MGR_H