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