qvm_ls.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646
  1. # pylint: disable=too-few-public-methods
  2. #
  3. # The Qubes OS Project, https://www.qubes-os.org/
  4. #
  5. # Copyright (C) 2015 Joanna Rutkowska <joanna@invisiblethingslab.com>
  6. # Copyright (C) 2015 Wojtek Porczyk <woju@invisiblethingslab.com>
  7. # Copyright (C) 2017 Marek Marczykowski-Górecki
  8. # <marmarek@invisiblethingslab.com>
  9. #
  10. # This program is free software; you can redistribute it and/or modify
  11. # it under the terms of the GNU Lesser General Public License as published by
  12. # the Free Software Foundation; either version 2.1 of the License, or
  13. # (at your option) any later version.
  14. #
  15. # This program is distributed in the hope that it will be useful,
  16. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18. # GNU Lesser General Public License for more details.
  19. #
  20. # You should have received a copy of the GNU Lesser General Public License along
  21. # with this program; if not, write to the Free Software Foundation, Inc.,
  22. # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  23. #
  24. '''qvm-ls - List available domains'''
  25. from __future__ import print_function
  26. import argparse
  27. import collections
  28. import sys
  29. import textwrap
  30. import qubesadmin
  31. import qubesadmin.spinner
  32. import qubesadmin.tools
  33. import qubesadmin.utils
  34. import qubesadmin.vm
  35. #
  36. # columns
  37. #
  38. class Column(object):
  39. '''A column in qvm-ls output characterised by its head and a way
  40. to fetch a parameter describing the domain.
  41. :param str head: Column head (usually uppercase).
  42. :param str attr: Attribute, possibly complex (containing ``.``). This may \
  43. also be a callable that gets as its only argument the domain.
  44. :param str doc: Description of column (will be visible in --help-columns).
  45. '''
  46. #: collection of all columns
  47. columns = {}
  48. def __init__(self, head, attr=None, doc=None):
  49. self.ls_head = head
  50. self.__doc__ = doc
  51. # intentionally not always do set self._attr,
  52. # to cause AttributeError in self.format()
  53. if attr is not None:
  54. self._attr = attr
  55. self.__class__.columns[self.ls_head] = self
  56. def cell(self, vm):
  57. '''Format one cell.
  58. .. note::
  59. This is only for technical formatting (filling with space). If you
  60. want to subclass the :py:class:`Column` class, you should override
  61. :py:meth:`Column.format` method instead.
  62. :param qubes.vm.qubesvm.QubesVM: Domain to get a value from.
  63. :returns: string to display
  64. :rtype: str
  65. '''
  66. value = self.format(vm) or '-'
  67. return value
  68. def format(self, vm):
  69. '''Format one cell value.
  70. Return value to put in a table cell.
  71. :param qubes.vm.qubesvm.QubesVM: Domain to get a value from.
  72. :returns: Value to put, or :py:obj:`None` if no value.
  73. :rtype: str or None
  74. '''
  75. ret = None
  76. try:
  77. if isinstance(self._attr, str):
  78. ret = vm
  79. for attrseg in self._attr.split('.'):
  80. ret = getattr(ret, attrseg)
  81. elif isinstance(self._attr, collections.Callable):
  82. ret = self._attr(vm)
  83. except (AttributeError, ZeroDivisionError):
  84. # division by 0 may be caused by arithmetic in callable attr
  85. return None
  86. if ret is None:
  87. return None
  88. return str(ret)
  89. def __repr__(self):
  90. return '{}(head={!r})'.format(self.__class__.__name__,
  91. self.ls_head)
  92. def __eq__(self, other):
  93. return self.ls_head == other.ls_head
  94. def __lt__(self, other):
  95. return self.ls_head < other.ls_head
  96. class PropertyColumn(Column):
  97. '''Column that displays value from property (:py:class:`property` or
  98. :py:class:`qubes.property`) of domain.
  99. :param name: Name of VM property.
  100. '''
  101. def __init__(self, name):
  102. ls_head = name.replace('_', '-').upper()
  103. super(PropertyColumn, self).__init__(
  104. head=ls_head,
  105. attr=name)
  106. def __repr__(self):
  107. return '{}(head={!r}'.format(
  108. self.__class__.__name__,
  109. self.ls_head)
  110. def process_vm(vm):
  111. '''Process VM object to find all listable properties.
  112. :param qubesmgmt.vm.QubesVM vm: VM object.
  113. '''
  114. for prop_name in vm.property_list():
  115. PropertyColumn(prop_name)
  116. def flag(field):
  117. '''Mark method as flag field.
  118. :param int field: Which field to fill (counted from 1)
  119. '''
  120. def decorator(obj):
  121. # pylint: disable=missing-docstring
  122. obj.field = field
  123. return obj
  124. return decorator
  125. def simple_flag(field, letter, attr, doc=None):
  126. '''Create simple, binary flag.
  127. :param str attr: Attribute name to check. If result is true, flag is fired.
  128. :param str letter: The letter to show.
  129. '''
  130. def helper(self, vm):
  131. # pylint: disable=missing-docstring,unused-argument
  132. try:
  133. value = getattr(vm, attr)
  134. except AttributeError:
  135. value = False
  136. if value:
  137. return letter[0]
  138. helper.__doc__ = doc
  139. helper.field = field
  140. return helper
  141. class FlagsColumn(Column):
  142. '''Some fancy flags that describe general status of the domain.'''
  143. # pylint: disable=no-self-use
  144. def __init__(self):
  145. super(FlagsColumn, self).__init__(
  146. head='FLAGS',
  147. doc=self.__class__.__doc__)
  148. @flag(1)
  149. def type(self, vm):
  150. '''Type of domain.
  151. 0 AdminVM (AKA Dom0)
  152. aA AppVM
  153. dD DisposableVM
  154. sS StandaloneVM
  155. tT TemplateVM
  156. When it is HVM (optimised VM), the letter is capital.
  157. '''
  158. type_codes = {
  159. 'AdminVM': '0',
  160. 'TemplateVM': 't',
  161. 'AppVM': 'a',
  162. 'StandaloneVM': 's',
  163. 'DispVM': 'd',
  164. }
  165. ret = type_codes.get(vm.klass, None)
  166. if ret == '0':
  167. return ret
  168. if ret is not None:
  169. if getattr(vm, 'virt_mode', 'pv') == 'hvm':
  170. return ret.upper()
  171. return ret
  172. @flag(2)
  173. def power(self, vm):
  174. '''Current power state.
  175. r running
  176. t transient
  177. p paused
  178. s suspended
  179. h halting
  180. d dying
  181. c crashed
  182. ? unknown
  183. '''
  184. state = vm.get_power_state().lower()
  185. if state == 'unknown':
  186. return '?'
  187. if state in ('running', 'transient', 'paused', 'suspended',
  188. 'halting', 'dying', 'crashed'):
  189. return state[0]
  190. updateable = simple_flag(3, 'U', 'updateable',
  191. doc='If the domain is updateable.')
  192. provides_network = simple_flag(4, 'N', 'provides_network',
  193. doc='If the domain provides network.')
  194. installed_by_rpm = simple_flag(5, 'R', 'installed_by_rpm',
  195. doc='If the domain is installed by RPM.')
  196. internal = simple_flag(6, 'i', 'internal',
  197. doc='If the domain is internal (not normally shown, no appmenus).')
  198. debug = simple_flag(7, 'D', 'debug',
  199. doc='If the domain is being debugged.')
  200. autostart = simple_flag(8, 'A', 'autostart',
  201. doc='If the domain is marked for autostart.')
  202. # TODO (not sure if really):
  203. # include in backups
  204. # uses_custom_config
  205. def _no_flag(self, vm):
  206. '''Reserved for future use.'''
  207. @classmethod
  208. def get_flags(cls):
  209. '''Get all flags as list.
  210. Holes between flags are filled with :py:meth:`_no_flag`.
  211. :rtype: list
  212. '''
  213. flags = {}
  214. for mycls in cls.__mro__:
  215. for attr in mycls.__dict__.values():
  216. if not hasattr(attr, 'field'):
  217. continue
  218. if attr.field in flags:
  219. continue
  220. flags[attr.field] = attr
  221. return [(flags[i] if i in flags else cls._no_flag)
  222. for i in range(1, max(flags) + 1)]
  223. def format(self, vm):
  224. return ''.join((flag(self, vm) or '-') for flag in self.get_flags())
  225. def calc_size(vm, volume_name):
  226. ''' Calculates the volume size in MB '''
  227. try:
  228. return vm.volumes[volume_name].size // 1024 // 1024
  229. except KeyError:
  230. return 0
  231. def calc_usage(vm, volume_name):
  232. ''' Calculates the volume usage in MB '''
  233. try:
  234. return vm.volumes[volume_name].usage // 1024 // 1024
  235. except KeyError:
  236. return 0
  237. def calc_used(vm, volume_name):
  238. ''' Calculates the volume usage in percent '''
  239. size = calc_size(vm, volume_name)
  240. if size == 0:
  241. return 0
  242. usage = calc_usage(vm, volume_name)
  243. return '{}%'.format(usage * 100 // size)
  244. # todo maxmem
  245. Column('STATE',
  246. attr=(lambda vm: vm.get_power_state()),
  247. doc='Current power state.')
  248. Column('CLASS',
  249. attr=(lambda vm: vm.klass),
  250. doc='Class of the qube.')
  251. Column('GATEWAY',
  252. attr='netvm.gateway',
  253. doc='Network gateway.')
  254. Column('MEMORY',
  255. attr=(lambda vm: vm.get_mem() / 1024 if vm.is_running() else None),
  256. doc='Memory currently used by VM')
  257. Column('DISK',
  258. attr=(lambda vm: vm.get_disk_utilization() // 1024 // 1024),
  259. doc='Total disk utilisation.')
  260. Column('PRIV-CURR',
  261. attr=(lambda vm: calc_usage(vm, 'private')),
  262. doc='Disk utilisation by private image (/home, /usr/local).')
  263. Column('PRIV-MAX',
  264. attr=(lambda vm: calc_size(vm, 'private')),
  265. doc='Maximum available space for private image.')
  266. Column('PRIV-USED',
  267. attr=(lambda vm: calc_used(vm, 'private')),
  268. doc='Disk utilisation by private image as a percentage of available space.')
  269. Column('ROOT-CURR',
  270. attr=(lambda vm: calc_usage(vm, 'root')),
  271. doc='Disk utilisation by root image (/usr, /lib, /etc, ...).')
  272. Column('ROOT-MAX',
  273. attr=(lambda vm: calc_size(vm, 'root')),
  274. doc='Maximum available space for root image.')
  275. Column('ROOT-USED',
  276. attr=(lambda vm: calc_used(vm, 'root')),
  277. doc='Disk utilisation by root image as a percentage of available space.')
  278. FlagsColumn()
  279. class Table(object):
  280. '''Table that is displayed to the user.
  281. :param domains: Domains to include in the table.
  282. :param list colnames: Names of the columns (need not to be uppercase).
  283. '''
  284. def __init__(self, domains, colnames, spinner, raw_data=False):
  285. self.domains = domains
  286. self.columns = tuple(Column.columns[col.upper().replace('_', '-')]
  287. for col in colnames)
  288. self.spinner = spinner
  289. self.raw_data = raw_data
  290. def get_head(self):
  291. '''Get table head data (all column heads).'''
  292. return [col.ls_head for col in self.columns]
  293. def get_row(self, vm):
  294. '''Get single table row data (all columns for one domain).'''
  295. ret = []
  296. for col in self.columns:
  297. ret.append(col.cell(vm))
  298. self.spinner.update()
  299. return ret
  300. def write_table(self, stream=sys.stdout):
  301. '''Write whole table to file-like object.
  302. :param file stream: Stream to write the table to.
  303. '''
  304. table_data = []
  305. if not self.raw_data:
  306. self.spinner.show('please wait...')
  307. table_data.append(self.get_head())
  308. self.spinner.update()
  309. for vm in sorted(self.domains):
  310. table_data.append(self.get_row(vm))
  311. self.spinner.hide()
  312. qubesadmin.tools.print_table(table_data, stream=stream)
  313. else:
  314. for vm in sorted(self.domains):
  315. stream.write('|'.join(self.get_row(vm)) + '\n')
  316. #: Available formats. Feel free to plug your own one.
  317. formats = {
  318. 'simple': ('name', 'state', 'class', 'label', 'template', 'netvm'),
  319. 'network': ('name', 'state', 'netvm', 'ip', 'ipback', 'gateway'),
  320. 'kernel': ('name', 'state', 'class', 'template', 'kernel', 'kernelopts'),
  321. 'full': ('name', 'state', 'class', 'label', 'qid', 'xid', 'uuid'),
  322. # 'perf': ('name', 'state', 'cpu', 'memory'),
  323. 'disk': ('name', 'state', 'disk',
  324. 'priv-curr', 'priv-max', 'priv-used',
  325. 'root-curr', 'root-max', 'root-used'),
  326. }
  327. class _HelpColumnsAction(argparse.Action):
  328. '''Action for argument parser that displays all columns and exits.'''
  329. # pylint: disable=redefined-builtin
  330. def __init__(self,
  331. option_strings,
  332. dest=argparse.SUPPRESS,
  333. default=argparse.SUPPRESS,
  334. help='list all available columns with short descriptions and exit'):
  335. super(_HelpColumnsAction, self).__init__(
  336. option_strings=option_strings,
  337. dest=dest,
  338. default=default,
  339. nargs=0,
  340. help=help)
  341. def __call__(self, parser, namespace, values, option_string=None):
  342. width = max(len(column.ls_head) for column in Column.columns.values())
  343. wrapper = textwrap.TextWrapper(width=80,
  344. initial_indent=' ', subsequent_indent=' ' * (width + 6))
  345. text = 'Available columns:\n' + '\n'.join(
  346. wrapper.fill('{head:{width}s} {doc}'.format(
  347. head=column.ls_head,
  348. doc=column.__doc__ or '',
  349. width=width))
  350. for column in sorted(Column.columns.values()))
  351. text += '\n\nAdditionally any VM property may be used as a column, ' \
  352. 'see qvm-prefs --help-properties for available values'
  353. parser.exit(message=text + '\n')
  354. class _HelpFormatsAction(argparse.Action):
  355. '''Action for argument parser that displays all formats and exits.'''
  356. # pylint: disable=redefined-builtin
  357. def __init__(self,
  358. option_strings,
  359. dest=argparse.SUPPRESS,
  360. default=argparse.SUPPRESS,
  361. help='list all available formats with their definitions and exit'):
  362. super(_HelpFormatsAction, self).__init__(
  363. option_strings=option_strings,
  364. dest=dest,
  365. default=default,
  366. nargs=0,
  367. help=help)
  368. def __call__(self, parser, namespace, values, option_string=None):
  369. width = max(len(fmt) for fmt in formats)
  370. text = 'Available formats:\n' + ''.join(
  371. ' {fmt:{width}s} {columns}\n'.format(
  372. fmt=fmt, columns=','.join(formats[fmt]).upper(), width=width)
  373. for fmt in sorted(formats))
  374. parser.exit(message=text)
  375. # common VM power states for easy command-line filtering
  376. DOMAIN_POWER_STATES = ['running', 'paused', 'halted']
  377. def matches_power_states(domain, **states):
  378. '''Filter domains by their power state'''
  379. # if all values are False (default) => return match on every VM
  380. if not states or set(states.values()) == {False}:
  381. return True
  382. # otherwise => only VMs matching True states
  383. requested_states = [state for state, active in states.items() if active]
  384. return domain.get_power_state().lower() in requested_states
  385. def get_parser():
  386. '''Create :py:class:`argparse.ArgumentParser` suitable for
  387. :program:`qvm-ls`.
  388. '''
  389. # parser creation is delayed to get all the columns that are scattered
  390. # thorough the modules
  391. wrapper = textwrap.TextWrapper(width=80, break_on_hyphens=False,
  392. initial_indent=' ', subsequent_indent=' ')
  393. parser = qubesadmin.tools.QubesArgumentParser(
  394. vmname_nargs=argparse.ZERO_OR_MORE,
  395. formatter_class=argparse.RawTextHelpFormatter,
  396. description='List Qubes domains and their parametres.',
  397. epilog='available formats (see --help-formats):\n{}\n\n'
  398. 'available columns (see --help-columns):\n{}'.format(
  399. wrapper.fill(', '.join(sorted(formats.keys()))),
  400. wrapper.fill(', '.join(sorted(sorted(Column.columns.keys()))))))
  401. parser.add_argument('--help-columns', action=_HelpColumnsAction)
  402. parser.add_argument('--help-formats', action=_HelpFormatsAction)
  403. parser_formats = parser.add_mutually_exclusive_group()
  404. parser_formats.add_argument('--format', '-o', metavar='FORMAT',
  405. action='store', choices=formats.keys(), default='simple',
  406. help='preset format')
  407. parser_formats.add_argument('--fields', '-O', metavar='FIELD,...',
  408. action='store',
  409. help='user specified format (see available columns below)')
  410. parser.add_argument('--tags', nargs='+', metavar='TAG',
  411. help='show only VMs having specific tag(s)')
  412. for pwrstate in DOMAIN_POWER_STATES:
  413. parser.add_argument('--{}'.format(pwrstate), action='store_true',
  414. help='show {} VMs'.format(pwrstate))
  415. parser.add_argument('--raw-data', action='store_true',
  416. help='Display specify data of specified VMs. Intended for '
  417. 'bash-parsing.')
  418. parser.add_argument('--spinner',
  419. action='store_true', dest='spinner',
  420. help='reenable spinner')
  421. parser.add_argument('--no-spinner',
  422. action='store_false', dest='spinner',
  423. help='disable spinner')
  424. # shortcuts, compatibility with Qubes 3.2
  425. parser.add_argument('--raw-list', action='store_true',
  426. help='Same as --raw-data --fields=name')
  427. parser.add_argument('--disk', '-d',
  428. action='store_const', dest='format', const='disk',
  429. help='Same as --format=disk')
  430. parser.add_argument('--network', '-n',
  431. action='store_const', dest='format', const='network',
  432. help='Same as --format=network')
  433. parser.add_argument('--kernel', '-k',
  434. action='store_const', dest='format', const='kernel',
  435. help='Same as --format=kernel')
  436. parser.set_defaults(spinner=True)
  437. # parser.add_argument('--conf', '-c',
  438. # action='store', metavar='CFGFILE',
  439. # help='Qubes config file')
  440. return parser
  441. def main(args=None, app=None):
  442. '''Main routine of :program:`qvm-ls`.
  443. :param list args: Optional arguments to override those delivered from \
  444. command line.
  445. :param app: Operate on given app object instead of instantiating new one.
  446. '''
  447. parser = get_parser()
  448. try:
  449. args = parser.parse_args(args, app=app)
  450. except qubesadmin.exc.QubesException as e:
  451. parser.print_error(str(e))
  452. return 1
  453. if args.raw_list:
  454. args.raw_data = True
  455. args.fields = 'name'
  456. if args.fields:
  457. columns = [col.strip() for col in args.fields.split(',')]
  458. else:
  459. columns = formats[args.format]
  460. # assume unknown columns are VM properties
  461. for col in columns:
  462. if col.upper() not in Column.columns:
  463. PropertyColumn(col.lower())
  464. if args.spinner and not args.raw_data:
  465. # we need Enterprise Edition™, since it's the only one that detects TTY
  466. # and uses dots if we are redirected somewhere else
  467. spinner = qubesadmin.spinner.QubesSpinnerEnterpriseEdition(sys.stderr)
  468. else:
  469. spinner = qubesadmin.spinner.DummySpinner(sys.stderr)
  470. if args.domains:
  471. domains = args.domains
  472. else:
  473. domains = args.app.domains
  474. if args.tags:
  475. # filter only VMs having at least one of the specified tags
  476. domains = [dom for dom in domains
  477. if set(dom.tags).intersection(set(args.tags))]
  478. pwrstates = {state: getattr(args, state) for state in DOMAIN_POWER_STATES}
  479. domains = filter(lambda x: matches_power_states(x, **pwrstates), domains)
  480. table = Table(domains, columns, spinner, args.raw_data)
  481. table.write_table(sys.stdout)
  482. return 0
  483. if __name__ == '__main__':
  484. sys.exit(main())