An OpenNebula Image represents a VM disk. Images can have multiple formats (e.g. filesystem or block device) and can store OS installations, data filesystems, images or kernels. In this guide you’ll learn about different Image types, and how to mange and use them.

Types and Persistency

OpenNebula uses three different Image types to represent VM disks. A VM can use multiple Image types simultaneously:

  • Operating System (OS): Main disk, the VM will start from this Image. Every VM must include an OS Image.

  • CD-ROM ISO (CDROM): These Images are read-only data. Only one Image of this type can be used in a VM.

  • Data Disk (DATABLOCK): A generic disk to store data. These Images can contain existing data, e.g. a database, or can be formatted as an empty drive.

Additionally, file Images represents plain files that can be used as:

  • OS kernel (KERNEL): used as kernel for the Guest OS to start the VM.

  • RAM disk (RAMDISK): loaded by initrd at boot time.

  • Generic file (CONTEXT): a plain file to be included in the context CD-ROM. Once started, the VM will have access to this file.


KERNEL, RAMDISK and CONTEXT file Images can be registered only in Files & Kernels Datastore. Some of the operations described in this guide do not apply to them, in particular: clone and persistent.

Images of the previous types can also operate in two modes:

  • Peristent, the modifications you made to persistent images will be preserved after terminating the VM. There can be only one VM using a persistent Image at any given time.

  • Non-Persistent, the modifications will not be preserved after terminating the VM. Non-persistent images can be used by multiple VMs at the same time as each one will work on its own copy.

States and Life-cycle

The images in your cloud will be moving through different states to represent the actions you perform and their status. The following table summarizes the Image states and their meaning:


Short state

OpenNebula State Names





Image is being copied or created. VMs that use the image will wait for the operation to finish






Image ready to be used.




Image used by at least one VM.





Image disabled by the owner, it cannot be used by new VMs.




Error state, an operation failed. See the Image information with oneimage show for an error message.




Image is being deleted from the Datastore.




Image is being cloned.

Creating Images

You have multiple options when creating a new Image in OpenNebula, from using your existing disk images to download them from public marketplaces. In this section you will learn how to use the oneimage command to create an Image.

No matter the method you use to create your images, there is a set of common options that will be useful in any case. The following table summarizes the main options that we will use:



--name name

Name of the new Image

--datastore name | ID

Name/ID of the Datastore to store the new Image

--description description

Description for the new Image (Optional)

--type type



Set the Image to persistent mode

--prefix prefix

Device/bus to expose the disk to guest OS (e.g. hd, sd or vd)

--target target

Device the disk will be attached to

--path path

Path/URL of the Image

--source source

Source to be used. Useful for not file-based Images

--size size

Size in MB. Used for DATABLOCK type or to resize the Image on boot

Using your existing disk files

You can use your existing virtual disks in OpenNebula. Simply, pick a name for your Image, grab the path where the disk is stored in the front-end, and choose the Datastore where you want to create the Image. The command will be similar to (by default OS Images are created):

oneimage create --datastore default --name Ubuntu --path /home/cloud/images/ubuntu-desktop/disk.0.qcow2 \
  --description "Ubuntu desktop for developers."

For OS Images, you need to install the OpenNebula context packages for your target guest OS before using them. There are no additional steps if you are creating a data disk.


You can use gz compressed image files when registering them in OpenNebula.


Susntone will allow you to upload disk images from your desktop.

When you need to set a complex number of options when creating the Image, you can also pass all of them in a file. We call these files templates. This is how the template for previous example looks like:

NAME          = "Ubuntu"
PATH          = "/home/cloud/images/ubuntu-desktop/disk.0.qcow2"
DESCRIPTION   = "Ubuntu desktop for developers."

Then simply pass the template file to the oneimage create command:

oneimage create --datastore default
ID: 0

The complete reference of attributes for the Image template is here.

Formatted data volumes

You can also create plain data disks to define user storage or scratch areas in your VMs. In this case you need to define the size and the format for the disk (either raw or qcow2). You may also instruct OpenNebula to create a file system in the Image. For example to create a 10G qcow2 disk use:

