"Fossies" - the Fresh Open Source Software Archive

Member "kea-1.6.2/src/bin/dhcp6/ctrl_dhcp6_srv.h" (21 Feb 2020, 16697 Bytes) of package /linux/misc/kea-1.6.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "ctrl_dhcp6_srv.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.6.1_vs_1.6.2.

    1 // Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC")
    2 //
    3 // This Source Code Form is subject to the terms of the Mozilla Public
    4 // License, v. 2.0. If a copy of the MPL was not distributed with this
    5 // file, You can obtain one at http://mozilla.org/MPL/2.0/.
    6 
    7 #ifndef CTRL_DHCPV6_SRV_H
    8 #define CTRL_DHCPV6_SRV_H
    9 
   10 #include <asiolink/asio_wrapper.h>
   11 #include <asiolink/asiolink.h>
   12 #include <cc/data.h>
   13 #include <cc/command_interpreter.h>
   14 #include <database/database_connection.h>
   15 #include <dhcpsrv/timer_mgr.h>
   16 #include <dhcp6/dhcp6_srv.h>
   17 
   18 namespace isc {
   19 namespace dhcp {
   20 
   21 /// @brief Controlled version of the DHCPv6 server
   22 ///
   23 /// This is a class that is responsible for DHCPv6 server being controllable,
   24 /// by reading configuration file from disk.
   25 class ControlledDhcpv6Srv : public isc::dhcp::Dhcpv6Srv {
   26 public:
   27 
   28     /// @brief Constructor
   29     ///
   30     /// @param server_port UDP port to be opened for DHCP traffic
   31     /// @param client_port UDP port where all responses are sent to.
   32     ControlledDhcpv6Srv(uint16_t server_port = DHCP6_SERVER_PORT,
   33                         uint16_t client_port = 0);
   34 
   35     /// @brief Destructor.
   36     virtual ~ControlledDhcpv6Srv();
   37 
   38     /// @brief Initializes the server.
   39     ///
   40     /// It reads the JSON file from disk or may perform any other setup
   41     /// operation. In particular, it also install signal handlers.
   42     ///
   43     /// This method may throw if initialization fails.
   44     void init(const std::string& config_file);
   45 
   46     /// @brief Loads specific configuration file
   47     ///
   48     /// This utility method is called whenever we know a filename of the config
   49     /// and need to load it. It calls config-set command once the content of
   50     /// the file has been loaded and verified to be a sane JSON configuration.
   51     /// config-set handler will process the config file (apply it as current
   52     /// configuration).
   53     ///
   54     /// @param file_name name of the file to be loaded
   55     /// @return status of the file loading and outcome of config-set
   56     isc::data::ConstElementPtr
   57     loadConfigFile(const std::string& file_name);
   58 
   59     /// @brief Performs cleanup, immediately before termination
   60     ///
   61     /// This method performs final clean up, just before the Dhcpv6Srv object
   62     /// is destroyed. Currently it is a no-op.
   63     void cleanup();
   64 
   65     /// @brief Initiates shutdown procedure for the whole DHCPv6 server.
   66     void shutdown();
   67 
   68     /// @brief command processor
   69     ///
   70     /// This method is uniform for all config backends. It processes received
   71     /// command (as a string + JSON arguments). Internally, it's just a
   72     /// wrapper that calls process*Command() methods and catches exceptions
   73     /// in them.
   74     ///
   75     /// Currently supported commands are:
   76     /// - config-reload
   77     /// - config-test
   78     /// - leases-reclaim
   79     /// - libreload
   80     /// - shutdown
   81     /// ...
   82     ///
   83     /// @note It never throws.
   84     ///
   85     /// @param command Text representation of the command (e.g. "shutdown")
   86     /// @param args Optional parameters
   87     ///
   88     /// @return status of the command
   89     static isc::data::ConstElementPtr
   90     processCommand(const std::string& command, isc::data::ConstElementPtr args);
   91 
   92     /// @brief configuration processor
   93     ///
   94     /// This is a method for handling incoming configuration updates.
   95     /// This method should be called by all configuration backends when the
   96     /// server is starting up or when configuration has changed.
   97     ///
   98     /// As pointer to this method is used a callback in ASIO used in
   99     /// ModuleCCSession, it has to be static.
  100     ///
  101     /// @param new_config textual representation of the new configuration
  102     ///
  103     /// @return status of the config update
  104     static isc::data::ConstElementPtr
  105     processConfig(isc::data::ConstElementPtr new_config);
  106 
  107     /// @brief Configuration checker
  108     ///
  109     /// This is a method for checking incoming configuration.
  110     ///
  111     /// @param new_config JSON representation of the new configuration
  112     ///
  113     /// @return status of the config check
  114     isc::data::ConstElementPtr
  115     checkConfig(isc::data::ConstElementPtr new_config);
  116 
  117     /// @brief returns pointer to the sole instance of Dhcpv6Srv
  118     ///
  119     /// @return server instance (may return NULL, if called before server is spawned)
  120     static ControlledDhcpv6Srv* getInstance() {
  121         return (server_);
  122     }
  123 
  124 private:
  125 
  126     /// @brief Callback that will be called from iface_mgr when data
  127     /// is received over control socket.
  128     ///
  129     /// This static callback method is called from IfaceMgr::receive6() method,
  130     /// when there is a new command or configuration sent over control socket
  131     /// (that was sent from some yet unspecified sender).
  132     static void sessionReader(void);
  133 
  134     /// @brief handler for processing 'shutdown' command
  135     ///
  136     /// This handler processes shutdown command, which initializes shutdown
  137     /// procedure.
  138     /// @param command (parameter ignored)
  139     /// @param args (parameter ignored)
  140     ///
  141     /// @return status of the command
  142     isc::data::ConstElementPtr
  143     commandShutdownHandler(const std::string& command,
  144                            isc::data::ConstElementPtr args);
  145 
  146     /// @brief handler for processing 'libreload' command
  147     ///
  148     /// This handler processes libreload command, which unloads all hook
  149     /// libraries and reloads them.
  150     ///
  151     /// @param command (parameter ignored)
  152     /// @param args (parameter ignored)
  153     ///
  154     /// @return status of the command
  155     isc::data::ConstElementPtr
  156     commandLibReloadHandler(const std::string& command,
  157                             isc::data::ConstElementPtr args);
  158 
  159     /// @brief handler for processing 'config-reload' command
  160     ///
  161     /// This handler processes config-reload command, which processes
  162     /// configuration specified in args parameter.
  163     ///
  164     /// @param command (parameter ignored)
  165     /// @param args configuration to be processed
  166     ///
  167     /// @return status of the command
  168     isc::data::ConstElementPtr
  169     commandConfigReloadHandler(const std::string& command,
  170                                isc::data::ConstElementPtr args);
  171 
  172     /// @brief handler for processing 'get-config' command
  173     ///
  174     /// This handler processes get-config command, which retrieves
  175     /// the current configuration and returns it in response.
  176     ///
  177     /// @param command (ignored)
  178     /// @param args (ignored)
  179     /// @return current configuration wrapped in a response
  180     isc::data::ConstElementPtr
  181     commandConfigGetHandler(const std::string& command,
  182                             isc::data::ConstElementPtr args);
  183 
  184     /// @brief handler for processing 'write-config' command
  185     ///
  186     /// This handle processes write-config command, which writes the
  187     /// current configuration to disk. This command takes one optional
  188     /// parameter called filename. If specified, the current configuration
  189     /// will be written to that file. If not specified, the file used during
  190     /// Kea start-up will be used. To avoid any exploits, the path is
  191     /// always relative and .. is not allowed in the filename. This is
  192     /// a security measure against exploiting file writes remotely.
  193     ///
  194     /// @param command (ignored)
  195     /// @param args may contain optional string argument filename
  196     /// @return status of the configuration file write
  197     isc::data::ConstElementPtr
  198     commandConfigWriteHandler(const std::string& command,
  199                               isc::data::ConstElementPtr args);
  200 
  201     /// @brief handler for processing 'config-set' command
  202     ///
  203     /// This handler processes config-set command, which processes
  204     /// configuration specified in args parameter.
  205     /// @param command (parameter ignored)
  206     /// @param args configuration to be processed. Expected format:
  207     /// map containing Dhcp6 map that contains DHCPv6 server configuration.
  208     /// May also contain Logging map that specifies logging configuration
  209     /// for backward compatibility.
  210     ///
  211     /// @return status of the command
  212     isc::data::ConstElementPtr
  213     commandConfigSetHandler(const std::string& command,
  214                             isc::data::ConstElementPtr args);
  215 
  216     /// @brief handler for processing 'config-test' command
  217     ///
  218     /// This handler processes config-test command, which checks
  219     /// configuration specified in args parameter.
  220     /// @param command (parameter ignored)
  221     /// @param args configuration to be checked. Expected format:
  222     /// map containing Dhcp6 map that contains DHCPv6 server configuration.
  223     /// May also contain Logging map that specifies logging configuration
  224     /// for backward compatibility.
  225     ///
  226     /// @return status of the command
  227     isc::data::ConstElementPtr
  228     commandConfigTestHandler(const std::string& command,
  229                              isc::data::ConstElementPtr args);
  230 
  231     /// @brief A handler for processing 'dhcp-disable' command.
  232     ///
  233     /// @param command command name (ignored).
  234     /// @param args aguments for the command. It must be a map and
  235     /// it may include optional 'max-period' parameter.
  236     ///
  237     /// @return result of the command.
  238     isc::data::ConstElementPtr
  239     commandDhcpDisableHandler(const std::string& command,
  240                               isc::data::ConstElementPtr args);
  241 
  242     /// @brief A handler for processing 'dhcp-enable' command.
  243     ///
  244     /// @param command command name (ignored)
  245     /// @param args arguments for the command (ignored).
  246     ///
  247     /// @return result of the command.
  248     isc::data::ConstElementPtr
  249     commandDhcpEnableHandler(const std::string& command,
  250                              isc::data::ConstElementPtr args);
  251 
  252     /// @Brief handler for processing 'version-get' command
  253     ///
  254     /// This handler processes version-get command, which returns
  255     /// over the control channel the -v and -V command line arguments.
  256     /// @param command (parameter ignored)
  257     /// @param args (parameter ignored)
  258     ///
  259     /// @return status of the command with the version in text and
  260     /// the extended version in arguments.
  261     isc::data::ConstElementPtr
  262     commandVersionGetHandler(const std::string& command,
  263                              isc::data::ConstElementPtr args);
  264 
  265     /// @brief handler for processing 'build-report' command
  266     ///
  267     /// This handler processes build-report command, which returns
  268     /// over the control channel the -W command line argument.
  269     /// @param command (parameter ignored)
  270     /// @param args (parameter ignored)
  271     ///
  272     /// @return status of the command with the config report
  273     isc::data::ConstElementPtr
  274     commandBuildReportHandler(const std::string& command,
  275                               isc::data::ConstElementPtr args);
  276 
  277     /// @brief Handler for processing 'leases-reclaim' command
  278     ///
  279     /// This handler processes leases-reclaim command, which triggers
  280     /// the leases reclamation immediately.
  281     /// No limit for processing time or number of processed leases applies.
  282     ///
  283     /// @param command (parameter ignored)
  284     /// @param args arguments map { "remove": <bool> }
  285     ///        if true a lease is removed when it is reclaimed,
  286     ///        if false its state is changed to "expired-reclaimed".
  287     ///
  288     /// @return status of the command (should be success unless args
  289     ///         was not a Bool Element).
  290     isc::data::ConstElementPtr
  291     commandLeasesReclaimHandler(const std::string& command,
  292                                 isc::data::ConstElementPtr args);
  293 
  294     /// @brief handler for server-tag-get command
  295     ///
  296     /// This method handles the server-tag-get command, which retrieves
  297     /// the current server tag and returns it in response.
  298     ///
  299     /// @param command (ignored)
  300     /// @param args (ignored)
  301     /// @return current configuration wrapped in a response
  302     isc::data::ConstElementPtr
  303     commandServerTagGetHandler(const std::string& command,
  304                                isc::data::ConstElementPtr args);
  305 
  306     /// @brief Reclaims expired IPv6 leases and reschedules timer.
  307     ///
  308     /// This is a wrapper method for @c AllocEngine::reclaimExpiredLeases6.
  309     /// It reschedules the timer for leases reclamation upon completion of
  310     /// this method.
  311     ///
  312     /// @param max_leases Maximum number of leases to be reclaimed.
  313     /// @param timeout Maximum amount of time that the reclamation routine
  314     /// may be processing expired leases, expressed in milliseconds.
  315     /// @param remove_lease A boolean value indicating if the lease should
  316     /// be removed when it is reclaimed (if true) or it should be left in the
  317     /// database in the "expired-reclaimed" state (if false).
  318     /// @param max_unwarned_cycles A number of consecutive processing cycles
  319     /// of expired leases, after which the system issues a warning if there
  320     /// are still expired leases in the database. If this value is 0, the
  321     /// warning is never issued.
  322     void reclaimExpiredLeases(const size_t max_leases, const uint16_t timeout,
  323                               const bool remove_lease,
  324                               const uint16_t max_unwarned_cycles);
  325 
  326 
  327     /// @brief Deletes reclaimed leases and reschedules the timer.
  328     ///
  329     /// This is a wrapper method for @c AllocEngine::deleteExpiredReclaimed6.
  330     /// It reschedules the timer for leases reclamation upon completion of
  331     /// this method.
  332     ///
  333     /// @param secs Minimum number of seconds after which a lease can be
  334     /// deleted.
  335     void deleteExpiredReclaimedLeases(const uint32_t secs);
  336 
  337     /// @brief Attempts to reconnect the server to the DB backend managers
  338     ///
  339     /// This is a self-rescheduling function that attempts to reconnect to the
  340     /// server's DB backends after connectivity to one or more have been
  341     /// lost.  Upon entry it will attempt to reconnect via @ref CfgDdbAccess::
  342     /// createManagers.  If this is succesful, DHCP servicing is re-enabled and
  343     /// server returns to normal operation.
  344     ///
  345     /// If reconnection fails and the maximum number of retries has not been
  346     /// exhausted, it will schedule a call to itself to occur at the
  347     /// configured retry interval. DHCP service remains disabled.
  348     ///
  349     /// If the maximum number of retries has been exhausted an error is logged
  350     /// and the server shuts down.
  351     /// @param db_reconnect_ctl pointer to the ReconnectCtl containing the
  352     /// configured reconnect parameters
  353     ///
  354     void dbReconnect(db::ReconnectCtlPtr db_reconnect_ctl);
  355 
  356     /// @brief Callback DB backends should invoke upon loss of connectivity
  357     ///
  358     /// This function is invoked by DB backends when they detect a loss of
  359     /// connectivity.  The parameter, db_reconnect_ctl, conveys the configured
  360     /// maximum number of reconnect retries as well as the interval to wait
  361     /// between retry attempts.
  362     ///
  363     /// If either value is zero, reconnect is presumed to be disabled and
  364     /// the function will schedule a shutdown and return false.  This instructs
  365     /// the DB backend layer (the caller) to treat the connectivity loss as fatal.
  366     ///
  367     /// Otherwise, the function saves db_reconnect_ctl and invokes
  368     /// dbReconnect to initiate the reconnect process.
  369     ///
  370     /// @param db_reconnect_ctl pointer to the ReconnectCtl containing the
  371     /// configured reconnect parameters
  372     bool dbLostCallback(db::ReconnectCtlPtr db_reconnect_ctl);
  373 
  374     /// @brief Callback invoked periodically to fetch configuration updates
  375     /// from the Config Backends.
  376     ///
  377     /// This method calls @c CBControlDHCPv6::databaseConfigFetch and then
  378     /// reschedules the timer.
  379     ///
  380     /// @param srv_cfg Server configuration holding the database credentials
  381     /// and server tag.
  382     /// @param failure_count pointer to failure counter which causes this
  383     /// callback to stop scheduling the timer after 10 consecutive failures
  384     /// to fetch the updates.
  385     void cbFetchUpdates(const SrvConfigPtr& srv_cfg,
  386                         boost::shared_ptr<unsigned> failure_count);
  387 
  388     /// @brief Static pointer to the sole instance of the DHCP server.
  389     ///
  390     /// This is required for config and command handlers to gain access to
  391     /// the server. Some of them need to be static methods.
  392     static ControlledDhcpv6Srv* server_;
  393 
  394     /// @brief IOService object, used for all ASIO operations.
  395     isc::asiolink::IOService io_service_;
  396 
  397     /// @brief Instance of the @c TimerMgr.
  398     ///
  399     /// Shared pointer to the instance of timer @c TimerMgr is held here to
  400     /// make sure that the @c TimerMgr outlives instance of this class.
  401     TimerMgrPtr timer_mgr_;
  402 };
  403 
  404 }; // namespace isc::dhcp
  405 }; // namespace isc
  406 
  407 #endif