subnet.h 19.2 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 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.

#ifndef SUBNET_H
#define SUBNET_H

18
19
20
21
22
23
#include <boost/shared_ptr.hpp>
#include <boost/multi_index_container.hpp>
#include <boost/multi_index/hashed_index.hpp>
#include <boost/multi_index/sequenced_index.hpp>
#include <boost/multi_index/mem_fun.hpp>
#include <boost/multi_index/member.hpp>
24

25
26
27
28
29
#include <asiolink/io_address.h>
#include <dhcp/option.h>
#include <dhcpsrv/pool.h>
#include <dhcpsrv/triplet.h>

30
31
32
33
34
35
36
37
38
39
namespace isc {
namespace dhcp {

/// @brief a base class for Subnet4 and Subnet6
///
/// This class presents a common base for IPv4 and IPv6 subnets.
/// In a physical sense, a subnet defines a single network link with all devices
/// attached to it. In most cases all devices attached to a single link can
/// share the same parameters. Therefore Subnet holds several values that are
/// typically shared by all hosts: renew timer (T1), rebind timer (T2) and
40
41
42
43
/// leased addresses lifetime (valid-lifetime). It also holds the set
/// of DHCP option instances configured for the subnet. These options are
/// included in DHCP messages being sent to clients which are connected
/// to the particular subnet.
44
45
///
/// @todo: Implement support for options here
46
47
48
49
50


/// @brief Unique indentifier for a subnet (both v4 and v6)
typedef uint32_t SubnetID;

51
52
class Subnet {
public:
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

    /// @brief Option descriptor.
    ///
    /// Option descriptor holds information about option configured for
    /// a particular subnet. This information comprises the actual option
    /// instance and information whether this option is sent to DHCP client
    /// only on request (persistent = false) or always (persistent = true).
    struct OptionDescriptor {
        /// Option instance.
        OptionPtr option;
        /// Persistent flag, if true option is always sent to the client,
        /// if false option is sent to the client on request.
        bool persistent;

        /// @brief Constructor.
        ///
69
70
        /// @param opt option
        /// @param persist if true option is always sent.
71
72
        OptionDescriptor(OptionPtr& opt, bool persist)
            : option(opt), persistent(persist) {};
73
74
75
76
77
78

        /// @brief Constructor
        ///
        /// @param persist if true option is always sent.
        OptionDescriptor(bool persist)
            : option(OptionPtr()), persistent(persist) {};
79
80
81
82
    };

    /// @brief Extractor class to extract key with another key.
    ///
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
    /// This class solves the problem of accessing index key values
    /// that are stored in objects nested in other objects.
    /// Each OptionDescriptor structure contains the OptionPtr object.
    /// The value retured by one of its accessors (getType) is used
    /// as an indexing value in the multi_index_container defined below.
    /// There is no easy way to mark that value returned by Option::getType
    /// should be an index of this multi_index_container. There are standard
    /// key extractors such as 'member' or 'mem_fun' but they are not
    /// sufficient here. The former can be used to mark that member of
    /// the structure that is held in the container should be used as an
    /// indexing value. The latter can be used if the indexing value is
    /// a product of the class being held in the container. In this complex
    /// scenario when the indexing value is a product of the function that
    /// is wrapped by the structure, this new extractor template has to be
    /// defined. The template class provides a 'chain' of two extractors
    /// to access the value returned by nested object and to use it as
    /// indexing value.
    /// For some more examples of complex keys see:
    /// http://www.cs.brown.edu/~jwicks/boost/libs/multi_index/doc/index.html
102
103
104
105
106
107
    ///
    /// @tparam KeyExtractor1 extractor used to access data in
    /// OptionDescriptor::option
    /// @tparam KeyExtractor2 extractor used to access
    /// OptionDescriptor::option member.
    template<typename KeyExtractor1, typename KeyExtractor2>
108
109
    class KeyFromKey {
    public:
110
111
112
        typedef typename KeyExtractor1::result_type result_type;

        /// @brief Constructor.
113
114
        KeyFromKey()
            : key1_(KeyExtractor1()), key2_(KeyExtractor2()) { };
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

        /// @brief Extract key with another key.
        ///
        /// @param arg the key value.
        ///
        /// @tparam key value type.
        template<typename T>
        result_type operator() (T& arg) const {
            return (key1_(key2_(arg)));
        }
    private:
        KeyExtractor1 key1_; ///< key 1.
        KeyExtractor2 key2_; ///< key 2.
    };

