auth_srv.h 16.8 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
// Copyright (C) 2009  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 __AUTH_SRV_H
#define __AUTH_SRV_H 1

JINMEI Tatuya's avatar
cleanup  
JINMEI Tatuya committed
18 19
#include <string>

20
// For InMemoryClientPtr below.  This should be a temporary definition until
21 22 23
// we reorganize the data source framework.
#include <boost/shared_ptr.hpp>

24
#include <cc/data.h>
25
#include <config/ccsession.h>
26
#include <dns/message.h>
27
#include <dns/opcode.h>
28
#include <util/buffer.h>
29

30 31 32
#include <asiodns/dns_server.h>
#include <asiodns/dns_lookup.h>
#include <asiodns/dns_answer.h>
33 34 35
#include <asiolink/io_message.h>
#include <asiolink/io_service.h>
#include <asiolink/simple_callback.h>
36

37
#include <asiolink/asiolink.h>
38
#include <server_common/portconfig.h>
39
#include <auth/statistics.h>
40

41
namespace isc {
42
namespace datasrc {
43
class InMemoryClient;
44
}
45 46
namespace xfr {
class AbstractXfroutClient;
47
}
48 49 50
namespace dns {
class TSIGKeyRing;
}
51 52
}

53

54 55
/// \brief The implementation class for the \c AuthSrv class using the pimpl
/// idiom.
56
class AuthSrvImpl;
57

