- either use ``pool=`` to put all volumes there, or ``pool:<volume>=`` for individual volumes - both forms are not allowed at the same time
* - ``admin.vm.CreateDisposable``
- template
-`-`
-`-`
- name
- Create new DisposableVM, ``template`` is any AppVM with ``dispvm_allowed`` set to True, or ``dom0`` to use default defined in ``default_dispvm`` property of calling VM; VM created with this call will be automatically removed after its shutdown; the main difference from ``admin.vm.Create.DispVM`` is automatic (random) name generation.
- Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal ``\n`` and literal ``\`` are encoded as ``\\``.
* - ``admin.property.GetDefault``
-``dom0``
- propety
-`-`
-``type={str|int|bool|vm|label|list} <value>``
- Type ``list`` is added in R4.1. Values are of type ``str`` and each entry is suffixed with newline character.
- Get all the properties in one call. Each property is returned on a separate line and use the same value encoding as property.Get method, with an exception that newlines are encoded as literal ``\n`` and literal ``\`` are encoded as ``\\``.
* - ``admin.vm.property.GetDefault``
-``vm``
- property
-`-`
-``type={str|int|bool|vm|label|type} <value>``
- Type ``list`` is added in R4.1. Each list entry is suffixed with a newline character
- rules syntax as in :doc:`firewall interface </developer/debugging/vm-interface>` (Firewall Rules in 4x) with addition of ``expire=`` and ``comment=`` options; ``comment=`` (if present) must be the last option
* - ``admin.vm.firewall.Set``
- vm
-`-`
-``<rule>``
-`-`
- set firewall rules, see ``admin.vm.firewall.Get`` for syntax
* - ``admin.vm.firewall.Reload``
- vm
-`-`
-`-`
-`-`
- force reload firewall without changing any rule
* - ``admin.vm.device.<class>.Attach``
- vm
- device
- options
-`-`
-``device`` is in form ``<backend-name>+<device-ident>`` optional options given in ``key=value`` format, separated with spaces; options can include ``persistent=True`` to "persistently" attach the device (default is temporary)
* - ``admin.vm.device.<class>.Detach``
- vm
- device
-`-`
-`-`
-``device`` is in form ``<backend-name>+<device-ident>``
* - ``admin.vm.device.<class>.Set.persistent``
- vm
- device
-``True|False``
-`-`
-``device`` is in form ``<backend-name>+<device-ident>``
* - ``admin.vm.device.<class>.List``
- vm
-`-`
-`-`
-``<device> <options>``
- options can include ``persistent=True`` for "persistently" attached devices (default is temporary)
- optional service argument may be used to get info about a single device, optional (device class specific) properties are in ``key=value`` form, `description` must be the last one and is the only one allowed to contain spaces
* - ``admin.pool.List``
-``dom0``
-`-`
-`-`
-``<pool>``
-
* - ``admin.pool.ListDrivers``
-``dom0``
-`-`
-`-`
-``<pool-driver> <property> ...``
- Properties allowed in ``admin.pool.Add``
* - ``admin.pool.Info``
-``dom0``
- pool
-`-`
-``<property>=<value>``
-
* - ``admin.pool.Add``
-``dom0``
- driver
-``<property>=<value>``
-`-`
-
* - ``admin.pool.Set.revisions_to_keep``
-``dom0``
- pool
-``<value>``
-`-`
-
* - ``admin.pool.Remove``
-``dom0``
- pool
-`-`
-`-`
-
* - ``admin.pool.volume.List``
-``dom0``
- pool
-`-`
- volume id
-
* - ``admin.pool.volume.Info``
-``dom0``
- pool
- vid
-``<property>=<value>``
-
* - ``admin.pool.volume.Set.revisions_to_keep``
-``dom0``
- pool
-``<vid> <value>``
-`-`
-
* - ``admin.pool.volume.ListSnapshots``
-``dom0``
- pool
- vid
-``<snapshot>``
-
* - ``admin.pool.volume.Snapshot``
-``dom0``
- pool
- vid
- snapshot
-
* - ``admin.pool.volume.Revert``
-``dom0``
- pool
-``<vid> <snapshot>``
-`-`
-
* - ``admin.pool.volume.Resize``
-``dom0``
- pool
-``<vid> <size_in_bytes>``
-`-`
-
* - ``admin.pool.volume.Import``
-``dom0``
- pool
-``<vid> <raw volume data>``
-`-`
-
* - ``admin.pool.volume.CloneFrom``
-``dom0``
- pool
- vid
- token, to be used in ``admin.pool.volume.CloneTo``
- obtain a token to copy volume ``vid`` in ``pool``; the token is one time use only, it's invalidated by ``admin.pool.volume.CloneTo``, even if the operation fails
* - ``admin.pool.volume.CloneTo``
-``dom0``
- pool
-``<vid> <token>``
-`-`
- copy volume pointed by a token to volume ``vid`` in ``pool``
* - ``admin.vm.volume.List``
- vm
-`-`
-`-`
-``<volume>``
-``<volume>`` is per-VM volume name (``root``, ``private``, etc), ``<vid>`` is pool-unique volume id
* - ``admin.vm.volume.Info``
- vm
- volume
-`-`
-``<property>=<value>``
-
* - ``admin.vm.volume.Set.revisions_to_keep``
- vm
- volume
- value
-`-`
-
* - ``admin.vm.volume.ListSnapshots``
- vm
- volume
-`-`
- snapshot
- duplicate of ``admin.pool.volume.``, but with other call params
* - ``admin.vm.volume.Snapshot``
- vm
- volume
-`-`
- snapshot
- id.
* - ``admin.vm.volume.Revert``
- vm
- volume
- snapshot
-`-`
- id.
* - ``admin.vm.volume.Resize``
- vm
- volume
- size_in_bytes
-`-`
- id.
* - ``admin.vm.volume.Import``
- vm
- volume
- raw volume data
-`-`
- id.
* - ``admin.vm.volume.ImportWithSize``
- vm
- volume
-``<size_in_bytes> <raw volume data>``
-`-`
- new version of ``admin.vm.volume.Import``, allows new volume to be different size
* - ``admin.vm.volume.Clear``
- vm
- volume
-`-`
-`-`
- clear contents of volume
* - ``admin.vm.volume.CloneFrom``
- vm
- volume
-`-`
- token, to be used in ``admin.vm.volume.CloneTo``
- obtain a token to copy ``volume`` of ``vm``; the token is one time use only, it's invalidated by ``admin.vm.volume.CloneTo``, even if the operation fails
* - ``admin.vm.volume.CloneTo``
- vm
- volume
- token, obtained with ``admin.vm.volume.CloneFrom``
-`-`
- copy volume pointed by a token to ``volume`` of ``vm``
* - ``admin.vm.CurrentState``
- vm
-`-`
-`-`
-``<state-property>=<value>``
- state properties: ``power_state``, ``mem``, ``mem_static_max``, ``cputime``
* - ``admin.vm.Start``
- vm
-`-`
-`-`
-`-`
-
* - ``admin.vm.Shutdown``
- vm
-`-`
-`-`
-`-`
-
* - ``admin.vm.Pause``
- vm
-`-`
-`-`
-`-`
-
* - ``admin.vm.Unpause``
- vm
-`-`
-`-`
-`-`
-
* - ``admin.vm.Kill``
- vm
-`-`
-`-`
-`-`
-
* - ``admin.backup.Execute``
-``dom0``
- config id
-`-`
-`-`
- config in ``/etc/qubes/backup/<id>.conf``, only one backup operation of given ``config id`` can be running at once
* - ``admin.backup.Info``
-``dom0``
- config id
-`-`
- backup info
- info what would be included in the backup
* - ``admin.backup.Cancel``
-``dom0``
- config id
-`-`
-`-`
- cancel running backup operation
* - ``admin.Events``
-``dom0|vm``
-`-`
-`-`
- events
-
* - ``admin.vm.Stats``
-``dom0|vm``
-`-`
-`-`
-``vm-stats`` events, see below
- emit VM statistics (CPU, memory usage) in form of events
Volume properties:
-``pool``
-``vid``
-``size``
-``usage``
-``rw``
-``source``
-``save_on_stop``
-``snap_on_start``
-``revisions_to_keep``
-``is_outdated``
Method ``admin.vm.Stats`` returns ``vm-stats`` events every
``stats_interval`` seconds, for every running VM. Parameters of
``vm-stats`` events:
-``memory_kb`` - memory usage in kB
-``cpu_time`` - absolute CPU time (in milliseconds) spent by the VM
since its startup, normalized for one CPU
-``cpu_usage`` - CPU usage in percents
Returned messages
=================
First byte of a message is a message type. This is 8 bit non-zero
integer. Values start at 0x30 (48, ``'0'``, zero digit in ASCII) for
readability in hexdump. Next byte must be 0x00 (a separator).
This alternatively can be thought of as zero-terminated string
containing single ASCII digit.
OK (0)
------
::
30 00 <content>
Server will close the connection after delivering single message.
