322 lines
8.4 KiB
HTML
322 lines
8.4 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LOSETUP</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LOSETUP</H1>
|
|
Section: System Administration (8)<BR>Updated: November 2015<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
losetup - set up and control loop devices
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
Get info:
|
|
<P>
|
|
|
|
<B>losetup</B>
|
|
|
|
[<I>loopdev</I>]
|
|
<P>
|
|
<B>losetup -l</B>
|
|
|
|
[<B>-a</B>]
|
|
|
|
<P>
|
|
<B>losetup -j</B>
|
|
|
|
<I>file</I>
|
|
|
|
[<B>-o</B>
|
|
|
|
<I>offset</I>]
|
|
|
|
<P>
|
|
|
|
Detach a loop device:
|
|
<P>
|
|
|
|
<B>losetup -d</B>
|
|
|
|
<I>loopdev</I>...
|
|
|
|
<P>
|
|
|
|
Detach all associated loop devices:
|
|
<P>
|
|
|
|
<B>losetup -D</B>
|
|
|
|
<P>
|
|
|
|
Set up a loop device:
|
|
<P>
|
|
|
|
<B>losetup</B>
|
|
|
|
[<B>-o</B>
|
|
|
|
<I>offset</I>]
|
|
|
|
[<B>--sizelimit</B>
|
|
|
|
<I>size</I>]
|
|
|
|
[<B>--sector-size</B>
|
|
|
|
<I>size</I>]
|
|
|
|
|
|
[<B>-Pr</B>]
|
|
|
|
[<B>--show</B>]<B> -f</B>|<B></B><I>loopdev</I>
|
|
|
|
<I>file</I>
|
|
|
|
<P>
|
|
|
|
Resize a loop device:
|
|
<P>
|
|
|
|
<B>losetup -c</B>
|
|
|
|
<I>loopdev</I>
|
|
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>losetup</B>
|
|
|
|
is used to associate loop devices with regular files or block devices,
|
|
to detach loop devices, and to query the status of a loop device. If only the
|
|
<I>loopdev</I> argument is given, the status of the corresponding loop
|
|
device is shown. If no option is given, all loop devices are shown.
|
|
<P>
|
|
Note that the old output format (i.e., <B>losetup -a</B>) with comma-delimited
|
|
strings is deprecated in favour of the <B>--list</B> output format.
|
|
<P>
|
|
It's possible to create more independent loop devices for the same backing
|
|
file.
|
|
<B>This setup may be dangerous, can cause data loss, corruption and overwrites.</B>
|
|
|
|
Use <B>--nooverlap</B> with <B>--find</B> during setup to avoid this problem.
|
|
<P>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
The <I>size</I> and <I>offset</I>
|
|
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.
|
|
<P>
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-a</B>,<B> --all</B>
|
|
|
|
<DD>
|
|
Show the status of all loop devices. Note that not all information is accessible
|
|
for non-root users. See also <B>--list</B>. The old output format (as printed
|
|
without <B>--list)</B> is deprecated.
|
|
<DT id="2"><B>-d</B>,<B> --detach </B><I>loopdev</I>...
|
|
|
|
<DD>
|
|
Detach the file or device associated with the specified loop 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.
|
|
<DT id="3"><B>-D</B>,<B> --detach-all</B>
|
|
|
|
<DD>
|
|
Detach all associated loop devices.
|
|
<DT id="4"><B>-f</B>,<B> --find </B>[<I>file</I>]
|
|
|
|
<DD>
|
|
Find the first unused loop device. If a <I>file</I> argument is present, use
|
|
the found device as loop device. Otherwise, just print its name.
|
|
<DT id="5"><B>--show</B><DD>
|
|
Display the name of the assigned loop device if the <B>-f</B> option and a
|
|
<I>file</I> argument are present.
|
|
<DT id="6"><B>-L</B>,<B> --nooverlap</B>
|
|
|
|
<DD>
|
|
Check for conflicts between loop devices to avoid situation when the same
|
|
backing file is shared between more loop 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 <B>--find</B>.
|
|
<DT id="7"><B>-j</B>,<B> --associated </B><I>file</I><B> </B>[<B>-o </B><I>offset</I>]
|
|
|
|
<DD>
|
|
Show the status of all loop devices associated with the given <I>file</I>.
|
|
<DT id="8"><B>-o</B>,<B> --offset </B><I>offset</I>
|
|
|
|
<DD>
|
|
The data start is moved <I>offset</I> bytes into the specified file or device. The <I>offset</I>
|
|
may be followed by the multiplicative suffixes; see above.
|
|
<DT id="9"><B>--sizelimit </B><I>size</I><DD>
|
|
The data end is set to no more than <I>size</I> bytes after the data start. The <I>size</I>
|
|
may be followed by the multiplicative suffixes; see above.
|
|
<DT id="10"><B>-b</B>,<B> --sector-size </B><I>size</I>
|
|
|
|
<DD>
|
|
Set the logical sector size of the loop device in bytes (since Linux 4.14). The
|
|
option may be used when create a new loop device as well as stand-alone command
|
|
to modify sector size of the already existing loop device.
|
|
<DT id="11"><B>-c</B>,<B> --set-capacity </B><I>loopdev</I>
|
|
|
|
<DD>
|
|
Force the loop driver to reread the size of the file associated with the
|
|
specified loop device.
|
|
<DT id="12"><B>-P</B>,<B> --partscan</B>
|
|
|
|
<DD>
|
|
Force the kernel to scan the partition table on a newly created loop 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 <B>--sector-size</B> together with <B>--partscan</B>.
|
|
<DT id="13"><B>-r</B>,<B> --read-only</B>
|
|
|
|
<DD>
|
|
Set up a read-only loop device.
|
|
<DT id="14"><B>--direct-io</B>[<B>=on</B>|<B>off</B>]
|
|
|
|
<DD>
|
|
Enable or disable direct I/O for the backing file. The optional argument
|
|
can be either <B>on</B> or <B>off</B>. If the argument is omitted, it defaults
|
|
to <B>on</B>.
|
|
<DT id="15"><B>-v</B>,<B> --verbose</B>
|
|
|
|
<DD>
|
|
Verbose mode.
|
|
<DT id="16"><B>-l</B>,<B> --list</B>
|
|
|
|
<DD>
|
|
If a loop device or the <B>-a</B> option is specified, print the default columns
|
|
for either the specified loop device or all loop devices; the default is to
|
|
print info about all devices. See also <B>--output</B>, <B>--noheadings</B>,
|
|
<B>--raw</B>, and <B>--json</B>.
|
|
<DT id="17"><B>-O</B>,<B> --output </B><I>column</I>[,<I>column</I>]...
|
|
|
|
<DD>
|
|
Specify the columns that are to be printed for the <B>--list</B> output.
|
|
Use <B>--help</B> to get a list of all supported columns.
|
|
<DT id="18"><B>--output-all</B>
|
|
|
|
<DD>
|
|
Output all available columns.
|
|
<DT id="19"><B>-n</B>,<B> --noheadings</B>
|
|
|
|
<DD>
|
|
Don't print headings for <B>--list</B> output format.
|
|
<DT id="20"><B>--raw</B><DD>
|
|
Use the raw <B>--list</B> output format.
|
|
<DT id="21"><B>-J</B>,<B> --json</B>
|
|
|
|
<DD>
|
|
Use JSON format for <B>--list</B> output.
|
|
<DT id="22"><B>-V</B>,<B> --version</B>
|
|
|
|
<DD>
|
|
Display version information and exit.
|
|
<DT id="23"><B>-h</B>,<B> --help</B>
|
|
|
|
<DD>
|
|
Display help text and exit.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ENCRYPTION</H2>
|
|
|
|
<B>Cryptoloop is no longer supported in favor of dm-crypt.</B>
|
|
|
|
<B>For more details see <A HREF="/cgi-bin/man/man2html?8+cryptsetup">cryptsetup</A>(8).</B>
|
|
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
<B>losetup</B>
|
|
|
|
returns 0 on success, nonzero on failure. When
|
|
<B>losetup</B>
|
|
|
|
displays the status of a loop device, it returns 1 if the device
|
|
is not configured and 2 if an error occurred which prevented
|
|
determining the status of the device.
|
|
<P>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="24"><I>/dev/loop[0..N]</I>
|
|
|
|
<DD>
|
|
loop block devices
|
|
<DT id="25"><I>/dev/loop-control</I>
|
|
|
|
<DD>
|
|
loop control device
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>EXAMPLE</H2>
|
|
|
|
The following commands can be used as an example of using the loop device.
|
|
<PRE>
|
|
<DL COMPACT>
|
|
<DT id="26"><DD># dd if=/dev/zero of=~/file.img bs=1024k count=10
|
|
# losetup --find --show ~/file.img
|
|
/dev/loop0
|
|
# mkfs -t ext2 /dev/loop0
|
|
# mount /dev/loop0 /mnt
|
|
...
|
|
# umount /dev/loop0
|
|
# losetup --detach /dev/loop0
|
|
</PRE>
|
|
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="27">LOOPDEV_DEBUG=all<DD>
|
|
enables debug output.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
Karel Zak <<A HREF="mailto:kzak@redhat.com">kzak@redhat.com</A>>, based on the original version from
|
|
Theodore Ts'o <<A HREF="mailto:tytso@athena.mit.edu">tytso@athena.mit.edu</A>>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>AVAILABILITY</H2>
|
|
|
|
The losetup command is part of the util-linux package and is available from
|
|
<A HREF="https://www.kernel.org/pub/linux/utils/util-linux/.">https://www.kernel.org/pub/linux/utils/util-linux/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="28"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="29"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="30"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="31"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="32"><A HREF="#lbAF">ENCRYPTION</A><DD>
|
|
<DT id="33"><A HREF="#lbAG">RETURN VALUE</A><DD>
|
|
<DT id="34"><A HREF="#lbAH">FILES</A><DD>
|
|
<DT id="35"><A HREF="#lbAI">EXAMPLE</A><DD>
|
|
<DT id="36"><A HREF="#lbAJ">ENVIRONMENT</A><DD>
|
|
<DT id="37"><A HREF="#lbAK">AUTHORS</A><DD>
|
|
<DT id="38"><A HREF="#lbAL">AVAILABILITY</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:13 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|