ctrl_dhcp6_srv.h 11.9 KB
Newer Older
1
// Copyright (C) 2012-2017 Internet Systems Consortium, Inc. ("ISC")
2
//
3 4 5
// 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/.
6 7 8 9

#ifndef CTRL_DHCPV6_SRV_H
#define CTRL_DHCPV6_SRV_H

10
#include <asiolink/asio_wrapper.h>
11
#include <asiolink/asiolink.h>
12
#include <cc/data.h>
13
#include <cc/command_interpreter.h>
14
#include <dhcpsrv/timer_mgr.h>
15
#include <dhcp6/dhcp6_srv.h>
16 17 18 19 20 21

namespace isc {
namespace dhcp {

/// @brief Controlled version of the DHCPv6 server
///
22 23
/// This is a class that is responsible for DHCPv6 server being controllable,
/// by reading configuration file from disk.
24 25 26 27 28 29
class ControlledDhcpv6Srv : public isc::dhcp::Dhcpv6Srv {
public:

    /// @brief Constructor
    ///
    /// @param port UDP port to be opened for DHCP traffic
30
    ControlledDhcpv6Srv(uint16_t port = DHCP6_SERVER_PORT);
31 32

    /// @brief Destructor.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
33
    virtual ~ControlledDhcpv6Srv();
34

35
    /// @brief Initializes the server.
36
    ///
37 38 39
    /// Depending on the configuration backend, it establishes msgq session,
    /// reads the JSON file from disk or may perform any other setup
    /// operation. For specific details, see actual implementation in
Tomek Mrugalski's avatar
Tomek Mrugalski committed
40
    /// *_backend.cc
41
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
42 43
    /// This method may throw if initialization fails. Exception types may be
    /// specific to used configuration backend.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
44
    void init(const std::string& config_file);
45

Tomek Mrugalski's avatar
Tomek Mrugalski committed
46
    /// @brief Performs cleanup, immediately before termination
47
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
48
    /// This method performs final clean up, just before the Dhcpv6Srv object
49
    /// is destroyed. Currently it is a no-op.
50
    void cleanup();
51 52 53 54

    /// @brief Initiates shutdown procedure for the whole DHCPv6 server.
    void shutdown();

Tomek Mrugalski's avatar
Tomek Mrugalski committed
55 56 57 58 59 60 61
    /// @brief command processor
    ///
    /// This method is uniform for all config backends. It processes received
    /// command (as a string + JSON arguments). Internally, it's just a
    /// wrapper that calls process*Command() methods and catches exceptions
    /// in them.
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
62 63
    /// Currently supported commands are:
    /// - config-reload
64
    /// - config-test
Francis Dupont's avatar
Francis Dupont committed
65
    /// - leases-reclaim
66 67
    /// - libreload    
    /// - shutdown
Francis Dupont's avatar
Francis Dupont committed
68
    /// ...
Tomek Mrugalski's avatar
Tomek Mrugalski committed
69
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
70
    /// @note It never throws.
71
    ///
72
    /// @param command Text representation of the command (e.g. "shutdown")
73
    /// @param args Optional parameters
74 75 76
    ///
    /// @return status of the command
    static isc::data::ConstElementPtr
Tomek Mrugalski's avatar
Tomek Mrugalski committed
77
    processCommand(const std::string& command, isc::data::ConstElementPtr args);
78

Tomek Mrugalski's avatar
Tomek Mrugalski committed
79
    /// @brief configuration processor
80
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
81
    /// This is a method for handling incoming configuration updates.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
82 83
    /// This method should be called by all configuration backends when the
    /// server is starting up or when configuration has changed.
84 85 86 87 88 89 90 91
    ///
    /// As pointer to this method is used a callback in ASIO used in
    /// ModuleCCSession, it has to be static.
    ///
    /// @param new_config textual representation of the new configuration
    ///
    /// @return status of the config update
    static isc::data::ConstElementPtr
Tomek Mrugalski's avatar
Tomek Mrugalski committed
92
    processConfig(isc::data::ConstElementPtr new_config);
93

Francis Dupont's avatar
Francis Dupont committed
94 95 96 97
    /// @brief Configuration checker
    ///
    /// This is a method for checking incoming configuration.
    ///
98
    /// @param new_config JSON representation of the new configuration
Francis Dupont's avatar
Francis Dupont committed
99 100 101 102 103
    ///
    /// @return status of the config check
    isc::data::ConstElementPtr
    checkConfig(isc::data::ConstElementPtr new_config);

Tomek Mrugalski's avatar
Tomek Mrugalski committed
104
    /// @brief returns pointer to the sole instance of Dhcpv6Srv
105
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
106
    /// @return server instance (may return NULL, if called before server is spawned)
Tomek Mrugalski's avatar
Tomek Mrugalski committed
107 108 109 110
    static ControlledDhcpv6Srv* getInstance() {
        return (server_);
    }

111
private:
112

Tomek Mrugalski's avatar
Tomek Mrugalski committed
113 114
    /// @brief Callback that will be called from iface_mgr when data
    /// is received over control socket.
115 116
    ///
    /// This static callback method is called from IfaceMgr::receive6() method,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
117
    /// when there is a new command or configuration sent over control socket
118
    /// (that was sent from some yet unspecified sender).
119 120
    static void sessionReader(void);

Tomek Mrugalski's avatar
Tomek Mrugalski committed
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144
    /// @brief handler for processing 'shutdown' command
    ///
    /// This handler processes shutdown command, which initializes shutdown
    /// procedure.
    /// @param command (parameter ignored)
    /// @param args (parameter ignored)
    ///
    /// @return status of the command
    isc::data::ConstElementPtr
    commandShutdownHandler(const std::string& command,
                           isc::data::ConstElementPtr args);

