1a13a36e8ef47ac10018aede81bbbb83160bdab7
[dragonfly.git] / usr.sbin / vnconfig / vnconfig.8
1 .\" Copyright (c) 1993 University of Utah.
2 .\" Copyright (c) 1980, 1989, 1991, 1993
3 .\"     The Regents of the University of California.  All rights reserved.
4 .\"
5 .\" This code is derived from software contributed to Berkeley by
6 .\" the Systems Programming Group of the University of Utah Computer
7 .\" Science Department.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\"    notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\"    notice, this list of conditions and the following disclaimer in the
16 .\"    documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\"    must display the following acknowledgement:
19 .\"     This product includes software developed by the University of
20 .\"     California, Berkeley and its contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\"    may be used to endorse or promote products derived from this software
23 .\"    without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" SUCH DAMAGE.
36 .\"
37 .\"     @(#)vnconfig.8  8.1 (Berkeley) 6/5/93
38 .\" $FreeBSD: src/usr.sbin/vnconfig/vnconfig.8,v 1.14.2.8 2003/01/04 22:35:53 keramida Exp $
39 .\" $DragonFly: src/usr.sbin/vnconfig/vnconfig.8,v 1.10 2008/07/27 22:36:01 thomas Exp $
40 .\"
41 .Dd January 30, 2008
42 .Dt VNCONFIG 8
43 .Os
44 .Sh NAME
45 .Nm vnconfig
46 .Nd configure and enable vnode disks
47 .Sh SYNOPSIS
48 .Nm
49 .Op Fl cdeguvTZ
50 .Op Fl s Ar options
51 .Op Fl r Ar options
52 .Op Fl S Ar value
53 .Ar special_file Op Ar regular_file
54 .Op Ar feature
55 .Nm
56 .Fl a
57 .Op Fl cdeguv
58 .Op Fl s Ar options
59 .Op Fl r Ar options
60 .Op Fl f Ar config_file
61 .Nm
62 .Fl l
63 .Op Ar special_file Ar ...
64 .Sh DESCRIPTION
65 The
66 .Nm
67 command configures, enables and lists vnode pseudo disk devices.
68 The first form of the command will associate the special file
69 .Ar special_file
70 with the regular file
71 .Ar regular_file
72 allowing the latter to be accessed as though it were a disk.
73 Hence a regular file within the filesystem can be used for swapping
74 or can contain a filesystem that is mounted in the name space.  If you
75 want to use swap backing store for your device instead of a file, you
76 can leave
77 .Ar regular_file
78 out and specify the size of the block device
79 with the
80 .Fl S
81 option.
82 .Pp
83 Options indicate an action to be performed:
84 .Bl -tag -width indent
85 .It Fl a
86 Read a command file and performs the
87 specified actions for each device/file pair.
88 .It Fl c
89 Configure the device.
90 If successful, references to
91 .Ar special_file
92 will access the contents of
93 .Ar regular_file .
94 .It Fl d
95 Disable (if possible) the specified feature.
96 .It Fl e
97 Configure the device and enables any
98 .Ar feature
99 that was specified.
100 If no feature was specified,
101 .Fl e
102 is the same as
103 .Fl c .
104 .It Fl f Ar config_file
105 Use
106 .Ar config_file
107 as an alternate config file.
108 .It Fl g
109 Fiddle global options.
110 .It Fl l Ar special_file Ar ...
111 List the VN devices and indicate which ones are in use.
112 If a
113 .Ar special_file
114 list is given, only those devices will be described.
115 .It Fl r Ar options
116 Reset
117 .Ar options ,
118 which is a comma separated string of options.
119 The list of allowed options and their meanings are:
120 .Bl -tag -width "follow"
121 .It Ar reserve
122 Pre-reserve the blocks underlying the file or swap backing store.  Currently only
123 works for swap backing store.  This option also disables on-the-fly freeing of
124 the underlying backing store (for example, when you remove a large file).
125 Use this option if you wish to avoid long-term fragmentation of the backing
126 store.  Also note that when this option is used, the initial contents of the
127 backing store may contain garbage rather than zeros.  It may even be possible to
128 recover the prior contents of a swap-backed VN across a reboot if the VN device
129 is configured before any swap is allocated by the system.
130 .It Ar follow
131 debug flow in the
132 .Xr vn 4
133 driver.
134 .It Ar debug
135 debug data in the
136 .Xr vn 4
137 driver.
138 .It Ar io
139 debug I/O in the
140 .Xr vn 4
141 driver.
142 .It Ar all
143 turn on all options.
144 .It Ar none
145 turn off all options.
146 .El
147 .It Fl s Ar options
148 Set
149 .Ar options ,
150 which is a comma separated string of options.
151 The list of allowed options and their meanings are the same as for the
152 .Fl r
153 option.
154 .It Fl S Xo
155 .Sm off
156 .Ar value
157 .Es \&{ \&}
158 .En Cm k , m , g , t
159 .Sm on
160 .Xc
161 If no regular file is specified, VN will use swap for backing store.
162 This option specifies the size of the device.  For example,
163 .Sq 23m
164 for
165 23 megabytes.
166 In the absence of a size modifier,
167 .Cm m
168 is implied.
169 The VN device will round the size up to a machine page boundary.
170 Filesystems up to 7.9 terabytes are supported.  When specified along with
171 a regular file, this option overrides the regular file's size insofar as
172 VN is concerned.
173 .It Fl T
174 When a regular file is specified, VN will
175 .Fn ftruncate
176 the file to length 0 first.
177 Normally you should also specify the
178 .Fl S
179 option to set the size of the file.
180 This option also creates the file if it did not previously exist.
181 This option is only meaningful if the
182 .Fl S
183 option has been specified.
184 .It Fl Z
185 When a regular file is specified, VN will zero the contents of the file to
186 ensure that all blocks have been allocated by the filesystem.  This option is
187 only meaningful if the
188 .Fl S
189 option has been specified.
190 .It Fl u
191 Disable and ``unconfigure'' the device.
192 .It Fl v
193 Print messages to stdout describing actions taken.
194 .El
195 .Pp
196 If no action option is given,
197 .Fl c
198 is assumed.
199 .Pp
200 The
201 .Ar feature
202 argument specifies a feature that can be enabled via the
203 .Fl e
204 option:
205 .Bl -tag -width indent
206 .It Dv swap
207 Swapping is enabled on the special file.
208 See
209 .Xr swapon 2 .
210 .It Dv mountro Ns = Ns Pa mount_point
211 The special file is mounted read-only on
212 .Ar mount_point .
213 See
214 .Xr mount 2 .
215 .It Dv mountrw Ns = Ns Pa mount_point
216 The special file is mounted read-write on
217 .Ar mount_point .
218 See
219 .Xr mount 2 .
220 .It Dv mount Ns = Ns Pa mount_point
221 Same as ``mountrw=''.
222 .El
223 .Pp
224 A configuration file contains one line per device/file pair in the form:
225 .Bd -literal
226         special_file    regular_file    [ feature ]
227 .Ed
228 .Pp
229 where fields are separated by white space.
230 The previously described action options serve to configure, enable,
231 disable or unconfigure all devices in the configuration file.
232 .Sh FILES
233 .Bl -tag -width /etc/vntab -compact
234 .It Pa /etc/vntab
235 default configuration file for
236 .Fl a
237 option
238 .El
239 .Sh EXAMPLES
240 .Dl vnconfig vn0 /tmp/diskimage
241 .Pp
242 Configures the vnode disk
243 .Pa vn0 .
244 .Pp
245 .Dl vnconfig -e vn0 /var/swapfile swap
246 .Pp
247 Configures
248 .Pa vn0
249 and enables swapping on it.
250 .Pp
251 .Dl vnconfig -c -v /dev/vn0 cdimage.iso
252 .Dl mount -t cd9660 -o ro /dev/vn0 /mnt
253 .Pp
254 Mount an ISO9660 CD image file.
255 .Pp
256 .Dl umount /mnt
257 .Dl vnconfig -u vn0
258 .Pp
259 Unmount the CD image file.
260 .Pp
261 .Dl vnconfig -d vn0 myfilesystem mount=/mnt
262 .Pp
263 Unmounts (disables)
264 .Pa vn0 .
265 .Pp
266 .Dl vnconfig -ae
267 .Pp
268 Configures and enables all devices specified in
269 .Pa /etc/vntab .
270 .Pp
271 .Dl vnconfig -c vn0 somebackingfile
272 .Dl disklabel -r -w vn0s0 auto
273 .Dl disklabel -e vn0s0
274 .Pp
275 Is an example of how to configure a file-backed VN disk with a disk label
276 and to initialize and then edit the label.  Once you create the label, you
277 can partition your VN disk and, for example, create a filesystem on one of
278 the partitions.  If you are using a file as backing store, it may be possible
279 to recover your VN disk after a crash by vnconfig'ing the same file again
280 and using the VN configuration already stored in the file rather than
281 relabeling and recreating the filesystem.  It is even possible to fsck the
282 VN partitions that previously contained filesystems.
283 .Pp
284 .Dl vnconfig -e -s reserve -S 400m vn1
285 .Dl disklabel -r -w vn1s0 auto
286 .Dl newfs /dev/vn1s0
287 .Dl mount /dev/vn1s0 /usr/obj
288 .Pp
289 Is an example of a swap-backed VN disk configuration.  This example assumes
290 that you have at least 400 megabytes of swap free (and hopefully much more).
291 The swap space is pre-reserved in order to maintain maximum performance.
292 We then label the disk, newfs it, and mount it as
293 .Pa /usr/obj .
294 Swap-backed VN
295 devices are recoverable after a crash if you (A) use the reserve option, and if
296 (B) the same swap is reserved as was the last time, meaning that such
297 vnconfig's would have to be run in your rc.local.  In general, though, you
298 only use swap-backed VN devices to hold information you don't mind losing
299 on every reboot.
300 .Sh SEE ALSO
301 .Xr mount 2 ,
302 .Xr swapon 2 ,
303 .Xr unmount 2 ,
304 .Xr vn 4