1 '\" te
2 .\" Copyright 2013 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
4 .\" 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.
5 .\" 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
6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH LOFIADM 1M "Aug 28, 2013"
8 .SH NAME
9 lofiadm \- administer files available as block devices through lofi
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBlofiadm\fR [\fB-r\fR] \fB-a\fR \fIfile\fR [\fIdevice\fR]
14 .fi
15
16 .LP
17 .nf
18 \fBlofiadm\fR [\fB-r\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
19 .fi
20
21 .LP
22 .nf
23 \fBlofiadm\fR [\fB-r\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-k\fR \fIraw_key_file\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
24 .fi
25
26 .LP
27 .nf
28 \fBlofiadm\fR [\fB-r\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-T\fR \fItoken_key\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
29 .fi
30
31 .LP
32 .nf
33 \fBlofiadm\fR [\fB-r\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-T\fR \fItoken_key\fR
34 \fB-k\fR \fIwrapped_key_file\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
35 .fi
36
37 .LP
38 .nf
43 .nf
44 \fBlofiadm\fR \fB-C\fR \fIalgorithm\fR [\fB-s\fR \fIsegment_size\fR] \fIfile\fR
45 .fi
46
47 .LP
48 .nf
49 \fBlofiadm\fR \fB-d\fR \fIfile\fR | \fIdevice\fR
50 .fi
51
52 .LP
53 .nf
54 \fBlofiadm\fR \fB-U\fR \fIfile\fR
55 .fi
56
57 .LP
58 .nf
59 \fBlofiadm\fR [ \fIfile\fR | \fIdevice\fR]
60 .fi
61
62 .SH DESCRIPTION
63 .sp
64 .LP
65 \fBlofiadm\fR administers \fBlofi\fR, the loopback file driver. \fBlofi\fR
66 allows a file to be associated with a block device. That file can then be
67 accessed through the block device. This is useful when the file contains an
68 image of some filesystem (such as a floppy or \fBCD-ROM\fR image), because the
69 block device can then be used with the normal system utilities for mounting,
70 checking or repairing filesystems. See \fBfsck\fR(1M) and \fBmount\fR(1M).
71 .sp
72 .LP
73 Use \fBlofiadm\fR to add a file as a loopback device, remove such an
74 association, or print information about the current associations.
75 .sp
76 .LP
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
81 In the global zone, \fBlofiadm\fR can be used on both the global
82 zone devices and all devices owned by other non-global zones on the system.
83 .sp
84 .SH OPTIONS
85 .sp
86 .LP
87 The following options are supported:
88 .sp
89 .ne 2
90 .na
91 \fB\fB-a\fR \fIfile\fR [\fIdevice\fR]\fR
92 .ad
93 .sp .6
94 .RS 4n
95 Add \fIfile\fR as a block device.
96 .sp
97 If \fIdevice\fR is not specified, an available device is picked.
98 .sp
99 If \fIdevice\fR is specified, \fBlofiadm\fR attempts to assign it to
100 \fIfile\fR. \fIdevice\fR must be available or \fBlofiadm\fR will fail. The
101 ability to specify a device is provided for use in scripts that wish to
102 reestablish a particular set of associations.
103 .RE
104
105 .sp
120 \fIlzma\fR stands for the LZMA (Lempel-Ziv-Markov) compression algorithm.
121 .sp
122 Note that you cannot write to a compressed file, nor can you mount a compressed
123 file read/write.
124 .RE
125
126 .sp
127 .ne 2
128 .na
129 \fB\fB-d\fR \fIfile\fR | \fIdevice\fR\fR
130 .ad
131 .sp .6
132 .RS 4n
133 Remove an association by \fIfile\fR or \fIdevice\fR name, if the associated
134 block device is not busy, and deallocates the block device.
135 .RE
136
137 .sp
138 .ne 2
139 .na
140 \fB\fB-r\fR
141 .ad
142 .sp .6
143 .RS 4n
144 If the \fB-r\fR option is specified before the \fB-a\fR option, the
145 \fIdevice\fR will be opened read-only.
146 .RE
147
148 .sp
149 .ne 2
150 .na
151 \fB\fB-s\fR \fIsegment_size\fR\fR
152 .ad
153 .sp .6
154 .RS 4n
155 The segment size to use to divide the file being compressed. \fIsegment_size\fR
156 can be an integer multiple of 512.
157 .RE
158
159 .sp
204 .sp .6
205 .RS 4n
206 The key in a PKCS#11 token to use for the encryption or for unwrapping the key
207 file.
208 .sp
209 If \fB-k\fR is also specified, \fB-T\fR identifies the unwrapping key, which
210 must be an RSA private key.
211 .RE
212
213 .sp
214 .ne 2
215 .na
216 \fB\fB-e\fR\fR
217 .ad
218 .sp .6
219 .RS 4n
220 Generate an ephemeral symmetric encryption key.
221 .RE
222
223 .SH OPERANDS
224 .sp
225 .LP
226 The following operands are supported:
227 .sp
228 .ne 2
229 .na
230 \fB\fIcrypto_algorithm\fR\fR
231 .ad
232 .sp .6
233 .RS 4n
234 One of: \fBaes-128-cbc\fR, \fBaes-192-cbc\fR, \fBaes-256-cbc\fR,
235 \fBdes3-cbc\fR, \fBblowfish-cbc\fR.
236 .RE
237
238 .sp
239 .ne 2
240 .na
241 \fB\fIdevice\fR\fR
242 .ad
243 .sp .6
244 .RS 4n
703 .LP
704 Attempts to map the filesystem without encryption will succeed, however
705 attempts to mount and use the filesystem will fail:
706
707 .sp
708 .in +2
709 .nf
710 # \fBlofiadm -a /export/home/secrets\fR
711 /dev/lofi/1
712 # \fBlofiadm\fR
713 Block Device File Options
714 /dev/lofi/1 /export/home/secrets -
715 # \fBmount /dev/lofi/1 /mnt\fR
716 mount: /dev/lofi/1 is not this fstype
717 #
718 .fi
719 .in -2
720 .sp
721
722 .SH ENVIRONMENT VARIABLES
723 .sp
724 .LP
725 See \fBenviron\fR(5) for descriptions of the following environment variables
726 that affect the execution of \fBlofiadm\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR
727 and \fBNLSPATH\fR.
728 .SH EXIT STATUS
729 .sp
730 .LP
731 The following exit values are returned:
732 .sp
733 .ne 2
734 .na
735 \fB\fB0\fR\fR
736 .ad
737 .sp .6
738 .RS 4n
739 Successful completion.
740 .RE
741
742 .sp
743 .ne 2
744 .na
745 \fB\fB>0\fR\fR
746 .ad
747 .sp .6
748 .RS 4n
749 An error occurred.
750 .RE
751
752 .SH SEE ALSO
753 .sp
754 .LP
755 \fBfsck\fR(1M), \fBmount\fR(1M), \fBmount_ufs\fR(1M), \fBnewfs\fR(1M),
756 \fBattributes\fR(5), \fBlofi\fR(7D), \fBlofs\fR(7FS)
757 .SH NOTES
758 .sp
759 .LP
760 Just as you would not directly access a disk device that has mounted file
761 systems, you should not access a file associated with a block device except
762 through the \fBlofi\fR file driver. It might also be appropriate to ensure that
763 the file has appropriate permissions to prevent such access.
764 .sp
765 .LP
766 The abilities of \fBlofiadm\fR, and who can use them, are controlled by the
767 permissions of \fB/dev/lofictl\fR. Read-access allows query operations, such as
768 listing all the associations. Write-access is required to do any state-changing
769 operations, like adding an association. As shipped, \fB/dev/lofictl\fR is owned
770 by \fBroot\fR, in group \fBsys\fR, and mode \fB0644\fR, so all users can do
771 query operations but only root can change anything. The administrator can give
772 users write-access, allowing them to add or delete associations, but that is
773 very likely a security hole and should probably only be given to a trusted
774 group.
775 .sp
776 .LP
777 When mounting a filesystem image, take care to use appropriate mount options.
778 In particular, the \fBnosuid\fR mount option might be appropriate for \fBUFS\fR
|
1 '\" te
2 .\" Copyright (c) 2016 Andrey Sokolov
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 .TH LOFIADM 1M "Aug 28, 2013"
9 .SH NAME
10 lofiadm \- administer files available as block devices through lofi
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fBlofiadm\fR [\fB-r\fR] \fB-a\fR \fIfile\fR [\fIdevice\fR]
15 .fi
16
17 .LP
18 .nf
19 \fBlofiadm\fR [\fB-r\fR] [\fB-o\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
20 .fi
21
22 .LP
23 .nf
24 \fBlofiadm\fR [\fB-r\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-k\fR \fIraw_key_file\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
25 .fi
26
27 .LP
28 .nf
29 \fBlofiadm\fR [\fB-r\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-T\fR \fItoken_key\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
30 .fi
31
32 .LP
33 .nf
34 \fBlofiadm\fR [\fB-r\fR] \fB-c\fR \fIcrypto_algorithm\fR \fB-T\fR \fItoken_key\fR
35 \fB-k\fR \fIwrapped_key_file\fR \fB-a\fR \fIfile\fR [\fIdevice\fR]
36 .fi
37
38 .LP
39 .nf
44 .nf
45 \fBlofiadm\fR \fB-C\fR \fIalgorithm\fR [\fB-s\fR \fIsegment_size\fR] \fIfile\fR
46 .fi
47
48 .LP
49 .nf
50 \fBlofiadm\fR \fB-d\fR \fIfile\fR | \fIdevice\fR
51 .fi
52
53 .LP
54 .nf
55 \fBlofiadm\fR \fB-U\fR \fIfile\fR
56 .fi
57
58 .LP
59 .nf
60 \fBlofiadm\fR [ \fIfile\fR | \fIdevice\fR]
61 .fi
62
63 .SH DESCRIPTION
64 .LP
65 \fBlofiadm\fR administers \fBlofi\fR, the loopback file driver. \fBlofi\fR
66 allows a file to be associated with a block device. That file can then be
67 accessed through the block device. This is useful when the file contains an
68 image of some filesystem (such as a floppy or \fBCD-ROM\fR image), because the
69 block device can then be used with the normal system utilities for mounting,
70 checking or repairing filesystems. See \fBfsck\fR(1M) and \fBmount\fR(1M).
71 .sp
72 .LP
73 Use \fBlofiadm\fR to add a file as a loopback device, remove such an
74 association, or print information about the current associations.
75 .sp
76 .LP
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
81 In the global zone, \fBlofiadm\fR can be used on both the global
82 zone devices and all devices owned by other non-global zones on the system.
83 .sp
84 .SH OPTIONS
85 .LP
86 The following options are supported:
87 .sp
88 .ne 2
89 .na
90 \fB\fB-a\fR \fIfile\fR [\fIdevice\fR]\fR
91 .ad
92 .sp .6
93 .RS 4n
94 Add \fIfile\fR as a block device.
95 .sp
96 If \fIdevice\fR is not specified, an available device is picked.
97 .sp
98 If \fIdevice\fR is specified, \fBlofiadm\fR attempts to assign it to
99 \fIfile\fR. \fIdevice\fR must be available or \fBlofiadm\fR will fail. The
100 ability to specify a device is provided for use in scripts that wish to
101 reestablish a particular set of associations.
102 .RE
103
104 .sp
119 \fIlzma\fR stands for the LZMA (Lempel-Ziv-Markov) compression algorithm.
120 .sp
121 Note that you cannot write to a compressed file, nor can you mount a compressed
122 file read/write.
123 .RE
124
125 .sp
126 .ne 2
127 .na
128 \fB\fB-d\fR \fIfile\fR | \fIdevice\fR\fR
129 .ad
130 .sp .6
131 .RS 4n
132 Remove an association by \fIfile\fR or \fIdevice\fR name, if the associated
133 block device is not busy, and deallocates the block device.
134 .RE
135
136 .sp
137 .ne 2
138 .na
139 \fB\fB-o\fR
140 .ad
141 .sp .6
142 .RS 4n
143 If the \fB-o\fR option is specified lofiadm will prompt for a passphrase once.
144 .RE
145
146 .sp
147 .ne 2
148 .na
149 \fB\fB-r\fR
150 .ad
151 .sp .6
152 .RS 4n
153 If the \fB-r\fR option is specified before the \fB-a\fR option, the
154 \fIdevice\fR will be opened read-only.
155 .RE
156
157 .sp
158 .ne 2
159 .na
160 \fB\fB-s\fR \fIsegment_size\fR\fR
161 .ad
162 .sp .6
163 .RS 4n
164 The segment size to use to divide the file being compressed. \fIsegment_size\fR
165 can be an integer multiple of 512.
166 .RE
167
168 .sp
213 .sp .6
214 .RS 4n
215 The key in a PKCS#11 token to use for the encryption or for unwrapping the key
216 file.
217 .sp
218 If \fB-k\fR is also specified, \fB-T\fR identifies the unwrapping key, which
219 must be an RSA private key.
220 .RE
221
222 .sp
223 .ne 2
224 .na
225 \fB\fB-e\fR\fR
226 .ad
227 .sp .6
228 .RS 4n
229 Generate an ephemeral symmetric encryption key.
230 .RE
231
232 .SH OPERANDS
233 .LP
234 The following operands are supported:
235 .sp
236 .ne 2
237 .na
238 \fB\fIcrypto_algorithm\fR\fR
239 .ad
240 .sp .6
241 .RS 4n
242 One of: \fBaes-128-cbc\fR, \fBaes-192-cbc\fR, \fBaes-256-cbc\fR,
243 \fBdes3-cbc\fR, \fBblowfish-cbc\fR.
244 .RE
245
246 .sp
247 .ne 2
248 .na
249 \fB\fIdevice\fR\fR
250 .ad
251 .sp .6
252 .RS 4n
711 .LP
712 Attempts to map the filesystem without encryption will succeed, however
713 attempts to mount and use the filesystem will fail:
714
715 .sp
716 .in +2
717 .nf
718 # \fBlofiadm -a /export/home/secrets\fR
719 /dev/lofi/1
720 # \fBlofiadm\fR
721 Block Device File Options
722 /dev/lofi/1 /export/home/secrets -
723 # \fBmount /dev/lofi/1 /mnt\fR
724 mount: /dev/lofi/1 is not this fstype
725 #
726 .fi
727 .in -2
728 .sp
729
730 .SH ENVIRONMENT VARIABLES
731 .LP
732 See \fBenviron\fR(5) for descriptions of the following environment variables
733 that affect the execution of \fBlofiadm\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR
734 and \fBNLSPATH\fR.
735 .SH EXIT STATUS
736 .LP
737 The following exit values are returned:
738 .sp
739 .ne 2
740 .na
741 \fB\fB0\fR\fR
742 .ad
743 .sp .6
744 .RS 4n
745 Successful completion.
746 .RE
747
748 .sp
749 .ne 2
750 .na
751 \fB\fB>0\fR\fR
752 .ad
753 .sp .6
754 .RS 4n
755 An error occurred.
756 .RE
757
758 .SH SEE ALSO
759 .LP
760 \fBfsck\fR(1M), \fBmount\fR(1M), \fBmount_ufs\fR(1M), \fBnewfs\fR(1M),
761 \fBattributes\fR(5), \fBlofi\fR(7D), \fBlofs\fR(7FS)
762 .SH NOTES
763 .LP
764 Just as you would not directly access a disk device that has mounted file
765 systems, you should not access a file associated with a block device except
766 through the \fBlofi\fR file driver. It might also be appropriate to ensure that
767 the file has appropriate permissions to prevent such access.
768 .sp
769 .LP
770 The abilities of \fBlofiadm\fR, and who can use them, are controlled by the
771 permissions of \fB/dev/lofictl\fR. Read-access allows query operations, such as
772 listing all the associations. Write-access is required to do any state-changing
773 operations, like adding an association. As shipped, \fB/dev/lofictl\fR is owned
774 by \fBroot\fR, in group \fBsys\fR, and mode \fB0644\fR, so all users can do
775 query operations but only root can change anything. The administrator can give
776 users write-access, allowing them to add or delete associations, but that is
777 very likely a security hole and should probably only be given to a trusted
778 group.
779 .sp
780 .LP
781 When mounting a filesystem image, take care to use appropriate mount options.
782 In particular, the \fBnosuid\fR mount option might be appropriate for \fBUFS\fR
|