vnconfig.8: Describe autocloning & improve markup
[dragonfly.git] / usr.sbin / vnconfig / vnconfig.8
CommitLineData
984263bc
MD
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 $
daa51328 39.\" $DragonFly: src/usr.sbin/vnconfig/vnconfig.8,v 1.10 2008/07/27 22:36:01 thomas Exp $
984263bc 40.\"
77a09e6f 41.Dd September 28, 2009
984263bc
MD
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
daa51328
TN
50.Op Fl s Ar options
51.Op Fl r Ar options
984263bc
MD
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
daa51328
TN
58.Op Fl s Ar options
59.Op Fl r Ar options
984263bc 60.Op Fl f Ar config_file
30c1fde0
CT
61.Nm
62.Fl l
63.Op Ar special_file Ar ...
984263bc
MD
64.Sh DESCRIPTION
65The
66.Nm
30c1fde0 67command configures, enables and lists vnode pseudo disk devices.
984263bc
MD
68The first form of the command will associate the special file
69.Ar special_file
70with the regular file
71.Ar regular_file
72allowing the latter to be accessed as though it were a disk.
73Hence a regular file within the filesystem can be used for swapping
77a09e6f
TN
74or can contain a filesystem that is mounted in the name space.
75If you want to use swap backing store for your device instead of a file,
76you can leave
daa51328
TN
77.Ar regular_file
78out and specify the size of the block device
d2469606 79with the
c0ae5e43 80.Fl S
d2469606 81option.
984263bc
MD
82.Pp
83Options indicate an action to be performed:
84.Bl -tag -width indent
85.It Fl a
86Read a command file and performs the
87specified actions for each device/file pair.
88.It Fl c
89Configure the device.
90If successful, references to
91.Ar special_file
92will access the contents of
93.Ar regular_file .
77a09e6f
TN
94.Pp
95A
96.Nm vn
97device is autocloned if
98.Ar special_file
99is given as
100.Pa vn ,
101the name of the resulting device is printed on stdout.
984263bc
MD
102.It Fl d
103Disable (if possible) the specified feature.
104.It Fl e
105Configure the device and enables any
106.Ar feature
107that was specified.
108If no feature was specified,
109.Fl e
110is the same as
111.Fl c .
112.It Fl f Ar config_file
77a09e6f
TN
113Specify configuration file.
114Default is
115.Pa /etc/vntab .
984263bc
MD
116.It Fl g
117Fiddle global options.
daa51328 118.It Fl l Ar special_file Ar ...
77a09e6f
TN
119List the
120.Nm vn
121devices and indicate which ones are in use.
30c1fde0
CT
122If a
123.Ar special_file
124list is given, only those devices will be described.
daa51328 125.It Fl r Ar options
984263bc 126Reset
daa51328
TN
127.Ar options ,
128which is a comma separated string of options.
129The list of allowed options and their meanings are:
77a09e6f
TN
130.Bl -tag -width "reserve"
131.It Cm reserve
132Pre-reserve the blocks underlying the file or swap backing store.
133Currently only works for swap backing store.
134This option also disables on-the-fly freeing of
984263bc
MD
135the underlying backing store (for example, when you remove a large file).
136Use this option if you wish to avoid long-term fragmentation of the backing
77a09e6f
TN
137store.
138Also note that when this option is used, the initial contents of the
139backing store may contain garbage rather than zeros.
140It may even be possible to
141recover the prior contents of a swap-backed
142.Nm vn
143across a reboot if the
144.Nm vn
145device
984263bc 146is configured before any swap is allocated by the system.
77a09e6f
TN
147.It Cm follow
148Debug flow in the
984263bc
MD
149.Xr vn 4
150driver.
77a09e6f
TN
151.It Cm debug
152Debug data in the
984263bc
MD
153.Xr vn 4
154driver.
77a09e6f
TN
155.It Cm io
156Debug
157.Tn I/O
158in the
984263bc
MD
159.Xr vn 4
160driver.
77a09e6f
TN
161.It Cm all
162Turn on all options.
163.It Cm none
164Turn off all options.
984263bc 165.El
daa51328 166.It Fl s Ar options
984263bc 167Set
daa51328
TN
168.Ar options ,
169which is a comma separated string of options.
170The list of allowed options and their meanings are the same as for the
984263bc
MD
171.Fl r
172option.
173.It Fl S Xo
174.Sm off
175.Ar value
176.Es \&{ \&}
177.En Cm k , m , g , t
178.Sm on
179.Xc
77a09e6f
TN
180If no regular file is specified,
181.Nm vn
182will use swap for backing store.
183This option specifies the size of the device.
184For example,
daa51328
TN
185.Sq 23m
186for
1d1a622a
SK
18723 megabytes.
188In the absence of a size modifier,
189.Cm m
190is implied.
77a09e6f
TN
191The
192.Nm vn
193device will round the size up to a machine page boundary.
194Filesystems up to 7.9 terabytes are supported.
195When specified along with
984263bc 196a regular file, this option overrides the regular file's size insofar as
77a09e6f
TN
197.Nm vn
198is concerned.
984263bc 199.It Fl T
77a09e6f
TN
200When a regular file is specified,
201.Nm
202will
daa51328
TN
203.Fn ftruncate
204the file to length 0 first.
d2469606 205Normally you should also specify the
c0ae5e43 206.Fl S
d2469606 207option to set the size of the file.
984263bc 208This option also creates the file if it did not previously exist.
d2469606 209This option is only meaningful if the
c0ae5e43 210.Fl S
d2469606 211option has been specified.
984263bc 212.It Fl Z
77a09e6f
TN
213When a regular file is specified,
214.Nm
215will zero the contents of the file to
216ensure that all blocks have been allocated by the filesystem.
217This option is only meaningful if the
c0ae5e43 218.Fl S
d2469606 219option has been specified.
984263bc
MD
220.It Fl u
221Disable and ``unconfigure'' the device.
222.It Fl v
223Print messages to stdout describing actions taken.
224.El
225.Pp
226If no action option is given,
227.Fl c
228is assumed.
229.Pp
230The
231.Ar feature
232argument specifies a feature that can be enabled via the
233.Fl e
234option:
235.Bl -tag -width indent
77a09e6f 236.It Cm swap
984263bc
MD
237Swapping is enabled on the special file.
238See
239.Xr swapon 2 .
77a09e6f 240.It Cm mountro= Ns Ar mount_point
984263bc
MD
241The special file is mounted read-only on
242.Ar mount_point .
243See
244.Xr mount 2 .
77a09e6f 245.It Cm mountrw= Ns Ar mount_point
984263bc
MD
246The special file is mounted read-write on
247.Ar mount_point .
248See
249.Xr mount 2 .
77a09e6f
TN
250.It Cm mount= Ns Ar mount_point
251Same as
252.Cm mountrw= Ns Ar mount_point .
984263bc
MD
253.El
254.Pp
255A configuration file contains one line per device/file pair in the form:
256.Bd -literal
77a09e6f 257 special_file regular_file [feature]
984263bc
MD
258.Ed
259.Pp
260where fields are separated by white space.
261The previously described action options serve to configure, enable,
262disable or unconfigure all devices in the configuration file.
263.Sh FILES
264.Bl -tag -width /etc/vntab -compact
265.It Pa /etc/vntab
266default configuration file for
267.Fl a
268option
269.El
270.Sh EXAMPLES
77a09e6f
TN
271.Dl vnconfig vn /tmp/diskimage
272.Pp
273Configures an autocloned vnode disk,
274the name of the resulting device is printed, e.g.\&
275.Pa vn4 .
276.Pp
f5ba7fbd 277.Dl vnconfig vn0 /tmp/diskimage
984263bc
MD
278.Pp
279Configures the vnode disk
f5ba7fbd 280.Pa vn0 .
984263bc 281.Pp
f5ba7fbd 282.Dl vnconfig -e vn0 /var/swapfile swap
984263bc
MD
283.Pp
284Configures
f5ba7fbd 285.Pa vn0
984263bc
MD
286and enables swapping on it.
287.Pp
288.Dl vnconfig -c -v /dev/vn0 cdimage.iso
289.Dl mount -t cd9660 -o ro /dev/vn0 /mnt
290.Pp
291Mount an ISO9660 CD image file.
292.Pp
293.Dl umount /mnt
f5ba7fbd 294.Dl vnconfig -u vn0
984263bc
MD
295.Pp
296Unmount the CD image file.
297.Pp
f5ba7fbd 298.Dl vnconfig -d vn0 myfilesystem mount=/mnt
984263bc
MD
299.Pp
300Unmounts (disables)
f5ba7fbd 301.Pa vn0 .
984263bc
MD
302.Pp
303.Dl vnconfig -ae
304.Pp
305Configures and enables all devices specified in
306.Pa /etc/vntab .
307.Pp
45e80934 308.Dl vnconfig -c vn0 somebackingfile
f5ba7fbd
SW
309.Dl disklabel -r -w vn0s0 auto
310.Dl disklabel -e vn0s0
984263bc 311.Pp
77a09e6f
TN
312Is an example of how to configure a file-backed
313.Nm vn
314disk with a disk label
315and to initialize and then edit the label.
316Once you create the label, you
317can partition your
318.Nm vn
319disk and, for example, create a filesystem on one of the partitions.
320If you are using a file as backing store, it may be possible
321to recover your
322.Nm vn
323disk after a crash by
324.Nm Ns 'ing
325the same file again and using the
326.Nm vn
327configuration already stored in the file rather than
328relabeling and recreating the filesystem.
329It is even possible to
330.Xr fsck 8
331the
332.Nm vn
333partitions that previously contained filesystems.
984263bc 334.Pp
45e80934 335.Dl vnconfig -e -s reserve -S 400m vn1
f5ba7fbd
SW
336.Dl disklabel -r -w vn1s0 auto
337.Dl newfs /dev/vn1s0
338.Dl mount /dev/vn1s0 /usr/obj
984263bc 339.Pp
77a09e6f
TN
340Is an example of a swap-backed
341.Nm vn
342disk configuration.
343This example assumes
984263bc
MD
344that you have at least 400 megabytes of swap free (and hopefully much more).
345The swap space is pre-reserved in order to maintain maximum performance.
daa51328
TN
346We then label the disk, newfs it, and mount it as
347.Pa /usr/obj .
77a09e6f
TN
348Swap-backed
349.Nm vn
350devices are recoverable after a crash if you (A) use the
351.Cm reserve
352option, and if
984263bc 353(B) the same swap is reserved as was the last time, meaning that such
77a09e6f
TN
354.Nm Ns 's
355would have to be run in your
356.Xr rc.local 8 .
357In general, though, you only use swap-backed
358.Nm vn
359devices to hold information you don't mind losing on every reboot.
984263bc
MD
360.Sh SEE ALSO
361.Xr mount 2 ,
362.Xr swapon 2 ,
363.Xr unmount 2 ,
364.Xr vn 4