58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
/// \brief The authoritative nameserver class.
///
/// \c AuthSrv is a concrete class that implements authoritative DNS server
/// protocol processing.
/// An \c AuthSrv object is primarily responsible for handling incoming DNS
/// requests: It parses the request and dispatches subsequent processing to
/// the corresponding module (which may be an internal library or a separate
/// process) depending on the request type.  For normal queries, the
/// \c AuthSrv object searches configured data sources for the answer to the
/// query, and builds a response containing the answer.
///
/// This class uses the "pimpl" idiom, and hides detailed implementation
/// through the \c impl_ pointer (which points to an instance of the
/// \c AuthSrvImpl class).  An \c AuthSrv object is supposed to exist for quite
/// a long period, and only a few \c AuthSrv objects will be created (in fact,
/// in this current implementation there will only be one object), so the
/// construction overhead of this approach should be acceptable.
///
/// The design of this class is still in flux.  It's quite likely to change
/// in future versions.
78
///
79
class AuthSrv {
80 81 82
    ///
    /// \name Constructors, Assignment Operator and Destructor.
    ///
83 84
    /// Note: The copy constructor and the assignment operator are
    /// intentionally defined as private.
85 86 87 88
    //@{
private:
    AuthSrv(const AuthSrv& source);
    AuthSrv& operator=(const AuthSrv& source);
89
public:
90 91 92 93 94 95 96
    /// The constructor.
    ///
    /// \param use_cache Whether to enable hot spot cache for lookup results.
    /// \param xfrout_client Communication interface with a separate xfrout
    /// process.  It's normally a reference to an xfr::XfroutClient object,
    /// but can refer to a local mock object for testing (or other
    /// experimental) purposes.
97 98
    AuthSrv(const bool use_cache,
            isc::xfr::AbstractXfroutClient& xfrout_client);
99
    ~AuthSrv();
100
    //@}
101

102 103 104 105
    /// Stop the server.
    ///
    /// It stops the internal event loop of the server and subsequently
    /// returns the control to the top level context.
106 107
    ///
    /// This method should never throw an exception.
108 109
    void stop();

110
    /// \brief Process an incoming DNS message, then signal 'server' to resume 
Evan Hunt's avatar
Evan Hunt committed
111 112 113 114 115 116
    ///
    /// A DNS query (or other message) has been received by a \c DNSServer
    /// object.  Find an answer, then post the \c DNSServer object on the
    /// I/O service queue and return.  When the server resumes, it can
    /// send the reply.
    ///
Evan Hunt's avatar
Evan Hunt committed
117
    /// \param io_message The raw message received
118 119
    /// \param message the \c Message object
    /// \param buffer an \c OutputBuffer for the resposne
Evan Hunt's avatar
Evan Hunt committed
120
    /// \param server Pointer to the \c DNSServer
121 122
    ///
    /// \throw isc::Unexpected Protocol type of \a message is unexpected
123
    void processMessage(const isc::asiolink::IOMessage& io_message,
124 125
                        isc::dns::Message& message,
                        isc::util::OutputBuffer& buffer,
126
                        isc::asiodns::DNSServer* server);
Evan Hunt's avatar
Evan Hunt committed
127

128 129 130 131 132 133 134 135 136
    /// \brief Updates the data source for the \c AuthSrv object.
    ///
    /// This method installs or replaces the data source that the \c AuthSrv
    /// object refers to for query processing.
    /// Although the method name is generic, the only thing it does is to
    /// update the data source information.
    /// If there is a data source installed, it will be replaced with the
    /// new one.
    ///
137
    /// In the current implementation, the SQLite data source and InMemoryClient
Jerry's avatar
Jerry committed
138 139 140 141
    /// are assumed.
    /// We can enable memory data source and get the path of SQLite database by
    /// the \c config parameter.  If we disabled memory data source, the SQLite
    /// data source will be used.
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
    ///
    /// On success this method returns a data \c Element (in the form of a
    /// pointer like object) indicating the successful result,
    /// i.e., {"result": [0]}.
    /// Otherwise, it returns a data \c Element explaining the error:
    /// {"result": [1, <error-description>]}.
    ///
    /// This method is mostly exception free (error conditions are represented
    /// via the return value).  But it may still throw a standard exception
    /// if memory allocation fails inside the method.
    /// When a standard exception is thrown or an implementation specific
    /// exception is triggered and caught internally, this function provides
    /// the strong exception guarantee: Unless everything succeeds, currently
    /// installed data source (if any) won't be replaced.
    ///
    /// \param config An immutable pointer-like object to a data \c Element,
    /// possibly containing the data source information to be used.
    /// \return An immutable pointer-like object to a data \c Element
    /// containing the result of the update operation.
161
    isc::data::ConstElementPtr updateConfig(isc::data::ConstElementPtr config);
162

Jeremy C. Reed's avatar
Jeremy C. Reed committed
163
    /// \brief Returns the command and configuration session for the
164 165 166 167 168 169
    /// \c AuthSrv.
    ///
    /// This method never throws an exception.
    ///
    /// \return A pointer to \c ModuleCCSession object stored in the
    /// \c AuthSrv object.  In this implementation it could be NULL.
170
    isc::config::ModuleCCSession* getConfigSession() const;
171

172 173 174 175 176 177 178 179 180 181 182 183 184
    /// \brief Set the command and configuration session for the \c AuthSrv.
    ///
    /// Note: this interface is tentative.  We'll revisit the ASIO and session
    /// frameworks, at which point the session will probably be passed on
    /// construction of the server.
    /// In the current implementation, this method is expected to be called
    /// exactly once as part of initialization.  If this method is called
    /// multiple times, previously specified session is silently overridden.
    ///
    /// This method never throws an exception.
    ///
    /// \param config_session A pointer to \c ModuleCCSession object to receive
    /// control commands and configuration updates.
185
    void setConfigSession(isc::config::ModuleCCSession* config_session);
186 187

    /// \brief Return this object's ASIO IO Service queue
188
    isc::asiolink::IOService& getIOService();
189

190
    /// \brief Return pointer to the DNS Lookup callback function
191
    isc::asiodns::DNSLookup* getDNSLookupProvider() const { return (dns_lookup_); }
192 193

    /// \brief Return pointer to the DNS Answer callback function
194
    isc::asiodns::DNSAnswer* getDNSAnswerProvider() const { return (dns_answer_); }
195 196

    /// \brief Return pointer to the Checkin callback function
197
    isc::asiolink::SimpleCallback* getCheckinProvider() const { return (checkin_); }
198

JINMEI Tatuya's avatar
JINMEI Tatuya committed
199 200 201
    /// \brief Set or update the size (number of slots) of hot spot cache.
    ///
    /// If the specified size is 0, it means the size will be unlimited.
202 203
    /// The specified size is recorded even if the cache is disabled; the
    /// new size will be effective when the cache is enabled.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
204 205 206 207 208 209 210 211
    ///
    /// This method never throws an exception.
    ///
    /// \param slots The number of cache slots.
    void setCacheSlots(const size_t slots);