oneimage create --size 10240 --name db-disk --format qcow2 --datastore default
ID: 2

You can even create a filesystem in the new image so it is ready-to-use by the VMs:

oneimage create --size 10240 --name fs-vol --format qcow2 --fs ext4 --datastore default
ID: 3

Using Marketplaces

OpenNebula leverages the applications created by several popular marketplaces, like DockerHub or These are great places to grab a working installation of an OS/application ready to use in your Cloud. The OpenNebula project also prepares contextualized OS installations of popular distributions and applications, you can check the list in the OpenNebula Marketplace.

You can find more information on using these Marketplaces here.

Using a Dockerfile

You can create Images using your own dockerfiles. The PATH in this case has the following format:






Path in OpenNebula server where the Dockerfile is located.


Dockerfile in Base64 form. If this is specified, the path is ignored.


If it set to yes, OpenNebula context packages are added. If it is not set or set to no, they are omitted.


Filesystem type (ext4, ext3, ext2 or xfs)


Image tag name (default latest).


(Optional) base OS distribution.


Multistage Dockerfiles are not supported, only one FROM directive can be included.

To create an image using your own Dockerfile use the oneimage create command with a dockerfile:// path. For example:

$ oneimage create --name testing-df --path 'dockerfile:///tmp/my_dockerfile?size=256' --datastore 1 --prefix vd
  ID: 0
$ oneimage list
  0  oneadmin oneadmin testing-df default   256M OS    No rdy     0

There is also a dedicated oneimage dockerfile command that will open an editor so you can easily edit your Dockerfile there.

Installing the Guest OS

Finally, you can boot a VM from an ISO installation image and install the OS. Please refer to the Guest OS installation guide for more information.

LUKS encrypted Images

LUKS-encrypted Images can be used only on KVM based hypervisors. First you need to create an encrypted volume using raw format, for example:

qemu-img create --object secret,id=sec0,data=secret-passphrase -o key-secret=sec0 -f luks /tmp/luks.vol 10G

Then create the image into the OpenNebula Datastore as usual:

oneimage create --name luks-image --path /tmp/luks.vol -d default

Finally you need to define the secret in the libvirt, prepare a secret.xml file

cat secret.xml
<secret ephemeral='no' private='yes'>
      <description>luks key</description>

Then define the secret and set its value, beware it’s base64 encoded. This has to be done on every hypervisor

virsh -c qemu:///system secret-define secret.xml
virsh -c qemu:///system secret-set-value a94c5c16-d936-4346-89ad-7067517f411a "$(echo secret-passphrase | base64)"

Managing Images

Listing Images

You can use the oneimage list command to check the available images in the Datastores.

oneimage list
   0 oneadmin   oneadmin   ttylinux-vd     default       200M OS    No used    8
   1 johndoe    users      my-ubuntu-disk- default       200M OS   Yes used    1
   2 alice      testgroup  customized-ubun default       200M OS   Yes used    1

To get complete information about an Image, use oneimage show, or list Images continuously with oneimage top.


Orphan images (i.e images not referenced by any VM template) can be shown with oneimage orphans command.

Cloning Images

Existing Images can be cloned to a new one. This is useful to make a backup of an Image before you modify it, or to get a private persistent copy of an Image shared by other user. To clone an Image, execute

oneimage clone Ubuntu new_image

You can optionally clone the Image to a different Datastore. The new Datastore must use the same DS_MAD driver.

oneimage clone Ubuntu new_image --datastore new_img_ds

Sharing Images with other Users

Users can share their Images with other users in their group, or with all the users in OpenNebula. Full details are described in the Managing Permissions guide. Following you can see a quick example: to share the Image 0 with users in your group grant the USE right bit for GROUP:

oneimage show 0
OWNER          : um-
GROUP          : ---
OTHER          : ---
oneimage chmod 0 640
oneimage show 0
OWNER          : um-
GROUP          : u--
OTHER          : ---

Changing the Persistent Mode