    /// @brief Multi index container for DHCP option descriptors.
    ///
    /// This container comprises three indexes to access option
    /// descriptors:
    /// - sequenced index: used to access elements in the order they
    /// have been added to the container,
    /// - option type index: used to search option descriptors containing
    /// options with specific option code (aka option type).
    /// - persistency flag index: used to search option descriptors with
    /// 'persistent' flag set to true.
    ///
    /// This container is the equivalent of three separate STL containers:
    /// - std::list of all options,
    /// - std::multimap of options with option code used as a multimap key,
    /// - std::multimap of option descriptors with option persistency flag
    /// used as a multimap key.
    /// The major advantage of this container over 3 separate STL containers
    /// is automatic synchronization of all indexes when elements are added,
    /// removed or modified in the container. With separate containers,
    /// the synchronization would have to be guaranteed by the Subnet class
    /// code. This would increase code complexity and presumably it would
    /// be much harder to add new search criteria (indexes).
    ///
    /// @todo we may want to search for options using option spaces when
    /// they are implemented.
    ///
    /// @see http://www.boost.org/doc/libs/1_51_0/libs/multi_index/doc/index.html
    typedef boost::multi_index_container<
        // Container comprises elements of OptionDescriptor type.
        OptionDescriptor,
        // 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.
164
            // Sequenced is an index #0.
165
166
167
168
169
170
171
172
173
174
            boost::multi_index::sequenced<>,
            // Start definition of index #1.
            boost::multi_index::hashed_non_unique<
                // KeyFromKey is the index key extractor that allows accessing
                // option type being held by the OptionPtr through
                // OptionDescriptor structure.
                KeyFromKey<
                    // Use option type as the index key. The type is held
                    // in OptionPtr object so we have to call Option::getType
                    // to retrieve this key for each element.
175
                    boost::multi_index::const_mem_fun<
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
                        Option,
                        uint16_t,
                        &Option::getType
                    >,
                    // Indicate that OptionPtr is a member of
                    // OptionDescriptor structure.
                    boost::multi_index::member<
                        OptionDescriptor,
                        OptionPtr,
                        &OptionDescriptor::option
                    >
                 >
            >,
            // Start definition of index #2.
            // Use 'persistent' struct member as a key.
            boost::multi_index::hashed_non_unique<
                boost::multi_index::member<
                    OptionDescriptor,
                    bool,
                    &OptionDescriptor::persistent
                >
            >
        >
    > OptionContainer;

    /// Type of the index #1 - option type.
    typedef OptionContainer::nth_index<1>::type OptionContainerTypeIndex;
203
204
205
206
207
    /// Pair of iterators to represent the range of options having the
    /// same option type value. The first element in this pair represents
    /// the begining of the range, the second element represents the end.
    typedef std::pair<OptionContainerTypeIndex::const_iterator,
                      OptionContainerTypeIndex::const_iterator> OptionContainerTypeRange;
208
209
210
    /// Type of the index #2 - option persistency flag.
    typedef OptionContainer::nth_index<2>::type OptionContainerPersistIndex;

211
212
213
    /// @brief checks if specified address is in range
    bool inRange(const isc::asiolink::IOAddress& addr) const;

214
215
216
217
218
219
220
    /// @brief Add new option instance to the collection.
    ///
    /// @param option option instance.
    /// @param persistent if true, send an option regardless if client
    /// requested it or not.
    ///
    /// @throw isc::BadValue if invalid option provided.
221
    void addOption(OptionPtr& option, bool persistent = false);
222
223
224
225

    /// @brief Delete all options configured for the subnet.
    void delOptions();

226
227
228
229
230
231
    /// @brief checks if the specified address is in pools
    ///
    /// Note the difference between inSubnet() and inPool(). For a given
    /// subnet (e.g. 2001::/64) there may be one or more pools defined
    /// that may or may not cover entire subnet, e.g. pool 2001::1-2001::10).
    /// inPool() returning true implies inSubnet(), but the reverse implication
Tomek Mrugalski's avatar
Tomek Mrugalski committed
232
    /// is not always true. For the given example, 2001::1234:abcd would return
233
234
    /// true for inSubnet(), but false for inPool() check.
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
235
236
    /// @param addr this address will be checked if it belongs to any pools in
    ///        that subnet
237
    /// @return true if the address is in any of the pools
238
    bool inPool(const isc::asiolink::IOAddress& addr) const;
239

240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
    /// @brief return valid-lifetime for addresses in that prefix
    Triplet<uint32_t> getValid() const {
        return (valid_);
    }

    /// @brief returns T1 (renew timer), expressed in seconds
    Triplet<uint32_t> getT1() const {
        return (t1_);
    }

