ctrl_dhcp6_srv.h 11 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
Tomek Mrugalski's avatar
Tomek Mrugalski committed
67
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
68
    /// @note It never throws.
69
    ///
70
    /// @param command Text representation of the command (e.g. "shutdown")
71
    /// @param args Optional parameters
72 73 74
    ///
    /// @return status of the command
    static isc::data::ConstElementPtr
Tomek Mrugalski's avatar
Tomek Mrugalski committed
75
    processCommand(const std::string& command, isc::data::ConstElementPtr args);
76

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

Tomek Mrugalski's avatar
Tomek Mrugalski committed
92
    /// @brief returns pointer to the sole instance of Dhcpv6Srv
93
    ///
Tomek Mrugalski's avatar
Tomek Mrugalski committed
94
    /// @return server instance (may return NULL, if called before server is spawned)
Tomek Mrugalski's avatar
Tomek Mrugalski committed
95 96 97 98
    static ControlledDhcpv6Srv* getInstance() {
        return (server_);
    }

99
private:
100

Tomek Mrugalski's avatar
Tomek Mrugalski committed
101 102
    /// @brief Callback that will be called from iface_mgr when data
    /// is received over control socket.
103 104
    ///
    /// This static callback method is called from IfaceMgr::receive6() method,
Tomek Mrugalski's avatar
Tomek Mrugalski committed
105
    /// when there is a new command or configuration sent over control socket
106
    /// (that was sent from some yet unspecified sender).
107 108
    static void sessionReader(void);

Tomek Mrugalski's avatar
Tomek Mrugalski committed
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
    /// @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);
133

Tomek Mrugalski's avatar
Tomek Mrugalski committed
134 135 136 137 138 139 140 141 142 143 144 145
    /// @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);
146

147 148 149 150 151 152 153 154
    /// @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
155
    isc::data::ConstElementPtr
156
    commandConfigGetHandler(const std::string& command,
157 158
                            isc::data::ConstElementPtr args);

159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
    /// @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);

176 177 178 179 180 181 182 183 184 185 186 187 188 189
    /// @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
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
    /// @brief handler for processing 'version-get' command
    ///
    /// 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
215
    /// @brief Handler for processing 'leases-reclaim' command
216 217
    ///
    /// This handler processes leases-reclaim command, which triggers
Francis Dupont's avatar
Francis Dupont committed
218 219
    /// the leases reclamation immediately.
    /// No limit for processing time or number of processed leases applies.
220 221
    ///
    /// @param command (parameter ignored)
Francis Dupont's avatar
Francis Dupont committed
222 223 224
    /// @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".
225
    ///
Francis Dupont's avatar
Francis Dupont committed
226 227
    /// @return status of the command (should be success unless args
    ///         was not a Bool Element).
228 229 230 231
    isc::data::ConstElementPtr
    commandLeasesReclaimHandler(const std::string& command,
                                isc::data::ConstElementPtr args);

232 233 234 235 236 237 238
    /// @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
239
    /// @param timeout Maximum amount of time that the reclamation routine
240 241 242 243
    /// 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).
244 245 246 247
    /// @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.
248
    void reclaimExpiredLeases(const size_t max_leases, const uint16_t timeout,
249 250 251
                              const bool remove_lease,
                              const uint16_t max_unwarned_cycles);

252 253 254 255 256 257 258 259 260 261 262

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

263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
    /// @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_;

278 279 280 281 282 283
};

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

#endif