LOSETUP(8)

NAME
losetup - set up and control loop devices

SYNOPSIS
losetup [options] loop_device file
losetup -F [options] loop_device [file]
losetup [ -d ] loop_device
losetup -a
losetup -f
losetup -R loop_device

DESCRIPTION
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 loop_device argument is given, the status of the corresponding loop device is shown.

OPTIONS

-a  Show status of all loop devices.

-C itercountk
    Runs hashed passphrase through itercountk thousand iterations of AES-256 before using it for loop encryption. This consumes lots of CPU cycles at loop setup/mount time but not thereafter. In combination with passphrase seed this slows down dictionary attacks. Iteration is not done in multi-key mode.

-d  Detach the file or device associated with the specified loop device.

-e encryption
    Enable data encryption. Following encryption types are recognized:

    NONE
        Use no encryption (default).
    XOR Use a simple XOR encryption.
    AES128 AES
        Use 128 bit AES encryption. Passphrase is hashed with SHA-256 by default.
    AES192
        Use 192 bit AES encryption. Passphrase is hashed with SHA-384 by default.
    AES256
        Use 256 bit AES encryption. Passphrase is hashed with SHA-512 by default.

    twofish128 twofish160 twofish192 twofish256
    blowfish128 blowfish160 blowfish192 blowfish256
    serpent128 serpent192 serpent256 mars128 mars192
    mars256 rc6-128 rc6-192 rc6-256 tripleDES
        These encryption types are available if they are enabled in kernel configuration or corresponding modules have been loaded to kernel.

-f  Find and show next unused loop device.

-F  Reads and uses mount options from /etc/fstab that match specified loop device, including offset= sizelimit= encryption= pseed= phash= loinit= gpgkey= gpghome= cleartextkey= itercountk= and looped to device/file name. loop= option in /etc/fstab must match specified loop device name. Command line options take precedence in case of conflict.

-G gpghome
    Set gpg home directory to gpghome, so that gpg uses public/private keys on gpghome directory. This is only used when gpgkey file needs to be decrypted using public/private keys. If gpgkey file is encrypted with symmetric cipher only, public/private keys are not required and this option has no effect.

-H phash
    Uses phash function to hash passphrase. Available hash functions are sha256, sha384, sha512 and rmd160. unhashed1, unhashed2 and unhashed3 functions also exist for compatibility with some obsolete implementations.

    Hash function random does not ask for passphrase but sets up random keys and attempts to put loop to multi-key mode. When random/1777 hash type is used as mount option for mount program, mount program will create new file system on the loop device and construct initial permissions of file system root directory from octal digits that follow the slash character.

    WARNING! DO NOT USE RANDOM HASH TYPE ON PARTITION WITH EXISTING IMPORTANT DATA ON IT. RANDOM HASH TYPE WILL DESTROY YOUR DATA.

-I loinit
    Passes a numeric value of loinit as a parameter to cipher transfer function. Cipher transfer functions are free to interpret value as they want.

-K gpgkey
    Passphrase is piped to gpg so that gpg can decrypt file gpgkey which contains the real keys that are used to encrypt loop device. If decryption requires public/private keys and gpghome is not specified, all users use their own gpg public/private keys to decrypt gpgkey. Decrypted gpgkey should contain 1 or 64 or 65 keys, each key at least 20 characters and separated by newline. If decrypted gpgkey contains 64 or 65 keys, then loop device is put to multi-key mode. In multi-key mode first key is used for first sector, second key for second sector, and so on. 65th key, if present, is used as additional input to MD5 IV computation.

-o offset
    The data start is moved offset bytes into the specified file or device. Normally offset is included in IV (initialization vector) computations. If offset is prefixed with @ character, then offset is not included in IV computations. @ prefix functionality may not be supported on some older kernels and/or loop drivers.

-p passwdfd
    Read the passphrase from file descriptor passwdfd instead of the terminal. If -K option is not being used (no gpg key file), then losetup attempts to read 65 keys from passwdfd, each key at least 20 characters and separated by newline. If losetup successfully reads 64 or 65 keys, then loop device is put to multi-key mode. If losetup encounters end-of-file before 64 keys are read, then only first key is used in single-key mode.

    echo SecretPassphraseHere | losetup -p0 -K foo.gpg -e AES128 ...

    In above example, losetup reads passphrase from file descriptor 0 (stdin).

-P cleartextkey
    Read the passphrase from file cleartextkey instead of the terminal. If -K option is not being used (no gpg key file), then losetup attempts to read 65 keys from cleartextkey, each key at least 20 characters and separated by newline. If losetup successfully reads 64 or 65 keys, then loop device is put to multi-key mode. If losetup encounters end-of-file before 64 keys are read, then only first key is used in single-key mode. If both -p and -P options are used, then -p option takes precedence. These are equivalent:

    losetup -p3 -K foo.gpg -e AES128 ... 3<someFileName

    losetup -P someFileName -K foo.gpg -e AES128 ...

    In first line of above example, in addition to normal open file descriptors (0==stdin 1==stdout 2==stderr), shell opens the file and passes open file descriptor to started losetup program. In second line of above example, losetup opens the file itself.

-r  Read-only mode.

-R  Resize existing, already set up loop device, to new changed underlying device size. This option is for changing mounted live file system size on LVM volume. This functionality may not be supported on some older kernels and/or loop drivers.

-s sizelimit
    Size of loop device is limited to sizelimit bytes. If unspecified or set to zero, loop device size is set to maximum available (file size minus offset). This option may not be supported on some older kernels and/or loop drivers.

-S pseed
    Sets encryption passphrase seed pseed which is appended to user supplied passphrase before hashing. Using different seeds for different partitions makes dictionary attacks slower but does not prevent them if user supplied passphrase is guessable. Seed is not used in multi-key mode.

-T  Asks passphrase twice.

-v  Verbose mode.

RETURN VALUE
losetup returns 0 on success, nonzero on failure. When 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 losetup from determining the status of the device.

FILES
/dev/loop0,/dev/loop1,...   loop devices (major=7)

EXAMPLE
The following commands can be used as an example of using the loop device.

dd if=/dev/zero of=/file bs=1k count=500
head -c 3705 /dev/random | uuencode -m - | head -n 66 \
    | tail -n 65 | gpg --symmetric -a >/etc/fskey9.gpg
losetup -e AES128 -K /etc/fskey9.gpg /dev/loop0 /file
mkfs -t ext2 /dev/loop0
mount -t ext2 /dev/loop0 /mnt
 ...
umount /dev/loop0
losetup -d /dev/loop0

RESTRICTION
XOR encryption is terribly weak.

AUTHORS
Original version: Theodore Ts'o <tytso@athena.mit.edu>
AES support: Jari Ruusu