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