lofiadm(1M)						  System Administration Commands					       lofiadm(1M)

NAME

       lofiadm - administer files available as block devices through lofi

SYNOPSIS

       /usr/sbin/lofiadm -a file [device]

       /usr/sbin/lofiadm -a -c crypto_algorithm file [device]

       /usr/sbin/lofiadm -a -c crypto_algorithm -k raw_key_file file [device]

       /usr/sbin/lofiadm -a -c crypto_algorithm -T token_key file [device]

       /usr/sbin/lofiadm -a -c crypto_algorithm -T token_key
	    -k wrapped_key_file file [device]

       /usr/sbin/lofiadm -a -c crypto_algorithm -e file [device]

       /usr/sbin/lofiadm -C algorithm [-s segment_size] file

       /usr/sbin/lofiadm -d file | device

       /usr/sbin/lofiadm -U file

       /usr/sbin/lofiadm [ file | device]

DESCRIPTION

       lofiadm	administers lofi(7D), the loopback file driver. lofi(7D) 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(1M)
       and mount(1M).

       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.

       The lofi(7D) driver is not available and will not work inside a zone.

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.

       -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.

       -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.

       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.

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 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 annoy-
       ing) 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 -a -c aes-256-cbc /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
	 #

ENVIRONMENT VARIABLES

       See environ(5) 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.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |ATTRIBUTE TYPE		     |ATTRIBUTE VALUE		   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       fsck(1M), mount(1M), mount_ufs(1M), newfs(1M), attributes(5), lofi(7D), lofs(7FS)

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(1M) requires one.

       The output of lofiadm (without arguments) might change in future releases.

SunOS 5.11							    10 Mar 2009 						       lofiadm(1M)