__init__.py 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717
  1. #
  2. # The Qubes OS Project, https://www.qubes-os.org/
  3. #
  4. # Copyright (C) 2010-2015 Joanna Rutkowska <joanna@invisiblethingslab.com>
  5. # Copyright (C) 2011-2015 Marek Marczykowski-Górecki
  6. # <marmarek@invisiblethingslab.com>
  7. # Copyright (C) 2014-2015 Wojtek Porczyk <woju@invisiblethingslab.com>
  8. #
  9. # This program is free software; you can redistribute it and/or modify
  10. # it under the terms of the GNU General Public License as published by
  11. # the Free Software Foundation; either version 2 of the License, or
  12. # (at your option) any later version.
  13. #
  14. # This program is distributed in the hope that it will be useful,
  15. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17. # GNU General Public License for more details.
  18. #
  19. # You should have received a copy of the GNU General Public License along
  20. # with this program; if not, write to the Free Software Foundation, Inc.,
  21. # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  22. #
  23. '''
  24. Qubes OS
  25. :copyright: © 2010-2015 Invisible Things Lab
  26. '''
  27. import builtins
  28. import collections
  29. import os
  30. import os.path
  31. import string
  32. import lxml.etree
  33. import qubes.config
  34. import qubes.events
  35. import qubes.exc
  36. __author__ = 'Invisible Things Lab'
  37. __license__ = 'GPLv2 or later'
  38. __version__ = 'R3'
  39. class Label(object):
  40. '''Label definition for virtual machines
  41. Label specifies colour of the padlock displayed next to VM's name.
  42. When this is a :py:class:`qubes.vm.dispvm.DispVM`, padlock is overlayed
  43. with recycling pictogram.
  44. :param int index: numeric identificator of label
  45. :param str color: colour specification as in HTML (``#abcdef``)
  46. :param str name: label's name like "red" or "green"
  47. '''
  48. def __init__(self, index, color, name):
  49. #: numeric identificator of label
  50. self.index = index
  51. #: colour specification as in HTML (``#abcdef``)
  52. self.color = color
  53. #: label's name like "red" or "green"
  54. self.name = name
  55. #: freedesktop icon name, suitable for use in
  56. #: :py:meth:`PyQt4.QtGui.QIcon.fromTheme`
  57. self.icon = 'appvm-' + name
  58. #: freedesktop icon name, suitable for use in
  59. #: :py:meth:`PyQt4.QtGui.QIcon.fromTheme` on DispVMs
  60. self.icon_dispvm = 'dispvm-' + name
  61. @classmethod
  62. def fromxml(cls, xml):
  63. '''Create label definition from XML node
  64. :param lxml.etree._Element xml: XML node reference
  65. :rtype: :py:class:`qubes.Label`
  66. '''
  67. index = int(xml.get('id').split('-', 1)[1])
  68. color = xml.get('color')
  69. name = xml.text
  70. return cls(index, color, name)
  71. def __xml__(self):
  72. element = lxml.etree.Element(
  73. 'label', id='label-{}'.format(self.index), color=self.color)
  74. element.text = self.name
  75. return element
  76. def __str__(self):
  77. return self.name
  78. def __repr__(self):
  79. return '{}({!r}, {!r}, {!r})'.format(
  80. self.__class__.__name__,
  81. self.index,
  82. self.color,
  83. self.name)
  84. def __eq__(self, other):
  85. if isinstance(other, Label):
  86. return self.name == other.name
  87. return NotImplemented
  88. def __hash__(self):
  89. return hash(self.name)
  90. @builtins.property
  91. def icon_path(self):
  92. '''Icon path
  93. .. deprecated:: 2.0
  94. use :py:meth:`PyQt4.QtGui.QIcon.fromTheme` and :py:attr:`icon`
  95. '''
  96. return os.path.join(qubes.config.system_path['qubes_icon_dir'],
  97. self.icon) + ".png"
  98. @builtins.property
  99. def icon_path_dispvm(self):
  100. '''Icon path
  101. .. deprecated:: 2.0
  102. use :py:meth:`PyQt4.QtGui.QIcon.fromTheme` and :py:attr:`icon_dispvm`
  103. '''
  104. return os.path.join(qubes.config.system_path['qubes_icon_dir'],
  105. self.icon_dispvm) + ".png"
  106. class property(object): # pylint: disable=redefined-builtin,invalid-name
  107. '''Qubes property.
  108. This class holds one property that can be saved to and loaded from
  109. :file:`qubes.xml`. It is used for both global and per-VM properties.
  110. Property can be unset by ordinary ``del`` statement or assigning
  111. :py:attr:`DEFAULT` special value to it. After deletion (or before first
  112. assignment/load) attempting to read a property will get its default value
  113. or, when no default, py:class:`exceptions.AttributeError`.
  114. :param str name: name of the property
  115. :param collections.Callable setter: if not :py:obj:`None`, this is used to \
  116. initialise value; first parameter to the function is holder instance \
  117. and the second is value; this is called before ``type``
  118. :param collections.Callable saver: function to coerce value to something \
  119. readable by setter
  120. :param type type: if not :py:obj:`None`, value is coerced to this type
  121. :param object default: default value; if callable, will be called with \
  122. holder as first argument
  123. :param int load_stage: stage when property should be loaded (see \
  124. :py:class:`Qubes` for description of stages)
  125. :param int order: order of evaluation (bigger order values are later)
  126. :param bool clone: :py:meth:`PropertyHolder.clone_properties` will not \
  127. include this property by default if :py:obj:`False`
  128. :param str doc: docstring; this should be one paragraph of plain RST, no \
  129. sphinx-specific features
  130. Setters and savers have following signatures:
  131. .. :py:function:: setter(self, prop, value)
  132. :noindex:
  133. :param self: instance of object that is holding property
  134. :param prop: property object
  135. :param value: value being assigned
  136. .. :py:function:: saver(self, prop, value)
  137. :noindex:
  138. :param self: instance of object that is holding property
  139. :param prop: property object
  140. :param value: value being saved
  141. :rtype: str
  142. :raises property.DontSave: when property should not be saved at all
  143. '''
  144. #: Assigning this value to property means setting it to its default value.
  145. #: If property has no default value, this will unset it.
  146. DEFAULT = object()
  147. # internal use only
  148. _NO_DEFAULT = object()
  149. def __init__(self, name, setter=None, saver=None, type=None,
  150. default=_NO_DEFAULT, write_once=False, load_stage=2, order=0,
  151. save_via_ref=False, clone=True,
  152. doc=None):
  153. # pylint: disable=redefined-builtin
  154. self.__name__ = name
  155. self._setter = setter
  156. self._saver = saver if saver is not None else (
  157. lambda self, prop, value: str(value))
  158. self.type = type
  159. self._default = default
  160. self._write_once = write_once
  161. self.order = order
  162. self.load_stage = load_stage
  163. self.save_via_ref = save_via_ref
  164. self.clone = clone
  165. self.__doc__ = doc
  166. self._attr_name = '_qubesprop_' + name
  167. def __get__(self, instance, owner):
  168. if instance is None:
  169. return self
  170. # XXX this violates duck typing, shall we keep it?
  171. if not isinstance(instance, PropertyHolder):
  172. raise AttributeError('qubes.property should be used on '
  173. 'qubes.PropertyHolder instances only')
  174. try:
  175. return getattr(instance, self._attr_name)
  176. except AttributeError:
  177. if self._default is self._NO_DEFAULT:
  178. raise AttributeError(
  179. 'property {!r} not set'.format(self.__name__))
  180. elif isinstance(self._default, collections.Callable):
  181. return self._default(instance)
  182. else:
  183. return self._default
  184. def __set__(self, instance, value):
  185. self._enforce_write_once(instance)
  186. if value is self.__class__.DEFAULT:
  187. self.__delete__(instance)
  188. return
  189. try:
  190. oldvalue = getattr(instance, self.__name__)
  191. has_oldvalue = True
  192. except AttributeError:
  193. has_oldvalue = False
  194. if self._setter is not None:
  195. value = self._setter(instance, self, value)
  196. if self.type not in (None, type(value)):
  197. value = self.type(value)
  198. if has_oldvalue:
  199. instance.fire_event('property-pre-set:' + self.__name__,
  200. pre_event=True,
  201. name=self.__name__, newvalue=value, oldvalue=oldvalue)
  202. else:
  203. instance.fire_event('property-pre-set:' + self.__name__,
  204. pre_event=True,
  205. name=self.__name__, newvalue=value)
  206. instance._property_init(self, value) # pylint: disable=protected-access
  207. if has_oldvalue:
  208. instance.fire_event('property-set:' + self.__name__,
  209. name=self.__name__, newvalue=value, oldvalue=oldvalue)
  210. else:
  211. instance.fire_event('property-set:' + self.__name__,
  212. name=self.__name__, newvalue=value)
  213. def __delete__(self, instance):
  214. self._enforce_write_once(instance)
  215. try:
  216. oldvalue = getattr(instance, self._attr_name)
  217. has_oldvalue = True
  218. except AttributeError:
  219. has_oldvalue = False
  220. if has_oldvalue:
  221. instance.fire_event('property-pre-del:' + self.__name__,
  222. pre_event=True,
  223. name=self.__name__, oldvalue=oldvalue)
  224. delattr(instance, self._attr_name)
  225. instance.fire_event('property-del:' + self.__name__,
  226. name=self.__name__, oldvalue=oldvalue)
  227. else:
  228. instance.fire_event('property-pre-del:' + self.__name__,
  229. pre_event=True,
  230. name=self.__name__)
  231. instance.fire_event('property-del:' + self.__name__,
  232. name=self.__name__)
  233. def __repr__(self):
  234. default = ' default={!r}'.format(self._default) \
  235. if self._default is not self._NO_DEFAULT \
  236. else ''
  237. return '<{} object at {:#x} name={!r}{}>'.format(
  238. self.__class__.__name__, id(self), self.__name__, default)
  239. def __str__(self):
  240. return self.__name__
  241. def __hash__(self):
  242. return hash(self.__name__)
  243. def __lt__(self, other):
  244. if isinstance(other, property):
  245. return (self.load_stage, self.order, self.__name__) <\
  246. (other.load_stage, other.order, other.__name__)
  247. return NotImplemented
  248. def __eq__(self, other):
  249. if isinstance(other, str):
  250. return self.__name__ == other
  251. return isinstance(other, property) and self.__name__ == other.__name__
  252. def _enforce_write_once(self, instance):
  253. if self._write_once and not instance.property_is_default(self):
  254. raise AttributeError(
  255. 'property {!r} is write-once and already set'.format(
  256. self.__name__))
  257. def sanitize(self, *, untrusted_newvalue):
  258. '''Coarse sanitization of value to be set, before sending it to a
  259. setter. Can raise QubesValueError if the value is invalid.
  260. :param untrusted_newvalue: value to be validated
  261. :return: sanitized value
  262. :raises: qubes.exc.QubesValueError
  263. '''
  264. # do not treat type='str' as sufficient validation
  265. if self.type is not None and self.type is not str:
  266. # assume specific type will preform enough validation
  267. try:
  268. untrusted_newvalue = untrusted_newvalue.decode('ascii',
  269. errors='strict')
  270. except UnicodeDecodeError:
  271. raise qubes.exc.QubesValueError
  272. if self.type is bool:
  273. return self.bool(None, None, untrusted_newvalue)
  274. else:
  275. try:
  276. return self.type(untrusted_newvalue)
  277. except ValueError:
  278. raise qubes.exc.QubesValueError
  279. else:
  280. # 'str' or not specified type
  281. try:
  282. untrusted_newvalue = untrusted_newvalue.decode('ascii',
  283. errors='strict')
  284. except UnicodeDecodeError:
  285. raise qubes.exc.QubesValueError
  286. allowed_set = string.printable
  287. if not all(x in allowed_set for x in untrusted_newvalue):
  288. raise qubes.exc.QubesValueError(
  289. 'Invalid characters in property value')
  290. return untrusted_newvalue
  291. #
  292. # exceptions
  293. #
  294. class DontSave(Exception):
  295. '''This exception may be raised from saver to sign that property should
  296. not be saved.
  297. '''
  298. pass
  299. @staticmethod
  300. def dontsave(self, prop, value):
  301. '''Dummy saver that never saves anything.'''
  302. # pylint: disable=bad-staticmethod-argument,unused-argument
  303. raise property.DontSave()
  304. #
  305. # some setters provided
  306. #
  307. @staticmethod
  308. def forbidden(self, prop, value):
  309. '''Property setter that forbids loading a property.
  310. This is used to effectively disable property in classes which inherit
  311. unwanted property. When someone attempts to load such a property, it
  312. :throws AttributeError: always
  313. ''' # pylint: disable=bad-staticmethod-argument,unused-argument
  314. raise AttributeError(
  315. 'setting {} property on {} instance is forbidden'.format(
  316. prop.__name__, self.__class__.__name__))
  317. @staticmethod
  318. def bool(self, prop, value):
  319. '''Property setter for boolean properties.
  320. It accepts (case-insensitive) ``'0'``, ``'no'`` and ``false`` as
  321. :py:obj:`False` and ``'1'``, ``'yes'`` and ``'true'`` as
  322. :py:obj:`True`.
  323. ''' # pylint: disable=bad-staticmethod-argument,unused-argument
  324. if isinstance(value, str):
  325. lcvalue = value.lower()
  326. if lcvalue in ('0', 'no', 'false', 'off'):
  327. return False
  328. if lcvalue in ('1', 'yes', 'true', 'on'):
  329. return True
  330. raise qubes.exc.QubesValueError(
  331. 'Invalid literal for boolean property: {!r}'.format(value))
  332. return bool(value)
  333. def stateless_property(func):
  334. '''Decorator similar to :py:class:`builtins.property`, but for properties
  335. exposed through management API (including qvm-prefs etc)'''
  336. return property(func.__name__,
  337. setter=property.forbidden,
  338. saver=property.DontSave,
  339. default=func,
  340. doc=func.__doc__)
  341. class PropertyHolder(qubes.events.Emitter):
  342. '''Abstract class for holding :py:class:`qubes.property`
  343. Events fired by instances of this class:
  344. .. event:: property-load (subject, event)
  345. Fired once after all properties are loaded from XML. Individual
  346. ``property-set`` events are not fired.
  347. .. event:: property-set:<propname> \
  348. (subject, event, name, newvalue[, oldvalue])
  349. Fired when property changes state. Signature is variable,
  350. *oldvalue* is present only if there was an old value.
  351. :param name: Property name
  352. :param newvalue: New value of the property
  353. :param oldvalue: Old value of the property
  354. .. event:: property-pre-set:<propname> \
  355. (subject, event, name, newvalue[, oldvalue])
  356. Fired before property changes state. Signature is variable,
  357. *oldvalue* is present only if there was an old value.
  358. :param name: Property name
  359. :param newvalue: New value of the property
  360. :param oldvalue: Old value of the property
  361. .. event:: property-del:<propname> \
  362. (subject, event, name[, oldvalue])
  363. Fired when property gets deleted (is set to default). Signature is
  364. variable, *oldvalue* is present only if there was an old value.
  365. :param name: Property name
  366. :param oldvalue: Old value of the property
  367. .. event:: property-pre-del:<propname> \
  368. (subject, event, name[, oldvalue])
  369. Fired before property gets deleted (is set to default). Signature
  370. is variable, *oldvalue* is present only if there was an old value.
  371. :param name: Property name
  372. :param oldvalue: Old value of the property
  373. .. event:: clone-properties (subject, event, src, proplist)
  374. :param src: object, from which we are cloning
  375. :param proplist: list of properties
  376. Members:
  377. '''
  378. def __init__(self, xml, **kwargs):
  379. self.xml = xml
  380. propvalues = {}
  381. all_names = set(prop.__name__ for prop in self.property_list())
  382. for key in list(kwargs):
  383. if not key in all_names:
  384. continue
  385. propvalues[key] = kwargs.pop(key)
  386. super(PropertyHolder, self).__init__(**kwargs)
  387. for key, value in propvalues.items():
  388. setattr(self, key, value)
  389. if self.xml is not None:
  390. # check if properties are appropriate
  391. all_names = set(prop.__name__ for prop in self.property_list())
  392. for node in self.xml.xpath('./properties/property'):
  393. name = node.get('name')
  394. if name not in all_names:
  395. raise TypeError(
  396. 'property {!r} not applicable to {!r}'.format(
  397. name, self.__class__.__name__))
  398. @classmethod
  399. def property_list(cls, load_stage=None):
  400. '''List all properties attached to this VM's class
  401. :param load_stage: Filter by load stage
  402. :type load_stage: :py:func:`int` or :py:obj:`None`
  403. '''
  404. props = set()
  405. for class_ in cls.__mro__:
  406. props.update(prop for prop in class_.__dict__.values()
  407. if isinstance(prop, property))
  408. if load_stage is not None:
  409. props = set(prop for prop in props
  410. if prop.load_stage == load_stage)
  411. return sorted(props)
  412. def _property_init(self, prop, value):
  413. '''Initialise property to a given value, without side effects.
  414. :param qubes.property prop: property object of particular interest
  415. :param value: value
  416. '''
  417. # pylint: disable=protected-access
  418. setattr(self, self.property_get_def(prop)._attr_name, value)
  419. def property_is_default(self, prop):
  420. '''Check whether property is in it's default value.
  421. Properties when unset may return some default value, so
  422. ``hasattr(vm, prop.__name__)`` is wrong in some circumstances. This
  423. method allows for checking if the value returned is in fact it's
  424. default value.
  425. :param qubes.property prop: property object of particular interest
  426. :rtype: bool
  427. ''' # pylint: disable=protected-access
  428. # both property_get_def() and ._attr_name may throw AttributeError,
  429. # which we don't want to catch
  430. attrname = self.property_get_def(prop)._attr_name
  431. return not hasattr(self, attrname)
  432. @classmethod
  433. def property_get_def(cls, prop):
  434. '''Return property definition object.
  435. If prop is already :py:class:`qubes.property` instance, return the same
  436. object.
  437. :param prop: property object or name
  438. :type prop: qubes.property or str
  439. :rtype: qubes.property
  440. '''
  441. if isinstance(prop, qubes.property):
  442. return prop
  443. for p in cls.property_list():
  444. if p.__name__ == prop:
  445. return p
  446. raise AttributeError('No property {!r} found in {!r}'.format(
  447. prop, cls))
  448. def load_properties(self, load_stage=None):
  449. '''Load properties from immediate children of XML node.
  450. ``property-set`` events are not fired for each individual property.
  451. :param int load_stage: Stage of loading.
  452. '''
  453. if self.xml is None:
  454. return
  455. all_names = set(
  456. prop.__name__ for prop in self.property_list(load_stage))
  457. for node in self.xml.xpath('./properties/property'):
  458. name = node.get('name')
  459. value = node.get('ref') or node.text
  460. if not name in all_names:
  461. continue
  462. setattr(self, name, value)
  463. def xml_properties(self, with_defaults=False):
  464. '''Iterator that yields XML nodes representing set properties.
  465. :param bool with_defaults: If :py:obj:`True`, then it also includes \
  466. properties which were not set explicite, but have default values \
  467. filled.
  468. '''
  469. properties = lxml.etree.Element('properties')
  470. for prop in self.property_list():
  471. # pylint: disable=protected-access
  472. try:
  473. value = getattr(
  474. self, (prop.__name__ if with_defaults else prop._attr_name))
  475. except AttributeError:
  476. continue
  477. try:
  478. value = prop._saver(self, prop, value)
  479. except property.DontSave:
  480. continue
  481. element = lxml.etree.Element('property', name=prop.__name__)
  482. if prop.save_via_ref:
  483. element.set('ref', value)
  484. else:
  485. element.text = value
  486. properties.append(element)
  487. return properties
  488. # this was clone_attrs
  489. def clone_properties(self, src, proplist=None):
  490. '''Clone properties from other object.
  491. :param PropertyHolder src: source object
  492. :param iterable proplist: list of properties \
  493. (:py:obj:`None` or omit for all properties except those with \
  494. :py:attr:`property.clone` set to :py:obj:`False`)
  495. '''
  496. if proplist is None:
  497. proplist = [prop for prop in self.property_list()
  498. if prop.clone]
  499. else:
  500. proplist = [prop for prop in self.property_list()
  501. if prop.__name__ in proplist or prop in proplist]
  502. for prop in proplist:
  503. try:
  504. # pylint: disable=protected-access
  505. self._property_init(prop, getattr(src, prop._attr_name))
  506. except AttributeError:
  507. continue
  508. self.fire_event('clone-properties', src=src, proplist=proplist)
  509. def property_require(self, prop, allow_none=False, hard=False):
  510. '''Complain badly when property is not set.
  511. :param prop: property name or object
  512. :type prop: qubes.property or str
  513. :param bool allow_none: if :py:obj:`True`, don't complain if \
  514. :py:obj:`None` is found
  515. :param bool hard: if :py:obj:`True`, raise :py:class:`AssertionError`; \
  516. if :py:obj:`False`, log warning instead
  517. '''
  518. if isinstance(prop, qubes.property):
  519. prop = prop.__name__
  520. try:
  521. value = getattr(self, prop)
  522. if value is None and not allow_none:
  523. raise AttributeError()
  524. except AttributeError:
  525. # pylint: disable=no-member
  526. msg = 'Required property {!r} not set on {!r}'.format(prop, self)
  527. if hard:
  528. raise AssertionError(msg)
  529. else:
  530. # pylint: disable=no-member
  531. self.log.fatal(msg)
  532. def close(self):
  533. super().close()
  534. # Remove all properties -- somewhere in them there are cyclic
  535. # references. This just removes all the properties, just in case.
  536. # They are removed directly, bypassing write_once.
  537. for prop in self.property_list():
  538. # pylint: disable=protected-access
  539. try:
  540. delattr(self, prop._attr_name)
  541. except AttributeError:
  542. pass
  543. # pylint: disable=wrong-import-position
  544. from qubes.vm import VMProperty
  545. from qubes.app import Qubes
  546. __all__ = [
  547. 'Label',
  548. 'PropertyHolder',
  549. 'Qubes',
  550. 'VMProperty',
  551. 'property',
  552. ]