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