mount/losetup.8

   1 .TH LOSETUP 8 "2003-07-01" "Linux" "MAINTENANCE COMMANDS"
   2 .SH NAME
   3 losetup \- set up and control loop devices
   4 .SH SYNOPSIS
   5 .ad l
   6 Get info:
   7 .sp
   8 .in +5
   9 .B losetup
  10 .I loopdev
  11 .sp
  12 .B losetup -a
  13 .sp
  14 .B losetup -j
  15 .I file
  16 .RB [ \-o
  17 .IR offset ]
  18 .sp
  19 .in -5
  20 Delete loop:
  21 .sp
  22 .in +5
  23 .B "losetup \-d"
  24 .IR loopdev ...
  25 .sp
  26 .in -5
  27 Print name of first unused loop device:
  28 .sp
  29 .in +5
  30 .B "losetup \-f"
  31 .sp
  32 .in -5
  33 Setup loop device:
  34 .sp
  35 .in +5
  36 .B losetup
  37 .RB [{ \-e | \-E }
  38 .IR encryption ]
  39 .RB [ \-o
  40 .IR offset ]
  41 .RB [ \-\-sizelimit
  42 .IR limit ]
  43 .in +8
  44 .RB [ \-p
  45 .IR pfd ]
  46 .RB [ \-r ]
  47 .RB { \-f [ \-\-show ]| \fIloopdev\fP }
  48 .I file
  49 .sp
  50 .in -13
  51 Resize loop device:
  52 .sp
  53 .in +5
  54 .B "losetup \-c"
  55 .I loopdev
  56 .in -5
  57 .ad b
  58 .SH DESCRIPTION
  59 .B losetup
  60 is used to associate loop devices with regular files or block devices,
  61 to detach loop devices and to query the status of a loop device. If only the
  62 \fIloopdev\fP argument is given, the status of the corresponding loop
  63 device is shown.
  64
  65 .SS "Encryption"
  66 It is possible to specify transfer functions (for encryption/decryption
  67 or other purposes) using one of the
  68 .B \-E
  69 and
  70 .B \-e
  71 options.
  72 There are two mechanisms to specify the desired encryption: by number
  73 and by name. If an encryption is specified by number then one
  74 has to make sure that the Linux kernel knows about the encryption with that
  75 number, probably by patching the kernel. Standard numbers that are
  76 always present are 0 (no encryption) and 1 (XOR encryption).
  77 When the cryptoloop module is loaded (or compiled in), it uses number 18.
  78 This cryptoloop module will take the name of an arbitrary encryption type
  79 and find the module that knows how to perform that encryption.
  80 .SH OPTIONS
  81 .IP "\fB\-a, \-\-all\fP"
  82 show status of all loop devices
  83 .IP "\fB\-c, \-\-set-capacity\fP \fIloopdev\fP
  84 force loop driver to reread size of the file associated with the specified loop device
  85 .IP "\fB\-d, \-\-detach\fP \fIloopdev\fP..."
  86 detach the file or device associated with the specified loop device(s)
  87 .IP "\fB\-e, \-E, \-\-encryption \fIencryption_type\fP"
  88 enable data encryption with specified name or number
  89 .IP "\fB\-f, \-\-find\fP"
  90 find the first unused loop device. If a
  91 .I file
  92 argument is present, use this device. Otherwise, print its name
  93 .IP "\fB\-h, \-\-help\fP"
  94 print help
  95 .IP "\fB\-j, \-\-associated \fIfile\fP"
  96 show status of all loop devices associated with given
  97 .I file
  98 .IP "\fB\-o, \-\-offset \fIoffset\fP"
  99 the data start is moved \fIoffset\fP bytes into the specified file or
 100 device
 101 .IP "\fB\-\-sizelimit \fIlimit\fP"
 102 the data end is set to no more than \fIsizelimit\fP bytes after the data start
 103 .IP "\fB\-p, \-\-pass-fd \fInum\fP"
 104 read the passphrase from file descriptor with number
 105 .I num
 106 instead of from the terminal
 107 .IP "\fB\-r, \-\-read-only\fP"
 108 setup read-only loop device
 109 .IP "\fB\-\-show\fP"
 110 print device name if the
 111 .I -f
 112 option and a
 113 .I file
 114 argument are present.
 115
 116 The short form of this option (\fB\-s\fP) is deprecated.  This short form could
 117 be in collision with Loop-AES implementation where the same option is used for
 118 \fB\-\-sizelimit\fP.
 119 .IP "\fB\-v, \-\-verbose\fP"
 120 verbose mode
 121
 122 .SH RETURN VALUE
 123 .B losetup
 124 returns 0 on success, nonzero on failure. When
 125 .B losetup
 126 displays the status of a loop device, it returns 1 if the device
 127 is not configured and 2 if an error occurred which prevented
 128 .B losetup
 129 from determining the status of the device.
 130
 131 .SH FILES
 132 .nf
 133 /dev/loop0, /dev/loop1, ...   loop devices (major=7)
 134 .fi
 135 .SH EXAMPLE
 136 If you are using the loadable module you must have the module loaded
 137 first with the command
 138 .IP
 139 # modprobe loop
 140 .LP
 141 Maybe also encryption modules are needed.
 142 .IP
 143 # modprobe des
 144 # modprobe cryptoloop
 145 .LP
 146 The following commands can be used as an example of using the loop device.
 147 .nf
 148 .IP
 149 # dd if=/dev/zero of=/file bs=1k count=100
 150 # losetup -e des /dev/loop0 /file
 151 Password:
 152 Init (up to 16 hex digits):
 153 # mkfs -t ext2 /dev/loop0 100
 154 # mount -t ext2 /dev/loop0 /mnt
 155  ...
 156 # umount /dev/loop0
 157 # losetup -d /dev/loop0
 158 .fi
 159 .LP
 160 If you are using the loadable module you may remove the module with
 161 the command
 162 .IP
 163 # rmmod loop
 164 .LP
 165 .fi
 166 .SH RESTRICTION
 167 DES encryption is painfully slow. On the other hand, XOR is terribly weak.
 168
 169 Cryptoloop is deprecated in favor of dm-crypt. For more details see
 170 .BR cryptsetup (8).
 171 .SH AVAILABILITY
 172 The losetup command is part of the util-linux-ng package and is available from
 173 ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.
 174 .\" .SH AUTHORS
 175 .\" .nf
 176 .\" Original version: Theodore Ts'o <tytso@athena.mit.edu>
 177 .\" Original DES by: Eric Young <eay@psych.psy.uq.oz.au>
 178 .\" .fi