xl-disk-configuration - XL Disk Configuration Syntax



  • NAME
        xl-disk-configuration - XL Disk Configuration Syntax
    
    SYNTAX
        This document specifies the xl config file format disk configuration
        option. It has the following form:
    
           disk = [ 'DISKSPEC', 'DISKSPEC', ... ]
    
        where each "DISKSPEC" is in this form:
    
           [<key>=<value>|<flag>,]*,
             [<target>, [<format>, [<vdev>, [<access>]]]],
             [<key>=<value>|<flag>,]*
             [target=<target>]
    
        For example, these strings are equivalent:
    
            /dev/vg/guest-volume,,hda
            /dev/vg/guest-volume,raw,hda,rw
            format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
            raw:/dev/vg/guest-volume,hda,w  (deprecated, see below)
    
        As are these:
    
            /root/image.iso,,hdc,cdrom
            /root/image.iso,,hdc,,cdrom
            /root/image.iso,raw,hdc,devtype=cdrom
            format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
            raw:/root/image.iso,hdc:cdrom,ro   (deprecated, see below)
    
        These might be specified in the domain config file like this:
    
            disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
    
        More formally, the string is a series of comma-separated keyword/value
        pairs, flags and positional parameters. Parameters which are not bare
        keywords and which do not contain "=" symbols are assigned to the
        so-far-unspecified positional parameters, in the order below. The
        positional parameters may also be specified explicitly by name.
    
        Each parameter may be specified at most once, either as a positional
        parameter or a named parameter. Default values apply if the parameter is
        not specified, or if it is specified with an empty value (whether
        positionally or explicitly).
    
        Whitespace may appear before each parameter and will be ignored.
    
    Positional Parameters
        target
    
            Description
                Block device or image file path. When this is used as a path, /dev
                will be prepended if the path doesn't start with a '/'.
    
            Supported values
                N/A
    
            Deprecated values
                N/A
    
            Default value
                None. While a path is provided in most cases there is an
                exception: for a cdrom device, lack of this attribute would imply
                an empty cdrom drive.
    
            Special syntax
                When this parameter is specified by name, ie with the "target="
                syntax in the configuration file, it consumes the whole rest of
                the "DISKSPEC" including trailing whitespaces. Therefore in that
                case it must come last. This is permissible even if an empty value
                for the target was already specified as a positional parameter.
                This is the only way to specify a target string containing
                metacharacters such as commas and (in some cases) colons, which
                would otherwise be misinterpreted.
    
                Future parameter and flag names will start with an ascii letter
                and contain only ascii alphanumerics, hyphens and underscores, and
                will not be legal as vdevs. Targets which might match that syntax
                should not be specified as positional parameters.
    
        format
    
            Description
                Specifies the format of image file.
    
            Supported values
                raw, qcow, qcow2, vhd, qed
    
            Deprecated values
                None
    
            Default value
                raw
    
        vdev
    
            Description
                Virtual device as seen by the guest (also referred to as guest
                drive designation in some specifications). xen-vbd-interface(7)
    
            Supported values
                hd[x], xvd[x], sd[x] etc. Please refer to the above specification
                for further details.
    
            Deprecated values
                None
    
            Default Value
                None, this parameter is mandatory.
    
        access
    
            Description
                Specified access control information. Whether or not the block
                device is provided to the guest in read-only or read-write mode
                depends on this attribute.
    
            Supported values
                "ro", "r" (specifies read-only)
    
                "rw", "w" (specifies read/write)
    
            Deprecated values
                None
    
            Default value
                "rw" unless devtype=cdrom, in which case "r"
    
    Other Parameters And Flags
        devtype=DEVTYPE
    
            Description
                Qualifies virtual device type.
    
            Supported values
                cdrom
    
            Deprecated values
                None
    
            Mandatory
                No
    
        cdrom
            Convenience alias for "devtype=cdrom".
    
        backend=DOMAIN-NAME
    
            Description
                Designates a backend domain for the device
    
            Supported values
                Valid domain names
    
            Mandatory
                No
    
            Specifies the backend domain which this device should attach to. This
            defaults to domain 0. Specifying another domain requires setting up a
            driver domain which is outside the scope of this document.
    
        backendtype=TYPE
    
            Description
                Specifies the backend implementation to use
    
            Supported values
                phy, tap, qdisk
    
            Mandatory
                No
    
            Default value
                Automatically determine which backend to use.
    
            This does not affect the guest's view of the device. It controls which
            software implementation of the Xen backend driver is used.
    
            Not all backend drivers support all combinations of other options. For
            example, "phy" does not support formats other than "raw". Normally
            this option should not be specified, in which case libxl will
            automatically determine the most suitable backend.
    
        script=SCRIPT
            Specifies that target is not a normal host path, but rather
            information to be interpreted by the executable program SCRIPT,
            (looked for in /etc/xen/scripts, if it doesn't contain a slash).
    
            These scripts are normally called "block-SCRIPT".
    
        direct-io-safe
    
            Description
                Disables non-O_DIRECT workaround
    
            Supported values
                absent, present
    
            Mandatory
                No
    
            Default value
                absent (workaround may be enabled)
    
            There is a memory lifetime bug in some driver domain (dom0) kernels
            which can cause crashes when using O_DIRECT. The bug occurs due to a
            mismatch between the backend-visible lifetime of pages used for the
            Xen PV network protocol and that expected by the backend kernel's
            networking subsystem. This can cause crashes when using certain
            backends with certain underlying storage.
    
            See:
            <http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html>
    
            For this reason, (this version of) the Xen libxl toolstack disables
            O_DIRECT when using the qemu-based Xen PV backend ("qdisk").
    
            However, this workaround has performance and scaling implications, and
            it is only necessary if the underlying device is a network filesystem.
            If the underlying device is not, then it is good to disable it; that
            is what this option is for.
    
            This option simply requests that the workaround be disabled. (However,
            not all backends versions which use the workaround understand this
            option, so this is on a best effort basis.)
    
            It's important to note that if you are storing the VM disk on a
            network filesystem or a network block device (NFS or ISCSI) it might
            not be safe to use this option. Otherwise specifying it is safe and
            can give better performances.
    
            If in the future the bug is fixed properly this option will then be
            silently ignored.
    
        discard / no-discard
    
            Description
                Request that backend advertise discard support to frontend
    
            Supported values
                discard, no-discard
    
            Mandatory
                No
    
            Default value
                discard
    
            An advisory setting for the backend driver, specifying whether to
            advertise discard support (TRIM, UNMAP) to the frontend. The real
            benefit of this option is to be able to force it off rather than on.
            It can be used to disable "hole punching" for file based backends
            which were intentionally created non-sparse to avoid fragmentation of
            the file.
    
    COLO Parameters
        colo
            Enable COLO HA for disk. For better understanding block replication on
            QEMU, please refer to:
            <http://wiki.qemu.org/Features/BlockReplication> Note that the COLO
            configuration settings should be considered unstable. They may change
            incompatibly in future versions of Xen.
    
        colo-host
    
            Description
                Secondary host's address
    
            Mandatory
                Yes when COLO enabled
    
        colo-port
    
            Description
                Secondary port. We will run a nbd server on secondary host, and
                the nbd server will listen this port.
    
            Mandatory
                Yes when COLO enabled
    
        colo-export
    
            Description
                We will run a nbd server on secondary host, exportname is the nbd
                server's disk export name.
    
            Mandatory
                Yes when COLO enabled
    
        active-disk
    
            Description
                This is used by secondary. Secondary guest's write will be
                buffered in this disk.
    
            Mandatory
                Yes when COLO enabled
    
        hidden-disk
    
            Description
                This is used by secondary. It buffers the original content that is
                modified by the primary VM.
    
            Mandatory
                Yes when COLO enabled
    
    Deprecated Parameters, Prefixes And Syntaxes
        Deprecated forms are acceptable and are intended work compatibly with xend
        and xl from xen 4.1. In future they may print a warning. Support for
        deprecated parameters and syntaxes are likely to be dropped in future
        versions of xl.
    
        There is support for a deprecated old syntax for "DISKSPEC":
    
          [<format>:][<target>],<vdev>[:<devtype>],<access>   (deprecated)
    
        This syntax also supports deprecated prefixes, described below. These are
        found prepended to the format parameter - eg "tap:aio:qcow:".
    
        format
    
            Description
                Specifies the format (deprecated)
    
            Supported values
                raw: qcow2: vhd:
    
            In xend and old versions of libxl it was necessary to specify the
            format with a prefix. For compatibility, these three prefixes are
            recognised as specifying the corresponding format. They are equivalent
            to "format=FORMAT" or the specification of format (without a colon) as
            a positional parameter.
    
        script
    
            Description
                Specifies the script (deprecated)
    
            Supported values
                iscsi: nbd: enbd: drbd:
    
            In xend and old versions of libxl it was necessary to specify the
            "script" (see above) with a prefix. For compatibility, these four
            prefixes are recognised as specifying the corresponding script. They
            are equivalent to "script=block-SCRIPT".
    
        deprecated-prefix
    
            Description
                Deprecated prefix, ignored
    
            Supported values
                tapdisk: tap2: aio: ioemu: file: phy:
    
            Various prefixes were required by xend and older versions of libxl to
            make the block devices work. In some cases these options would
            override the backend type, but in other cases they would be ignored in
            favour of "making it work"; in yet other cases it would be necessary
            to specify several of these, for example:
    
              tap:aio:/some/path...
    
            All of these prefixes are now stripped and ignored.
    
      Missing format and empty target
        The following syntax is also supported:
    
          ,<vdev>:<devtype>,<access>   (deprecated)
    
        This is solely for compatibility with xend's syntax for empty cdroms,
        which is (for example) ",hdc:cdrom,r".

Log in to reply
 

© Lightnetics 2024