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