VMKFSTOOLS

Section: Misc. Reference Manual Pages ()
Updated: VMware ESX Manual
Index Return to Main Contents

BSD mandoc
VMnix

NAME

vmkfstools - VMware ESX file system management tool

SYNOPSIS

vmkfstools OPTIONS
vmkfstools OPTIONS PARTITION
vmkfstools OPTIONS DEVICE
vmkfstools OPTIONS PATH

COPYRIGHT

DESCRIPTION

vmkfstools is a program for creating and manipulating virtual disks, file systems, logical volumes and physical storage devices on the VMware ESX. It supports the creation of VMware ESX File System (VMFS) on a partition of a disk, and the management of files (such as virtual disks) stored on VMFS.
OPTIONS is one or more command-line options that specify the operation. The file or VMFS file system being manipulated may be specified after the options by a relative or absolute file path name in the /vmfs hierarchy.
The disk partition target is specified using a vml.<vml_ID>:P where <vml_ID> is the device ID returned by the storage array and P is an integer that represents the partition number. The partition digit must be greater than zero and should correspond to a valid VMFS
The DEVICE argument is used for specifying devices, and should be a path name beginning with /vmfs/devices , which is the mount point of the device file system. There are sub-mounts for each device class. For example, /vmfs/devices/disks for local or SAN-based disks, /vmfs/devices/lvm for VMKernel logical volumes, /vmfs/devices/generic for generic SCSI devices like tape drives, etc.

The PATH argument is used for specifying a VMFS file system or file, and should be an absolute or relative path that names a directory or a file under /vmfs For example, a VMFS file system could be specified via a path such as:
/vmfs/volumes/<file_system_UUID> or /vmfs/volumes/<file_system_label>
A VMFS file would be specified via a path such as:
/vmfs/volumes/<file_system_label|file_system_UUID>/[dir]/myDisk.vmdk or myDisk.vmdk
if the current working directory is the parent directory of myDisk.vmdk.

FILE SYSTEM OPTIONS

