virt-scenario.1

.\" Automatically generated by Pandoc 2.18
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "" "" "" "" ""
.hy
.SH Name
.PP
virt-scenario - Create XML config and prepare host for a specific
scenario
.SH Goals
.PP
This is an \f[B]EXPERIMENTATION\f[R] project for SUSE ALP
MICRO (https://documentation.suse.com/alp/all/)
.PP
It prepares a libvirt XML guest configuration and the host to run a
customized guest.
Idea is to use multiple \f[B]templates\f[R] and concatenate them to
create the expected Guest XML file.
.PP
IE: setting up a secure VM is not so easy from scratch, this tool will
prepare the host, the XML guest config with secure parameter, and will
deal with all the certificate, attestation and launch measurement.
In only 2 commands you can start a secure VM on an AMD SEV system!
It also simplify the usage of disk Image encryption.
.PP
Customization to match a specific scenario is not graved in stone.
The idea is to prepare a configuration which should improved the usage
compared to a basic setting.
This will \f[B]NOT guarantee\f[R] that this is perfect as this higly
depends on your current system.
.PP
[IMAGE: Interactive (https://i.postimg.cc/rsHLgQMw/vs-interactive.jpg)]
[IMAGE: Gtk (https://img.youtube.com/vi/6JdvKknc-2A/0.jpg)] (https://www.youtube.com/watch?v=6JdvKknc-2A)
.SH User Settings
.PP
User can set some parameter in the
\f[B]/etc/virt-scenario/virtscenario.yaml\f[R].
This will override the scenario settings.
A table will be displayed showing the recommended settings VS the
current one.
.PP
Example:
.IP
.nf
\f[C]
# WARNING: INCORRET PARAMATERS WILL LEAD TO BAD VM CONFIGURATION
# Dont change the section name
# This will overwrite scenario settings....
config:
  - path: /etc/virt-scenario
  - vm-config-store: /etc/virts-scenario/vmconfig
emulator:
  - emulator: /usr/bin/qemu-system-x86_64
input:
  - keyboard: virtio
  - mouse: virtio
architecture:
  - arch: x86_64
STORAGE_DATA:
# some options are only available with qcow2 format and
# will be ignored in case of any other image format
  - disk_type: file
#  - disk_cache: none
  - disk_target: vda
  - disk_bus: virtio
  - path: /var/livirt/images
  - format: qcow2
# host side: qemu-img creation options (-o), qemu-img --help
  - unit: G
  - capacity: 20
  - cluster_size: 1024
  - lazy_refcounts: on
# preallocation: off, metadata (qcow2), falloc, full
  - preallocation: off
  - compression_type: zlib
  - encryption: off
host_filesystem:
  - fmode: 644
  - dmode: 755
  - source_dir: /tmp
  - target_dir: /tmp/host
\f[R]
.fi
.PP
\f[B]/etc/virt-scenario/virthosts.yaml\f[R] is used to define an
Hypervisors list mostly for secure VM configuration.
.IP
.nf
\f[C]
localhost:
  url: qemu:///system
# Generate with \[aq]sevctl export --full filename.pdh\[aq] on the given host
  sev-cert: /path/to/host-cert-chain.pdh
\f[R]
.fi
.SH Usage
.SS Get it and use it
.SS From source code
.PP
\f[B]main.py\f[R] will create an \f[B]xml\f[R] based file on template
and validate it.
It will also prepare the host system and create the VM image file.
Currently \f[B]desktop\f[R], \f[B]computation\f[R] and
\f[B]securevm\f[R] are available.
.IP
.nf
\f[C]
git clone https://github.com/aginies/virt-scenario.git
cd virt-scenario/src
python3 -m virtscenario
> conf virtscenario.yaml
> desktop
\f[R]
.fi
.PP
Tool to select a firmware based on feature:
.IP
.nf
\f[C]
python3 -m virt_select_firmware
\f[R]
.fi
.PP
Tool to launch the VM from the config file generated by virt-scenario:
.IP
.nf
\f[C]
python3 -m virtscenario-launch
\f[R]
.fi
.PP
GTK virt-scenario:
.IP
.nf
\f[C]
python3 -m vsmygtk
\f[R]
.fi
.SS From Package
.PP
Get the package for your Distribution and install it.
For openSUSE, SLES:
.IP \[bu] 2
devel stable
project (https://build.opensuse.org/package/show/Virtualization/virt-scenario)
.IP \[bu] 2
devel
unstable (https://build.opensuse.org/package/show/home:aginies/virt-scenario)
.PP
You should run this tool as \f[B]root\f[R] to configure host part, for
the Gtk you can use \f[B]gnomesu\f[R] to launch it as root.
.IP \[bu] 2
\f[B]virt-scenario\f[R]: CMD Interactive mode (console)
.IP \[bu] 2
\f[B]virt-scenario-gtk\f[R]: The GTK interface
.SS virt-scenario as an API
.PP
\f[B]virt-scenario\f[R] is usable from \f[B]Cmd Interactive\f[R] or
using a \f[B]GTK interface\f[R].
It also provides an \f[B]API\f[R].
A commented Demo example file is available.
.SS Default configuration
.PP
The default configuration for VM definition are: * \f[B]disk path
image\f[R]: /var/libvirt/qemu * \f[B]arch\f[R]: x86_64 *
\f[B]machine\f[R]: pc-q35-6.2 * \f[B]boot_dev\f[R]: hd *
\f[B]emulator\f[R]: /usr/bin/qemu-system-x86_64 * \f[B]input\f[R]:
keyboard and mouse as virtio
.PP
They could be overwriten by the choosen scenario.
.PP
Depending on scenario the default will change to some other value.
.SS Interactive commands
.SS virt-scenario configuration
.IP \[bu] 2
\f[B]overwrite\f[R]: Force overwrite previous setting
.IP \[bu] 2
\f[B]mode\f[R]: Guest/Host/Both mode
.IP \[bu] 2
\f[B]conf\f[R]: Setting the virt-scenario configuration file
.SS Hypervisor configuration
.IP \[bu] 2
\f[B]hvconf\f[R]: Load Hypervisor configuration
.IP \[bu] 2
\f[B]hvselect\f[R]: Set hypervisor for which VMs are configured
.IP \[bu] 2
\f[B]hvlist\f[R]: List available hypervisors
.IP \[bu] 2
\f[B]force_sev\f[R]: Force the extract of a localhost PDH file.
This is \f[B]NOT secure\f[R] as this file should be stored in a secure
place!
Only for demo purpose
.SS Guest configuration
.IP \[bu] 2
\f[B]name\f[R]: Define a name for the VM
.IP \[bu] 2
\f[B]vcpu\f[R]: Choose how many VCPU
.IP \[bu] 2
\f[B]memory\f[R]: Choose the Memory size (in GiB)
.IP \[bu] 2
\f[B]vnet\f[R]: Virtual Network for the VM
.IP \[bu] 2
\f[B]machine\f[R]: Select the Machine type (from a list)
.IP \[bu] 2
\f[B]bootdev\f[R]: Select the boot dev (from a list)
.IP \[bu] 2
\f[B]cdrom\f[R]: File Path to CD/DVD installation media
.IP \[bu] 2
\f[B]vmimage\f[R]: File path to an already existing VM image
.SS Storage Guest configuration
.IP \[bu] 2
\f[B]capacity\f[R]: Disk Size image (GiB)
.IP \[bu] 2
\f[B]format\f[R]: Select the Disk Image format (qcow2/raw)
.IP \[bu] 2
\f[B]cache\f[R]: Specify the Disk Cache mode
.IP \[bu] 2
\f[B]encryption\f[R]: Encrypt the VM Disk image
.IP \[bu] 2
\f[B]diskpath\f[R]: Directory where to store disk image
.SS Generate the XML configuration and prepare the host
.IP \[bu] 2
\f[B]computation\f[R]: Create an XML configuration and host config to do
computation VM
.IP \[bu] 2
\f[B]desktop\f[R]: Create an XML configuration and host config for
Desktop VM
.IP \[bu] 2
\f[B]securevm\f[R]: Create an XML configuration and host config for
Secure VM
.SS Others
.IP \[bu] 2
\f[B]shell\f[R]: Execution of a system command
.IP \[bu] 2
\f[B]info\f[R]: Get current host information about CPU and Memory
.SH Possible Scenarios
.SS Default Settings Comparison
.PP
This settings should be better than default one.
Of course this is not perfect, and there is maybe some mistakes.
Feel free to comment on this parameters or request addition of new one.
.PP
default_settings
.SS Not yet ready
.IP \[bu] 2
Testing an OS
.IP \[bu] 2
Easy migration of VM
.IP \[bu] 2
Soft RT VM (latency improvments)
.SH Devel Information
.PP
This is still \f[B]WIP\f[R], but the code is relatively stable.
.SS Devel planning / TODO
.IP \[bu] 2
[STRIKEOUT:mechanism to create the Guest XML file from template]
.IP \[bu] 2
[STRIKEOUT:define all scenarios (list)]
.IP \[bu] 2
[STRIKEOUT:post customization of XML config]
.IP \[bu] 2
[STRIKEOUT:show host configuration]
.IP \[bu] 2
[STRIKEOUT:implement interactive shell]
.IP \[bu] 2
[STRIKEOUT:check if running inside a container (for host
configuration)\&...]
.IP \[bu] 2
[STRIKEOUT:do more configuration on the Host side]
.IP \[bu] 2
[STRIKEOUT:create needed files on host: images, network definition,
etc\&...]
.IP \[bu] 2
[STRIKEOUT:define conflict/compatibility between scenarios (is this
still needed?)]
.IP \[bu] 2
improve customization based on scenario (need to get some QA on
this\&...)
.SS Code
.PP
Source (https://github.com/aginies/virt-scenario)
.PP
Issues (https://github.com/aginies/virt-scenario/issues)
.SS Class / Functions
.PP
All scenarios are define in the \f[B]Scenarios\f[R] class.
It can do direct configuration calling \f[B]BasicConfiguration.XXX\f[R]
or \f[B]ComplexConfiguration.XXX\f[R], or request a specific features
calling \f[B]Features.XXX\f[R].
User setting always overwrite any values set automatically by scenario.
.PP
Scenarios()
.IP
.nf
\f[C]
class Scenarios()
    -> BasicConfiguration.XXX
    -> ComplexConfiguration.XXX
    -> Features.XXX
\f[R]
.fi
.PP
Features()
.IP
.nf
\f[C]
class Features()
    -> XXX_perf() -> BasicConfiguration.XXX
                  -> ComplexConfiguration.XXX
\f[R]
.fi
.PP
BasicConfiguration()
.IP
.nf
\f[C]
class BasicConfiguration()
    name(self, name)
    vcpu(self, vcpu)
    cpumode_pass(self, migratable, extra)
    power(self, suspend_to_mem, suspend_to_disk)
    audio(self, model)
    input(self, inputtype, bus)
    usb(self, model)
    watchdog(self, model, action)
    emulator(self, emulator)
    memory(self, unit, max_memory, memory)
    osdef(self, arch, machine, boot_dev)
    ondef(self, on_poweroff, on_reboot, on_crash)
    features(self, features)
    clock(self, clock_offset, clock)
    iothreads(self, iothreads)
    security_f(self, sectype, secdata)
    video(self, model_type)
\f[R]
.fi
.PP
ComplexConfiguration()
.IP
.nf
\f[C]
ComplexConfiguration()
    disk(self, disk)
    network(self, mac, network, intertype, iommu)
    access_host_fs(self)
    tpm(self, tpm_model, tpm_type, device_path)
    tpm_emulated(self, tpm_model, tpm_type, version)
    access_host_fs(self, fmode, dmode, source_dir, target_dir)
\f[R]
.fi
.SS Templates definition
.PP
All templates are in the python lib \f[B]virt-scenario/template.py\f[R]
file.
.SS Files (virtscenario)
.IP \[bu] 2
virtscenario.yaml: user setting (overwrite scenario settings)
.IP \[bu] 2
virthosts.yaml Hypervisors list and settings
.IP \[bu] 2
libvirt.py Wrapper for getting libVirt domain capabilities
.IP \[bu] 2
firmware.py Select the firmware with the required feature-set
.IP \[bu] 2
sev.py Get parameters for configuring an SEV or SEV-ES VM and do
detaction
.IP \[bu] 2
template.py libvirt XML template definition
.IP \[bu] 2
scenario.py different call to create the XML based on the selected
scenario
.IP \[bu] 2
dict.py create the dict with data to file the template
.IP \[bu] 2
configuration.py all stuff related to configuration
.IP \[bu] 2
features.py prepare some features for the VM
.IP \[bu] 2
host.py create the storage and prepare the host
.IP \[bu] 2
guest.py create dict to file all the templates
.IP \[bu] 2
immutable.py Immutable data (to be removed when implementation will be
done\&...)
.IP \[bu] 2
qemulist.py provide list of available options in qemu and some default
path
.IP \[bu] 2
util.py internal needed functions
.IP \[bu] 2
cmd.py Python CMD interactive part
.IP \[bu] 2
main.py launch the tool and create the final XML file and host
configuration
.IP \[bu] 2
hypervisors.py list, select, connect to an hypervisor (or any other HV
action)
.IP \[bu] 2
configstore.py Guest configuration store (used mostly for Confidential
computing)
.SS Host configuration
.IP \[bu] 2
check CPU flag: sev, sev-es, pdpe1gb, pse
.IP \[bu] 2
check SEV on the system and libvirt enablement
.IP \[bu] 2
enable an AMD SEV system
.IP \[bu] 2
generate SEV attestation and update VM XML
.IP \[bu] 2
configure HugePages and THP
.IP \[bu] 2
enable/disable KSM
.IP \[bu] 2
adjust swappiness
.IP \[bu] 2
manage IO scheduler
.SS Possible Guest VM Features
.IP \[bu] 2
CPU performance
.IP \[bu] 2
System features
.IP \[bu] 2
Security
.IP \[bu] 2
Memory performance
.IP \[bu] 2
Storage performance
.IP \[bu] 2
Video (virtio or others)
.IP \[bu] 2
Network performance
.IP \[bu] 2
Clock performance
.IP \[bu] 2
Using host hardware
.IP \[bu] 2
Access host OS filesystem
.IP \[bu] 2
AMD SEV
.IP \[bu] 2
select right firmware for VM guest
.IP \[bu] 2
Disk Encryption
.SS Stuff currently immutable
.PP
This is currently not changeable using the template, this needs to be
adjusted in the futur (or not\&...): * console_data * channel_data *
memballoon_data * rng_data * Memory Backing * metadata_data * only
support 1 disk per VM
.SH Example with securevm (Confidential Computing)
.PP
virt-scenario currently only support setting secure Virtual Machine on
AMD SEV or SEV-ES system.
For more information about SUSE and SEV please refer to SLES AMD SEV.
.SS Prepare Your VM
.PP
virt-scenario provides different options to configure the Virtual
Machine.
In our example we will set different parameters to suit our needs, most
of them provides completion using the [TAB] key:
.IP
.nf
\f[C]
name ALPOS
vcpu 4
memory 8
vnet default
bootdev hd
vmimage /var/lib/libvirt/images/ALP-VM.x86_64-0.0.1-kvm_encrypted-Snapshot20230309.qcow2
force_sev on
\f[R]
.fi
.PP
This end up with a prompt like:
.IP
.nf
\f[C]
---------- User Settings ----------
Disk Path: /var/lib/libvirt/images
Main Configuration: /etc/virt-scenario/virtscenario.yaml
Hypervisor Configuration: /etc/virt-scenario/virthosts.yaml
Force SEV PDH extraction: on
Name: ALPOS
Vcpu: 4
Memory: 8
Boot Device: hd
Virtual Network: default
VM Image file: /var/lib/libvirt/images/ALP-VM.x86_64-0.0.1-kvm_encrypted-Snapshot20230309.qcow2
\f[R]
.fi
.SS Generate XML and prepare the host
.PP
You are ready to run \f[B]securevm\f[R] to prepare the host system and
generate the XML libvirt config:
.IP
.nf
\f[C]
securevm
\f[R]
.fi
.PP
The generated XML file is available in
\f[B]\[ti]/etc/virt-scenario/vmconfig/ALPOS/domain.xml\f[R].
You can also find a \f[B]config.yaml\f[R] which contains host data about
this VM.
In our case \f[B]attestation\f[R] will be set to true, the host will be
\f[B]localhost\f[R].
The \f[B]/etc/virt-scenario/virthosts.yaml\f[R] will be updated to
configure the correct path to the extracted PDH file (sev-cert).
.SS Launch the VM
.PP
Launch the VM with the \f[B]virt-scenario-launch\f[R] tool:
.IP
.nf
\f[C]
# virt-scenario-launch --start ALPOS
Connected to libvirtd socket; Version: 7001000
SEV(-ES) attestation passed!
Validation successfull for domain ALPOS
\f[R]
.fi
.SH Authors
.PP
Written by Antoine Ginies
.PP
Contributors: Joerg Roedel