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