qubesadmin.backup package

Submodules

qubesadmin.backup.core2 module

Parser for core2 qubes.xml

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

Bases: qubesadmin.backup.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: qubesadmin.backup.BackupVM

VM object

handle_firewall_xml(vm, stream)

Load old (Qubes < 4.0) firewall XML format

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: qubesadmin.backup.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: qubesadmin.backup.BackupVM

VM object

handle_firewall_xml(vm, stream)

Load new (Qubes >= 4.0) firewall XML format

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

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': 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>>)}

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

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

good_to_go

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

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

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

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

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

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

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

run()

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

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

VM path in the backup

features = None

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

handle_firewall_xml(vm, stream)

Import appropriate format of firewall.xml

included_in_backup

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