Bug #2387

Incomplete, inconsistent, and inaccurate documentation of 'fstype' options for "oneimage create"

Added by Bill Cole over 7 years ago. Updated over 7 years ago.

Status:ClosedStart date:10/15/2013
Priority:NormalDue date:
Assignee:-% Done:


Target version:Release 4.4
Resolution:fixed Pull request:
Affected Versions:OpenNebula 4.2


The help blurb in Sunstone, the 'man' page for oneimage, and the usage message emitted by oneimage all document the "fstype" argument given when creating a new datablock image as:

         Type of file system to be built. This can be any
          value understood by mkfs unix command.

This obfuscates the reality of the code in /usr/lib/one/sh/scripts_common.sh which implements handling of "raw", "swap", "qcow2", and (sloppily) "vmdk_*" as possible values. The web documentation mentions "swap" and "qcow2" as possible values but not the vmdk_* options. The "Image Guide" page lists fs types that may or may not reflect those available on any particular system without any additional explanation, while the "Image Template" page explicitly states non-support for VMWare.

There's an underlying design error here that arguably should be fixed by making "fstype" strictly as the man page says (with "swap" as a possible addition) while breaking out the image formats to an independent parameter, but with the code as it is, the docs lead to confusion. The best example is qcow2: the apparent but wrong way to create an empty qcow2 image with oneimage is to use a "driver" value of "qcow2" and an arbitrary fstype, since it is a required parameter. That runs and creates an image, but it is useless: raw format, marked for use with the qcow2 transfer driver. Documenting the quirky design pending a proper fix would help users who are not ready to investigate what the code really does.


#1 Updated by Ruben S. Montero over 7 years ago

  • Category set to Documentation
  • Status changed from Pending to New
  • Target version set to Release 4.4

I agree that the documentation maybe misleading and probably spread in several guides, depending on the hypervisor.

The underlying problem is the there are two operating modes, depending on the format used for the images:
  1. Plain. When the disk image is used directly by the hypervisor we can format the image, and so it is ready to be used by the guest OS.
  2. Formatted. The disk image is stored in a hypervisor specific format VMDK or Qcow2. Then we cannot really make a filesystem on the image, just create the device and let the guest OS format the disk.

The helper function in scripts_common.sh has been designed to deal with the previous modes. I agree that a better documentation will definitely help. Probably we could split the FSTYPE in twotwo different attributes (at least at the interface level) one for the "outer" type (raw, qcow2, vmdk_*) and other for the "inner" (ext2,ext3,swap...,) Note that "inner" is only supported for raw.

#2 Updated by Daniel Molina over 7 years ago

  • Status changed from New to Closed
  • % Done changed from 0 to 100
  • Resolution set to fixed

I have updated the FSTYPE description, with the comments of this ticket

Also available in: Atom PDF