    /// @brief handler for processing 'libreload' command
    ///
    /// This handler processes libreload command, which unloads all hook
    /// libraries and reloads them.
    ///
    /// @param command (parameter ignored)
    /// @param args (parameter ignored)
    ///
    /// @return status of the command
    isc::data::ConstElementPtr
    commandLibReloadHandler(const std::string& command,
                            isc::data::ConstElementPtr args);
145

Tomek Mrugalski's avatar
Tomek Mrugalski committed
146 147 148 149 150 151 152 153 154 155 156 157
    /// @brief handler for processing 'config-reload' command
    ///
    /// This handler processes config-reload command, which processes
    /// configuration specified in args parameter.
    ///
    /// @param command (parameter ignored)
    /// @param args configuration to be processed
    ///
    /// @return status of the command
    isc::data::ConstElementPtr
    commandConfigReloadHandler(const std::string& command,
                               isc::data::ConstElementPtr args);
158

159 160 161 162 163 164 165 166
    /// @brief handler for processing 'get-config' command
    ///
    /// This handler processes get-config command, which retrieves
    /// the current configuration and returns it in response.
    ///
    /// @param command (ignored)
    /// @param args (ignored)
    /// @return current configuration wrapped in a response
167
    isc::data::ConstElementPtr
168
    commandConfigGetHandler(const std::string& command,
169 170
                            isc::data::ConstElementPtr args);

171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187
    /// @brief handler for processing 'write-config' command
    ///
    /// This handle processes write-config comamnd, which writes the
    /// current configuration to disk. This command takes one optional
    /// parameter called filename. If specified, the current configuration
    /// will be written to that file. If not specified, the file used during
    /// Kea start-up will be used. To avoid any exploits, the path is
    /// always relative and .. is not allowed in the filename. This is
    /// a security measure against exploiting file writes remotely.
    ///
    /// @param command (ignored)
    /// @param args may contain optional string argument filename
    /// @return status of the configuration file write
    isc::data::ConstElementPtr
    commandConfigWriteHandler(const std::string& command,
                              isc::data::ConstElementPtr args);

188 189 190 191 192 193 194 195 196 197 198 199 200 201
    /// @brief handler for processing 'set-config' command
    ///
    /// This handler processes set-config command, which processes
    /// configuration specified in args parameter.
    /// @param command (parameter ignored)
    /// @param args configuration to be processed. Expected format:
    /// map containing Dhcp6 map that contains DHCPv6 server configuration.
    /// May also contain Logging map that specifies logging configuration.
    ///
    /// @return status of the command
    isc::data::ConstElementPtr
    commandSetConfigHandler(const std::string& command,
                            isc::data::ConstElementPtr args);

Francis Dupont's avatar
Francis Dupont committed
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216
    /// @brief handler for processing 'config-test' command
    ///
    /// This handler processes config-test command, which checks
    /// configuration specified in args parameter.
    /// @param command (parameter ignored)
    /// @param args configuration to be checked. Expected format:
    /// map containing Dhcp6 map that contains DHCPv6 server configuration.
    /// May also contain Logging map that specifies logging configuration.
    ///
    /// @return status of the command
    isc::data::ConstElementPtr
    commandConfigTestHandler(const std::string& command,
                             isc::data::ConstElementPtr args);