    /// \brief Get the current size (number of slots) of hot spot cache.
    ///
212 213
    /// It always returns the recorded size regardless of the cache is enabled.
    ///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
214 215 216 217 218
    /// This method never throws an exception.
    ///
    /// \return The current number of cache slots.
    size_t getCacheSlots() const;

219 220
    /// \brief Set the communication session with a separate process for
    /// outgoing zone transfers.
221 222 223 224 225 226 227 228 229 230 231 232
    ///
    /// Note: this interface is tentative.  We'll revisit the ASIO and session
    /// frameworks, at which point the session will probably be passed on
    /// construction of the server.
    ///
    /// \param xfrin_session A Session object over which NOTIFY message
    /// information is exchanged with a XFRIN handler.
    /// The session must be established before setting in the server
    /// object.
    /// Ownership isn't transferred: the caller is responsible for keeping
    /// this object to be valid while the server object is working and for
    /// disconnecting the session and destroying the object when the server
233
    /// is shutdown.
234 235
    ///
    void setXfrinSession(isc::cc::AbstractSession* xfrin_session);
236

237
    /// A shared pointer type for \c InMemoryClient.
238 239 240 241
    ///
    /// This is defined inside the \c AuthSrv class as it's supposed to be
    /// a short term interface until we integrate the in-memory and other
    /// data source frameworks.
242
    typedef boost::shared_ptr<isc::datasrc::InMemoryClient> InMemoryClientPtr;
243

244 245 246
    /// An immutable shared pointer type for \c InMemoryClient.
    typedef boost::shared_ptr<const isc::datasrc::InMemoryClient>
    ConstInMemoryClientPtr;
247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263

    /// Returns the in-memory data source configured for the \c AuthSrv,
    /// if any.
    ///
    /// The in-memory data source is configured per RR class.  However,
    /// the data source may not be available for all RR classes.
    /// If it is not available for the specified RR class, an exception of
    /// class \c InvalidParameter will be thrown.
    /// This method never throws an exception otherwise.
    ///
    /// Even for supported RR classes, the in-memory data source is not
    /// configured by default.  In that case a NULL (shared) pointer will
    /// be returned.
    ///
    /// \param rrclass The RR class of the requested in-memory data source.
    /// \return A pointer to the in-memory data source, if configured;
    /// otherwise NULL.
264
    InMemoryClientPtr getInMemoryClient(const isc::dns::RRClass& rrclass);
265 266 267

    /// Sets or replaces the in-memory data source of the specified RR class.
    ///
268
    /// As noted in \c getInMemoryClient(), some RR classes may not be
269 270 271 272 273 274 275 276 277 278
    /// supported, in which case an exception of class \c InvalidParameter
    /// will be thrown.
    /// This method never throws an exception otherwise.
    ///
    /// If there is already an in memory data source configured, it will be
    /// replaced with the newly specified one.
    /// \c memory_datasrc can be NULL, in which case it will (re)disable the
    /// in-memory data source.
    ///
    /// \param rrclass The RR class of the in-memory data source to be set.
279 280 281
    /// \param memory_datasrc A (shared) pointer to \c InMemoryClient to be set.
    void setInMemoryClient(const isc::dns::RRClass& rrclass,
                           InMemoryClientPtr memory_client);
282

283 284
    /// \brief Set the communication session with Statistics.
    ///
285
    /// This function never throws an exception as far as
286
    /// AuthCounters::setStatisticsSession() doesn't throw.
287 288 289 290 291
    ///
    /// Note: this interface is tentative.  We'll revisit the ASIO and
    /// session frameworks, at which point the session will probably
    /// be passed on construction of the server.
    ///
292
    /// \param statistics_session A Session object over which statistics
293 294 295 296 297 298 299
    /// information is exchanged with statistics module.
    /// The session must be established before setting in the server
    /// object.
    /// Ownership isn't transferred: the caller is responsible for keeping
    /// this object to be valid while the server object is working and for
    /// disconnecting the session and destroying the object when the server
    /// is shutdown.
300
    void setStatisticsSession(isc::cc::AbstractSession* statistics_session);
301

302
    /// Return the interval of periodic submission of statistics in seconds.
303 304 305 306 307 308 309 310 311
    ///
    /// If the statistics submission is disabled, it returns 0.
    ///
    /// This method never throws an exception.
    uint32_t getStatisticsTimerInterval() const;

