qubesadmin.backup package

Submodules

qubesadmin.backup.core2 module

Parser for core2 qubes.xml

class qubesadmin.backup.core2.Core2Qubes(store=None)

Bases: BackupApp

Parsed qubes.xml

import_core2_vm(element)

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()

Load qubes.xml

load_globals(element)

Load global settings

Parameters:

element – XML element containing global settings (root node)

set_netvm_dependency(element)

Set dependencies between VMs

class qubesadmin.backup.core2.Core2VM

Bases: BackupVM

VM object

handle_firewall_xml(vm, stream)

Load old (Qubes < 4.0) firewall XML format

property included_in_backup

Report whether a VM is included in the backup

static rule_from_xml_v1(node, action)

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

Parameters:

• 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)

Bases: BackupApp

Parsed qubes.xml

static get_property(xml_obj, prop)

Get property of given object (XML node)

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

import_core3_vm(element)

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()

Load qubes.xml

load_globals(globals_element)

Load global settings

Parameters:

globals_element – XML element containing global settings

load_labels(labels_element)

Load labels table

class qubesadmin.backup.core3.Core3VM

Bases: BackupVM

VM object

handle_firewall_xml(vm, stream)

Load new (Qubes >= 4.0) firewall XML format

property included_in_backup

Report whether a VM is included in the backup

qubesadmin.backup.restore module

Backup restore module

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

Bases: 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)

Bases: object

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

class Header(field, t, validator)

Bases: tuple

field

Alias for field number 0

t

Alias for field number 1

validator

Alias for field number 2

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

load(untrusted_header_text)

Parse backup header file.

Parameters:

untrusted_header_text (basestring) – header content

Warning

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

save(filename)

Save backup header into a file

validate()

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=None)

Bases: object

Usage:

>>> 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)

Bases: VMToRestore

Information about dom0 home to restore

USERNAME_MISMATCH = <object object>

backup was performed on system with different dom0 username

class VMToRestore(vm)

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

property good_to_go

Is the VM ready for restore?

app

qubes.Qubes instance

backup_app

VMs included in the backup

backup_location

backup path, inside VM pointed by backup_vm

backup_vm

VM from which backup should be retrieved

canceled

is the backup operation canceled

check_disk_space()

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.

Returns:

force_compression_filter

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

get_restore_info()

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)

Return a ASCII formatted table with restore info summary

header_data

basic information about the backup

location_is_service

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)

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

options how the backup should be restored

passphrase

passphrase protecting backup integrity and optionally decryption

processes_to_kill_on_cancel

list of processes (Popen objects) to kill on cancel

restore_do(restore_info)

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

Parameters:

restore_info –

Returns:

restore_info_verify(restore_info)

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

class qubesadmin.backup.restore.BackupRestoreOptions

Bases: object

Options for restore operation

dom0_home

restore dom0 home

exclude

list of VM names to exclude

ignore_size_limit

ignore size limit calculated from backup metadata

ignore_username_mismatch

restore dom0 home even if username is different

override_pool

restore VMs into selected storage pool

verify_only

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)

Bases: Process

Process for handling inner tar layer of backup archive

base_dir

paths on the queue are relative to this dir

blocks_backedup

progress

check_processes(processes)

Check if any process failed.

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

cleanup_tar2(wait=True, terminate=False)

Cleanup running tar2_process

Parameters:

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

• terminate – terminate the process if still running

collect_tar_output()

Retrieve tar stderr and handle it appropriately

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

compressed

is the backup compressed?

crypto_algorithm

what crypto algorithm is used for encryption?

decompressor_process

decompressor subprocess.Popen instance

decryptor_process

decryptor subprocess.Popen instance

encrypted

is the backup encrypted?

feed_tar2(filename, input_pipe)

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

handle_dir(dirname)

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

data import multiprocessing.Process instance

passphrase

passphrase to decrypt/authenticate data

progress_callback

callback reporting progress to UI

queue

queue with files to extract

run()

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

tar2_current_file

current inner tar archive name

tar2_feeder

cat process feeding tar2_process

tar2_process

inner tar layer extraction (subprocess.Popen instance)

verify_only

only verify integrity, don’t extract anything

qubesadmin.backup.restore.get_supported_crypto_algo(crypto_algorithm=None)

Generate a list of supported hmac algorithms

Parameters:

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

qubesadmin.backup.restore.get_supported_hmac_algo(hmac_algorithm=None)

Generate a list of supported hmac algorithms

Parameters:

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

qubesadmin.backup.restore.init_supported_hmac_and_crypto()

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)

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)

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

Parameters:

• action – ‘enc’ or ‘dec’

• input_name – input path or ‘-’ for stdin

• output_name – output path or ‘-’ for stdout

• passphrase – passphrase

Returns:

subprocess.Popen object

Module contents

Qubes backup

class qubesadmin.backup.BackupApp(qubes_xml)

Bases: object

Interface for backup collection

load()

Load qubes.xml

class qubesadmin.backup.BackupVM

Bases: object

Interface for a single VM in the backup

backup_path

VM path in the backup

features

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

handle_firewall_xml(vm, stream)

Import appropriate format of firewall.xml

property included_in_backup

Report whether a VM is included in the backup

klass

VM class

label

VM label

name

VM name

properties

VM properties

size

size of the VM

tags

VM tags

template

VM template