lofiadm man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

LOFIADM(1M)							   LOFIADM(1M)

NAME
       lofiadm - administer files available as block devices through lofi

SYNOPSIS
       lofiadm [-r] -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(1M)   and
       mount(1M).

       Use lofiadm to add a file as a loopback device, remove such an associa‐
       tion, or print information about the current associations.

       Encryption and compression options are mutually exclusive on  the  com‐
       mand  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.

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 spec‐
	   ify	a  device is provided for use in scripts that wish to reestab‐
	   lish 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.

       -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. seg‐
	   ment_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 unwrap‐
	   ping 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.	 File‐
	   names 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.


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 fol‐
       lowing 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 con‐
       fidence.

       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 help‐
       ful 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 plat‐
       form:

	 # 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 uncom‐
       pressing 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
	 #

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.

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  appropri‐
       ate 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 com‐
       patibility 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.

				 Aug 28, 2013			   LOFIADM(1M)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net