qubesadmin.backup package


qubesadmin.backup.core2 module

Parser for core2 qubes.xml

class qubesadmin.backup.core2.Core2Qubes(store=None)[source]

Bases: qubesadmin.backup.BackupApp

Parsed qubes.xml


Parse a single VM from given XML node

This method load only VM properties not depending on other VMs (other than template). VM connections are set later. :param element: XML node


Load qubes.xml


Load global settings

Parameters:element – XML element containing global settings (root node)

Set dependencies between VMs

class qubesadmin.backup.core2.Core2VM[source]

Bases: qubesadmin.backup.BackupVM

VM object

handle_firewall_xml(vm, stream)[source]

Load old (Qubes < 4.0) firewall XML format


Report whether a VM is included in the backup

static rule_from_xml_v1(node, action)[source]

Parse single rule in old XML format (pre Qubes 4.0)

  • node – XML node for the rule
  • action – action to apply (in old format it wasn’t part of the rule itself)

qubesadmin.backup.core3 module

Parser for core3 qubes.xml

class qubesadmin.backup.core3.Core3Qubes(store=None)[source]

Bases: qubesadmin.backup.BackupApp

Parsed qubes.xml

static get_property(xml_obj, prop)[source]

Get property of given object (XML node)

Object can be any PropertyHolder serialized to XML - in practice BaseVM or Qubes.


Parse a single VM from given XML node

This method load only VM properties not depending on other VMs (other than template). VM connections are set later. :param element: XML node


Load qubes.xml


Load global settings

Parameters:globals_element – XML element containing global settings

Load labels table

class qubesadmin.backup.core3.Core3VM[source]

Bases: qubesadmin.backup.BackupVM

VM object

handle_firewall_xml(vm, stream)[source]

Load new (Qubes >= 4.0) firewall XML format


Report whether a VM is included in the backup

qubesadmin.backup.restore module

Backup restore module

exception qubesadmin.backup.restore.BackupCanceledError(msg, tmpdir=None)[source]

Bases: qubesadmin.exc.QubesException

Exception raised when backup/restore was cancelled

class qubesadmin.backup.restore.BackupHeader(header_data=None, version=None, encrypted=None, compressed=None, compression_filter=None, hmac_algorithm=None, crypto_algorithm=None, backup_id=None)[source]

Bases: object

Structure describing backup-header file included as the first file in backup archive

class Header(field, t, validator)

Bases: tuple


Alias for field number 0


Alias for field number 1


Alias for field number 2

known_headers = {'backup-id': Header(field='backup_id', t=<class 'str'>, validator=<function BackupHeader.<lambda>>), 'compressed': Header(field='compressed', t=<class 'bool'>, validator=<function BackupHeader.<lambda>>), 'compression-filter': Header(field='compression_filter', t=<class 'str'>, validator=<function BackupHeader.<lambda>>), 'crypto-algorithm': Header(field='crypto_algorithm', t=<class 'str'>, validator=<function BackupHeader.<lambda>>), 'encrypted': Header(field='encrypted', t=<class 'bool'>, validator=<function BackupHeader.<lambda>>), 'hmac-algorithm': Header(field='hmac_algorithm', t=<class 'str'>, validator=<function BackupHeader.<lambda>>), 'version': Header(field='version', t=<class 'int'>, validator=<function BackupHeader.<lambda>>)}

Parse backup header file.

Parameters:untrusted_header_text (basestring) – header content


This function may be exposed to not yet verified header, so is security critical.


Save backup header into a file


Validate header data, according to header version

class qubesadmin.backup.restore.BackupRestore(app, backup_location, backup_vm, passphrase, location_is_service=False, force_compression_filter=None, tmpdir='/var/tmp')[source]

Bases: object


>>> restore_op = BackupRestore(...)
>>> # adjust restore_op.options here
>>> restore_info = restore_op.get_restore_info()
>>> # manipulate restore_info to select VMs to restore here
>>> restore_op.restore_do(restore_info)
class Dom0ToRestore(vm, subdir=None)[source]

Bases: qubesadmin.backup.restore.VMToRestore

Information about dom0 home to restore

USERNAME_MISMATCH = <object object>

backup was performed on system with different dom0 username

class VMToRestore(vm)[source]

Bases: object

Information about a single VM to be restored

ALREADY_EXISTS = <object object>

VM with such name already exists on the host

EXCLUDED = <object object>

VM excluded from restore by user

MISSING_KERNEL = <object object>

Kernel used by the VM does not exists on the host

MISSING_NETVM = <object object>

NetVM used by the VM does not exists on the host

MISSING_TEMPLATE = <object object>

TemplateVM used by the VM does not exists on the host


Is the VM ready for restore?

app = None

qubes.Qubes instance

backup_app = None

VMs included in the backup

backup_location = None

backup path, inside VM pointed by backup_vm

backup_vm = None

VM from which backup should be retrieved

canceled = None

is the backup operation canceled


Check if there is enough disk space to restore the backup.

