sbin/mdconfig/mdconfig.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 .\" 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 3, 2012
  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 u Ar unit
  76 .Nm
  77 .Ar file
  78 .Sh DESCRIPTION
  79 The
  80 .Nm
  81 utility configures and enables
  82 .Xr md 4
  83 devices.
  84 .Pp
  85 Options indicate an action to be performed:
  86 .Bl -tag -width indent
  87 .It Fl a
  88 Attach a memory disk.
  89 This will configure and attach a memory disk with the
  90 parameters specified and attach it to the system.
  91 .It Fl d
  92 Detach a memory disk from the system and release all resources.
  93 .It Fl r
  94 Resize a memory disk.
  95 .It Fl t Ar type
  96 Select the type of the memory disk.
  97 .Bl -tag -width "malloc"
  98 .It Cm malloc
  99 Storage for this type of memory disk is allocated with
 100 .Xr malloc 9 .
 101 This limits the size to the malloc bucket limit in the kernel.
 102 If the
 103 .Fl o Cm reserve
 104 option is not set, creating and filling a large
 105 malloc-backed memory disk is a very easy way to
 106 panic a system.
 107 .It Cm vnode
 108 A file specified with
 109 .Fl f Ar file
 110 becomes the backing store for this memory disk.
 111 .It Cm swap
 112 Storage for this type of memory disk is allocated from buffer
 113 memory.
 114 Pages get pushed out to swap when the system is under memory
 115 pressure, otherwise they stay in the operating memory.
 116 Using
 117 .Cm swap
 118 backing is generally preferred instead of using
 119 .Cm malloc
 120 backing.
 121 .El
 122 .It Fl f Ar file
 123 Filename to use for the vnode type memory disk.
 124 The
 125 .Fl a
 126 and
 127 .Fl t Ar vnode
 128 options are implied if not specified.
 129 .It Fl l
 130 List configured devices.
 131 If given with
 132 .Fl u ,
 133 display details about that particular device.
 134 If the
 135 .Fl v
 136 option is specified, show all details.
 137 .It Fl n
 138 When printing
 139 .Xr md 4
 140 device names, print only the unit number without the
 141 .Xr md 4
 142 prefix.
 143 .It Fl s Ar size
 144 Size of the memory disk.
 145 .Ar Size
 146 is the number of 512 byte sectors unless suffixed with a
 147 .Cm b , k , m , g ,
 148 or
 149 .Cm t
 150 which
 151 denotes byte, kilobyte, megabyte, gigabyte and terabyte respectively.
 152 The
 153 .Fl a
 154 and
 155 .Fl t Ar swap
 156 options are implied if not specified.
 157 .It Fl S Ar sectorsize
 158 Sectorsize to use for the memory disk, in bytes.
 159 .It Fl x Ar sectors/track
 160 See the description of the
 161 .Fl y
 162 option below.
 163 .It Fl y Ar heads/cylinder
 164 For
 165 .Cm malloc
 166 or
 167 .Cm vnode
 168 backed devices, the
 169 .Fl x
 170 and
 171 .Fl y
 172 options can be used to specify a synthetic geometry.
 173 This is useful for constructing bootable images for later download to
 174 other devices.
 175 .It Fl o Oo Cm no Oc Ns Ar option
 176 Set or reset options.
 177 .Bl -tag -width indent
 178 .It Oo Cm no Oc Ns Cm async
 179 For
 180 .Cm vnode
 181 backed devices: avoid
 182 .Dv IO_SYNC
 183 for increased performance but
 184 at the risk of deadlocking the entire kernel.
 185 .It Oo Cm no Oc Ns Cm reserve
 186 Allocate and reserve all needed storage from the start, rather than as needed.
 187 .It Oo Cm no Oc Ns Cm cluster
 188 Enable clustering on this disk.
 189 .It Oo Cm no Oc Ns Cm compress
 190 Enable/disable compression features to reduce memory usage.
 191 .It Oo Cm no Oc Ns Cm force
 192 Disable/enable extra sanity checks to prevent the user from doing something
 193 that might adversely affect the system.
 194 .It Oo Cm no Oc Ns Cm readonly
 195 Enable/disable readonly mode.
 196 .El
 197 .It Fl u Ar unit
 198 Request a specific unit number for the
 199 .Xr md 4
 200 device instead of automatic allocation.
 201 .El
 202 .Pp
 203 The last form,
 204 .Nm
 205 .Ar file ,
 206 is provided for convenience as an abbreviation of
 207 .Nm
 208 .Fl a
 209 .Fl t Ar vnode
 210 .Fl f Ar file .
 211 .Sh EXAMPLES
 212 Create a 4 megabyte
 213 .Xr malloc 9
 214 backed memory disk.
 215 The name of the allocated unit will be printed on stdout, such as
 216 .Dq Li md3 :
 217 .Pp
 218 .Dl mdconfig -a -t malloc -s 4m
 219 .Pp
 220 Create a disk named
 221 .Pa /dev/md4
 222 with
 223 .Pa /tmp/boot.flp
 224 as backing storage:
 225 .Pp
 226 .Dl mdconfig -a -t vnode -f /tmp/boot.flp -u 4
 227 .Pp
 228 Detach and free all resources used by
 229 .Pa /dev/md4 :
 230 .Pp
 231 .Dl mdconfig -d -u 4
 232 .Pp
 233 Create a 128MByte swap backed disk, initialize an
 234 .Xr ffs 7
 235 file system on it, and mount it on
 236 .Pa /tmp :
 237 .Bd -literal -offset indent
 238 mdconfig -a -t swap -s 128M -u 10
 239 newfs -U /dev/md10
 240 mount /dev/md10 /tmp
 241 chmod 1777 /tmp
 242 .Ed
 243 .Pp
 244 Create a 5MB file-backed disk
 245 .Po Fl a
 246 and
 247 .Fl t Ar vnode
 248 are implied
 249 .Pc :
 250 .Bd -literal -offset indent
 251 dd if=/dev/zero of=somebackingfile bs=1k count=5k
 252 mdconfig -f somebackingfile -u 0
 253 bsdlabel -w md0 auto
 254 newfs md0c
 255 mount /dev/md0c /mnt
 256 .Ed
 257 .Pp
 258 Create an
 259 .Xr md 4
 260 device out of an ISO 9660 CD image file
 261 .Po Fl a
 262 and
 263 .Fl t Ar vnode
 264 are implied
 265 .Pc , using the first available
 266 .Xr md 4
 267 device, and then mount the new memory disk:
 268 .Bd -literal -offset indent
 269 mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt
 270 .Pp
 271 .Ed
 272 Create a file-backed device from a hard disk image that begins
 273 with 512K of raw header information.
 274 .Xr gnop 8
 275 is used to skip over the header information, positioning
 276 .Pa md1.nop
 277 to the start of the filesystem in the image.
 278 .Bd -literal -offset indent
 279 mdconfig -f diskimage.img -u 1
 280 gnop create -o 512K md1
 281 mount /dev/md1.nop /mnt
 282 .Ed
 283 .Sh SEE ALSO
 284 .Xr md 4 ,
 285 .Xr ffs 7 ,
 286 .Xr bsdlabel 8 ,
 287 .Xr fdisk 8 ,
 288 .Xr mdmfs 8 ,
 289 .Xr malloc 9
 290 .Sh HISTORY
 291 The
 292 .Nm
 293 utility first appeared in
 294 .Fx 5.0
 295 as a cleaner replacement for the
 296 .Xr vn 4
 297 and
 298 .Xr vnconfig 8
 299 combo.
 300 .Sh AUTHORS
 301 The
 302 .Nm
 303 utility was written by
 304 .An Poul-Henning Kamp
 305 .Aq phk@FreeBSD.org .