Compatibility Guide

This guide is aimed at OpenNebula 6.6.x users and administrators who want to upgrade to the latest version. The following sections summarize the new features and usage changes that should be taken into account, or are prone to cause confusion. You can check the upgrade process in the corresponding section. If upgrading from previous versions, please make sure you read all the intermediate versions’ Compatibility Guides for possible pitfalls.

Visit the Features list and the What’s New guide for a comprehensive list of what’s new in OpenNebula 7.0.

Configuration Files Headers

In order to avoid breaking compatibility with older versions of OpenNebula headers have been removed from all the configuration files. This change will be taken care transparently by the onecfg tool, but it will show in manual diffs with older versions of the configuration files.

/* -------------------------------------------------------------------------- */
/* Copyright 2002-2023, OpenNebula Project, OpenNebula Systems                */
/*                                                                            */
/* Licensed under the Apache License, Version 2.0 (the "License"); you may    */
/* not use this file except in compliance with the License. You may obtain    */
/* a copy of the License at                                                   */
/*                                                                            */
/*                                 */
/*                                                                            */
/* Unless required by applicable law or agreed to in writing, software        */
/* distributed under the License is distributed on an "AS IS" BASIS,          */
/* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   */
/* See the License for the specific language governing permissions and        */
/* limitations under the License.                                             */
/* -------------------------------------------------------------------------- */

Datastore & Transfer Manager Drivers Arguments

Datastore driver actions take the information from stdin to prevent a Argument list too long error when there is a large number of images in a datastore. All configuration and driver files has been updated and no special action needs to be performed. However if you have develop your own datastore drivers those should be updated accordingly.

The backup operation now includes a new argument to accommodate the backup jobs. This shifts the vm_id and ds_id one position to preserve the convention across actions. Additionally the backup URLs (restic:// and rsync://) also include the backup job id, that also changes the position of some URL tokes. This will only affect to custom backup drivers.

KVM and Shared/Qcow2 Transfer Manager Drivers

In order to implement the disk-snapshot delete operation (via virsh blockcommit/blockpush and qemu-img rebase) some internal changes has been made, namely:

  • KVM deployment files are re-written on the fly to resolve the disk.<disk_id> symbolic links. This solves an issue that prevents a correct backingStore to be constructed by libvirt for the VMs.

  • When a snapshot is deleted (<vm_folder>/disk.<disk_id>.snap/<snap_id>) some times it is necessary to adjust actual file names supporting a given snapshot. In this case a file ended by .current is created. All related operations have been updated to react to the presence of this file.

This changes are not exposed by any OpenNebula interface and are not an issue for any existing VM while upgrading your cloud.


Some CLI commands that accept template files are able to receive the same template via STDIN, thus bypassing the need of a temporary file to hold the template contents. This means the file argument is now optional and the OpenNebula CLI will check for STDIN if the file argument is missing. The template must have bash symbols like $ escaped, these are used for TEMPLATE references.

Restricted Attributes

Previous versions of OpenNebula silently ignored the removal of restricted attributes. However, with the resolution of the issue 6315, an error will be generated always in such cases.


In previous versions of OpenNebula, label casing was consistently preserved. However, starting with version 6.8.0, in light of enhancements to our filtering system, we’ve transitioned to standardizing label names in uppercase. This change ensures better system consistency and performance. For a more detailed overview of this change you can refer to the related discussion here.

To ensure a seamless experience for our users, we’ve introduced a migrator in this update, which automatically handles the transition.

OneGate Proxy

We are actively developing an enhanced version of the OneGate Proxy implementation that comes with reduced requirements. Starting from release 6.8.2, we strongly recommend disabling this component and following the recommened network configuration outlined in the OneGate Configuration guide.