xref: /freebsd/sbin/mdconfig/mdconfig.8 (revision 13de33a5dc2304b13d595d75d48c51793958474f)
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.\" Copyright (c) 2000
5.\"	Poul-Henning Kamp  All rights reserved.
6.\"
7.\" This code is derived from software contributed to Berkeley by
8.\" the Systems Programming Group of the University of Utah Computer
9.\" Science Department.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\" 1. Redistributions of source code must retain the above copyright
15.\"    notice, this list of conditions and the following disclaimer.
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\"    notice, this list of conditions and the following disclaimer in the
18.\"    documentation and/or other materials provided with the distribution.
19.\" 3. All advertising materials mentioning features or use of this software
20.\"    must display the following acknowledgement:
21.\"	This product includes software developed by the University of
22.\"	California, Berkeley and its contributors.
23.\" 4. Neither the name of the University nor the names of its contributors
24.\"    may be used to endorse or promote products derived from this software
25.\"    without specific prior written permission.
26.\"
27.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
28.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
29.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
30.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
31.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
32.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
33.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
34.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
35.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
36.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37.\" SUCH DAMAGE.
38.\"
39.\"     @(#)vnconfig.8	8.1 (Berkeley) 6/5/93
40.\" from: src/usr.sbin/vnconfig/vnconfig.8,v 1.19 2000/12/27 15:30:29
41.\"
42.\" $FreeBSD$
43.\"
44.Dd November 30, 2013
45.Dt MDCONFIG 8
46.Os
47.Sh NAME
48.Nm mdconfig
49.Nd configure and enable memory disks
50.Sh SYNOPSIS
51.Nm
52.Fl a
53.Fl t Ar type
54.Op Fl n
55.Oo Fl o Oo Cm no Oc Ns Ar option Oc ...
56.Op Fl f Ar file
57.Op Fl s Ar size
58.Op Fl S Ar sectorsize
59.Op Fl u Ar unit
60.Op Fl x Ar sectors/track
61.Op Fl y Ar heads/cylinder
62.Nm
63.Fl d
64.Fl u Ar unit
65.Op Fl o Oo Cm no Oc Ns Ar force
66.Nm
67.Fl r
68.Fl u Ar unit
69.Fl s Ar size
70.Op Fl o Oo Cm no Oc Ns Ar force
71.Nm
72.Fl l
73.Op Fl n
74.Op Fl v
75.Op Fl f Ar file
76.Op Fl u Ar unit
77.Nm
78.Ar file
79.Sh DESCRIPTION
80The
81.Nm
82utility configures and enables
83.Xr md 4
84devices.
85.Pp
86Options indicate an action to be performed:
87.Bl -tag -width indent
88.It Fl a
89Attach a memory disk.
90This will configure and attach a memory disk with the
91parameters specified and attach it to the system.
92If the
93.Fl u Ar unit
94option is not provided, the newly created device name will be printed on stdout.
95.It Fl d
96Detach a memory disk from the system and release all resources.
97.It Fl r
98Resize a memory disk.
99.It Fl t Ar type
100Select the type of the memory disk.
101.Bl -tag -width "malloc"
102.It Cm malloc
103Storage for this type of memory disk is allocated with
104.Xr malloc 9 .
105This limits the size to the malloc bucket limit in the kernel.
106If the
107.Fl o Cm reserve
108option is not set, creating and filling a large
109malloc-backed memory disk is a very easy way to
110panic a system.
111.It Cm vnode
112A file specified with
113.Fl f Ar file
114becomes the backing store for this memory disk.
115.It Cm swap
116Storage for this type of memory disk is allocated from buffer
117memory.
118Pages get pushed out to swap when the system is under memory
119pressure, otherwise they stay in the operating memory.
120Using
121.Cm swap
122backing is generally preferred instead of using
123.Cm malloc
124backing.
125.It Cm null
126Bitsink; all writes do nothing, all reads return zeroes.
127.El
128.It Fl f Ar file
129Filename to use for the vnode type memory disk.
130The
131.Fl a
132and
133.Fl t Ar vnode
134options are implied if not specified.
135.It Fl l
136List configured devices.
137If given with
138.Fl u ,
139display details about that particular device.
140If given with
141.Fl f Ar file ,
142display
143.Xr md 4
144device names of which
145.Ar file
146is used as the backing store.
147If both of
148.Fl u
149and
150.Fl f
151options are specified,
152display devices which match the two conditions.
153If the
154.Fl v
155option is specified, show all details.
156.It Fl n
157When printing
158.Xr md 4
159device names, print only the unit number without the
160.Xr md 4
161prefix.
162.It Fl s Ar size
163Size of the memory disk.
164.Ar Size
165is the number of 512 byte sectors unless suffixed with a
166.Cm b , k , m , g ,
167or
168.Cm t
169which
170denotes byte, kilobyte, megabyte, gigabyte and terabyte respectively.
171The
172.Fl a
173and
174.Fl t Ar swap
175options are implied if not specified.
176.It Fl S Ar sectorsize
177Sectorsize to use for the memory disk, in bytes.
178.It Fl x Ar sectors/track
179See the description of the
180.Fl y
181option below.
182.It Fl y Ar heads/cylinder
183For
184.Cm malloc
185or
186.Cm vnode
187backed devices, the
188.Fl x
189and
190.Fl y
191options can be used to specify a synthetic geometry.
192This is useful for constructing bootable images for later download to
193other devices.
194.It Fl o Oo Cm no Oc Ns Ar option
195Set or reset options.
196.Bl -tag -width indent
197.It Oo Cm no Oc Ns Cm async
198For
199.Cm vnode
200backed devices: avoid
201.Dv IO_SYNC
202for increased performance but
203at the risk of deadlocking the entire kernel.
204.It Oo Cm no Oc Ns Cm reserve
205Allocate and reserve all needed storage from the start, rather than as needed.
206.It Oo Cm no Oc Ns Cm cluster
207Enable clustering on this disk.
208.It Oo Cm no Oc Ns Cm compress
209Enable/disable compression features to reduce memory usage.
210.It Oo Cm no Oc Ns Cm force
211Disable/enable extra sanity checks to prevent the user from doing something
212that might adversely affect the system.
213.It Oo Cm no Oc Ns Cm readonly
214Enable/disable readonly mode.
215.El
216.It Fl u Ar unit
217Request a specific unit number or device name for the
218.Xr md 4
219device instead of automatic allocation.
220If a device name is specified, it must be start with
221.Dq md
222followed by the unit number.
223.El
224.Pp
225The last form,
226.Nm
227.Ar file ,
228is provided for convenience as an abbreviation of
229.Nm
230.Fl a
231.Fl t Ar vnode
232.Fl f Ar file .
233.Sh EXAMPLES
234Create a 4 megabyte
235.Xr malloc 9
236backed memory disk.
237The name of the allocated unit will be printed on stdout, such as
238.Dq Li md3 :
239.Pp
240.Dl mdconfig -a -t malloc -s 4m
241.Pp
242Create a disk named
243.Pa /dev/md4
244with
245.Pa /tmp/boot.flp
246as backing storage:
247.Pp
248.Dl mdconfig -a -t vnode -f /tmp/boot.flp -u md4
249.Pp
250Detach and free all resources used by
251.Pa /dev/md4 :
252.Pp
253.Dl mdconfig -d -u md4
254.Pp
255Create a 128MByte swap backed disk, initialize an
256.Xr ffs 7
257file system on it, and mount it on
258.Pa /tmp :
259.Bd -literal -offset indent
260mdconfig -a -t swap -s 128M -u md10
261newfs -U /dev/md10
262mount /dev/md10 /tmp
263chmod 1777 /tmp
264.Ed
265.Pp
266Create a 5MB file-backed disk
267.Po Fl a
268and
269.Fl t Ar vnode
270are implied
271.Pc :
272.Bd -literal -offset indent
273dd if=/dev/zero of=somebackingfile bs=1k count=5k
274mdconfig -f somebackingfile -u md0
275bsdlabel -w md0 auto
276newfs md0c
277mount /dev/md0c /mnt
278.Ed
279.Pp
280Create an
281.Xr md 4
282device out of an ISO 9660 CD image file
283.Po Fl a
284and
285.Fl t Ar vnode
286are implied
287.Pc , using the first available
288.Xr md 4
289device, and then mount the new memory disk:
290.Bd -literal -offset indent
291mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt
292.Pp
293.Ed
294Create a file-backed device from a hard disk image that begins
295with 512K of raw header information.
296.Xr gnop 8
297is used to skip over the header information, positioning
298.Pa md1.nop
299to the start of the filesystem in the image.
300.Bd -literal -offset indent
301mdconfig -f diskimage.img -u md1
302gnop create -o 512K md1
303mount /dev/md1.nop /mnt
304.Ed
305.Sh SEE ALSO
306.Xr md 4 ,
307.Xr ffs 7 ,
308.Xr bsdlabel 8 ,
309.Xr fdisk 8 ,
310.Xr mdmfs 8 ,
311.Xr malloc 9
312.Sh HISTORY
313The
314.Nm
315utility first appeared in
316.Fx 5.0
317as a cleaner replacement for the
318.Xr vn 4
319and
320.Xr vnconfig 8
321combo.
322.Sh AUTHORS
323The
324.Nm
325utility was written by
326.An Poul-Henning Kamp
327.Aq phk@FreeBSD.org .
328