oVirt Engine - Open Virtualization Manager

Welcome to the oVirt Engine - Open Virtualization Manager source repository.

React webadmin (this fork)

This fork replaces the GWT webadmin with a React 19 / PatternFly 6 frontend and migrates the engine to Jakarta EE (WildFly 40, Java 21). The frontend lives in frontend/webadmin-react/ (Vite + TypeScript, plus a small Node BFF for httpOnly-cookie authentication) and is deployed alongside the engine RPMs with frontend/webadmin-react/deploy/install-frontend-bff.sh — see frontend/webadmin-react/README.md and frontend/webadmin-react/deploy/README.md.

A fresh engine-setup that provisions a local database targets PostgreSQL 16 (on EL9 it enables the postgresql:16 dnf module stream before initializing the cluster, so the postgresql:16 stream must be available from a configured repository). Existing PostgreSQL 13+ databases and remote databases remain supported unchanged.

Screenshots

These are real screenshots from a running deployment (not mockups) — three hosts, live utilization telemetry, and real inventory served by the engine’s REST API.

Figure 1. Dashboard

Figure 2. Hosts

Figure 3. Virtual Machines

Figure 4. Storage Domains

Figure 5. Data Centers

How to contribute

Submitting patches

Patches are welcome!

Please submit patches to github.com:ovirt-engine. If you are not familiar with the review process you can read about Working with oVirt on GitHub on the oVirt website.

Found a bug or documentation issue?

To submit a bug or suggest an enhancement for oVirt Engine please use oVirt GitHub issues.

If you find a documentation issue on the oVirt website please navigate and click "Report an issue on GitHub" in the page footer.

Still need help?

If you have any other questions, please join oVirt Users forum / mailing list and ask there.

Developer mode installation

Preparations

Prerequisites

Install the following system components:

• java-21-openjdk-devel

• mime-types or mailcap

• unzip

• openssl

• bind-utils

• postgresql-server >= 16 (on EL9: sudo dnf -y module enable postgresql:16 first; this fork standardizes on PostgreSQL 16 — existing 13+ databases remain supported)

• postgresql >= 16

• postgresql-contrib >= 16

• python3-dateutil / dateutil

• python3-cryptography / cryptography

• python3-m2crypto / m2crypto

• python3-psycopg2 / psycopg

• python3-jinja2 / Jinja2

• python3-libxml2 / libxml2[python]

• python3-daemon

• python3-otopi >= 1.10.0

• python3-ovirt-setup-lib

• maven >= 3.6.0

• ansible-core >= 2.12.0

• ansible-runner >= 2.1.3

• ovirt-ansible-roles >= 1.2.0

• ovirt-imageio-daemon >= 2.0.6

• ovirt-engine-metrics (optional)

• ovirt-provider-ovn (optional)

• python3-ovirt-engine-sdk4 (optional)

• ansible-lint / python3-ansible-lint (optional)

• python3-flake8 / pyflakes (optional)

• python3-pycodestyle / pycodestyle (optional)

• python3-isort (optional)

• python3-distro

Note on Java versions

The engine is built and runs on Java 21. The RPM build requires the maven-openjdk21 toolchain (see the BuildRequires lines in ovirt-engine.spec.in).

Prepare your dev environment for Java 21

• Use the alternatives command to select Java 21 for both java and javac:

$ sudo alternatives --config java
$ sudo alternatives --config javac

• If mvn is not already running on Java 21, export JAVA_HOME (for example in your ~/.bashrc) and verify:

$ export JAVA_HOME=/usr/lib/jvm/java-21-openjdk

$ mvn -v | grep "Java version: "
Java version: 21.0.4, vendor: Red Hat, Inc.

WildFly 40 is required along with ovirt-engine-wildfly-overlay. Preferred way is to install following packages:

• ovirt-engine-wildfly

• ovirt-engine-wildfly-overlay

Both packages can be installed from oVirt COPR CentOS repositories. Repository list can be updated using the following commands:

+ $ sudo dnf copr enable -y ovirt/ovirt-master-snapshot centos-stream-9 $ sudo dnf install -y ovirt-release-master

• For more info see copr master-snapshot repositories.