    /// @Brief handler for processing 'version-get' command
Francis Dupont's avatar
Francis Dupont committed
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240
    ///
    /// This handler processes version-get command, which returns
    /// over the control channel the -v and -V command line arguments.
    /// @param command (parameter ignored)
    /// @param args (parameter ignored) 
    ///
    /// @return status of the command with the version in text and
    /// the extended version in arguments.
    isc::data::ConstElementPtr
    commandVersionGetHandler(const std::string& command,
                             isc::data::ConstElementPtr args);

    /// @brief handler for processing 'build-report' command
    ///
    /// This handler processes build-report command, which returns
    /// over the control channel the -W command line argument.
    /// @param command (parameter ignored)
    /// @param args (parameter ignored) 
    ///
    /// @return status of the command with the config report
    isc::data::ConstElementPtr
    commandBuildReportHandler(const std::string& command,
                              isc::data::ConstElementPtr args);

Francis Dupont's avatar
Francis Dupont committed
241
    /// @brief Handler for processing 'leases-reclaim' command
242 243
    ///
    /// This handler processes leases-reclaim command, which triggers
Francis Dupont's avatar
Francis Dupont committed
244 245
    /// the leases reclamation immediately.
    /// No limit for processing time or number of processed leases applies.
246 247
    ///
    /// @param command (parameter ignored)
Francis Dupont's avatar
Francis Dupont committed
248 249 250
    /// @param args arguments map { "remove": <bool> }
    ///        if true a lease is removed when it is reclaimed,
    ///        if false its state is changed to "expired-reclaimed".
251
    ///
Francis Dupont's avatar
Francis Dupont committed
252 253
    /// @return status of the command (should be success unless args
    ///         was not a Bool Element).
254 255 256 257
    isc::data::ConstElementPtr
    commandLeasesReclaimHandler(const std::string& command,
                                isc::data::ConstElementPtr args);

258 259 260 261 262 263 264
    /// @brief Reclaims expired IPv6 leases and reschedules timer.
    ///
    /// This is a wrapper method for @c AllocEngine::reclaimExpiredLeases6.
    /// It reschedules the timer for leases reclamation upon completion of
    /// this method.
    ///
    /// @param max_leases Maximum number of leases to be reclaimed.
Francis Dupont's avatar
Francis Dupont committed
265
    /// @param timeout Maximum amount of time that the reclamation routine
266 267 268 269
    /// may be processing expired leases, expressed in milliseconds.
    /// @param remove_lease A boolean value indicating if the lease should
    /// be removed when it is reclaimed (if true) or it should be left in the
    /// database in the "expired-reclaimed" state (if false).
270 271 272 273
    /// @param max_unwarned_cycles A number of consecutive processing cycles
    /// of expired leases, after which the system issues a warning if there
    /// are still expired leases in the database. If this value is 0, the
    /// warning is never issued.
274
    void reclaimExpiredLeases(const size_t max_leases, const uint16_t timeout,
275 276 277
                              const bool remove_lease,
                              const uint16_t max_unwarned_cycles);

278 279 280 281 282 283 284 285 286 287 288

    /// @brief Deletes reclaimed leases and reschedules the timer.
    ///
    /// This is a wrapper method for @c AllocEngine::deleteExpiredReclaimed6.
    /// It reschedules the timer for leases reclamation upon completion of
    /// this method.
    ///
    /// @param secs Minimum number of seconds after which a lease can be
    /// deleted.
    void deleteExpiredReclaimedLeases(const uint32_t secs);

289 290 291 292 293 294 295 296 297 298 299 300 301 302 303
    /// @brief Static pointer to the sole instance of the DHCP server.
    ///
    /// This is required for config and command handlers to gain access to
    /// the server. Some of them need to be static methods.
    static ControlledDhcpv6Srv* server_;

    /// @brief IOService object, used for all ASIO operations.
    isc::asiolink::IOService io_service_;

    /// @brief Instance of the @c TimerMgr.
    ///
    /// Shared pointer to the instance of timer @c TimerMgr is held here to
    /// make sure that the @c TimerMgr outlives instance of this class.
    TimerMgrPtr timer_mgr_;

304 305 306 307 308 309
};

}; // namespace isc::dhcp
}; // namespace isc

#endif