LOFIADM(8) Maintenance Commands and Procedures LOFIADM(8)
NAME
lofiadm - administer files available as block devices through lofi
SYNOPSIS
lofiadm [
-r] [
-l]
-a file [
device]
lofiadm [
-r]
-c crypto_algorithm -a file [
device]
lofiadm [
-r]
-c crypto_algorithm -k raw_key_file -a file [
device]
lofiadm [
-r]
-c crypto_algorithm -T token_key -a file [
device]
lofiadm [
-r]
-c crypto_algorithm -T token_key -k wrapped_key_file -a file [
device]
lofiadm [
-r]
-c crypto_algorithm -e -a file [
device]
lofiadm -C algorithm [
-s segment_size]
file lofiadm -d file|
device lofiadm -U file lofiadm [
file|device]
DESCRIPTION
lofiadm administers
lofi, the loopback file driver.
lofi allows a file to
be associated with a block device. That file can then be accessed through
the block device. This is useful when the file contains an image of some
filesystem (such as a floppy or
CD-ROM image), because the block device can
then be used with the normal system utilities for mounting, checking or
repairing filesystems. See
fsck(8) and
mount(8).
Use
lofiadm to add a file as a loopback device, remove such an association,
or print information about the current associations.
Encryption and compression options are mutually exclusive on the command
line. Further, an encrypted file cannot be compressed later, nor can a
compressed file be encrypted later.
In the global zone,
lofiadm can be used on both the global zone devices and
all devices owned by other non-global zones on the system.
Labeled Devices
If the command line flag,
-l, is used while creating a loopack device,
lofi will create a labeled loopback device, and will generate device links in
/dev/{dsk,rdsk} directories for partitions or slices.
Before using these devices, users should create or verify partitioning by
using partition management tools such as
format(8) and
fdisk(8). Once the
device has been appropriately partitioned, the labeled device can be used
as normal disk to create and mount file systems and to store data.
Mappings created by
lofiadm are not permanent and not persisted by the
system. If power is lost or the system is rebooted, then the mappings will
need to be created again.
The partition table requires space from the mapped file.
lofi does not
support converting previously created unlabeled loopback device images to
labeled loopback devices. If an unlabeled device is used as a labeled
device, writing to it will corrupt it.
OPTIONS
The following options are supported:
-a file [
device]
Add
file as a block device.
If
device is not specified, an available device is picked.
If
device is specified,
lofiadm attempts to assign it to
file.
device must be available or
lofiadm will fail. The ability to
specify a device is provided for use in scripts that wish to
reestablish a particular set of associations. A device may not be
specified when using a labeled lofi device.
-C {gzip |
gzip-N |
lzma} Compress the file with the specified compression algorithm.
The
gzip compression algorithm uses the same compression as the
open-source
gzip command. You can specify the
gzip level by using
the value gzip-
N where
N is 6 (fast) or 9 (best compression ratio).
Currently,
gzip, without a number, is equivalent to
gzip-6 (which
is also the default for the
gzip command).
lzma stands for the LZMA (Lempel-Ziv-Markov) compression algorithm.
Note that you cannot write to a compressed file, nor can you mount
a compressed file read/write.
-d file|
device Remove an association by
file or
device name, if the associated
block device is not busy, and deallocates the block device.
-l This option should be used with
-a option to create labeled
loopback device. If created in local zone, the device has to be
enabled in zone configuration.
-r If the
-r option is specified before the
-a option, the
device will
be opened read-only.
-s segment_size The segment size to use to divide the file being compressed.
segment_size can be an integer multiple of 512.
-U file Uncompress a compressed file.
The following options are used when the file is encrypted:
-c crypto_algorithm Select the encryption algorithm. The algorithm must be specified
when encryption is enabled because the algorithm is not stored in
the disk image.
If none of
-e,
-k, or
-T is specified,
lofiadm prompts for a
passphrase, with a minimum length of eight characters, to be
entered. The passphrase is used to derive a symmetric encryption
key using PKCS#5 PBKD2.
-k raw_key_file |
wrapped_key_file Path to raw or wrapped symmetric encryption key. If a PKCS#11
object is also given with the
-T option, then the key is wrapped by
that object. If
-T is not specified, the key is used raw.
-T token_key The key in a PKCS#11 token to use for the encryption or for
unwrapping the key file.
If
-k is also specified,
-T identifies the unwrapping key, which
must be an RSA private key.
-e Generate an ephemeral symmetric encryption key.
OPERANDS
The following operands are supported:
crypto_algorithm One of:
aes-128-cbc,
aes-192-cbc,
aes-256-cbc,
des3-cbc,
blowfish-cbc.
device Display the file name associated with the block device
device.
Without arguments, print a list of the current associations.
Filenames must be valid absolute pathnames.
When a file is added, it is opened for reading or writing by root.
Any restrictions apply (such as restricted root access over
NFS).
The file is held open until the association is removed. It is not
actually accessed until the block device is used, so it will never
be written to if the block device is only opened read-only.
Note that the filename may appear as "?" if it is not possible to
resolve the path in the current context (for example, if it's an
NFS path in a non-global zone).
file Display the block device associated with
file.
raw_key_file Path to a file of the appropriate length, in bits, to use as a raw
symmetric encryption key.
token_key PKCS#11 token object in the format:
token_name:
manufacturer_id:
serial_number:
key_label All but the key label are optional and can be empty. For example,
to specify a token object with only its key label
MylofiKey, use
-T :::MylofiKey.
wrapped_key_file Path to file containing a symmetric encryption key wrapped by the
RSA private key specified by
-T.
ENVIRONMENT
See
environ(7) for descriptions of the following environment variables that
affect the execution of
lofiadm :
LC_CTYPE,
LC_MESSAGES and
NLSPATH.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred.
EXAMPLES
Example 1 Mounting an Existing CD-ROM Image
You should ensure that Solaris understands the image before
creating the
CD.
lofi allows you to mount the image and see if it
works.
This example mounts an existing
CD-ROM image (
sparc.iso), of the
Red Hat 6.0 CD which was downloaded from the Internet. It was
created with the
mkisofs utility from the Internet.
Use
lofiadm to attach a block device to it:
# lofiadm -a /home/mike_s/RH6.0/sparc.iso
/dev/lofi/1
lofiadm picks the device and prints the device name to the standard
output. You can run
lofiadm again by issuing the following
command:
# lofiadm
Block Device File Options
/dev/lofi/1 /home/mike_s/RH6.0/sparc.iso -
Or, you can give it one name and ask for the other, by issuing the
following command:
# lofiadm /dev/lofi/1
/home/mike_s/RH6.0/sparc.iso
Use the
mount(8) command to mount the image:
# mount -F hsfs -o ro /dev/lofi/1 /mnt
Check to ensure that Solaris understands the image:
# df -k /mnt
Filesystem kbytes used avail capacity Mounted on
/dev/lofi/1 512418 512418 0 100% /mnt
# ls /mnt
./ RedHat/ doc/ ls-lR rr_moved/
../ TRANS.TBL dosutils/ ls-lR.gz sbin@
.buildlog bin@ etc@ misc/ tmp/
COPYING boot/ images/ mnt/ usr@
README boot.cat* kernels/ modules/
RPM-PGP-KEY dev@ lib@ proc/
Solaris can mount the CD-ROM image, and understand the filenames.
The image was created properly, and you can now create the
CD-ROM with confidence.
As a final step, unmount and detach the images:
# umount /mnt
# lofiadm -d /dev/lofi/1
# lofiadm
Block Device File Options
Example 2 Mounting a Floppy Image
This is similar to the first example.
Using
lofi to help you mount files that contain floppy images is
helpful if a floppy disk contains a file that you need, but the
machine which you are on does not have a floppy drive. It is also
helpful if you do not want to take the time to use the
dd command
to copy the image to a floppy.
This is an example of getting to
MDB floppy for Solaris on an x86
platform:
# lofiadm -a /export/s28/MDB_s28x_wos/latest/boot.3
/dev/lofi/1
# mount -F pcfs /dev/lofi/1 /mnt
# ls /mnt
./ COMMENT.BAT* RC.D/ SOLARIS.MAP*
../ IDENT* REPLACE.BAT* X/
APPEND.BAT* MAKEDIR.BAT* SOLARIS/
# umount /mnt
# lofiadm -d /export/s28/MDB_s28x_wos/latest/boot.3
Example 3 Making a
UFS Filesystem on a File
Making a
UFS filesystem on a file can be useful, particularly if a
test suite requires a scratch filesystem. It can be painful (or
annoying) to have to repartition a disk just for the test suite,
but you do not have to. You can
newfs a file with
lofi.
Create the file:
# mkfile 35m /export/home/test
Attach it to a block device. You also get the character device
that
newfs requires, so
newfs that:
# lofiadm -a /export/home/test
/dev/lofi/1
# newfs /dev/rlofi/1
newfs: construct a new file system /dev/rlofi/1: (y/n)? y
/dev/rlofi/1: 71638 sectors in 119 cylinders of 1 tracks, 602 sectors
35.0MB in 8 cyl groups (16 c/g, 4.70MB/g, 2240 i/g)
super-block backups (for fsck -F ufs -o b=#) at:
32, 9664, 19296, 28928, 38560, 48192, 57824, 67456,
Note that
ufs might not be able to use the entire file. Mount and
use the filesystem:
# mount /dev/lofi/1 /mnt
# df -k /mnt
Filesystem kbytes used avail capacity Mounted on
/dev/lofi/1 33455 9 30101 1% /mnt
# ls /mnt
./ ../ lost+found/
# umount /mnt
# lofiadm -d /dev/lofi/1
Example 4 Creating a PC (FAT) File System on a Unix File
The following series of commands creates a
FAT file system on a
Unix file. The file is associated with a block device created by
lofiadm # mkfile 10M /export/test/testfs
# lofiadm -a /export/test testfs
/dev/lofi/1
Note use of
rlofi, not
lofi, in following command.
# mkfs -F pcfs -o nofdisk,size=20480 /dev/rlofi/1
Construct a new FAT file system on /dev/rlofi/1: (y/n)? y
# mount -F pcfs /dev/lofi/1 /mnt
# cd /mnt
# df -k .
Filesystem kbytes used avail capacity Mounted on
/dev/lofi/1 10142 0 10142 0% /mnt
Example 5 Compressing an Existing CD-ROM Image
The following example illustrates compressing an existing CD-ROM
image (
solaris.iso), verifying that the image is compressed, and
then uncompressing it.
# lofiadm -C gzip /export/home/solaris.iso
Use
lofiadm to attach a block device to it:
# lofiadm -a /export/home/solaris.iso
/dev/lofi/1
Check if the mapped image is compressed:
# lofiadm
Block Device File Options
/dev/lofi/1 /export/home/solaris.iso Compressed(gzip)
/dev/lofi/2 /export/home/regular.iso -
Unmap the compressed image and uncompress it:
# lofiadm -d /dev/lofi/1
# lofiadm -U /export/home/solaris.iso
Example 6 Creating an Encrypted UFS File System on a File
This example is similar to the example of making a UFS filesystem
on a file, above.
Create the file:
# mkfile 35m /export/home/test
Attach the file to a block device and specify that the file image
is encrypted. As a result of this command, you obtain the
character device, which is subsequently used by
newfs:
# lofiadm -c aes-256-cbc -a /export/home/secrets
Enter passphrase: My-M0th3r;l0v3s_m3+4lw4ys! (not echoed)
Re-enter passphrase: My-M0th3r;l0v3s_m3+4lw4ys! (not echoed)
/dev/lofi/1
# newfs /dev/rlofi/1
newfs: construct a new file system /dev/rlofi/1: (y/n)? y
/dev/rlofi/1: 71638 sectors in 119 cylinders of 1 tracks, 602 sectors
35.0MB in 8 cyl groups (16 c/g, 4.70MB/g, 2240 i/g)
super-block backups (for fsck -F ufs -o b=#) at:
32, 9664, 19296, 28928, 38560, 48192, 57824, 67456,
The mapped file system shows that encryption is enabled:
# lofiadm
Block Device File Options
/dev/lofi/1 /export/home/secrets Encrypted
Mount and use the filesystem:
# mount /dev/lofi/1 /mnt
# cp moms_secret_*_recipe /mnt
# ls /mnt
./ moms_secret_cookie_recipe moms_secret_soup_recipe
../ moms_secret_fudge_recipe moms_secret_stuffing_recipe
lost+found/ moms_secret_meatloaf_recipe moms_secret_waffle_recipe
# umount /mnt
# lofiadm -d /dev/lofi/1
Subsequent attempts to map the filesystem with the wrong key or the
wrong encryption algorithm will fail:
# lofiadm -c blowfish-cbc -a /export/home/secrets
Enter passphrase: mommy (not echoed)
Re-enter passphrase: mommy (not echoed)
lofiadm: could not map file /root/lofi: Invalid argument
# lofiadm
Block Device File Options
#
Attempts to map the filesystem without encryption will succeed,
however attempts to mount and use the filesystem will fail:
# lofiadm -a /export/home/secrets
/dev/lofi/1
# lofiadm
Block Device File Options
/dev/lofi/1 /export/home/secrets -
# mount /dev/lofi/1 /mnt
mount: /dev/lofi/1 is not this fstype
#
SEE ALSO
lofi(4D),
lofs(4FS),
attributes(7),
fdisk(8),
format(8),
fsck(8),
mount(8),
mount_ufs(8),
newfs(8)NOTES
Just as you would not directly access a disk device that has mounted file
systems, you should not access a file associated with a block device except
through the
lofi file driver. It might also be appropriate to ensure that
the file has appropriate permissions to prevent such access.
The abilities of
lofiadm , and who can use them, are controlled by the
permissions of
/dev/lofictl. Read-access allows query operations, such as
listing all the associations. Write-access is required to do any state-
changing operations, like adding an association. As shipped,
/dev/lofictl is owned by
root, in group
sys, and mode
0644, so all users can do query
operations but only root can change anything. The administrator can give
users write-access, allowing them to add or delete associations, but that
is very likely a security hole and should probably only be given to a
trusted group.
When mounting a filesystem image, take care to use appropriate mount
options. In particular, the
nosuid mount option might be appropriate for
UFS images whose origin is unknown. Also, some options might not be useful
or appropriate, like
logging or
forcedirectio for
UFS. For compatibility
purposes, a raw device is also exported along with the block device. For
example,
newfs(8) requires one.
The output of
lofiadm (without arguments) might change in future releases.
illumos June 14, 2016 illumos