Upgrading from Previous Versions 3.0

This guide describes the installation procedure for systems that are already running a 2.0 or 2.2 OpenNebula. The upgrade will preserve all current users, hosts, resources and configurations; for both Sqlite and MySQL backends.

Read the Compatibility Guide and Relase Notes to know what is new in OpenNebula 3.0 .


Before proceeding, make sure you don't have any VMs in a transient state (prolog, migr, epil, save). Wait until these VMs get to a final state (runn, suspended, stopped, done). Check the Managing Virtual Machines guide for more information on the VM life-cycle.

Stop OpenNebula and any other related services you may have running: EC2, OCCI, and Sunstone.

$ sunstone-server stop
$ econe-server stop
$ occi-server stop
$ one stop


Backup the configuration files located in /etc/one. You don't need to do a manual backup of your database, the onedb command will perform one automatically.


Follow the Installation guide, taking into account that you will already have configured the passwordless ssh access for oneadmin.

In case of conflict, merge the configuration files. Some custom drivers may need new additional parameters, check the oned.conf reference for 2.2 and 3.0 versions.

The configuration files format of the EC2, OCCI and Sunstone servers has changed. In OpenNebula 3.0, these parameters have to be defined using yaml instead of bash syntax. Check the configuration guides for more information.

Database Upgrade

The database schema and contents are incompatible between 2.x and 3.0 versions. The 3.0 OpenNebula daemon checks the existing DB version, and will fail to start if the version found is not the one expected, with the message 'Database version mismatch'.

You can upgrade the existing DB with the 'onedb' command. This command reads the DB connection parameters from oned.conf, but you can specify any Sqlite or MySQL database. Check the man page for more information.

After you install OpenNebula 3.0, and fix any possible conflicts in oned.conf, you can issue the 'onedb upgrade -v' command. If everything goes well, you should get an output similar to this:

$ onedb upgrade -v
Version read:
2.0 : Could not read any previous db_versioning data, assuming it is an OpenNebula 2.0 or 2.2 DB.

Sqlite database backup stored in /var/lib/one/one.db.bck
Use 'onedb restore' or copy the file back to restore the DB.
  > Running migrator /usr/lib/one/ruby/onedb/2.0_to_2.9.80.rb
  > Done

Database migrated from 2.0 to 3.0 (OpenNebula 3.0) by onedb command.

:!: Make sure you keep the backup file. If you face any issues, the onedb command can restore this backup, but it won't downgrade databases to previous versions.


You should be able now to start OpenNebula as usual, running 'one start' as oneadmin. OpenNebula will continue the monitoring and management of your previous Hosts and VMs.

As a measure of caution, look for any error messages in oned.log, and check that all drivers are loaded successfully. After that, keep an eye on oned.log while you issue the onevm, onevnet, oneimage, oneuser, onehost 'list a' commands. Try also using the show subcommand for some resources.

Restoring the Previous Version

If for any reason you need to restore your previous 2.0 or 2.2 OpenNebula, follow these steps:

  • With OpenNebula 3.0 still installed, restore the DB backup using 'onedb restore -f'
  • Uninstall OpenNebula 3.0, and install again version 2.0 or 2.2.
  • Copy back the backup of /etc/one you did to restore your configuration.

Known Issues

If the MySQL database password contains specials characters, such as @ or #, the onedb command will fail to connect to it.

The workaround is to temporarily change the oneadmin's password to an ASCII string. The set password statement can be used for this:

$ mysql -u oneadmin -p

mysql> SET PASSWORD = PASSWORD('newpass');

If you are using the MySQL backend, you can't use the command line options to specify the connection parameters. Read the Known Issues documentation for more details.