| .TH LOSETUP 8 "2003-07-01" "Linux" "MAINTENANCE COMMANDS" |
| .SH NAME |
| losetup \- set up and control loop devices |
| .SH SYNOPSIS |
| .ad l |
| Get info: |
| .sp |
| .in +5 |
| .B losetup |
| .I loopdev |
| .sp |
| .B losetup -a |
| .sp |
| .B losetup -j |
| .I file |
| .RB [ \-o |
| .IR offset ] |
| .sp |
| .in -5 |
| Delete loop: |
| .sp |
| .in +5 |
| .B "losetup \-d" |
| .IR loopdev ... |
| .sp |
| .in -5 |
| Print name of first unused loop device: |
| .sp |
| .in +5 |
| .B "losetup \-f" |
| .sp |
| .in -5 |
| Setup loop device: |
| .sp |
| .in +5 |
| .B losetup |
| .RB [{ \-e | \-E } |
| .IR encryption ] |
| .RB [ \-o |
| .IR offset ] |
| .RB [ \-\-sizelimit |
| .IR limit ] |
| .in +8 |
| .RB [ \-p |
| .IR pfd ] |
| .RB [ \-r ] |
| .RB { \-f [ \-\-show ]| \fIloopdev\fP } |
| .I file |
| .sp |
| .in -13 |
| Resize loop device: |
| .sp |
| .in +5 |
| .B "losetup \-c" |
| .I loopdev |
| .in -5 |
| .ad b |
| .SH DESCRIPTION |
| .B losetup |
| 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 |
| \fIloopdev\fP argument is given, the status of the corresponding loop |
| device is shown. |
| |
| .SS "Encryption" |
| It is possible to specify transfer functions (for encryption/decryption |
| or other purposes) using one of the |
| .B \-E |
| and |
| .B \-e |
| options. |
| There are two mechanisms to specify the desired encryption: by number |
| and by name. If an encryption is specified by number then one |
| has to make sure that the Linux kernel knows about the encryption with that |
| number, probably by patching the kernel. Standard numbers that are |
| always present are 0 (no encryption) and 1 (XOR encryption). |
| When the cryptoloop module is loaded (or compiled in), it uses number 18. |
| This cryptoloop module will take the name of an arbitrary encryption type |
| and find the module that knows how to perform that encryption. |
| .SH OPTIONS |
| .IP "\fB\-a, \-\-all\fP" |
| show status of all loop devices |
| .IP "\fB\-c, \-\-set-capacity\fP \fIloopdev\fP |
| force loop driver to reread size of the file associated with the specified loop device |
| .IP "\fB\-d, \-\-detach\fP \fIloopdev\fP..." |
| detach the file or device associated with the specified loop device(s) |
| .IP "\fB\-e, \-E, \-\-encryption \fIencryption_type\fP" |
| enable data encryption with specified name or number |
| .IP "\fB\-f, \-\-find\fP" |
| find the first unused loop device. If a |
| .I file |
| argument is present, use this device. Otherwise, print its name |
| .IP "\fB\-h, \-\-help\fP" |
| print help |
| .IP "\fB\-j, \-\-associated \fIfile\fP" |
| show status of all loop devices associated with given |
| .I file |
| .IP "\fB\-o, \-\-offset \fIoffset\fP" |
| the data start is moved \fIoffset\fP bytes into the specified file or |
| device |
| .IP "\fB\-\-sizelimit \fIlimit\fP" |
| the data end is set to no more than \fIsizelimit\fP bytes after the data start |
| .IP "\fB\-p, \-\-pass-fd \fInum\fP" |
| read the passphrase from file descriptor with number |
| .I num |
| instead of from the terminal |
| .IP "\fB\-r, \-\-read-only\fP" |
| setup read-only loop device |
| .IP "\fB\-\-show\fP" |
| print device name if the |
| .I -f |
| option and a |
| .I file |
| argument are present. |
| |
| The short form of this option (\fB\-s\fP) is deprecated. This short form could |
| be in collision with Loop-AES implementation where the same option is used for |
| \fB\-\-sizelimit\fP. |
| .IP "\fB\-v, \-\-verbose\fP" |
| verbose mode |
| |
| .SH RETURN VALUE |
| .B losetup |
| returns 0 on success, nonzero on failure. When |
| .B losetup |
| displays the status of a loop device, it returns 1 if the device |
| is not configured and 2 if an error occurred which prevented |
| .B losetup |
| from determining the status of the device. |
| |
| .SH FILES |
| .nf |
| /dev/loop0, /dev/loop1, ... loop devices (major=7) |
| .fi |
| .SH EXAMPLE |
| If you are using the loadable module you must have the module loaded |
| first with the command |
| .IP |
| # modprobe loop |
| .LP |
| Maybe also encryption modules are needed. |
| .IP |
| # modprobe des |
| # modprobe cryptoloop |
| .LP |
| The following commands can be used as an example of using the loop device. |
| .nf |
| .IP |
| # dd if=/dev/zero of=/file bs=1k count=100 |
| # losetup -e des /dev/loop0 /file |
| Password: |
| Init (up to 16 hex digits): |
| # mkfs -t ext2 /dev/loop0 100 |
| # mount -t ext2 /dev/loop0 /mnt |
| ... |
| # umount /dev/loop0 |
| # losetup -d /dev/loop0 |
| .fi |
| .LP |
| If you are using the loadable module you may remove the module with |
| the command |
| .IP |
| # rmmod loop |
| .LP |
| .fi |
| .SH RESTRICTION |
| DES encryption is painfully slow. On the other hand, XOR is terribly weak. |
| |
| Cryptoloop is deprecated in favor of dm-crypt. For more details see |
| .BR cryptsetup (8). |
| .SH AVAILABILITY |
| The losetup command is part of the util-linux-ng package and is available from |
| ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/. |
| .\" .SH AUTHORS |
| .\" .nf |
| .\" Original version: Theodore Ts'o <tytso@athena.mit.edu> |
| .\" Original DES by: Eric Young <eay@psych.psy.uq.oz.au> |
| .\" .fi |