Currently it checks only for the space in temporary directory, not the target storage pools.

force_compression_filter = None

force using specific application for (de)compression, instead of the one named in the backup header


Get restore info

Return information about what is included in the backup. That dictionary can be adjusted to select what VM should be restore.

static get_restore_summary(restore_info)[source]

Return a ASCII formatted table with restore info summary

header_data = None

basic information about the backup

location_is_service = None

use alternative qrexec service to retrieve backup data, instead of qubes.Restore with backup_location given on stdin

new_name_for_conflicting_vm(orig_name, restore_info)[source]

Generate new name for conflicting VM

Add a number suffix, until the name is unique. If no unique name can be found using this strategy, return None

options = None

options how the backup should be restored

passphrase = None

passphrase protecting backup integrity and optionally decryption

processes_to_kill_on_cancel = None

list of processes (Popen objects) to kill on cancel


High level workflow: 1. Create VMs object in host collection (qubes.xml) 2. Create them on disk (vm.create_on_disk) 3. Restore VM data, overriding/converting VM files 4. Apply possible fixups and save qubes.xml


Verify restore info - validate VM dependencies, name conflicts etc.

class qubesadmin.backup.restore.BackupRestoreOptions[source]

Bases: object

Options for restore operation

dom0_home = None

restore dom0 home

exclude = None

list of VM names to exclude

ignore_size_limit = None

ignore size limit calculated from backup metadata

ignore_username_mismatch = None

restore dom0 home even if username is different

override_pool = None

restore VMs into selected storage pool

verify_only = None

do not restore data, only verify backup integrity

class qubesadmin.backup.restore.ExtractWorker3(queue, base_dir, passphrase, encrypted, progress_callback, vmproc=None, compressed=False, crypto_algorithm='aes-256-cbc', compression_filter=None, verify_only=False, handlers=None)[source]

Bases: multiprocessing.context.Process

Process for handling inner tar layer of backup archive

base_dir = None

paths on the queue are relative to this dir

blocks_backedup = None



Check if any process failed.

And if so, wait for other relevant processes to cleanup.

cleanup_tar2(wait=True, terminate=False)[source]

Cleanup running tar2_process

  • wait – wait for it termination, otherwise method exit early if process is still running
  • terminate – terminate the process if still running

Retrieve tar stderr and handle it appropriately

Log errors, process file size if requested. This use tar2_process.

compressed = None

is the backup compressed?

crypto_algorithm = None

what crypto algorithm is used for encryption?

decompressor_process = None

decompressor subprocess.Popen instance

decryptor_process = None

decryptor subprocess.Popen instance

encrypted = None

is the backup encrypted?

feed_tar2(filename, input_pipe)[source]

Feed data from filename to input_pipe

Start a cat process to do that (do not block this process). Cat subprocess instance will be in tar2_feeder


Relocate files in given director when it’s already extracted

Parameters:dirname – directory path to handle (relative to backup root), without trailing slash
import_process = None

data import multiprocessing.Process instance

passphrase = None

passphrase to decrypt/authenticate data

progress_callback = None

callback reporting progress to UI

queue = None

queue with files to extract


Method to be run in sub-process; can be overridden in sub-class

tar2_current_file = None

current inner tar archive name

tar2_feeder = None

cat process feeding tar2_process

tar2_process = None

inner tar layer extraction (subprocess.Popen instance)

verify_only = None

only verify integrity, don’t extract anything


Generate a list of supported hmac algorithms

Parameters:crypto_algorithm – default algorithm, if given, it is placed as a first element

Generate a list of supported hmac algorithms

Parameters:hmac_algorithm – default algorithm, if given, it is placed as a first element

Collect supported hmac and crypto algorithms.

This calls openssl to list actual supported algos.

qubesadmin.backup.restore.launch_proc_with_pty(args, stdin=None, stdout=None, stderr=None, echo=True)[source]

Similar to pty.fork, but handle stdin/stdout according to parameters instead of connecting to the pty

:return tuple (subprocess.Popen, pty_master)

qubesadmin.backup.restore.launch_scrypt(action, input_name, output_name, passphrase)[source]

Launch ‘scrypt’ process, pass passphrase to it and return subprocess.Popen object.

  • action – ‘enc’ or ‘dec’
  • input_name – input path or ‘-’ for stdin
  • output_name – output path or ‘-’ for stdout
  • passphrase – passphrase

subprocess.Popen object

Module contents

Qubes backup

class qubesadmin.backup.BackupApp(qubes_xml)[source]

Bases: object

Interface for backup collection


Load qubes.xml

class qubesadmin.backup.BackupVM[source]

Bases: object

Interface for a single VM in the backup

backup_path = None

VM path in the backup

features = None

VM features (key/value), aka services in core2

handle_firewall_xml(vm, stream)[source]

Import appropriate format of firewall.xml


Report whether a VM is included in the backup

klass = None

VM class

label = None

VM label

name = None

VM name

properties = None

VM properties

size = None

size of the VM

tags = None

VM tags

template = None

VM template