The long and short forms of options, shown here listed together, are equivalent.
-C , -createfs vmfs3
-b , -blocksize #[mMkK]
-S , -setfsname fsName
    Create a VMFS file system on the specified partition,
    e.g. vml.<vml_ID>:1. The partition becomes the file system`s head
    partition. The file block size can be specified via the `-b`
    option. The default file block size is 1MB. The file block size
    must be either 1MB, 2MB, 4MB or 8MB. In ESX 3, VMFS-2 file
    systems are read-only in that users will not be allowed to create
    or modify them. VMFS-3 file systems will not be accessible from
    ESX 2.x hosts.

    The -S option sets the label of the VMFS file system, and can only
    be used in conjunction with the `-C` option. This label can then
    be used to specify a VMFS file system in subsequent vmkfstools
    commands or in a virtual machine configuration file. The label
    will also appear in a listing produced by `ls -l /vmfs/volumes`
    as a symbolic link to the VMFS file system. VMFS labels can be up
    to 128 characters long. They cannot contain leading or trailing
    spaces. After creating the file system, the label can be changed
    using the command `ln -sf /vmfs/volumes/<FS UUID>
    /vmfs/volumes/<New label>`.
-Z , -spanfs span-partition
    Extend the VMFS-3 file system with the specified head
    partition by spanning it across the partition designated by
    `span-partition`. The operation erases existing data on the
    spanned partition. A VMFS-3 file system can have at most 32
    partitions. This option will not work on VMFS-2 file systems as
    they are read-only in ESX 3. The `--extendfs` long option
    is deprecated.
-G , -growfs grow-partition
    Extend the VMFS-3 file system with the specified `grow-partition`.
    Prior to growing the file system, users must use a tool such as
    `fdisk` or `parted` to create the partition first.  Once the
    partition size `grow-partition` is available, file system can be grown by
    designating the `grow-partition` using the option `-G`.
    Existing data on the grow partition is preserved. This option will
    not work on VMFS-2 file systems as they are read-only in ESX 3.
-P , -queryfs
-h , -human-readable
    List the attributes of a VMFS file system when used on any file or
    directory of a VMFS file system. It lists the VMFS version number,
    the number of partitions constituting the specified VMFS file
    system, the file system label (if any), file system UUID,
    available space, and a listing of the device names of all the
    partitions constituting the file system. If partitions backing
    VMFS file system go offline then the number of partitions and
    available space reported change accordingly. The `h` option
    causes sizes to be printed in human-readable format (such as 5k,
    12.1M, or 2.1G).

FILE SYSTEM UPGRADE OPTIONS

VMFS-2 to VMFS-3 file system upgrade is a two step process. Before file system upgrade can begin the `vmfs2` and `vmfs3` drivers must be unloaded and the auxiliary file system driver, `fsaux`, should be loaded. The first step of upgrade uses the `-T` option. Once the first step completes, the auxiliary file system driver, `fsaux`, must be unloaded and the `vmfs2` and `vmfs3` drivers reloaded. The second step of file system upgrade makes use of the `-u` option.
-T , -tovmfs3
-x , -upgradetype [zeroedthick|eagerzeroedthick|thin]
    Converts a VMFS-2 file system to VMFS-3 format, preserving all files
    on the file system. Only file systems with block size 8MB or less
    can be converted. The conversion is in-place and the auxiliary file
    system driver (`fsaux`) module must be loaded. ESX will
    try to ensure that no local process or remote ESX is currently
    accessing the VMFS file system to be converted. The conversion is a
    one-way operation and once the VMFS-2 file system is converted to
    VMFS-3 file system, it cannot be rolled back to VMFS-2. The `-x
    thin` option results in the conversion of VMFS-2 files into
    thin-provisioned VMFS-3 files (as opposed to zeroedthick-provisioned
    files). File blocks that are part of a `zeroedthick` file, but were
    never written to, are discarded from the file to enable storage
    overcommitment.  The properties of the `zeroedthick` file is
    retained for the default upgrade option, `-x zeroedthick`.
    The `-x eagerzeroedthick` option eagerly zeroes out previously
    unwritten blocks. Note that the upgrade process may run much longer
    when invoked with the `-x eagerzeroedthick` option, as opposed
    to the other two options.
-u , -upgradefinish /vmfs/volumes/<file system label|file system UUID>
    Once the first step of file system upgrade has completed (using
    `-T`), the `vmfs2` and `vmfs3` modules must be reloaded and
    the `-u` option used to complete the upgrade.

VIRTUAL DISK OPTIONS

-c , -createvirtualdisk #[gGmMkK]
-a , -adaptertype [buslogic|lsilogic|ide] srcFile
-d , -diskformat [thin|zeroedthick|eagerzeroedthick]
    Create a virtual disk with the specified size on the VMFS file
    system. The size is specified in bytes by default, but can be
    specified in kilobytes, megabytes or gigabytes by adding a suffix
    of `k`, `m`, or `g` respectively. The `adaptertype` option
    allows users to indicate which device driver should be used to
    communicate with the virtual disk. See the `SUPPORTED DISK
    FORMATS` section for details on the disk formats supported by
    the `-d` option. The default disk format is `zeroedthick`. The
    `-d eagerzeroedthick` option is used to create a virtual disk
    which are allocated with the contents zeroed out at creation time.
-U , -deletevirtualdisk
    Delete files associated with the specified virtual disk.
-E , -renamevirtualdisk srcDisk
    Rename files associated with a specified virtual disk to the
    specified name.
-i , -clonevirtualdisk srcDisk
-d , -diskformat [rdm:<device>|rdmp:<device>|zeroedthick|thin|eagerzeroedthick|2gbsparse
    Create a copy of a virtual disk or raw disk. The copy will be in
    the specified disk format. See the `SUPPORTED DISK FORMATS`
    section for details on the disk formats supported by the `-d`
    option. The default disk format is pre-allocated. On ESX, to clone ESX
    REDO logs while preserving their hierarchy, use the Service
    Console command `cp(1)`.
-e , -exportvirtualdisk dstDisk
    This operation is deprecated. Use `-i srcDisk -d 2gbsparse` to
    achieve what it used to.
-X , -extendvirtualdisk #[gGmMkK]
    Extend the specified VMFS virtual disk to the specified length.
    You can extend the virtual disk to a `eagerzeroedthick` format,
    if specified with the `-d eagerzeroedthick` option.
    Extending a virtual disk will break any currently existing snapshots. This
    command is useful for extending the size of a virtual disk allocated to a
    virtual machine after the virtual machine has been created.  However, this
    command requires that the guest operating system has some capability for
    recognizing the new size of the virtual disk and taking advantage of this
    new size (e.g.  by updating the file system on the virtual disk to take
    advantage of the extra space).
-M , -migratevirtualdisk
    Migrate an ESX 2 virtual disk to an ESX 3 virtual disk.
-r , -createrdm /vmfs/devices/disks/...
    Map a raw disk to a file on a VMFS file system. Once the mapping
    is established, it can be used to access the raw disk like a
    normal VMFS virtual disk. The `file length` of the mapping is
    the same as the size of the raw disk that it points to.
-q , -queryrdm
    List the attributes of a raw disk mapping. When used with a
    `rdm:<device>` specification, it prints out the
    vml of the raw disk corresponding to the mapping
    referenced by the <device>. It also prints out identification
    information for the raw disk (if any).
-z , -createrdmpassthru /vmfs/devices/disks/...
    Map a passthrough raw disk to a file on a VMFS file system. This
    allows a virtual machine to bypass the VMKernel SCSI command
    filtering layer done for VMFS virtual disks. Once the mapping is
    established, it can be used to access the passthrough raw disk
    like a normal VMFS virtual disk.
-v , -verbose #
    This option is ignored for the queryrdm option. Setting the
    verbosity level will list additional information for the virtual disk
    configuration.
-g , -geometry
    Get the geometry information (cylinders, heads, sectors) of a
    virtual disk.
-w , -writezeros
    Initialize the virtual disk with zeros. Any existing data on virtual
    disk is lost.
-j , -inflatedisk
    Convert a thin virtual disk to preallocated with the additional
    guarantee that any data on thin disk is preserved and any blocks
    that were not allocated get allocated and zeroed out.
-k , -eagerzero
    Convert a preallocated virtual disk to eagerzeroedthick
    and maintains any existing data.

SUPPORTED DISK FORMATS

These are the arguments that can be passed to the `-d` option for the `-c` (create virtual disk) and `-i` (clone virtual disk) operations.
`zeroedthick`
    Space required for the virtual disk is allocated at creation time.
    Any data remaining on the physical device is not erased during
    creation, but will be zeroed out on demand at a later time on
    first write from the virtual machine. The virtual machine does not
    read stale data from disk.
`eagerzeroedthick`
    Space required for the virtual disk is allocated at creation
    time. In contrast to zeroedthick format, the data remaining on
    the physical device is zeroed out during creation. It might take
    much longer to create disks in this format than to create other
    types of disks.
`thin`
    Thin-provisioned virtual disk. Unlike the `zeroedthick` or
    `eagerzeroedthick` format, space required for the virtual disk is
    not allocated during creation, but, it is allocated on demand during
    first write issued to the block. Virtual disk size is zero at creation
    time.  This format provides more efficient user of storage space and
    enables thin provisioning of virtual disks. This format is recommended
    when space utilization is the main concern, and for all types of
    applications except clustering.

`rdm`
    Virtual compatibility mode raw disk mapping.
`rdmp`
    Physical compatibility mode (pass-through) raw disk mapping.
`2gbsparse`
    A sparse disk with 2GB maximum extent size.  You can use disks in
    this format with other VMware products. However, you cannot power
    on a sparse disk on an ESX/ESXi host unless you first re-import the
    disk in a compatible format, such as zeroedthick or eagerzeroedthick
    or thin, with vmkfstools.

DEVICE OPTIONS


-L , -lock  [reserve|release|lunreset|targetreset|busreset] /vmfs/devices/disks/<vml-ID>

    Manage SCSI reservations on physical targets or LUNs. These
    commands can interrupt the operations of other servers on a storage
    area network (SAN), so they should be used with great caution. The
    `reserve` command will reserve the specified raw disk.
    After the reservation, other servers will get a SCSI reservation
    conflict if they attempt to access that disk, but the server that did
    the reservation will be able to access the disk normally. The
    `release` command will release the reservation on the specified
    disk. Other servers will be able to access the disk again. The
    `lunreset` command resets a single LUN only instead of all
    the LUNs attached to a target. The `targetreset`  and `busreset`
    command will reset target and bus respectively causing SCSI
    reservations to be dropped. This option is potentially disruptive to
    all servers sharing the storage and is only meant to be used
    in the context of Clustering.
-B , -breaklock /vmfs/devices/disks/vml.<vml-ID>:partition
    This command is used to forcibly break the LVM device lock on a
    particular partition, in the event that a host crashed in the middle
    of a volume operation. When this command is issued, user must
    ensure that no other host is holding the lock.

    If it becomes necessary to forcibly break the LVM device lock due
    to a host crash in the middle of a volume operation like grow extent,
    add extent or resignature, after breaking the lock, data should be
    migrated off the volume and the volume reformatted.

EXAMPLES

vmkfstools -C vmfs3 -b 1m -S myVMFS vml.<vml_ID>:1
Creates a new VMFS-3 file system with label `myVMFS` on the 1st partition of the vml.<vml_ID> device. The file block size is 1MB.

vmkfstools -Z vml.<vml_ID>:4 vml.<vml_ID>:1
Extends the newly created file system by adding the 4th partition of the vml device. As a result, the file system will span two partitions. vml.<vml_ID>:1 and vml.<vml_ID>:4. Here, vml<vml_ID>:1 is the name of the head partition of the file system that is to be extended.
vmkfstools -c 2048m /vmfs/volumes/myVMFS/myOS.vmdk
Creates a 2GB VMFS virtual disk with the name `myOS.vmdk` on the VMFS file system named `myVMFS`. This virtual disk may then be accessed by a virtual machine.

vmkfstools -i /vmfs/volumes/templates/gold-master.vmdk
/vmfs/volumes/myVMFS/myOS.vmdk
Clones the contents of a gold master virtual disk image from a template repository to a virtual disk named `myOS.vmdk` on the VMFS file system called myVMFS. A virtual machine can be configured to use this virtual disk by adding the following lines to its configuration file:

scsi0:0.present = TRUE
scsi0:0.fileName = /vmfs/volumes/myVMFS/myOS.vmdk
vmkfstools -r /vmfs/devices/disks/vml.<vml_ID>:0 foo-rdm.vmdk
Creates a mapping file, `foo-rdm.vmdk`, to the raw disk `vml.<vml_ID>:0`. The mapping file `foo-rdm.vmdk` is created in the current VMFS working directory, and can be used in a virtual machine in the same manner as in the previous example.
vmkfstools -s vml.<vml_ID>
Scan adapter vml.<vml_ID> for any new targets or LUNs and for any removed targets or LUNs.
vmkfstools -B /vmfs/devices/disks/vml.<vml-ID>:partition
Break a LVM device lock on /vmfs/devices/disks/vml.<vml-ID>:partition

This document was created by man2html, using the manual pages. Brought to you by Bouke Groenescheij, www.jume.nl
Time: 15:25:41 GMT, May 26, 2009