    /// @brief returns T2 (rebind timer), expressed in seconds
    Triplet<uint32_t> getT2() const {
        return (t2_);
    }

255
256
    /// @brief Return a collection of options.
    ///
257
258
259
    /// @return reference to collection of options configured for a subnet.
    /// The returned reference is valid as long as the Subnet object which
    /// returned it still exists.
260
    const OptionContainer& getOptions() const {
261
262
263
        return (options_);
    }

Tomek Mrugalski's avatar
Tomek Mrugalski committed
264
265
266
267
268
269
270
271
272
273
274
    /// @brief returns the last address that was tried from this pool
    ///
    /// This method returns the last address that was attempted to be allocated
    /// from this subnet. This is used as helper information for the next
    /// iteration of the allocation algorithm.
    ///
    /// @todo: Define map<SubnetID, IOAddress> somewhere in the
    ///        AllocEngine::IterativeAllocator and keep the data there
    ///
    /// @return address that was last tried from this pool
    isc::asiolink::IOAddress getLastAllocated() const {
275
276
277
        return (last_allocated_);
    }

Tomek Mrugalski's avatar
Tomek Mrugalski committed
278
279
280
281
282
283
284
285
    /// @brief sets the last address that was tried from this pool
    ///
    /// This method sets the last address that was attempted to be allocated
    /// from this subnet. This is used as helper information for the next
    /// iteration of the allocation algorithm.
    ///
    /// @todo: Define map<SubnetID, IOAddress> somewhere in the
    ///        AllocEngine::IterativeAllocator and keep the data there
286
287
288
289
    void setLastAllocated(const isc::asiolink::IOAddress& addr) {
        last_allocated_ = addr;
    }

Tomek Mrugalski's avatar
Tomek Mrugalski committed
290
291
292
    /// @brief returns unique ID for that subnet
    /// @return unique ID for that subnet
    SubnetID getID() const { return (id_); }
293

294
295
296
    /// @brief returns subnet parameters (prefix and prefix length)
    ///
    /// @return (prefix, prefix length) pair
297
298
    std::pair<isc::asiolink::IOAddress, uint8_t> get() const {
        return (std::make_pair(prefix_, prefix_len_));
299
300
    }

301
302
303
304
305
306
307
308
    /// @brief Adds a new pool.
    /// @param pool pool to be added
    void addPool(const PoolPtr& pool);

    /// @brief Returns a pool that specified address belongs to
    ///
    /// @param addr address that the returned pool should cover (optional)
    /// @return Pointer to found Pool4 or Pool6 (or NULL)
309
310
311
312
313
314
315
316
317
318
319
320
321
    PoolPtr getPool(isc::asiolink::IOAddress addr);

    /// @brief Returns a pool without any address specified
    /// @return returns one of the pools defined
    PoolPtr getPool() {
        return (getPool(default_pool()));
    }

    /// @brief Returns the default address that will be used for pool selection
    ///
    /// It must be implemented in derived classes (should return :: for Subnet6
    /// and 0.0.0.0 for Subnet4)
    virtual isc::asiolink::IOAddress default_pool() const = 0;
322
323
324
325
326
327
328
329
330
331

    /// @brief returns all pools
    ///
    /// The reference is only valid as long as the object that returned it.
    ///
    /// @return a collection of all pools
    const PoolCollection& getPools() const {
        return pools_;
    }

332
333
334
    /// @brief returns textual representation of the subnet (e.g. "2001:db8::/64")
    ///
    /// @return textual representation
335
    virtual std::string toText() const;
336

337
338
339
340
341
342
343
344
345
346
protected:
    /// @brief protected constructor
    //
    /// By making the constructor protected, we make sure that noone will
    /// ever instantiate that class. Pool4 and Pool6 should be used instead.
    Subnet(const isc::asiolink::IOAddress& prefix, uint8_t len,
           const Triplet<uint32_t>& t1,
           const Triplet<uint32_t>& t2,
           const Triplet<uint32_t>& valid_lifetime);

347
348
349
350
351
352
    /// @brief virtual destructor
    ///
    /// A virtual destructor is needed because other classes
    /// derive from this class.
    virtual ~Subnet() { };

353
354
355
    /// @brief returns the next unique Subnet-ID
    ///
    /// @return the next unique Subnet-ID
356
357
    static SubnetID getNextID() {
        static SubnetID id = 0;
358
359
360
        return (id++);
    }

361
362
363
    /// @brief Check if option is valid and can be added to a subnet.
    ///
    /// @param option option to be validated.
364
    virtual void validateOption(const OptionPtr& option) const = 0;
365

366
367
368
369
    /// @brief subnet-id
    ///
    /// Subnet-id is a unique value that can be used to find or identify
    /// a Subnet4 or Subnet6.
370
    SubnetID id_;
371

372
373
374
    /// @brief collection of pools in that list
    PoolCollection pools_;

375
376
377
378
379
380
381
382
383
384
385
386
387
388
    /// @brief a prefix of the subnet
    isc::asiolink::IOAddress prefix_;

