| blob | 5eede96b526a76d1dec8303e6806a3fdee9c4d01 |
1 '\" te
2 .\" Copyright 2016 Toomas Soome <tsoome@me.com>
3 .\" Copyright 2013 Nexenta Systems, Inc. All rights reserved.
4 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
6 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
7 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .Dd Jun 14, 2016
9 .Dt LOFIADM 1M
10 .Os
11 .Sh NAME
12 .Nm lofiadm
13 .Nd administer files available as block devices through lofi
14 .Sh SYNOPSIS
15 .Nm
16 .Op Fl r
17 .Op Fl l
18 .Fl a Ar file Op Ar device
19 .Nm
20 .Op Fl r
21 .Fl c
22 .Ar crypto_algorithm
23 .Fl a
24 .Ar file Op Ar device
25 .Nm
26 .Op Fl r
27 .Fl c Ar crypto_algorithm
28 .Fl k Ar raw_key_file
29 .Fl a Ar file Op Ar device
30 .Nm
31 .Op Fl r
32 .Fl c Ar crypto_algorithm
33 .Fl T Ar token_key
34 .Fl a Ar file Op Ar device
35 .Nm
36 .Op Fl r
37 .Fl c Ar crypto_algorithm
38 .Fl T Ar token_key
39 .Fl k Ar wrapped_key_file
40 .Fl a Ar file Op Ar device
41 .Nm
42 .Op Fl r
43 .Fl c Ar crypto_algorithm
44 .Fl e
45 .Fl a Ar file Op Ar device
46 .Nm
47 .Fl C Ar algorithm
48 .Op Fl s Ar segment_size
49 .Ar file
50 .Nm
51 .Fl d Ar file Ns | Ns Ar device
52 .Nm
53 .Fl U Ar file
54 .Nm
55 .Op Ar file Ns | Ns device
56 .Sh DESCRIPTION
57 .Nm
58 administers
59 .Sy lofi ,
60 the loopback file driver.
61 .Sy lofi
62 allows a file to be associated with a block device. That file can then be
63 accessed through the block device. This is useful when the file contains an
64 image of some filesystem (such as a floppy or
65 .Sy CD-ROM
66 image), because the block device can then be used with the normal system
67 utilities for mounting, checking or repairing filesystems. See
68 .Xr fsck 1M
69 and
70 .Xr mount 1M .
71 .Pp
72 Use
73 .Nm
74 to add a file as a loopback device, remove such an
75 association, or print information about the current associations.
76 .Pp
77 Encryption and compression options are mutually exclusive on the command line.
78 Further, an encrypted file cannot be compressed later, nor can a compressed
79 file be encrypted later.
80 .Pp
81 In the global zone,
82 .Nm
83 can be used on both the global
84 zone devices and all devices owned by other non-global zones on the system.
85 .Ss Labeled Devices
86 If the command line flag,
87 .Fl l ,
88 is used while creating a loopack device,
89 .Sy lofi
90 will create a labeled loopback
91 device, and will generate device links in
92 .Pa /dev/{dsk,rdsk}
93 directories for partitions or slices.
94 .Pp
95 Before using these devices, users should create or verify
96 partitioning by using partition management tools such as
97 .Xr format 1M and
98 .Xr fdisk 1M .
99 Once the device has been appropriately partitioned, the labeled
100 device can be used as normal disk to create and mount file systems and to store
101 data. Mappings created by
102 .Nm
103 are not permanent and not persisted by the system. If power is lost or the system
104 is rebooted, then the mappings will need to be created again.
105 .Pp
106 The partition table requires space from the mapped file.
107 .Sy lofi
108 does not support converting previously created unlabeled loopback device images
109 to labeled loopback devices. If an unlabeled device is used as a labeled device,
110 writing to it will corrupt it.
111 .Sh OPTIONS
112 The following options are supported:
113 .Bl -tag -width Ds
114 .It Fl a Ar file Op Ar device
115 Add
116 .Sy file
117 as a block device.
118 .Pp
119 If
120 .Sy device
121 is not specified, an available device is picked.
122 .Pp
123 If
124 .Sy device
125 is specified,
126 .Nm
127 attempts to assign it to
128 .Sy file .
129 .Sy device
130 must be available or
131 .Nm
132 will fail. The ability to specify a device is provided for use in scripts that
133 wish to reestablish a particular set of associations.
134 A device may not be specified when using a labeled lofi device.
135 .It Fl C Ar {gzip | gzip-N | lzma}
136 Compress the file with the specified compression algorithm.
137 .Pp
138 The
139 .Sy gzip
140 compression algorithm uses the same compression as the open-source
141 .Sy gzip
142 command. You can specify the
143 .Sy gzip
144 level by using the value gzip-\fR\fIN\fR where \fIN\fR is 6 (fast) or 9
145 (best compression ratio). Currently,
146 .Sy gzip ,
147 without a number, is equivalent to
148 .Sy gzip-6
149 (which is also the default for the
150 .Sy gzip
151 command).
152 .Pp
153 .Sy lzma
154 stands for the LZMA (Lempel-Ziv-Markov) compression algorithm.
155 .Pp
156 Note that you cannot write to a compressed file, nor can you mount a compressed
157 file read/write.
158 .It Fl d Ar file Ns | Ns Ar device
159 Remove an association by
160 .Sy file
161 or
162 .Sy device
163 name, if the associated block device is not busy, and deallocates the block
164 device.
165 .It Fl l
166 This option should be used with
167 .Fl a
168 option to create labeled loopback device. If created in local zone, the device
169 has to be enabled in zone configuration.
170 .It Fl r
171 If the
172 .Fl r
173 option is specified before the
174 .Fl a
175 option, the
176 .Sy device
177 will be opened read-only.
178 .It Fl s Ar segment_size
179 The segment size to use to divide the file being compressed.
180 .Sy segment_size
181 can be an integer multiple of 512.
182 .It Fl U Ar file
183 Uncompress a compressed file.
184 .El
185 .Pp
186 The following options are used when the file is encrypted:
187 .Bl -tag -width Ds
188 .It Fl c Ar crypto_algorithm
189 Select the encryption algorithm. The algorithm must be specified when
190 encryption is enabled because the algorithm is not stored in the disk image.
191 .Pp
192 If none of
193 .Fl e ,
194 .Fl k ,
195 or
196 .Fl T
197 is specified,
198 .Nm
199 prompts for a passphrase, with a minimum length of eight characters, to be
200 entered.
201 The passphrase is used to derive a symmetric encryption key using PKCS#5 PBKD2.
202 .It Fl k Ar raw_key_file | Ar wrapped_key_file
203 Path to raw or wrapped symmetric encryption key. If a PKCS#11 object is also
204 given with the
205 .Fl T
206 option, then the key is wrapped by that object. If
207 .Fl T
208 is not specified, the key is used raw.
209 .It Fl T Ar token_key
210 The key in a PKCS#11 token to use for the encryption or for unwrapping the key
211 file.
212 .Pp
213 If
214 .Fl k
215 is also specified,
216 .Fl T
217 identifies the unwrapping key, which must be an RSA private key.
218 .It Fl e
219 Generate an ephemeral symmetric encryption key.
220 .El
221 .Sh OPERANDS
222 The following operands are supported:
223 .Bl -tag -width Ds
224 .It Ar crypto_algorithm
225 One of:
226 .Sy aes-128-cbc ,
227 .Sy aes-192-cbc ,
228 .Sy aes-256-cbc ,
229 .Sy des3-cbc ,
230 .Sy blowfish-cbc .
231 .It Ar device
232 Display the file name associated with the block device
233 .Sy device .
234 .Pp
235 Without arguments, print a list of the current associations. Filenames must be
236 valid absolute pathnames.
237 .Pp
238 When a file is added, it is opened for reading or writing by root. Any
239 restrictions apply (such as restricted root access over
240 .Sy NFS Ns ).
241 The file is held open until the association is removed. It is not actually
242 accessed until the block device is used, so it will never be written to if the
243 block device is only opened read-only.
244 .Pp
245 Note that the filename may appear as "?" if it is not possible to resolve the
246 path in the current context (for example, if it's an NFS path in a non-global
247 zone).
248 .It Ar file
249 Display the block device associated with
250 .Sy file .
251 .It Ar raw_key_file
252 Path to a file of the appropriate length, in bits, to use as a raw symmetric
253 encryption key.
254 .It Ar token_key
255 PKCS#11 token object in the format:
256 .Pp
257 .Ar token_name Ns : Ns Ar manufacturer_id Ns : Ns Ar serial_number Ns : Ns Ar key_label
258 .Pp
259 All but the key label are optional and can be empty. For example, to specify a
260 token object with only its key label
261 .Sy MylofiKey ,
262 use:
263 .Pp
264 .Fl T Ar ::: Ns Ar MylofiKey
265 .It Ar wrapped_key_file
266 Path to file containing a symmetric encryption key wrapped by the RSA private
267 key specified by
268 .Fl T .
269 .El
270 .Sh ENVIRONMENT
271 See
272 .Xr environ 5
273 for descriptions of the following environment variables
274 that affect the execution of
275 .Nm
276 :
277 .Sy LC_CTYPE ,
278 .Sy LC_MESSAGES
279 and
280 .Sy NLSPATH .
281 .Sh EXIT STATUS
282 The following exit values are returned:
283 .Bl -tag -width Ds
284 .It Sy 0
285 Successful completion.
286 .It Sy >0
287 An error occurred.
288 .El
289 .Sh EXAMPLES
290 .Bl -tag -width Ds
291 .It Sy Example 1 No Mounting an Existing CD-ROM Image
292 You should ensure that Solaris understands the image before creating the
293 .Sy CD .
294 .Sy lofi
295 allows you to mount the image and see if it works.
296 .Pp
297 This example mounts an existing
298 .Sy CD-ROM
299 image
300 .Pf ( Sy sparc.iso Ns ),
301 of the
302 .Sy Red Hat 6.0 CD
303 which was downloaded from the Internet. It was created
304 with the
305 .Sy mkisofs
306 utility from the Internet.
307 .Pp
308 Use
309 .Nm
310 to attach a block device to it:
311 .Bd -literal
312 # lofiadm -a /home/mike_s/RH6.0/sparc.iso
313 /dev/lofi/1
314 .Ed
315 .Pp
316 .Nm
317 picks the device and prints the device name to the standard
318 output. You can run
319 .Nm
320 again by issuing the following command:
321 .Bd -literal
322 # lofiadm
323 Block Device File Options
324 /dev/lofi/1 /home/mike_s/RH6.0/sparc.iso -
325 .Ed
326 .Pp
327 Or, you can give it one name and ask for the other, by issuing the following
328 command:
329 .Bd -literal
330 # lofiadm /dev/lofi/1
331 /home/mike_s/RH6.0/sparc.iso
332 .Ed
333 .Pp
334 Use the
335 .Xr mount 1M
336 command to mount the image:
337 .Bd -literal
338 # mount -F hsfs -o ro /dev/lofi/1 /mnt
339 .Ed
340 .Pp
341 Check to ensure that Solaris understands the image:
342 .Bd -literal
343 # df -k /mnt
344 Filesystem kbytes used avail capacity Mounted on
345 /dev/lofi/1 512418 512418 0 100% /mnt
346 # ls /mnt
347 \&./ RedHat/ doc/ ls-lR rr_moved/
348 \&../ TRANS.TBL dosutils/ ls-lR.gz sbin@
349 \&.buildlog bin@ etc@ misc/ tmp/
350 COPYING boot/ images/ mnt/ usr@
351 README boot.cat* kernels/ modules/
352 RPM-PGP-KEY dev@ lib@ proc/
353 .Ed
354 .Pp
355 Solaris can mount the CD-ROM image, and understand the filenames. The image was
356 created properly, and you can now create the
357 .Sy CD-ROM
358 with confidence.
359 .Pp
360 As a final step, unmount and detach the images:
361 .Bd -literal
362 # umount /mnt
363 # lofiadm -d /dev/lofi/1
364 # lofiadm
365 Block Device File Options
366 .Ed
367 .It Sy Example 2 No Mounting a Floppy Image
368 This is similar to the first example.
369 .Pp
370 Using
371 .Sy lofi
372 to help you mount files that contain floppy images is helpful
373 if a floppy disk contains a file that you need, but the machine which you are
374 on does not have a floppy drive. It is also helpful if you do not want to take
375 the time to use the
376 .Sy dd
377 command to copy the image to a floppy.
378 .Pp
379 This is an example of getting to
380 .Sy MDB
381 floppy for Solaris on an x86 platform:
382 .Bd -literal
383 # lofiadm -a /export/s28/MDB_s28x_wos/latest/boot.3
384 /dev/lofi/1
385 # mount -F pcfs /dev/lofi/1 /mnt
386 # ls /mnt
387 \&./ COMMENT.BAT* RC.D/ SOLARIS.MAP*
388 \&../ IDENT* REPLACE.BAT* X/
389 APPEND.BAT* MAKEDIR.BAT* SOLARIS/
390 # umount /mnt
391 # lofiadm -d /export/s28/MDB_s28x_wos/latest/boot.3
392 .Ed
393 .It Sy Example 3 No Making a Sy UFS No Filesystem on a File
394 Making a
395 .Sy UFS
396 filesystem on a file can be useful, particularly if a test
397 suite requires a scratch filesystem. It can be painful (or annoying) to have to
398 repartition a disk just for the test suite, but you do not have to. You can
399 .Sy newfs
400 a file with
401 .Sy lofi .
402 .Pp
403 Create the file:
404 .Bd -literal
405 # mkfile 35m /export/home/test
406 .Ed
407 .Pp
408 Attach it to a block device. You also get the character device that
409 .Sy newfs
410 requires, so
411 .Sy newfs
412 that:
413 .Bd -literal
414 # lofiadm -a /export/home/test
415 /dev/lofi/1
416 # newfs /dev/rlofi/1
417 newfs: construct a new file system /dev/rlofi/1: (y/n)? y
418 /dev/rlofi/1: 71638 sectors in 119 cylinders of 1 tracks, 602 sectors
419 35.0MB in 8 cyl groups (16 c/g, 4.70MB/g, 2240 i/g)
420 super-block backups (for fsck -F ufs -o b=#) at:
421 32, 9664, 19296, 28928, 38560, 48192, 57824, 67456,
422 .Ed
423 .Pp
424 Note that
425 .Sy ufs
426 might not be able to use the entire file. Mount and use the filesystem:
427 .Bd -literal
428 # mount /dev/lofi/1 /mnt
429 # df -k /mnt
430 Filesystem kbytes used avail capacity Mounted on
431 /dev/lofi/1 33455 9 30101 1% /mnt
432 # ls /mnt
433 \&./ ../ lost+found/
434 # umount /mnt
435 # lofiadm -d /dev/lofi/1
436 .Ed
437 .It Sy Example 4 No Creating a PC (FAT) File System on a Unix File
438 The following series of commands creates a
439 .Sy FAT
440 file system on a Unix file. The file is associated with a block device created by
441 .Nm
442 .
443 .Bd -literal
444 # mkfile 10M /export/test/testfs
445 # lofiadm -a /export/test testfs
446 /dev/lofi/1
447 .Ed
448 .Pp
449 Note use of
450 .Sy rlofi ,
451 not
452 .Sy lofi ,
453 in following command.
454 .Bd -literal
455 # mkfs -F pcfs -o nofdisk,size=20480 /dev/rlofi/1
456 Construct a new FAT file system on /dev/rlofi/1: (y/n)? y
457 # mount -F pcfs /dev/lofi/1 /mnt
458 # cd /mnt
459 # df -k .
460 Filesystem kbytes used avail capacity Mounted on
461 /dev/lofi/1 10142 0 10142 0% /mnt
462 .Ed
463 .It Sy Example 5 No Compressing an Existing CD-ROM Image
464 The following example illustrates compressing an existing CD-ROM image
465 .Pf ( Sy solaris.iso Ns ),
466 verifying that the image is compressed, and then uncompressing it.
467 .Bd -literal
468 # lofiadm -C gzip /export/home/solaris.iso
469 .Ed
470 .Pp
471 Use
472 .Nm
473 to attach a block device to it:
474 .Bd -literal
475 # lofiadm -a /export/home/solaris.iso
476 /dev/lofi/1
477 .Ed
478 .Pp
479 Check if the mapped image is compressed:
480 .Bd -literal
481 # lofiadm
482 Block Device File Options
483 /dev/lofi/1 /export/home/solaris.iso Compressed(gzip)
484 /dev/lofi/2 /export/home/regular.iso -
485 .Ed
486 .Pp
487 Unmap the compressed image and uncompress it:
488 .Bd -literal
489 # lofiadm -d /dev/lofi/1
490 # lofiadm -U /export/home/solaris.iso
491 .Ed
492 .It Sy Example 6 No Creating an Encrypted UFS File System on a File
493 This example is similar to the example of making a UFS filesystem on a file,
494 above.
495 .Pp
496 Create the file:
497 .Bd -literal
498 # mkfile 35m /export/home/test
499 .Ed
500 .Pp
501 Attach the file to a block device and specify that the file image is encrypted.
502 As a result of this command, you obtain the character device, which is
503 subsequently used by
504 .Sy newfs :
505 .Bd -literal
506 # lofiadm -c aes-256-cbc -a /export/home/secrets
507 Enter passphrase: My-M0th3r;l0v3s_m3+4lw4ys! (not echoed)
508 Re-enter passphrase: My-M0th3r;l0v3s_m3+4lw4ys! (not echoed)
509 /dev/lofi/1
511 # newfs /dev/rlofi/1
512 newfs: construct a new file system /dev/rlofi/1: (y/n)? y
513 /dev/rlofi/1: 71638 sectors in 119 cylinders of 1 tracks, 602 sectors
514 35.0MB in 8 cyl groups (16 c/g, 4.70MB/g, 2240 i/g)
515 super-block backups (for fsck -F ufs -o b=#) at:
516 32, 9664, 19296, 28928, 38560, 48192, 57824, 67456,
517 .Ed
518 .Pp
519 The mapped file system shows that encryption is enabled:
520 .Bd -literal
521 # lofiadm
522 Block Device File Options
523 /dev/lofi/1 /export/home/secrets Encrypted
524 .Ed
525 .Pp
526 Mount and use the filesystem:
527 .Bd -literal
528 # mount /dev/lofi/1 /mnt
529 # cp moms_secret_*_recipe /mnt
530 # ls /mnt
531 \&./ moms_secret_cookie_recipe moms_secret_soup_recipe
532 \&../ moms_secret_fudge_recipe moms_secret_stuffing_recipe
533 lost+found/ moms_secret_meatloaf_recipe moms_secret_waffle_recipe
534 # umount /mnt
535 # lofiadm -d /dev/lofi/1
536 .Ed
537 .Pp
538 Subsequent attempts to map the filesystem with the wrong key or the wrong
539 encryption algorithm will fail:
540 .Bd -literal
541 # lofiadm -c blowfish-cbc -a /export/home/secrets\fR
542 Enter passphrase: mommy (not echoed)
543 Re-enter passphrase: mommy (not echoed)
544 lofiadm: could not map file /root/lofi: Invalid argument
545 # lofiadm
546 Block Device File Options
547 #
548 .Ed
549 .Pp
550 Attempts to map the filesystem without encryption will succeed, however
551 attempts to mount and use the filesystem will fail:
552 .Bd -literal
553 # lofiadm -a /export/home/secrets
554 /dev/lofi/1
555 # lofiadm
556 Block Device File Options
557 /dev/lofi/1 /export/home/secrets -
558 # mount /dev/lofi/1 /mnt
559 mount: /dev/lofi/1 is not this fstype
560 #
561 .Ed
562 .El
563 .Sh SEE ALSO
564 .Xr fdisk 1M ,
565 .Xr format 1M ,
566 .Xr fsck 1M ,
567 .Xr mount 1M ,
568 .Xr mount_ufs 1M ,
569 .Xr newfs 1M ,
570 .Xr attributes 5 ,
571 .Xr lofi 7D ,
572 .Xr lofs 7FS
573 .Sh NOTES
574 Just as you would not directly access a disk device that has mounted file
575 systems, you should not access a file associated with a block device except
576 through the
577 .Sy lofi
578 file driver. It might also be appropriate to ensure that
579 the file has appropriate permissions to prevent such access.
580 .Pp
581 The abilities of
582 .Nm
583 , and who can use them, are controlled by the
584 permissions of
585 .Pa /dev/lofictl .
586 Read-access allows query operations, such as
587 listing all the associations. Write-access is required to do any state-changing
588 operations, like adding an association. As shipped,
589 .Pa /dev/lofictl
590 is owned by
591 .Sy root ,
592 in group
593 .Sy sys ,
594 and mode
595 .Sy 0644 ,
596 so all users can do query operations but only root can change anything.
597 The administrator can give users write-access, allowing them to add or
598 delete associations, but that is very likely a security hole and should
599 probably only be given to a trusted group.
600 .Pp
601 When mounting a filesystem image, take care to use appropriate mount options.
602 In particular, the
603 .Sy nosuid
604 mount option might be appropriate for
605 .Sy UFS
606 images whose origin is unknown. Also, some options might not be useful or
607 appropriate, like
608 .Sy logging
609 or
610 .Sy forcedirectio
611 for
612 .Sy UFS .
613 For compatibility purposes, a raw device is also exported along with the block
614 device. For example,
615 .Xr newfs 1M
616 requires one.
617 .Pp
618 The output of
619 .Nm
620 (without arguments) might change in future releases.