component.py 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504
  1. # Copyright (C) 2011 Internet Systems Consortium, Inc. ("ISC")
  2. #
  3. # Permission to use, copy, modify, and distribute this software for any
  4. # purpose with or without fee is hereby granted, provided that the above
  5. # copyright notice and this permission notice appear in all copies.
  6. #
  7. # THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SYSTEMS CONSORTIUM
  8. # DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  9. # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  10. # INTERNET SYSTEMS CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  11. # INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  12. # FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  13. # NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  14. # WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15. """
  16. Module for managing components (abstraction of process). It allows starting
  17. them in given order, handling when they crash (what happens depends on kind
  18. of component) and shutting down. It also handles the configuration of this.
  19. Dependencies between them are not yet handled. It might turn out they are
  20. needed, in that case they will be added sometime in future.
  21. """
  22. import isc.log
  23. from isc.log_messages.bind10_messages import *
  24. import time
  25. logger = isc.log.Logger("boss")
  26. DBG_TRACE_DATA = 20
  27. DBG_TRACE_DETAILED = 80
  28. START_CMD = 'start'
  29. STOP_CMD = 'stop'
  30. STARTED_OK_TIME = 10
  31. STATE_DEAD = 'dead'
  32. STATE_STOPPED = 'stopped'
  33. STATE_RUNNING = 'running'
  34. class Component:
  35. """
  36. This represents a single component. It has some defaults of behaviour,
  37. which should be reasonable for majority of ordinary components, but
  38. it might be inherited and modified for special-purpose components,
  39. like the core modules with different ways of starting up. Another
  40. way to tweak only the start of the component (eg. by providing some
  41. command line parameters) is to set _start_func function from within
  42. inherited class.
  43. The methods are marked if it is expected for them to be overridden.
  44. The component is in one of the three states:
  45. - Stopped - it is either not started yet or it was explicitly stopped.
  46. The component is created in this state (it must be asked to start
  47. explicitly).
  48. - Running - after start() was called, it started successfully and is
  49. now running.
  50. - Dead - it failed and can not be resurrected.
  51. Init
  52. | stop()
  53. | +-----------------------+
  54. | | |
  55. v | start() success |
  56. Stopped --------+--------> Running <----------+
  57. | | |
  58. |failure | failed() |
  59. | | |
  60. v | |
  61. +<-----------+ |
  62. | |
  63. | kind == dispensable or kind|== needed and failed late
  64. +-----------------------------+
  65. |
  66. | kind == core or kind == needed and it failed too soon
  67. v
  68. Dead
  69. """
  70. def __init__(self, process, boss, kind, address=None, params=None):
  71. """
  72. Creates the component in not running mode.
  73. The parameters are:
  74. - `process` is the name of the process to start.
  75. - `boss` the boss object to plug into. The component needs to plug
  76. into it to know when it failed, etc.
  77. - `kind` is the kind of component. It may be one of:
  78. * 'core' means the system can't run without it and it can't be
  79. safely restarted. If it does not start, the system is brought
  80. down. If it crashes, the system is turned off as well (with
  81. non-zero exit status).
  82. * 'needed' means the system is able to restart the component,
  83. but it is vital part of the service (like auth server). If
  84. it fails to start or crashes in less than 10s after the first
  85. startup, the system is brought down. If it crashes later on,
  86. it is restarted.
  87. * 'dispensable' means the component should be running, but if it
  88. doesn't start or crashes for some reason, the system simply tries
  89. to restart it and keeps running.
  90. - `address` is the address on message bus. It is used to ask it to
  91. shut down at the end. If you specialize the class for a component
  92. that is shut down differently, it might be None.
  93. - `params` is a list of parameters to pass to the process when it
  94. starts. It is currently unused and this support is left out for
  95. now.
  96. """
  97. if kind not in ['core', 'needed', 'dispensable']:
  98. raise ValueError('Component kind can not be ' + kind)
  99. self.__state = STATE_STOPPED
  100. self._kind = kind
  101. self._boss = boss
  102. self._process = process
  103. self._start_func = None
  104. self._address = address
  105. self._params = params
  106. self._procinfo = None
  107. def start(self):
  108. """
  109. Start the component for the first time or restart it. If you need to
  110. modify the way a component is started, do not replace this method,
  111. but _start_internal. This one does some more bookkeeping around.
  112. If you try to start an already running component, it raises ValueError.
  113. """
  114. if self.__state == STATE_DEAD:
  115. raise ValueError("Can't resurrect already dead component")
  116. if self.running():
  117. raise ValueError("Can't start already running component")
  118. logger.info(BIND10_COMPONENT_START, self.name())
  119. self.__state = STATE_RUNNING
  120. self.__start_time = time.time()
  121. try:
  122. self._start_internal()
  123. except Exception as e:
  124. logger.error(BIND10_COMPONENT_START_EXCEPTION, self.name(), e)
  125. self.failed(None)
  126. raise
  127. def _start_internal(self):
  128. """
  129. This method does the actual starting of a process. If you need to
  130. change the way the component is started, replace this method.
  131. You can change the "core" of this function by setting self._start_func
  132. to a function without parameters. Such function should start the
  133. process and return the procinfo object describing the running process.
  134. If you don't provide the _start_func, the usual startup by calling
  135. boss.start_simple is performed.
  136. If you override the method completely, you should consider overriding
  137. pid and _stop_internal (and possibly _failed_internal and name) as well.
  138. You should also register any processes started within boss.
  139. """
  140. # This one is not tested. For one, it starts a real process
  141. # which is out of scope of unit tests, for another, it just
  142. # delegates the starting to other function in boss (if a derived
  143. # class does not provide an override function), which is tested
  144. # by use.
  145. if self._start_func is not None:
  146. procinfo = self._start_func()
  147. else:
  148. # TODO Handle params, etc
  149. procinfo = self._boss.start_simple(self._process)
  150. self._procinfo = procinfo
  151. self._boss.register_process(self.pid(), self)
  152. def stop(self):
  153. """
  154. Stop the component. If you need to modify the way a component is
  155. stopped, do not replace this method, but _stop_internal. This one
  156. does some more bookkeeping.
  157. If you try to stop a component that is not running, it raises
  158. ValueError.
  159. """
  160. # This is not tested. It talks with the outher world, which is out
  161. # of scope of unittests.
  162. if not self.running():
  163. raise ValueError("Can't stop a component which is not running")
  164. logger.info(BIND10_COMPONENT_STOP, self.name())
  165. self.__state = STATE_STOPPED
  166. self._stop_internal()
  167. def _stop_internal(self):
  168. """
  169. This is the method that does the actual stopping of a component.
  170. You can replace this method if you want a different way to do it.
  171. If you're overriding this one, you probably want to replace the
  172. _start_internal and pid methods (and maybe _failed_internal and
  173. name as well).
  174. """
  175. self._boss.stop_process(self._process, self._address)
  176. # TODO Some way to wait for the process that doesn't want to
  177. # terminate and kill it would prove nice (or add it to boss somewhere?)
  178. def failed(self, exit_code):
  179. """
  180. Notify the component it crashed. This will be called from boss object.
  181. If you try to call failed on a component that is not running,
  182. a ValueError is raised.
  183. If it is a core component or needed component and it was started only
  184. recently, the component will become dead and will ask the boss to shut
  185. down with error exit status. A dead component can't be started again.
  186. Otherwise the component will try to restart.
  187. The exit code is used for logging. It might be None.
  188. """
  189. logger.error(BIND10_COMPONENT_FAILED, self.name(), self.pid(),
  190. exit_code if exit_code is not None else "unknown")
  191. if not self.running():
  192. raise ValueError("Can't fail component that isn't running")
  193. self.__state = STATE_STOPPED
  194. self._failed_internal()
  195. # If it is a core component or the needed component failed to start
  196. # (including it stopped really soon)
  197. if self._kind == 'core' or \
  198. (self._kind == 'needed' and time.time() - STARTED_OK_TIME <
  199. self.__start_time):
  200. self.__state = STATE_DEAD
  201. logger.fatal(BIND10_COMPONENT_UNSATISFIED, self.name())
  202. self._boss.component_shutdown(1)
  203. # This means we want to restart
  204. else:
  205. logger.warn(BIND10_COMPONENT_RESTART, self.name())
  206. self.start()
  207. def _failed_internal(self):
  208. """
  209. This method is called from failed. You can replace it if you need
  210. some specific behaviour when the component crashes. The default
  211. implementation is empty.
  212. Do not raise exceptions from here, please. The propper shutdown
  213. would have not happened.
  214. """
  215. pass
  216. def running(self):
  217. """
  218. Informs if the component is currently running. It assumes the failed
  219. is called whenever the component really fails and there might be some
  220. time in between actual failure and the call.
  221. It is not expected for this method to be overriden.
  222. """
  223. return self.__state == STATE_RUNNING
  224. def name(self):
  225. """
  226. Returns human-readable name of the component. This is usually the
  227. name of the executable, but it might be something different in a
  228. derived class (in case it is overriden).
  229. """
  230. return self._process
  231. def pid(self):
  232. """
  233. Provides a PID of a process, if the component is real running process.
  234. This implementation expects it to be a real process, but derived class
  235. may return None in case the component is something else.
  236. This returns None in case it is not yet running.
  237. You probably want to override this method if you're providing custom
  238. _start_internal.
  239. """
  240. return self._procinfo.pid if self._procinfo else None
  241. def kill(self, forcefull=False):
  242. """
  243. The component should be forcefully killed. This does not change the
  244. internal state, it just kills the external process and expects a
  245. failure to be reported when the process really dies.
  246. If it isn't running, it does nothing.
  247. If the forcefull is true, it uses SIGKILL instead of SIGTERM.
  248. """
  249. if self._procinfo:
  250. if forcefull:
  251. self._procinfo.process.kill()
  252. else:
  253. self._procinfo.process.terminate()
  254. class Configurator:
  255. """
  256. This thing keeps track of configuration changes and starts and stops
  257. components as it goes. It also handles the inital startup and final
  258. shutdown.
  259. Note that this will allow you to stop (by invoking reconfigure) a core
  260. component. There should be some kind of layer protecting users from ever
  261. doing so (users must not stop the config manager, message queue and stuff
  262. like that or the system won't start again).
  263. The parameters are:
  264. * `boss`: The boss we are managing for.
  265. * `specials`: Dict of specially started components. Each item is a class
  266. representing the component.
  267. The configuration passed to it (by startup() and reconfigure()) is a
  268. dictionary, each item represents one component that should be running.
  269. The key is an unique identifier used to reference the component. The
  270. value is a dictionary describing the component. All items in the
  271. description is optional and they are as follows:
  272. * `special` - Some components are started in a special way. If it is
  273. present, it specifies which class from the specials parameter should
  274. be used to create the component. In that case, some of the following
  275. items might be irrelevant, depending on the special component choosen.
  276. If it is not there, the basic Component class is used.
  277. * `process` - Name of the executable to start. If it is not present,
  278. it defaults to the identifier of the component.
  279. * `kind` - The kind of component, either of 'core', 'needed' and
  280. 'dispensable'. This specifies what happens if the component fails.
  281. Defaults to despensable.
  282. * `address` - The address of the component on message bus. It is used
  283. to shut down the component. All special components currently either
  284. know their own address or don't need one and ignore it. The common
  285. components should provide this.
  286. * `params` - The command line parameters of the executable. Defaults
  287. to no parameters. It is currently unused.
  288. * `priority` - When starting the component, the components with higher
  289. priority are started before the ones with lower priority. If it is
  290. not present, it defaults to 0.
  291. """
  292. def __init__(self, boss, specials = {}):
  293. """
  294. Initializes the configurator, but nothing is started yet.
  295. The boss parameter is the boss object used to start and stop processes.
  296. """
  297. self.__boss = boss
  298. # These could be __private, but as we access them from within unittest,
  299. # it's more comfortable to have them just _protected.
  300. # They are tuples (configuration, component)
  301. self._components = {}
  302. self._running = False
  303. self.__specials = specials
  304. def __reconfigure_internal(self, old, new):
  305. """
  306. Does a switch from one configuration to another.
  307. """
  308. self._run_plan(self._build_plan(old, new))
  309. def startup(self, configuration):
  310. """
  311. Starts the first set of processes. This configuration is expected
  312. to be hardcoded from the boss itself to start the configuration
  313. manager and other similar things.
  314. """
  315. if self._running:
  316. raise ValueError("Trying to start the component configurator " +
  317. "twice")
  318. logger.info(BIND10_CONFIGURATOR_START)
  319. self.__reconfigure_internal(self._components, configuration)
  320. self._running = True
  321. def shutdown(self):
  322. """
  323. Shuts everything down.
  324. """
  325. if not self._running:
  326. raise ValueError("Trying to shutdown the component " +
  327. "configurator while it's not yet running")
  328. logger.info(BIND10_CONFIGURATOR_STOP)
  329. self._running = False
  330. self.__reconfigure_internal(self._components, {})
  331. def reconfigure(self, configuration):
  332. """
  333. Changes configuration from the current one to the provided. It
  334. starts and stops all the components as needed (eg. if there's
  335. a component that was not in the original configuration, it is
  336. started, any component that was in the old and is not in the
  337. new one is stopped).
  338. """
  339. if not self._running:
  340. raise ValueError("Trying to reconfigure the component " +
  341. "configurator while it's not yet running")
  342. logger.info(BIND10_CONFIGURATOR_RECONFIGURE)
  343. self.__reconfigure_internal(self._components, configuration)
  344. def _build_plan(self, old, new):
  345. """
  346. Builds a plan how to transfer from the old configuration to the new
  347. one. It'll be sorted by priority and it will contain the components
  348. (already created, but not started). Each command in the plan is a dict,
  349. so it can be extended any time in future to include whatever
  350. parameters each operation might need.
  351. Any configuration problems are expected to be handled here, so the
  352. plan is not yet run.
  353. """
  354. logger.debug(DBG_TRACE_DATA, BIND10_CONFIGURATOR_BUILD, old, new)
  355. plan = []
  356. # Handle removals of old components
  357. for cname in old.keys():
  358. if cname not in new:
  359. component = self._components[cname][1]
  360. if component.running():
  361. plan.append({
  362. 'command': STOP_CMD,
  363. 'component': component,
  364. 'name': cname
  365. })
  366. # Handle transitions of configuration of what is here
  367. for cname in new.keys():
  368. if cname in old:
  369. for option in ['special', 'process', 'kind', 'address',
  370. 'params']:
  371. if new[cname].get(option) != old[cname][0].get(option):
  372. raise NotImplementedError('Changing configuration of' +
  373. ' a running component is ' +
  374. 'not yet supported. Remove' +
  375. ' and re-add ' + cname +
  376. 'to get the same effect')
  377. # Handle introduction of new components
  378. plan_add = []
  379. for cname in new.keys():
  380. if cname not in old:
  381. component_spec = new[cname]
  382. creator = Component
  383. if 'special' in component_spec:
  384. # TODO: Better error handling
  385. creator = self.__specials[component_spec['special']]
  386. component = creator(component_spec.get('process', cname),
  387. self.__boss,
  388. component_spec.get('kind', 'dispensable'),
  389. component_spec.get('address'),
  390. component_spec.get('params'))
  391. priority = component_spec.get('priority', 0)
  392. # We store tuples, priority first, so we can easily sort
  393. plan_add.append((priority, {
  394. 'component': component,
  395. 'command': START_CMD,
  396. 'name': cname,
  397. 'spec': component_spec
  398. }))
  399. # Push the starts there sorted by priority
  400. plan.extend([command for (_, command) in sorted(plan_add,
  401. reverse=True,
  402. key=lambda command:
  403. command[0])])
  404. return plan
  405. def running(self):
  406. """
  407. Returns if the configurator is running (eg. was started by startup and
  408. not yet stopped by shutdown).
  409. """
  410. return self._running
  411. def _run_plan(self, plan):
  412. """
  413. Run a plan, created beforehand by _build_plan.
  414. With the start and stop commands, it also adds and removes components
  415. in _components.
  416. Currently implemented commands are:
  417. * start
  418. * stop
  419. The plan is a list of tasks, each task is a dictionary. It must contain
  420. at last 'component' (a component object to work with) and 'command'
  421. (the command to do). Currently, both existing commands need 'name' of
  422. the component as well (the identifier from configuration). The 'start'
  423. one needs the 'spec' to be there, which is the configuration description
  424. of the component.
  425. """
  426. done = 0
  427. try:
  428. logger.debug(DBG_TRACE_DATA, BIND10_CONFIGURATOR_RUN, len(plan))
  429. for task in plan:
  430. component = task['component']
  431. command = task['command']
  432. logger.debug(DBG_TRACE_DETAILED, BIND10_CONFIGURATOR_TASK,
  433. command, component.name())
  434. if command == START_CMD:
  435. component.start()
  436. self._components[task['name']] = (task['spec'], component)
  437. elif command == STOP_CMD:
  438. if component.running():
  439. component.stop()
  440. del self._components[task['name']]
  441. else:
  442. # Can Not Happen (as the plans are generated by ourselves).
  443. # Therefore not tested.
  444. raise NotImplementedError("Command unknown: " + command)
  445. done += 1
  446. except:
  447. logger.error(BIND10_CONFIGURATOR_PLAN_INTERRUPTED, done, len(plan))
  448. raise