    /// @brief a prefix length of the subnet
    uint8_t prefix_len_;

    /// @brief a tripet (min/default/max) holding allowed renew timer values
    Triplet<uint32_t> t1_;

    /// @brief a tripet (min/default/max) holding allowed rebind timer values
    Triplet<uint32_t> t2_;

    /// @brief a tripet (min/default/max) holding allowed valid lifetime values
    Triplet<uint32_t> valid_;
389
390
391

    /// @brief a collection of DHCP options configured for a subnet.
    OptionContainer options_;
392

393
394
395
396
397
398
399
400
401
402
    /// @brief last allocated address
    ///
    /// This is the last allocated address that was previously allocated from
    /// this particular subnet. Some allocation algorithms (e.g. iterative) use
    /// that value, others do not. It should be noted that although the value
    /// is usually correct, there are cases when it is invalid, e.g. after
    /// removing a pool, restarting or changing allocation algorithms. For
    /// that purpose it should be only considered a help that should not be
    /// fully trusted.
    isc::asiolink::IOAddress last_allocated_;
403
404
};

405
406
407
/// @brief A generic pointer to either Subnet4 or Subnet6 object
typedef boost::shared_ptr<Subnet> SubnetPtr;

408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
/// @brief A configuration holder for IPv4 subnet.
///
/// This class represents an IPv4 subnet.
class Subnet4 : public Subnet {
public:

    /// @brief Constructor with all parameters
    ///
    /// @param prefix Subnet4 prefix
    /// @param length prefix length
    /// @param t1 renewal timer (in seconds)
    /// @param t2 rebind timer (in seconds)
    /// @param valid_lifetime preferred lifetime of leases (in seconds)
    Subnet4(const isc::asiolink::IOAddress& prefix, uint8_t length,
            const Triplet<uint32_t>& t1,
            const Triplet<uint32_t>& t2,
            const Triplet<uint32_t>& valid_lifetime);

protected:
427
428
429
430
431
432

    /// @brief Check if option is valid and can be added to a subnet.
    ///
    /// @param option option to be validated.
    ///
    /// @throw isc::BadValue if provided option is invalid.
433
    virtual void validateOption(const OptionPtr& option) const;
434

435
436
437
438
439
    /// @brief Returns default address for pool selection
    /// @return ANY IPv4 address
    virtual isc::asiolink::IOAddress default_pool() const {
        return (isc::asiolink::IOAddress("0.0.0.0"));
    }
440
441
442
443
444
445
446
447
448
};

/// @brief A pointer to a Subnet4 object
typedef boost::shared_ptr<Subnet4> Subnet4Ptr;

/// @brief A collection of Subnet6 objects
typedef std::vector<Subnet4Ptr> Subnet4Collection;


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
/// @brief A configuration holder for IPv6 subnet.
///
/// This class represents an IPv6 subnet.
class Subnet6 : public Subnet {
public:

    /// @brief Constructor with all parameters
    ///
    /// @param prefix Subnet6 prefix
    /// @param length prefix length
    /// @param t1 renewal timer (in seconds)
    /// @param t2 rebind timer (in seconds)
    /// @param preferred_lifetime preferred lifetime of leases (in seconds)
    /// @param valid_lifetime preferred lifetime of leases (in seconds)
    Subnet6(const isc::asiolink::IOAddress& prefix, uint8_t length,
            const Triplet<uint32_t>& t1,
            const Triplet<uint32_t>& t2,
            const Triplet<uint32_t>& preferred_lifetime,
            const Triplet<uint32_t>& valid_lifetime);

    /// @brief Returns preverred lifetime (in seconds)
    ///
    /// @return a triplet with preferred lifetime
    Triplet<uint32_t> getPreferred() const {
        return (preferred_);
    }

protected:
477
478
479
480
481
482

    /// @brief Check if option is valid and can be added to a subnet.
    ///
    /// @param option option to be validated.
    ///
    /// @throw isc::BadValue if provided option is invalid.
483
    virtual void validateOption(const OptionPtr& option) const;
484

485
486
487
488
489
490
    /// @brief Returns default address for pool selection
    /// @return ANY IPv6 address
    virtual isc::asiolink::IOAddress default_pool() const {
        return (isc::asiolink::IOAddress("::"));
    }

491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
    /// @brief collection of pools in that list
    Pool6Collection pools_;

    /// @brief a triplet with preferred lifetime (in seconds)
    Triplet<uint32_t> preferred_;
};

/// @brief A pointer to a Subnet6 object
typedef boost::shared_ptr<Subnet6> Subnet6Ptr;

/// @brief A collection of Subnet6 objects
typedef std::vector<Subnet6Ptr> Subnet6Collection;

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

#endif // SUBNET_T