OVN/OVS is an optional dependency. If you want to use it, check the requirements in the ovirt-engine.spec.in file for a list of packages. Otherwise, you should reply 'No' when asked about it by engine-setup.

System settings

Development environment by default uses ports 8080 (HTTP), 8443 (HTTPS), 8787 (java debug), and 54323 (ovirt-imageio-proxy) so make sure they are accessible from the outside. For example:

firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --add-port=8443/tcp --permanent
firewall-cmd --add-port=8787/tcp --permanent
firewall-cmd --add-port=54323/tcp --permanent

If you also want to connect to the database from the outside:

firewall-cmd --add-port=5432/tcp --permanent

Finally, apply changes using:

firewall-cmd --reload

If compiling in a virtual machine, javac might experience difficulties on guests with dynamically growing RAM so it’s better to have VM’s starting allocation and maximum allocation set to the same value.

PostgreSQL accessibility

On EL9, make sure the PostgreSQL 16 stream is enabled before installing the server packages (sudo dnf -y module enable postgresql:16), then initialize the PostgreSQL configuration files:

$ sudo postgresql-setup --initdb --unit postgresql

Configure PostgreSQL to accept user and password:

Locate pg_hba.conf within your distribution, common locations are:

• /var/lib/pgsql/data/pg_hba.conf

• /etc/postgresql-*/pg_hba.conf

