.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "xl-disk-configuration 5" .TH xl-disk-configuration 5 "2021-03-24" "4.11.4" "Xen" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" xl\-disk\-configuration \- XL Disk Configuration Syntax .SH "SYNTAX" .IX Header "SYNTAX" This document specifies the xl config file format disk configuration option. It has the following form: .PP .Vb 1 \& disk = [ \*(AqDISKSPEC\*(Aq, \*(AqDISKSPEC\*(Aq, ... ] .Ve .PP where each \f(CW\*(C`DISKSPEC\*(C'\fR is in this form: .PP .Vb 4 \& [=|,]*, \& [, [, [, []]]], \& [=|,]* \& [target=] .Ve .PP For example, these strings are equivalent: .PP .Vb 4 \& /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) .Ve .PP As are these: .PP .Vb 5 \& /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) .Ve .PP These might be specified in the domain config file like this: .PP .Vb 1 \& disk = [ \*(Aq/dev/vg/guest\-volume,,hda\*(Aq, \*(Aq/root/image.iso,,hdc,cdrom\*(Aq ] .Ve .PP 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 \*(L"=\*(R" symbols are assigned to the so-far-unspecified positional parameters, in the order below. The positional parameters may also be specified explicitly by name. .PP 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). .PP Whitespace may appear before each parameter and will be ignored. .SH "Positional Parameters" .IX Header "Positional Parameters" .IP "\fBtarget\fR" 4 .IX Item "target" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Block device or image file path. When this is used as a path, \fI/dev\fR will be prepended if the path doesn't start with a '/'. .IP "Supported values" 4 .IX Item "Supported values" N/A .IP "Deprecated values" 4 .IX Item "Deprecated values" N/A .IP "Default value" 4 .IX Item "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. .IP "Special syntax" 4 .IX Item "Special syntax" When this parameter is specified by name, ie with the \f(CW\*(C`target=\*(C'\fR syntax in the configuration file, it consumes the whole rest of the \&\f(CW\*(C`DISKSPEC\*(C'\fR 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. .Sp 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. .RE .RS 4 .RE .IP "\fBformat\fR" 4 .IX Item "format" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Specifies the format of image file. .IP "Supported values" 4 .IX Item "Supported values" raw, qcow, qcow2, vhd, qed .IP "Deprecated values" 4 .IX Item "Deprecated values" None .IP "Default value" 4 .IX Item "Default value" raw .RE .RS 4 .RE .IP "\fBvdev\fR" 4 .IX Item "vdev" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Virtual device as seen by the guest (also referred to as guest drive designation in some specifications). \fBxen\-vbd\-interface\fR\|(7) .IP "Supported values" 4 .IX Item "Supported values" hd[x], xvd[x], sd[x] etc. Please refer to the above specification for further details. .IP "Deprecated values" 4 .IX Item "Deprecated values" None .IP "Default Value" 4 .IX Item "Default Value" None, this parameter is mandatory. .RE .RS 4 .RE .IP "\fBaccess\fR" 4 .IX Item "access" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD 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. .IP "Supported values" 4 .IX Item "Supported values" \&\f(CW\*(C`ro\*(C'\fR, \f(CW\*(C`r\*(C'\fR (specifies read-only) .Sp \&\f(CW\*(C`rw\*(C'\fR, \f(CW\*(C`w\*(C'\fR (specifies read/write) .IP "Deprecated values" 4 .IX Item "Deprecated values" None .IP "Default value" 4 .IX Item "Default value" \&\f(CW\*(C`rw\*(C'\fR unless devtype=cdrom, in which case \f(CW\*(C`r\*(C'\fR .RE .RS 4 .RE .SH "Other Parameters And Flags" .IX Header "Other Parameters And Flags" .IP "\fBdevtype\fR=\fI\s-1DEVTYPE\s0\fR" 4 .IX Item "devtype=DEVTYPE" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Qualifies virtual device type. .IP "Supported values" 4 .IX Item "Supported values" cdrom .IP "Deprecated values" 4 .IX Item "Deprecated values" None .IP "Mandatory" 4 .IX Item "Mandatory" No .RE .RS 4 .RE .IP "\fBcdrom\fR" 4 .IX Item "cdrom" Convenience alias for \*(L"devtype=cdrom\*(R". .IP "\fBbackend\fR=\fIDOMAIN-NAME\fR" 4 .IX Item "backend=DOMAIN-NAME" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Designates a backend domain for the device .IP "Supported values" 4 .IX Item "Supported values" Valid domain names .IP "Mandatory" 4 .IX Item "Mandatory" No .RE .RS 4 .Sp 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. .RE .IP "\fBbackendtype\fR=\fI\s-1TYPE\s0\fR" 4 .IX Item "backendtype=TYPE" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Specifies the backend implementation to use .IP "Supported values" 4 .IX Item "Supported values" phy, tap, qdisk .IP "Mandatory" 4 .IX Item "Mandatory" No .IP "Default value" 4 .IX Item "Default value" Automatically determine which backend to use. .RE .RS 4 .Sp This does not affect the guest's view of the device. It controls which software implementation of the Xen backend driver is used. .Sp Not all backend drivers support all combinations of other options. For example, \*(L"phy\*(R" does not support formats other than \*(L"raw\*(R". Normally this option should not be specified, in which case libxl will automatically determine the most suitable backend. .RE .IP "\fBscript\fR=\fI\s-1SCRIPT\s0\fR" 4 .IX Item "script=SCRIPT" Specifies that \fBtarget\fR is not a normal host path, but rather information to be interpreted by the executable program \fI\s-1SCRIPT\s0\fR, (looked for in \fI/etc/xen/scripts\fR, if it doesn't contain a slash). .Sp These scripts are normally called "block\-\fI\s-1SCRIPT\s0\fR". .IP "\fBdirect-io-safe\fR" 4 .IX Item "direct-io-safe" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Disables non\-O_DIRECT workaround .IP "Supported values" 4 .IX Item "Supported values" absent, present .IP "Mandatory" 4 .IX Item "Mandatory" No .IP "Default value" 4 .IX Item "Default value" absent (workaround may be enabled) .RE .RS 4 .Sp 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 \s-1PV\s0 network protocol and that expected by the backend kernel's networking subsystem. This can cause crashes when using certain backends with certain underlying storage. .Sp See: .Sp For this reason, (this version of) the Xen libxl toolstack disables O_DIRECT when using the qemu-based Xen \s-1PV\s0 backend (\f(CW\*(C`qdisk\*(C'\fR). .Sp 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. .Sp 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.) .Sp It's important to note that if you are storing the \s-1VM\s0 disk on a network filesystem or a network block device (\s-1NFS\s0 or \s-1ISCSI\s0) it might not be safe to use this option. Otherwise specifying it is safe and can give better performances. .Sp If in the future the bug is fixed properly this option will then be silently ignored. .RE .IP "\fBdiscard\fR / \fBno-discard\fR" 4 .IX Item "discard / no-discard" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Request that backend advertise discard support to frontend .IP "Supported values" 4 .IX Item "Supported values" discard, no-discard .IP "Mandatory" 4 .IX Item "Mandatory" No .IP "Default value" 4 .IX Item "Default value" discard .RE .RS 4 .Sp An advisory setting for the backend driver, specifying whether to advertise discard support (\s-1TRIM, UNMAP\s0) 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 \*(L"hole punching\*(R" for file based backends which were intentionally created non-sparse to avoid fragmentation of the file. .RE .SH "COLO Parameters" .IX Header "COLO Parameters" .IP "\fBcolo\fR" 4 .IX Item "colo" Enable \s-1COLO HA\s0 for disk. For better understanding block replication on \&\s-1QEMU,\s0 please refer to: Note that the \s-1COLO\s0 configuration settings should be considered unstable. They may change incompatibly in future versions of Xen. .IP "\fBcolo-host\fR" 4 .IX Item "colo-host" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Secondary host's address .IP "Mandatory" 4 .IX Item "Mandatory" Yes when \s-1COLO\s0 enabled .RE .RS 4 .RE .IP "\fBcolo-port\fR" 4 .IX Item "colo-port" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Secondary port. We will run a nbd server on secondary host, and the nbd server will listen this port. .IP "Mandatory" 4 .IX Item "Mandatory" Yes when \s-1COLO\s0 enabled .RE .RS 4 .RE .IP "\fBcolo-export\fR" 4 .IX Item "colo-export" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD We will run a nbd server on secondary host, exportname is the nbd server's disk export name. .IP "Mandatory" 4 .IX Item "Mandatory" Yes when \s-1COLO\s0 enabled .RE .RS 4 .RE .IP "\fBactive-disk\fR" 4 .IX Item "active-disk" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD This is used by secondary. Secondary guest's write will be buffered in this disk. .IP "Mandatory" 4 .IX Item "Mandatory" Yes when \s-1COLO\s0 enabled .RE .RS 4 .RE .IP "\fBhidden-disk\fR" 4 .IX Item "hidden-disk" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD This is used by secondary. It buffers the original content that is modified by the primary \s-1VM.\s0 .IP "Mandatory" 4 .IX Item "Mandatory" Yes when \s-1COLO\s0 enabled .RE .RS 4 .RE .SH "Deprecated Parameters, Prefixes And Syntaxes" .IX Header "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. .PP There is support for a deprecated old syntax for \f(CW\*(C`DISKSPEC\*(C'\fR: .PP .Vb 1 \& [:][],[:], (deprecated) .Ve .PP This syntax also supports deprecated prefixes, described below. These are found prepended to the format parameter \- eg \f(CW\*(C`tap:aio:qcow:\*(C'\fR. .IP "\fBformat\fR" 4 .IX Item "format" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Specifies the format (deprecated) .IP "Supported values" 4 .IX Item "Supported values" raw: qcow2: vhd: .RE .RS 4 .Sp 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 \f(CW\*(C`format=FORMAT\*(C'\fR or the specification of \fBformat\fR (without a colon) as a positional parameter. .RE .IP "\fBscript\fR" 4 .IX Item "script" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Specifies the script (deprecated) .IP "Supported values" 4 .IX Item "Supported values" iscsi: nbd: enbd: drbd: .RE .RS 4 .Sp In xend and old versions of libxl it was necessary to specify the \&\*(L"script\*(R" (see above) with a prefix. For compatibility, these four prefixes are recognised as specifying the corresponding script. They are equivalent to \f(CW\*(C`script=block\-SCRIPT\*(C'\fR. .RE .IP "\fBdeprecated-prefix\fR" 4 .IX Item "deprecated-prefix" .RS 4 .PD 0 .IP "Description" 4 .IX Item "Description" .PD Deprecated prefix, ignored .IP "Supported values" 4 .IX Item "Supported values" tapdisk: tap2: aio: ioemu: file: phy: .RE .RS 4 .Sp 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 \*(L"making it work\*(R"; in yet other cases it would be necessary to specify several of these, for example: .Sp .Vb 1 \& tap:aio:/some/path... .Ve .Sp All of these prefixes are now stripped and ignored. .RE .SS "Missing format and empty target" .IX Subsection "Missing format and empty target" The following syntax is also supported: .PP .Vb 1 \& ,:, (deprecated) .Ve .PP This is solely for compatibility with xend's syntax for empty cdroms, which is (for example) \f(CW\*(C`,hdc:cdrom,r\*(C'\fR.