Use the oneimage persistent and oneimage nonpersistent commands to make your Images persistent or not. For example:

oneimage persistent Ubuntu
oneimage list
   0 oneadmin oneadmin Ubuntu       default        10G   OS Yes  rdy     0
oneimage nonpersistent 0
oneimage list
   0 oneadmin oneadmin Ubuntu       default        10G   OS  No  rdy     0

Managing Image Snapshots

Persistent Images can have snapshots if they are created during the life-cycle of the VM that uses them. The following operations allow the user to manage these snapshots directly:

  • oneimage snapshot-revert <image_id> <snapshot_id>: The active state of the Image is overwritten by the specified snapshot. Note that this operation discards any unsaved data of the disk state.

  • oneimage snapshot-delete <image_id> <snapshot_id>: Deletes a snapshot. This operation is only allowed if the snapshot is not the active snapshot and if it has no children.

  • oneimage snapshot-flatten <image_id> <snapshot_id>: This operation effectively converts the Image to an Image without snapshots. The saved disk state of the Image is the state of the specified snapshot. It’s an operation similar to running snapshot-revert and then deleting all the snapshots.


Images with snapshots cannot be cloned or made non-persistent. To run either of these operations the user would need to flatten the Image first.

How to Use Images in Virtual Machines

A VM uses an Image including it in its template as a DISK. A Disk can refer Images either by name (IMAGE) or ID (IMAGE_ID). If you are using Image names it is a good idea to scope the name to its owner (IMAGE_UNAME or IMAGE_UID) to prevent collisions.

For example the following template define a VM with two disks, the first one is based on Image with ID 7, the second will use the Image Ubuntu from oneadmin user.

CPU    = 1
MEMORY = 1024

DISK = [ IMAGE_ID   = 7 ]

DISK = [ IMAGE       = "Ubuntu",
         IMAGE_UNAME = "oneadmin" ]

NIC    = [ NETWORK_ID = 1 ]

Check the virtual machine user guide and the virtual machine template documentation for a more complete explanation.

Save Disk Changes to an Image

Once the VM is deployed and changes are made to its disks, you can save those changes in two different ways:

  • Disk snapshots, a snapshot of the disk state is saved, you can later revert to this saved state.

  • Disk save as, the disk is copied to a new Image in the datastore. The disk must be in a consistent state during the save_as operation (e.g. by unmounting the disk from the VM).

A detailed description of this process is described in section Virtual Machine Instances

How to Use File Images in Virtual Machines

Kernels and RAM disks

KERNEL and RAMDISK type Images can be used in the KERNEL_DS and INITRD_DS attributes of OS definition in the VM template. Example of a VM section that uses the Image with name kernel5.10 as kernel and Image ID 23 as RAM disk:

OS = [ KERNEL_DS  = "$FILE[IMAGE=kernel5.10]",
       INITRD_DS  = "$FILE[IMAGE_ID=23]",
       ROOT       = "sda1",
       KERNEL_CMD = "ro console=tty1" ]

For a complete description check the VM Template reference guide.

Generic files

The contextualization cdrom can include CONTEXT type Images, so the VM can access them at boot time. For Example, a VM section that includes the Image (file) with name webpageDB and Image ID 34 would be:

  FILES_DS   = "$FILE[IMAGE_ID=34] $FILE[IMAGE=webpageDB]",

Using Sunstone to Manage Images

You can also manage your Images using Sunstone. Select the Images tab, and there, you will be able to manage and check the information about your images in a user friendly way. By default this tab is available in the admin view, but not in the cloud or groupadmin views.


Uploading Images from Sunstone

When creating Images you can upload them to the Datastore via the client browser. The process copies the image from the client desktop to a temporal location and creates the Image from it (as described above).

Note that when file sizes become big (normally over 1GB), and depending on your hardware, it may take long to complete the copying. Since the upload request needs to stay pending until copying is successful (so it can delete the temp file safely), there might be Ajax timeouts and/or lack of response from the server. This may cause errors, or trigger re-uploads (which re-initiate the loading progress bar).