Coverage for src/lib/python/isc/bind10/component : 94%
Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
|
# Copyright (C) 2011 Internet Systems Consortium, Inc. ("ISC") # # Permission to use, copy, modify, and 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 INTERNET SYSTEMS CONSORTIUM # DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL # INTERNET SYSTEMS CONSORTIUM 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.
Module for managing components (abstraction of process). It allows starting them in given order, handling when they crash (what happens depends on kind of component) and shutting down. It also handles the configuration of this.
Dependencies between them are not yet handled. It might turn out they are needed, in that case they will be added sometime in future.
This framework allows for a single process to be started multiple times (by specifying multiple components with the same configuration). We might want to add a more convenient support (like providing a count argument to the configuration). This is yet to be designed. """
"""Return the symbolic name for a signal.""" return "unknown signal"
""" This represents a single component. This one is an abstract base class. There are some methods which should be left untouched, but there are others which define the interface only and should be overriden in concrete implementations.
The component is in one of the three states: - Stopped - it is either not started yet or it was explicitly stopped. The component is created in this state (it must be asked to start explicitly). - Running - after start() was called, it started successfully and is now running. - Dead - it failed and can not be resurrected.
Init | stop() | +-----------------------+ | | | v | start() success | Stopped --------+--------> Running <----------+ | | | |failure | failed() | | | | v | | +<-----------+ | | | | kind == dispensable or kind|== needed and failed late +-----------------------------+ | | kind == core or kind == needed and it failed too soon v Dead
Note that there are still situations which are not handled properly here. We don't recognize a component that is starting up, but not ready yet, one that is already shutting down, impossible to stop, etc. We need to add more states in future to handle it properly. """ """ Creates the component in not running mode.
The parameters are: - `boss` the boss object to plug into. The component needs to plug into it to know when it failed, etc. - `kind` is the kind of component. It may be one of: * 'core' means the system can't run without it and it can't be safely restarted. If it does not start, the system is brought down. If it crashes, the system is turned off as well (with non-zero exit status). * 'needed' means the system is able to restart the component, but it is vital part of the service (like auth server). If it fails to start or crashes in less than 10s after the first startup, the system is brought down. If it crashes later on, it is restarted (see below). * 'dispensable' means the component should be running, but if it doesn't start or crashes for some reason, the system simply tries to restart it and keeps running.
For components that are restarted, the restarts are not always immediate; if the component has run for more than COMPONENT_RESTART_DELAY (10) seconds, they are restarted right away. If the component has not run that long, the system waits until that time has passed (since the last start) until the component is restarted.
Note that the __init__ method of child class should have these parameters:
__init__(self, process, boss, kind, address=None, params=None)
The extra parameters are: - `process` - which program should be started. - `address` - the address on message bus, used to talk to the component. - `params` - parameters to the program.
The methods you should not override are: - start - stop - failed - running
You should override: - _start_internal - _stop_internal - _failed_internal (if you like, the empty default might be suitable) - name - pid - kill """
""" Start the component for the first time or restart it. It runs _start_internal to actually start the component.
If you try to start an already running component, it raises ValueError. """
""" Stop the component. It calls _stop_internal to do the actual stopping.
If you try to stop a component that is not running, it raises ValueError. """ # This is not tested. It talks with the outher world, which is out # of scope of unittests.
""" Notify the component it crashed. This will be called from boss object.
If you try to call failed on a component that is not running, a ValueError is raised.
If it is a core component or needed component and it was started only recently, the component will become dead and will ask the boss to shut down with error exit status. A dead component can't be started again.
Otherwise the component will try to restart.
The exit code is used for logging. It might be None.
It calls _failed_internal internally.
Returns True if the process was immediately restarted, returns False is the process was not restarted, either because it is considered a core or needed component, or because the component is to be restarted later. """
exit_str = "process exited normally with exit status %d" % (exit_code) exit_str = "process dumped core with exit status %d (killed by signal %d: %s)" % (exit_code, sig, signame) else: else: exit_str = "unknown condition with exit status %d" % (exit_code) else:
exit_str) # If it is a core component or the needed component failed to start # (including it stopped really soon) (self._kind == 'needed' and time.time() - STARTED_OK_TIME < self._original_start_time): # This means we want to restart else: # if the component was only running for a short time, don't # restart right away, but set a time it wants to restarted, # and return that it wants to be restarted later
"""Calculates and sets the time this component should be restarted. Currently, it uses a very basic algorithm; start time + RESTART_DELAY (10 seconds). This algorithm may be improved upon in the future. """
"""Returns the time at which this component should be restarted."""
"""Restarts the component if it has a restart_time and if the value of the restart_time is smaller than 'now'.
If the parameter 'now' is given, its value will be used instead of calling time.time().
Returns True if the component is restarted, False if not.""" self.get_restart_time() < now: else:
""" Informs if the component is currently running. It assumes the failed is called whenever the component really fails and there might be some time in between actual failure and the call, so this might be inaccurate (it corresponds to the thing the object thinks is true, not to the real "external" state).
It is not expected for this method to be overriden. """
""" This method does the actual starting of a process. You need to override this method to do the actual starting.
The ability to override this method presents some flexibility. It allows processes started in a strange way, as well as components that have no processes at all or components with multiple processes (in case of multiple processes, care should be taken to make their started/stopped state in sync and all the processes that can fail should be registered).
You should register all the processes created by calling self._boss.register_process. """ pass
""" This is the method that does the actual stopping of a component. You need to provide it in a concrete implementation.
Also, note that it is a bad idea to raise exceptions from here. Under such circumstance, the component will be considered stopped, and the exception propagated, but we can't be sure it really is dead. """ pass
""" This method is called from failed. You can replace it if you need some specific behaviour when the component crashes. The default implementation is empty.
Do not raise exceptions from here, please. The propper shutdown would have not happened. """
""" Provides human readable name of the component, for logging and similar purposes.
You need to provide this method in a concrete implementation. """
""" Provides a PID of a process, if the component is real running process. This may return None in cases when there's no process involved with the component or in case the component is not started yet.
However, it is expected the component preserves the pid after it was stopped, to ensure we can log it when we ask it to be killed (in case the process refused to stop willingly).
You need to provide this method in a concrete implementation. """
""" Kills the component.
If forcefull is true, it should do it in more direct and aggressive way (for example by using SIGKILL or some equivalent). If it is false, more peaceful way should be used (SIGTERM or equivalent).
You need to provide this method in a concrete implementation. """ pass
""" The most common implementation of a component. It can be used either directly, and it will just start the process without anything special, or slightly customised by passing a start_func hook to the __init__ to change the way it starts.
If such customisation isn't enough, you should inherit BaseComponent directly. It is not recommended to override methods of this class on one-by-one basis. """ start_func=None): """ Creates the component in not running mode.
The parameters are: - `process` is the name of the process to start. - `boss` the boss object to plug into. The component needs to plug into it to know when it failed, etc. - `kind` is the kind of component. Refer to the documentation of BaseComponent for details. - `address` is the address on message bus. It is used to ask it to shut down at the end. If you specialize the class for a component that is shut down differently, it might be None. - `params` is a list of parameters to pass to the process when it starts. It is currently unused and this support is left out for now. - `start_func` is a function called when it is started. It is supposed to start up the process and return a ProcInfo object describing it. There's a sensible default if not provided, which just launches the program without any special care. """
""" You can change the "core" of this function by setting self._start_func to a function without parameters. Such function should start the process and return the procinfo object describing the running process.
If you don't provide the _start_func, the usual startup by calling boss.start_simple is performed. """ # This one is not tested. For one, it starts a real process # which is out of scope of unit tests, for another, it just # delegates the starting to other function in boss (if a derived # class does not provide an override function), which is tested # by use. else: # TODO Handle params, etc
# TODO Some way to wait for the process that doesn't want to # terminate and kill it would prove nice (or add it to boss somewhere?)
""" Returns the name, derived from the process name. """
else:
""" This thing keeps track of configuration changes and starts and stops components as it goes. It also handles the inital startup and final shutdown.
Note that this will allow you to stop (by invoking reconfigure) a core component. There should be some kind of layer protecting users from ever doing so (users must not stop the config manager, message queue and stuff like that or the system won't start again). However, if a user specifies b10-auth as core, it is safe to stop that one.
The parameters are: * `boss`: The boss we are managing for. * `specials`: Dict of specially started components. Each item is a class representing the component.
The configuration passed to it (by startup() and reconfigure()) is a dictionary, each item represents one component that should be running. The key is an unique identifier used to reference the component. The value is a dictionary describing the component. All items in the description is optional unless told otherwise and they are as follows: * `special` - Some components are started in a special way. If it is present, it specifies which class from the specials parameter should be used to create the component. In that case, some of the following items might be irrelevant, depending on the special component chosen. If it is not there, the basic Component class is used. * `process` - Name of the executable to start. If it is not present, it defaults to the identifier of the component. * `kind` - The kind of component, either of 'core', 'needed' and 'dispensable'. This specifies what happens if the component fails. This one is required. * `address` - The address of the component on message bus. It is used to shut down the component. All special components currently either know their own address or don't need one and ignore it. The common components should provide this. * `params` - The command line parameters of the executable. Defaults to no parameters. It is currently unused. * `priority` - When starting the component, the components with higher priority are started before the ones with lower priority. If it is not present, it defaults to 0. """ """ Initializes the configurator, but nothing is started yet.
The boss parameter is the boss object used to start and stop processes. """ # These could be __private, but as we access them from within unittest, # it's more comfortable to have them just _protected.
# They are tuples (configuration, component)
""" Does a switch from one configuration to another. """
""" Starts the first set of processes. This configuration is expected to be hardcoded from the boss itself to start the configuration manager and other similar things. """ "twice")
""" Shuts everything down.
It is not expected that anyone would want to shutdown and then start the configurator again, so we don't explicitly make sure that would work. However, we are not aware of anything that would make it not work either. """ "configurator while it's not yet running")
""" Changes configuration from the current one to the provided. It starts and stops all the components as needed (eg. if there's a component that was not in the original configuration, it is started, any component that was in the old and is not in the new one is stopped). """ "configurator while it's not yet running")
""" Builds a plan how to transfer from the old configuration to the new one. It'll be sorted by priority and it will contain the components (already created, but not started). Each command in the plan is a dict, so it can be extended any time in future to include whatever parameters each operation might need.
Any configuration problems are expected to be handled here, so the plan is not yet run. """ # Handle removals of old components 'command': STOP_CMD, 'component': component, 'name': cname }) # Handle transitions of configuration of what is here 'params']: ' a running component is ' + 'not yet supported. Remove' + ' and re-add ' + cname + ' to get the same effect') # Handle introduction of new components # TODO: Better error handling self.__boss, component_config['kind'], component_config.get('address'), component_config.get('params')) # We store tuples, priority first, so we can easily sort 'component': component, 'command': START_CMD, 'name': cname, 'config': component_config })) # Push the starts there sorted by priority reverse=True, key=lambda command: command[0])])
""" Returns if the configurator is running (eg. was started by startup and not yet stopped by shutdown). """
""" Run a plan, created beforehand by _build_plan.
With the start and stop commands, it also adds and removes components in _components.
Currently implemented commands are: * start * stop
The plan is a list of tasks, each task is a dictionary. It must contain at last 'component' (a component object to work with) and 'command' (the command to do). Currently, both existing commands need 'name' of the component as well (the identifier from configuration). The 'start' one needs the 'config' to be there, which is the configuration description of the component. """ command, component.name()) component) else: # Can Not Happen (as the plans are generated by ourselves). # Therefore not tested. raise NotImplementedError("Command unknown: " + command) |