    /// Set the interval of periodic submission of statistics.
    ///
    /// If the specified value is non 0, the \c AuthSrv object will submit
312
    /// its statistics to the statistics module every \c interval seconds.
313
    /// If it's 0, and \c AuthSrv currently submits statistics, the submission
314 315
    /// will be disabled. \c interval must be equal to or shorter than 86400
    /// seconds (1 day).
316 317 318 319 320
    ///
    /// This method should normally not throw an exception; however, its
    /// underlying library routines may involve resource allocation, and
    /// when it fails it would result in a corresponding standard exception.
    ///
321
    /// \param interval The submission interval in seconds if non 0;
322 323 324
    /// or a value of 0 to disable the submission.
    void setStatisticsTimerInterval(uint32_t interval);

325 326 327
    /// \brief Submit statistics counters to statistics module.
    ///
    /// This function can throw an exception from
328
    /// AuthCounters::submitStatistics().
329 330 331
    ///
    /// \return true on success, false on failure (e.g. session timeout,
    /// session error).
332
    bool submitStatistics() const;
333

334
    /// \brief Get the value of counter in the AuthCounters.
335
    /// 
336 337
    /// This function calls AuthCounters::getCounter() and
    /// returns its return value.
338
    ///
339
    /// This function never throws an exception as far as
340
    /// AuthCounters::getCounter() doesn't throw.
341 342 343
    /// 
    /// Note: Currently this function is for testing purpose only.
    ///
344 345
    /// \param type Type of a counter to get the value of
    ///
346
    /// \return the value of the counter.
347

348
    uint64_t getCounter(const AuthCounters::ServerCounterType type) const;
349

350 351 352 353 354 355 356 357 358 359 360 361 362 363
    /// \brief Get the value of per Opcode counter in the Auth Counters.
    ///
    /// This function calls AuthCounters::getCounter(isc::dns::Opcode) and
    /// returns its return value.
    ///
    /// \note This is a tentative interface as an attempt of experimentally
    /// supporting more statistics counters.  This should eventually be more
    /// generalized.  In any case, this method is mainly for testing.
    ///
    /// \throw None
    /// \param opcode The opcode of the counter to get the value of
    /// \return the value of the counter.
    uint64_t getCounter(const isc::dns::Opcode opcode) const;

364 365 366 367 368 369 370 371 372 373 374 375 376 377
    /// \brief Get the value of per Rcode counter in the Auth Counters.
    ///
    /// This function calls AuthCounters::getCounter(isc::dns::Rcode) and
    /// returns its return value.
    ///
    /// \note This is a tentative interface as an attempt of experimentally
    /// supporting more statistics counters.  This should eventually be more
    /// generalized.  In any case, this method is mainly for testing.
    ///
    /// \throw None
    /// \param rcode The rcode of the counter to get the value of
    /// \return the value of the counter.
    uint64_t getCounter(const isc::dns::Rcode rcode) const;

378 379 380 381 382 383 384 385
    /**
     * \brief Set and get the addresses we listen on.
     */
    void setListenAddresses(const isc::server_common::portconfig::AddressList&
                            addreses);
    const isc::server_common::portconfig::AddressList& getListenAddresses()
        const;

Michal 'vorner' Vaner's avatar
Michal 'vorner' Vaner committed
386
    /// \brief Assign an ASIO DNS Service queue to this Auth object
387
    void setDNSService(isc::asiodns::DNSService& dnss);
388

389 390 391 392 393 394 395 396
    /// \brief Sets the keyring used for verifying and signing
    ///
    /// The parameter is pointer to shared pointer, because the automatic
    /// reloading routines of tsig keys replace the actual keyring object.
    /// It is expected the pointer will point to some statically-allocated
    /// object, it doesn't take ownership of it.
    void setTSIGKeyRing(const boost::shared_ptr<isc::dns::TSIGKeyRing>*
                        keyring);
397

398
private:
399
    AuthSrvImpl* impl_;
400 401 402 403
    isc::asiolink::SimpleCallback* checkin_;
    isc::asiodns::DNSLookup* dns_lookup_;
    isc::asiodns::DNSAnswer* dns_answer_;
    isc::asiodns::DNSService* dnss_;
404 405 406 407
};

#endif // __AUTH_SRV_H

JINMEI Tatuya's avatar
cleanup  
JINMEI Tatuya committed
408 409 410
// Local Variables: 
// mode: c++
// End: