ccsession.py 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437
  1. # Copyright (C) 2009 Internet Systems Consortium.
  2. # Copyright (C) 2010 CZ NIC
  3. #
  4. # Permission to use, copy, modify, and distribute this software for any
  5. # purpose with or without fee is hereby granted, provided that the above
  6. # copyright notice and this permission notice appear in all copies.
  7. #
  8. # THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SYSTEMS CONSORTIUM
  9. # DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
  10. # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
  11. # INTERNET SYSTEMS CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. # INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
  13. # FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  14. # NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
  15. # WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16. #
  17. # Client-side functionality for configuration and commands
  18. #
  19. # It keeps a cc-channel session with the configuration manager daemon,
  20. # and handles configuration updates and direct commands
  21. # modeled after ccsession.h/cc 'protocol' changes here need to be
  22. # made there as well
  23. """Classes and functions for handling configuration and commands
  24. This module provides the ModuleCCSession and UICCSession classes,
  25. as well as a set of utility functions to create and parse messages
  26. related to commands and configuration
  27. Modules should use the ModuleCCSession class to connect to the
  28. configuration manager, and receive updates and commands from
  29. other modules.
  30. Configuration user interfaces should use the UICCSession to connect
  31. to b10-cmdctl, and receive and send configuration and commands
  32. through that to the configuration manager.
  33. """
  34. from isc.cc import Session
  35. from isc.config.config_data import ConfigData, MultiConfigData, BIND10_CONFIG_DATA_VERSION
  36. import isc
  37. class ModuleCCSessionError(Exception): pass
  38. def parse_answer(msg):
  39. """Returns a tuple (rcode, value), where value depends on the
  40. command that was called. If rcode != 0, value is a string
  41. containing an error message"""
  42. if type(msg) != dict:
  43. raise ModuleCCSessionError("Answer message is not a dict: " + str(msg))
  44. if 'result' not in msg:
  45. raise ModuleCCSessionError("answer message does not contain 'result' element")
  46. elif type(msg['result']) != list:
  47. raise ModuleCCSessionError("wrong result type in answer message")
  48. elif len(msg['result']) < 1:
  49. raise ModuleCCSessionError("empty result list in answer message")
  50. elif type(msg['result'][0]) != int:
  51. raise ModuleCCSessionError("wrong rcode type in answer message")
  52. else:
  53. if len(msg['result']) > 1:
  54. if (msg['result'][0] != 0 and type(msg['result'][1]) != str):
  55. raise ModuleCCSessionError("rcode in answer message is non-zero, value is not a string")
  56. return msg['result'][0], msg['result'][1]
  57. else:
  58. return msg['result'][0], None
  59. def create_answer(rcode, arg = None):
  60. """Creates an answer packet for config&commands. rcode must be an
  61. integer. If rcode == 0, arg is an optional value that depends
  62. on what the command or option was. If rcode != 0, arg must be
  63. a string containing an error message"""
  64. if type(rcode) != int:
  65. raise ModuleCCSessionError("rcode in create_answer() must be an integer")
  66. if rcode != 0 and type(arg) != str:
  67. raise ModuleCCSessionError("arg in create_answer for rcode != 0 must be a string describing the error")
  68. if arg != None:
  69. return { 'result': [ rcode, arg ] }
  70. else:
  71. return { 'result': [ rcode ] }
  72. # 'fixed' commands
  73. """Fixed names for command and configuration messages"""
  74. COMMAND_CONFIG_UPDATE = "config_update"
  75. COMMAND_MODULE_SPECIFICATION_UPDATE = "module_specification_update"
  76. COMMAND_GET_COMMANDS_SPEC = "get_commands_spec"
  77. COMMAND_GET_CONFIG = "get_config"
  78. COMMAND_SET_CONFIG = "set_config"
  79. COMMAND_GET_MODULE_SPEC = "get_module_spec"
  80. COMMAND_MODULE_SPEC = "module_spec"
  81. COMMAND_SHUTDOWN = "shutdown"
  82. def parse_command(msg):
  83. """Parses what may be a command message. If it looks like one,
  84. the function returns (command, value) where command is a
  85. string. If it is not, this function returns None, None"""
  86. if type(msg) == dict and len(msg.items()) == 1:
  87. cmd, value = msg.popitem()
  88. if cmd == "command" and type(value) == list:
  89. if len(value) == 1 and type(value[0]) == str:
  90. return value[0], None
  91. elif len(value) > 1 and type(value[0]) == str:
  92. return value[0], value[1]
  93. return None, None
  94. def create_command(command_name, params = None):
  95. """Creates a module command message with the given command name (as
  96. specified in the module's specification, and an optional params
  97. object"""
  98. # TODO: validate_command with spec
  99. if type(command_name) != str:
  100. raise ModuleCCSessionError("command in create_command() not a string")
  101. cmd = [ command_name ]
  102. if params:
  103. cmd.append(params)
  104. msg = { 'command': cmd }
  105. return msg
  106. class ModuleCCSession(ConfigData):
  107. """This class maintains a connection to the command channel, as
  108. well as configuration options for modules. The module provides
  109. a specification file that contains the module name, configuration
  110. options, and commands. It also gives the ModuleCCSession two callback
  111. functions, one to call when there is a direct command to the
  112. module, and one to update the configuration run-time. These
  113. callbacks are called when 'check_command' is called on the
  114. ModuleCCSession"""
  115. def __init__(self, spec_file_name, config_handler, command_handler, cc_session = None):
  116. """Initialize a ModuleCCSession. This does *NOT* send the
  117. specification and request the configuration yet. Use start()
  118. for that once the ModuleCCSession has been initialized.
  119. specfile_name is the path to the specification file
  120. config_handler and command_handler are callback functions,
  121. see set_config_handler and set_command_handler for more
  122. information on their signatures."""
  123. module_spec = isc.config.module_spec_from_file(spec_file_name)
  124. ConfigData.__init__(self, module_spec)
  125. self._module_name = module_spec.get_module_name()
  126. self.set_config_handler(config_handler)
  127. self.set_command_handler(command_handler)
  128. if not cc_session:
  129. self._session = Session()
  130. else:
  131. self._session = cc_session
  132. self._session.group_subscribe(self._module_name, "*")
  133. self._remote_module_configs = {}
  134. def __del__(self):
  135. self._session.group_unsubscribe(self._module_name, "*")
  136. for module_name in self._remote_module_configs:
  137. self._session.group_unsubscribe(module_name)
  138. def start(self):
  139. """Send the specification for this module to the configuration
  140. manager, and request the current non-default configuration.
  141. The config_handler will be called with that configuration"""
  142. self.__send_spec()
  143. self.__request_config()
  144. def get_socket(self):
  145. """Returns the socket from the command channel session. This
  146. should *only* be used for select() loops to see if there
  147. is anything on the channel. If that loop is not completely
  148. time-critical, it is strongly recommended to only use
  149. check_command(), and not look at the socket at all."""
  150. return self._session._socket
  151. def close(self):
  152. """Close the session to the command channel"""
  153. self._session.close()
  154. def check_command(self, nonblock=True):
  155. """Check whether there is a command or configuration update on
  156. the channel. This function does a read on the cc session, and
  157. returns nothing.
  158. It calls check_command_without_recvmsg()
  159. to parse the received message.
  160. If nonblock is True, it just checks if there's a command
  161. and does nothing if there isn't. If nonblock is False, it
  162. waits until it arrives. It temporarily sets timeout to infinity,
  163. because commands may not come in arbitrary long time."""
  164. timeout_orig = self._session.get_timeout()
  165. self._session.set_timeout(0)
  166. try:
  167. msg, env = self._session.group_recvmsg(nonblock)
  168. finally:
  169. self._session.set_timeout(timeout_orig)
  170. self.check_command_without_recvmsg(msg, env)
  171. def check_command_without_recvmsg(self, msg, env):
  172. """Parse the given message to see if there is a command or a
  173. configuration update. Calls the corresponding handler
  174. functions if present. Responds on the channel if the
  175. handler returns a message."""
  176. # should we default to an answer? success-by-default? unhandled error?
  177. if msg is not None and not 'result' in msg:
  178. answer = None
  179. try:
  180. module_name = env['group']
  181. cmd, arg = isc.config.ccsession.parse_command(msg)
  182. if cmd == COMMAND_CONFIG_UPDATE:
  183. new_config = arg
  184. # If the target channel was not this module
  185. # it might be in the remote_module_configs
  186. if module_name != self._module_name:
  187. if module_name in self._remote_module_configs:
  188. # no checking for validity, that's up to the
  189. # module itself.
  190. newc = self._remote_module_configs[module_name].get_local_config()
  191. isc.cc.data.merge(newc, new_config)
  192. self._remote_module_configs[module_name].set_local_config(newc)
  193. # For other modules, we're not supposed to answer
  194. return
  195. # ok, so apparently this update is for us.
  196. errors = []
  197. if not self._config_handler:
  198. answer = create_answer(2, self._module_name + " has no config handler")
  199. elif not self.get_module_spec().validate_config(False, new_config, errors):
  200. answer = create_answer(1, ", ".join(errors))
  201. else:
  202. isc.cc.data.remove_identical(new_config, self.get_local_config())
  203. answer = self._config_handler(new_config)
  204. rcode, val = parse_answer(answer)
  205. if rcode == 0:
  206. newc = self.get_local_config()
  207. isc.cc.data.merge(newc, new_config)
  208. self.set_local_config(newc)
  209. else:
  210. # ignore commands for 'remote' modules
  211. if module_name == self._module_name:
  212. if self._command_handler:
  213. answer = self._command_handler(cmd, arg)
  214. else:
  215. answer = create_answer(2, self._module_name + " has no command handler")
  216. except Exception as exc:
  217. answer = create_answer(1, str(exc))
  218. if answer:
  219. self._session.group_reply(env, answer)
  220. def set_config_handler(self, config_handler):
  221. """Set the config handler for this module. The handler is a
  222. function that takes the full configuration and handles it.
  223. It should return an answer created with create_answer()"""
  224. self._config_handler = config_handler
  225. # should we run this right now since we've changed the handler?
  226. def set_command_handler(self, command_handler):
  227. """Set the command handler for this module. The handler is a
  228. function that takes a command as defined in the .spec file
  229. and return an answer created with create_answer()"""
  230. self._command_handler = command_handler
  231. def add_remote_config(self, spec_file_name):
  232. """Gives access to the configuration of a different module.
  233. These remote module options can at this moment only be
  234. accessed through get_remote_config_value(). This function
  235. also subscribes to the channel of the remote module name
  236. to receive the relevant updates. It is not possible to
  237. specify your own handler for this right now.
  238. start() must have been called on this CCSession
  239. prior to the call to this method.
  240. Returns the name of the module."""
  241. module_spec = isc.config.module_spec_from_file(spec_file_name)
  242. module_cfg = ConfigData(module_spec)
  243. module_name = module_spec.get_module_name()
  244. self._session.group_subscribe(module_name);
  245. # Get the current config for that module now
  246. seq = self._session.group_sendmsg(create_command(COMMAND_GET_CONFIG, { "module_name": module_name }), "ConfigManager")
  247. try:
  248. answer, env = self._session.group_recvmsg(False, seq)
  249. except isc.cc.SessionTimeout:
  250. raise ModuleCCSessionError("No answer from ConfigManager when "
  251. "asking about Remote module " +
  252. module_name)
  253. if answer:
  254. rcode, value = parse_answer(answer)
  255. if rcode == 0:
  256. if value != None and module_spec.validate_config(False, value):
  257. module_cfg.set_local_config(value);
  258. # all done, add it
  259. self._remote_module_configs[module_name] = module_cfg
  260. return module_name
  261. def remove_remote_config(self, module_name):
  262. """Removes the remote configuration access for this module"""
  263. if module_name in self._remote_module_configs:
  264. self._session.group_unsubscribe(module_name)
  265. del self._remote_module_configs[module_name]
  266. def get_remote_config_value(self, module_name, identifier):
  267. """Returns the current setting for the given identifier at the
  268. given module. If the module has not been added with
  269. add_remote_config, a ModuleCCSessionError is raised"""
  270. if module_name in self._remote_module_configs:
  271. return self._remote_module_configs[module_name].get_value(identifier)
  272. else:
  273. raise ModuleCCSessionError("Remote module " + module_name +
  274. " not found")
  275. def __send_spec(self):
  276. """Sends the data specification to the configuration manager"""
  277. msg = create_command(COMMAND_MODULE_SPEC, self.get_module_spec().get_full_spec())
  278. seq = self._session.group_sendmsg(msg, "ConfigManager")
  279. try:
  280. answer, env = self._session.group_recvmsg(False, seq)
  281. except isc.cc.SessionTimeout:
  282. # TODO: log an error?
  283. pass
  284. def __request_config(self):
  285. """Asks the configuration manager for the current configuration, and call the config handler if set.
  286. Raises a ModuleCCSessionError if there is no answer from the configuration manager"""
  287. seq = self._session.group_sendmsg(create_command(COMMAND_GET_CONFIG, { "module_name": self._module_name }), "ConfigManager")
  288. try:
  289. answer, env = self._session.group_recvmsg(False, seq)
  290. if answer:
  291. rcode, value = parse_answer(answer)
  292. if rcode == 0:
  293. if value != None and self.get_module_spec().validate_config(False, value):
  294. self.set_local_config(value);
  295. if self._config_handler:
  296. self._config_handler(value)
  297. else:
  298. # log error
  299. print("[" + self._module_name + "] Error requesting configuration: " + value)
  300. else:
  301. raise ModuleCCSessionError("No answer from configuration manager")
  302. except isc.cc.SessionTimeout:
  303. raise ModuleCCSessionError("CC Session timeout waiting for configuration manager")
  304. class UIModuleCCSession(MultiConfigData):
  305. """This class is used in a configuration user interface. It contains
  306. specific functions for getting, displaying, and sending
  307. configuration settings through the b10-cmdctl module."""
  308. def __init__(self, conn):
  309. """Initialize a UIModuleCCSession. The conn object that is
  310. passed must have send_GET and send_POST functions"""
  311. MultiConfigData.__init__(self)
  312. self._conn = conn
  313. self.request_specifications()
  314. self.request_current_config()
  315. def request_specifications(self):
  316. """Request the module specifications from b10-cmdctl"""
  317. # this step should be unnecessary but is the current way cmdctl returns stuff
  318. # so changes are needed there to make this clean (we need a command to simply get the
  319. # full specs for everything, including commands etc, not separate gets for that)
  320. specs = self._conn.send_GET('/module_spec')
  321. for module in specs.keys():
  322. self.set_specification(isc.config.ModuleSpec(specs[module]))
  323. def update_specs_and_config(self):
  324. self.request_specifications();
  325. self.request_current_config();
  326. def request_current_config(self):
  327. """Requests the current configuration from the configuration
  328. manager through b10-cmdctl, and stores those as CURRENT"""
  329. config = self._conn.send_GET('/config_data')
  330. if 'version' not in config or config['version'] != BIND10_CONFIG_DATA_VERSION:
  331. raise ModuleCCSessionError("Bad config version")
  332. self._set_current_config(config)
  333. def add_value(self, identifier, value_str):
  334. """Add a value to a configuration list. Raises a DataTypeError
  335. if the value does not conform to the list_item_spec field
  336. of the module config data specification"""
  337. module_spec = self.find_spec_part(identifier)
  338. if (type(module_spec) != dict or "list_item_spec" not in module_spec):
  339. raise isc.cc.data.DataNotFoundError(str(identifier) + " is not a list")
  340. value = isc.cc.data.parse_value_str(value_str)
  341. cur_list, status = self.get_value(identifier)
  342. if not cur_list:
  343. cur_list = []
  344. if value not in cur_list:
  345. cur_list.append(value)
  346. self.set_value(identifier, cur_list)
  347. def remove_value(self, identifier, value_str):
  348. """Remove a value from a configuration list. The value string
  349. must be a string representation of the full item. Raises
  350. a DataTypeError if the value at the identifier is not a list,
  351. or if the given value_str does not match the list_item_spec
  352. """
  353. module_spec = self.find_spec_part(identifier)
  354. if (type(module_spec) != dict or "list_item_spec" not in module_spec):
  355. raise isc.cc.data.DataNotFoundError(str(identifier) + " is not a list")
  356. if value_str is None:
  357. # we are directly removing an list index
  358. id, list_indices = isc.cc.data.split_identifier_list_indices(identifier)
  359. if list_indices is None:
  360. raise DataTypeError("identifier in remove_value() does not contain a list index, and no value to remove")
  361. else:
  362. self.set_value(identifier, None)
  363. else:
  364. value = isc.cc.data.parse_value_str(value_str)
  365. isc.config.config_data.check_type(module_spec, [value])
  366. cur_list, status = self.get_value(identifier)
  367. #if not cur_list:
  368. # cur_list = isc.cc.data.find_no_exc(self.config.data, identifier)
  369. if not cur_list:
  370. cur_list = []
  371. if value in cur_list:
  372. cur_list.remove(value)
  373. self.set_value(identifier, cur_list)
  374. def commit(self):
  375. """Commit all local changes, send them through b10-cmdctl to
  376. the configuration manager"""
  377. if self.get_local_changes():
  378. response = self._conn.send_POST('/ConfigManager/set_config',
  379. [ self.get_local_changes() ])
  380. answer = isc.cc.data.parse_value_str(response.read().decode())
  381. # answer is either an empty dict (on success), or one
  382. # containing errors
  383. if answer == {}:
  384. self.request_current_config()
  385. self.clear_local_changes()
  386. elif "error" in answer:
  387. print("Error: " + answer["error"])
  388. print("Configuration not committed")
  389. else:
  390. raise ModuleCCSessionError("Unknown format of answer in commit(): " + str(answer))