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 64 65
    /// Currently supported commands are:
    /// - shutdown
    /// - libreload
    /// - config-reload
Francis Dupont's avatar
Francis Dupont committed
66
    /// - leases-reclaim
Francis Dupont's avatar
Francis Dupont committed
67
    /// ...
Tomek Mrugalski's avatar
Tomek Mrugalski committed
68
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
69
    /// @note It never throws.
70
    ///
71
    /// @param command Text representation of the command (e.g. "shutdown")
72
    /// @param args Optional parameters
73 74 75
    ///
    /// @return status of the command
    static isc::data::ConstElementPtr
Tomek Mrugalski's avatar
Tomek Mrugalski committed
76
    processCommand(const std::string& command, isc::data::ConstElementPtr args);
77

Tomek Mrugalski's avatar
Tomek Mrugalski committed
78
    /// @brief configuration processor
79
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
80
    /// This is a method for handling incoming configuration updates.
Tomek Mrugalski's avatar
Tomek Mrugalski committed
81 82
    /// This method should be called by all configuration backends when the
    /// server is starting up or when configuration has changed.
83 84 85 86 87 88 89 90
    ///
    /// 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
91
    processConfig(isc::data::ConstElementPtr new_config);
92

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

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

110
private:
111

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

Tomek Mrugalski's avatar
Tomek Mrugalski committed
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
    /// @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);
144

Tomek Mrugalski's avatar
Tomek Mrugalski committed
145 146 147 148 149 150 151 152 153 154 155 156
    /// @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);
157

158 159 160 161 162 163 164 165
    /// @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
166
    isc::data::ConstElementPtr
167
    commandConfigGetHandler(const std::string& command,
168 169
                            isc::data::ConstElementPtr args);

170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
    /// @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);

187 188 189 190 191 192 193 194 195 196 197 198 199 200
    /// @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
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
    /// @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
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239
    ///
    /// 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
240
    /// @brief Handler for processing 'leases-reclaim' command
241 242
    ///
    /// This handler processes leases-reclaim command, which triggers
Francis Dupont's avatar
Francis Dupont committed
243 244
    /// the leases reclamation immediately.
    /// No limit for processing time or number of processed leases applies.
245 246
    ///
    /// @param command (parameter ignored)
Francis Dupont's avatar
Francis Dupont committed
247 248 249
    /// @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".
250
    ///
Francis Dupont's avatar
Francis Dupont committed
251 252
    /// @return status of the command (should be success unless args
    ///         was not a Bool Element).
253 254 255 256
    isc::data::ConstElementPtr
    commandLeasesReclaimHandler(const std::string& command,
                                isc::data::ConstElementPtr args);

257 258 259 260 261 262 263
    /// @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
264
    /// @param timeout Maximum amount of time that the reclamation routine
265 266 267 268
    /// 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).
269 270 271 272
    /// @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.
273
    void reclaimExpiredLeases(const size_t max_leases, const uint16_t timeout,
274 275 276
                              const bool remove_lease,
                              const uint16_t max_unwarned_cycles);

277 278 279 280 281 282 283 284 285 286 287

    /// @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);

288 289 290 291 292 293 294 295 296 297 298 299 300 301 302
    /// @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_;

303 304 305 306 307 308
};

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

#endif