diff options
Diffstat (limited to 'src/utils/sys-utils/xlosetup.8')
| -rw-r--r-- | src/utils/sys-utils/xlosetup.8 | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/src/utils/sys-utils/xlosetup.8 b/src/utils/sys-utils/xlosetup.8 new file mode 100644 index 0000000..4e063e6 --- /dev/null +++ b/src/utils/sys-utils/xlosetup.8 @@ -0,0 +1,215 @@ +.TH XLOSETUP 8 "September 2020" "util-linux" "System Administration" +.SH NAME +xlosetup \- set up and control xloop devices +.SH SYNOPSIS +.ad l +Get info: +.sp +.in +5 +.B xlosetup +[\fIxloopdev\fP] +.sp +.B xlosetup \-l +.RB [ \-a ] +.sp +.B xlosetup \-j +.I file +.RB [ \-o +.IR offset ] +.sp +.in -5 +Detach a xloop device: +.sp +.in +5 +.B "xlosetup \-d" +.IR xloopdev ... +.sp +.in -5 +Detach all associated xloop devices: +.sp +.in +5 +.B "xlosetup \-D" +.sp +.in -5 +Set up a xloop device: +.sp +.in +5 +.B xlosetup +.RB [ \-o +.IR offset ] +.RB [ \-\-sizelimit +.IR size ] +.RB [ \-\-sector\-size +.IR size ] +.in +8 +.RB [ \-Pr ] +.RB [ \-\-show ] " \-f" | \fIxloopdev\fP +.I file +.sp +.in -13 +Resize a xloop device: +.sp +.in +5 +.B "xlosetup \-c" +.I xloopdev +.in -5 +.ad b +.SH DESCRIPTION +.B xlosetup +is used to associate xloop devices with regular files or block devices, +to detach xloop devices, and to query the status of a xloop device. If only the +\fIxloopdev\fP argument is given, the status of the corresponding xloop +device is shown. If no option is given, all xloop devices are shown. +.sp +Note that the old output format (i.e., \fBxlosetup \-a\fR) with comma-delimited +strings is deprecated in favour of the \fB\-\-list\fR output format. +.sp +It's possible to create more independent xloop devices for the same backing +file. +.B This setup may be dangerous, can cause data loss, corruption and overwrites. +Use \fB\-\-nooverlap\fR with \fB\-\-find\fR during setup to avoid this problem. + +.SH OPTIONS +The \fIsize\fR and \fIoffset\fR +arguments may be followed by the multiplicative suffixes KiB (=1024), +MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is +optional, e.g., "K" has the same meaning as "KiB") or the suffixes +KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. + +.TP +.BR \-a , " \-\-all" +Show the status of all xloop devices. Note that not all information is accessible +for non-root users. See also \fB\-\-list\fR. The old output format (as printed +without \fB\-\-list)\fR is deprecated. +.TP +.BR \-d , " \-\-detach " \fIxloopdev\fR... +Detach the file or device associated with the specified xloop device(s). Note +that since Linux v3.7 kernel uses "lazy device destruction". The detach +operation does not return EBUSY error anymore if device is actively used by +system, but it is marked by autoclear flag and destroyed later. +.TP +.BR \-D , " \-\-detach\-all" +Detach all associated xloop devices. +.TP +.BR \-f , " \-\-find " "\fR[\fIfile\fR]" +Find the first unused xloop device. If a \fIfile\fR argument is present, use +the found device as xloop device. Otherwise, just print its name. +.IP "\fB\-\-show\fP" +Display the name of the assigned xloop device if the \fB\-f\fP option and a +\fIfile\fP argument are present. +.TP +.BR \-L , " \-\-nooverlap" +Check for conflicts between xloop devices to avoid situation when the same +backing file is shared between more xloop devices. If the file is already used +by another device then re-use the device rather than a new one. The option +makes sense only with \fB\-\-find\fP. +.TP +.BR \-j , " \-\-associated " \fIfile\fR " \fR[\fB\-o \fIoffset\fR]" +Show the status of all xloop devices associated with the given \fIfile\fR. +.TP +.BR \-o , " \-\-offset " \fIoffset +The data start is moved \fIoffset\fP bytes into the specified file or device. The \fIoffset\fP +may be followed by the multiplicative suffixes; see above. +.IP "\fB\-\-sizelimit \fIsize\fP" +The data end is set to no more than \fIsize\fP bytes after the data start. The \fIsize\fP +may be followed by the multiplicative suffixes; see above. +.TP +.BR \-b , " \-\-sector-size " \fIsize +Set the logical sector size of the xloop device in bytes (since Linux 4.14). The +option may be used when create a new xloop device as well as stand-alone command +to modify sector size of the already existing xloop device. +.TP +.BR \-c , " \-\-set\-capacity " \fIxloopdev +Force the xloop driver to reread the size of the file associated with the +specified xloop device. +.TP +.BR \-P , " \-\-partscan" +Force the kernel to scan the partition table on a newly created xloop device. Note that the +partition table parsing depends on sector sizes. The default is sector size is 512 bytes, +otherwise you need to use the option \fB\-\-sector\-size\fR together with \fB\-\-partscan\fR. +.TP +.BR \-r , " \-\-read\-only" +Set up a read-only xloop device. +.TP +.BR \-\-direct\-io [ =on | off ] +Enable or disable direct I/O for the backing file. The optional argument +can be either \fBon\fR or \fBoff\fR. If the argument is omitted, it defaults +to \fBoff\fR. +.TP +.BR \-t , " \-\-type \fIformat\fR" +Set the file format type of the xloop device. If no file format type is specified, +the RAW file format is used by default. Valid file formats are: \fBRAW\fR, +\fBQCOW\fR, \fBVDI\fR, \fBVMDK\fR. +.TP +.BR \-v , " \-\-verbose" +Verbose mode. +.TP +.BR \-l , " \-\-list" +If a xloop device or the \fB\-a\fR option is specified, print the default columns +for either the specified xloop device or all xloop devices; the default is to +print info about all devices. See also \fB\-\-output\fP, \fB\-\-noheadings\fP, +\fB\-\-raw\fP, and \fB\-\-json\fP. +.TP +.BR \-O , " \-\-output " \fIcolumn\fR[,\fIcolumn\fR]... +Specify the columns that are to be printed for the \fB\-\-list\fP output. +Use \fB\-\-help\fR to get a list of all supported columns. +.TP +.B \-\-output\-all +Output all available columns. +.TP +.BR \-n , " \-\-noheadings" +Don't print headings for \fB\-\-list\fP output format. +.IP "\fB\-\-raw\fP" +Use the raw \fB\-\-list\fP output format. +.TP +.BR \-J , " \-\-json" +Use JSON format for \fB\-\-list\fP output. +.TP +.BR \-V , " \-\-version" +Display version information and exit. +.TP +.BR \-h , " \-\-help" +Display help text and exit. + +.SH ENCRYPTION +.B Cryptoloop is no longer supported in favor of dm-crypt. +.B For more details see cryptsetup(8). + +.SH EXIT STATUS +.B xlosetup +returns 0 on success, nonzero on failure. When +.B xlosetup +displays the status of a xloop device, it returns 1 if the device +is not configured and 2 if an error occurred which prevented +determining the status of the device. + +.SH ENVIRONMENT +.IP XLOOPDEV_DEBUG=all +enables debug output. + +.SH FILES +.TP +.I /dev/xloop[0..N] +xloop block devices +.TP +.I /dev/xloop-control +xloop control device +.SH EXAMPLE +The following commands can be used as an example of using the xloop device. +.nf +.IP +# dd if=/dev/zero of=~/file.img bs=1024k count=10 +# xlosetup \-\-find \-\-show ~/file.img +/dev/xloop0 +# mkfs \-t ext2 /dev/xloop0 +# mount /dev/xloop0 /mnt + ... +# umount /dev/xloop0 +# xlosetup \-\-detach /dev/xloop0 +.fi +.SH AUTHORS +Karel Zak <kzak@redhat.com>, based on the original version from +Theodore Ts'o <tytso@athena.mit.edu> +.SH AVAILABILITY +The xlosetup command is part of the util-linux package and is available from +https://www.kernel.org/pub/linux/utils/util-linux/. |