• /etc/postgresql/*/main/pg_hba.conf

Within pg_hba.conf set method to password for 127.0.0.1/32 and ::1/128 for IPv4 and IPv6 local connections correspondingly.

If you want to make postgres accessible from the outside, change 127.0.0.1/32 to 0.0.0.0/0 and ::1/128 to ::/0.

Tune PostgreSQL configuration: Locate postgresql.conf within your distribution, common locations are:

• /var/lib/pgsql/data

• /etc/postgresql*

Within postgresql.conf make sure following values are set:

max_connections = 150
work_mem = 8MB
autovacuum_max_workers = 6
autovacuum_vacuum_scale_factor = 0.01
autovacuum_analyze_scale_factor = 0.075
maintenance_work_mem = 64MB

If you want to connect from the outside, set also:

listen_addresses = '*'

Enable and start (systemctl enable postgresql --now).

Database creation

Create database for ovirt-engine, usually the following sequence should work to create a user named engine that owns database named engine:

# su - postgres -c "psql -d template1"
template1=# create user engine password 'engine';
template1=# drop database engine;
template1=# create database engine owner engine template template0
encoding 'UTF8' lc_collate 'en_US.UTF-8' lc_ctype 'en_US.UTF-8';
template1=# \q

Enable uuid-ossp extension for the database:

# su - postgres -c "psql -d engine"
engine=# CREATE EXTENSION "uuid-ossp";
engine=# \q

Ansible Runner configration

Since oVirt 4.5 the engine is integrated with ansible-core and ansible-runner, so you need to install RPM packages for both, but not additional configuration is required.

All previously used configuration for ansible-runner-service is no longer relevant and 'ansible-runner-service*' packages and configuration can be removed.

Development

Environment

Development environment is supported only under non-root account. Do not run this sequence as root.

Each instance of application must be installed at different PREFIX and use its own database. Throughout this document application is installed using PREFIX="${PREFIX}" and engine database and user, these should be changed if a new instance is required. Do not mix different versions of product with same PREFIX/database.

From this point on, the "${PREFIX}" will be used to mark the prefix in which you selected to install the development environment.

Build

To build and install ovirt-engine at your home folder under ovirt-engine directory execute the following command:

$ make clean install-dev PREFIX="${PREFIX}"

Note	${PREFIX} should be replaced with the location in which you intend to install the environment.

Note	Add SKIP_CHECKS=1 to disable tests.

Build targets

all

Build project.

clean

Clean project.

all-dev

Build project for development.

install-dev

Install a development environment at PREFIX.

dist

Create source tarball out of git repository.

maven

Force execution of maven.

generated-files

Create file from templates (.in files).

When creating new templates, generated files will be automatically appears in .gitignore, updated .gitignore should be part of committing new templates.

Build customization

The following Makefile environment variables are available for build customization:

PREFIX

Installation root directory. Default is /usr/local.

BUILD_DEV

Add extra development flags. Usually this should not be used directly, as the all-dev sets this. Default is 0.

BUILD_UT

Perform unit tests during build. Default is 1.

BUILD_JAVA_OPTS_MAVEN

Maven JVM options. Can be defined as environment variable. Default is empty.

DEV_EXTRA_BUILD_FLAGS

Any extra maven build flags required for building.

DEV_REBUILD

Disable if only packaging components were modified. Default is 1.

PY_VERSION

Python defaults to python3 if available, use PY_VERSION=2 in order to override.
This options affects various services and several features written in python.

Note	engine-setup which runs otopi, uses different customized variable OTOPI_PYTHON

WILDFLY_OVERLAY_MODULES

Change location of WildFly overlay modules. If you want to disable WildFly overlay configuration completely, please set to empty string. Default is /usr/share/ovirt-engine-wildfly-overlay/modules.

ISORT

Set name/location of the isort utility, which is used during make validations (also called from make install-dev). Defaults to isort. If not found, that’s ok. If found, should be at least version 5.7. The version in CentOS Stream 8 is ok. The version provided by RHEL 8 (and rebuilds) is too old, 4.3. Some ways to get a newer version:

• dnf copr enable -y sbonazzo/EL8_collection

• Install from pypi in a python virtualenv/venv, e.g.:

sudo dnf install python3-virtualenv
mkdir -p $HOME/venv
cd $HOME/venv
virtualenv-3 python3-isort
. python3-isort/bin/activate
pip install isort

And, before running make,

export ISORT=$HOME/venv/python3-isort/bin/isort

If you do have an older version installed and want make to ignore it, you can point the variable at some non-existing name/location, e.g.:

export ISORT=nonexistent

Setup

To setup the product use the following command:

$ "${PREFIX}/bin/engine-setup"

Note	otopi, and therefore engine-setup, now defaults to python3 except el7, use: $ OTOPI_PYTHON=/usr/bin/python2 "${PREFIX}/bin/engine-setup" to override.

During engine setup, a certificate has to be issued and you will be asked for a hostname. If you want to upload and download images from administration portal, it has to be the name by which your machine is accessible from the outside.

JBoss

If you want to use different WildFly/EAP installation, specify it at --jboss-home= parameter of setup.

Environment

OVIRT_ENGINE_JAVA_HOME

Select a specific Java home.

OVIRT_ENGINE_JAVA_HOME_FORCE

Set to non zero to bypass Java compatibility check.

Refresh

If there are no significant changes, such as file structure or database schema, there is no need to run the setup again, make install-dev <args> will overwrite files as required, run engine-setup to refresh database schema.

Do remember to restart the engine service.

If there is a significant change, safest path is to stop service, remove ${PREFIX} directory, build and setup.

The ${PREFIX}/bin/engine-cleanup tool is also available to cleanup the environment, it is useful for application changes, less for packaging changes.

Service administration

Most utilities and services are operational, including PKI, host deploy.

To start/stop the engine service use:

$ "${PREFIX}/share/ovirt-engine/services/ovirt-engine/ovirt-engine.py" start

While the service is running, this command will not exit. Press <Ctrl>-C to stop service.

Access using HTTP or HTTPS:

• http://<server>:8080

• https://<server>:8443

Remote debug

By default, debug address is 127.0.0.1:8787. If you want to make engine accessible to the remote debugger, after running engine-setup edit the following file: ${PREFIX}/etc/ovirt-engine/engine.conf.d/10-setup-protocols.conf:

ENGINE_DEBUG_ADDRESS=0.0.0.0:8787

Running instance management (JMX)

ovirt-engine service supports jmx as management interface. Actually, this is the standard jboss jmx interface, while authentication can be done using any engine user with SuperUser role. Access is permitted only from the local host.

Access JMX shell using provide OPTIONAL_COMMAND for non interactive usage:

$ "${JBOSS_HOME}/bin/jboss-cli.sh" \
  --connect \
  --timeout=30000 \
  --controller=localhost:8706 \
  --user=admin@internal \
  --commands="OPTIONAL_COMMA_SEPARATED_COMMANDS"

Useful commands:

Modify log level

/subsystem=logging/logger=org.ovirt.engine.core.bll:write-attribute(name=level,value=DEBUG)

Create a new log category

/subsystem=logging/logger=org.ovirt.engine:add

Get the engine data-source statistics

ls /subsystem=datasources/data-source=ENGINEDataSource/statistics=jdbc/

Get threading info

ls /core-service=platform-mbean/type=threading/

By default JMX access is available only to localhost, to open JMX to world, add ${PREFIX}/etc/ovirt-engine/engine.conf.d/20-setup-jmx-debug.conf with:

ENGINE_JMX_INTERFACE=public

DAO tests

Create empty database for DAO tests refer to Database creation.

Provided user is engine, password is engine and database is engine_dao_tests.

$ PGPASSWORD=engine \
  ./packaging/dbscripts/schema.sh \
    -c apply -u engine -d engine_dao_tests

Run build as:

$ make maven BUILD_UT=1 EXTRA_BUILD_FLAGS="-P enable-dao-tests \
  -D engine.db.username=engine \
  -D engine.db.password=engine \
  -D engine.db.url=jdbc:postgresql://localhost/engine_dao_tests"

VM console

After the environment is setup and installed, some adjustments are required.

Copy vmconsole-host configuration:

$ sudo cp -p "${PREFIX}/share/ovirt-engine/conf/ovirt-vmconsole-proxy.conf \
/etc/ovirt-vmconsole/ovirt-vmconsole-proxy/conf.d/50-ovirt-vmconsole-proxy.conf

If selinux is enabled on your machine, set type on vmconsole helper using:

$ sudo chcon --type=bin_t "${PREFIX}/libexec/ovirt-vmconsole-proxy-helper/ovirt-vmconsole-list.py"

ovirt-imageio

After setup, you need to run ovirt-imageio manually if you want to upload and download images via the administration portal. To run ovirt-imageio, run the following command:

$ ovirt-imageio --conf-dir $PREFIX/etc/ovirt-imageio

This assumes you have installed ovirt-imageio-daemon and you have run engine-setup.

In development mode, ovirt-imageio logs to stderr using DEBUG level. If you would like to log to a file create a log directory:

$ mkdir $PREFIX/var/log/ovirt-imageio

And install a drop-in configuration file to override engine developement setup:

$ cat $PREFIX/etc/ovirt-imageio/conf.d/99-local.conf
[handlers]
keys = logfile

[logger_root]
handlers = logfile

[handler_logfile]
args = ('/home/username/ovirt-engine/log/ovirt-imageio/daemon.log',)

RPM packaging

$ make dist
$ rpmbuild -ts @tarball@
# yum-builddep @srpm@
# rpmbuild -tb @tarball@

The following spec file variable is available for package customization:

ovirt_build_quick

Quick build that skips unit tests, best for syntax checks. Default is 0.

Ansible Lint

To use ansible-lint locally you need to install it from PyPI in a python virtualenv/venv, e.g.:

sudo dnf install python3-virtualenv
mkdir -p $HOME/venv
python3 -m venv $HOME/venv/ansible-lint
. $HOME/venv/ansible-lint/bin/activate
pip3 install "ansible-lint>=6.0.0,<7.0.0"

Run of the lint:

$ ansible-lint -c build/ansible-lint.conf packaging/ansible-runner-service-project/project/roles/*

Branch/release management

Git branch master should always have the latest version.

Releases should be done from stable branches. So-called "bump patches", to increase the version, should be created using the script bump_release.sh. This creates two git commits - one for doing the release, which should be tagged, and the next one for getting back to development builds, which have a timestamp+git-hash in their RPMs names.

When branching stable branches, master branch should be bumped to the next Y or Z version. There is currently no script for doing that. It can be done using something like:

find . -name pom.xml -exec sed -i "s:4.5.1.3-SNAPSHOT:4.5.2-SNAPSHOT:" {} +

Replace 4.5.1.3 with the current version, and 4.5.2 with the version you want to bump to.