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. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)vnconfig.8  8.1 (Berkeley) 6/5/93
  36 .\" from: src/usr.sbin/vnconfig/vnconfig.8,v 1.19 2000/12/27 15:30:29
  37 .\"
  38 .\" $FreeBSD$
  39 .\"
  40 .Dd August 28, 2017
  41 .Dt MDCONFIG 8
  42 .Os
  43 .Sh NAME
  44 .Nm mdconfig
  45 .Nd create and control memory disks
  46 .Sh SYNOPSIS
  47 .Nm
  48 .Fl a
  49 .Fl t Ar type
  50 .Op Fl n
  51 .Oo Fl o Oo Cm no Oc Ns Ar option Oc ...
  52 .Op Fl f Ar file
  53 .Op Fl s Ar size
  54 .Op Fl S Ar sectorsize
  55 .Op Fl u Ar unit
  56 .Op Fl x Ar sectors/track
  57 .Op Fl y Ar heads/cylinder
  58 .Op Fl L Ar label
  59 .Nm
  60 .Fl d
  61 .Fl u Ar unit
  62 .Op Fl o Oo Cm no Oc Ns Ar force
  63 .Nm
  64 .Fl r
  65 .Fl u Ar unit
  66 .Fl s Ar size
  67 .Op Fl o Oo Cm no Oc Ns Ar force
  68 .Nm
  69 .Fl l
  70 .Op Fl n
  71 .Op Fl v
  72 .Op Fl f Ar file
  73 .Op Fl u Ar unit
  74 .Nm
  75 .Ar file
  76 .Sh DESCRIPTION
  77 The
  78 .Nm
  79 utility creates and controls
  80 .Xr md 4
  81 devices.
  82 .Pp
  83 Options indicate an action to be performed:
  84 .Bl -tag -width indent
  85 .It Fl a
  86 Attach a memory disk.
  87 This will configure and attach a memory disk with the
  88 parameters specified and attach it to the system.
  89 If the
  90 .Fl u Ar unit
  91 option is not provided, the newly created device name will be printed on stdout.
  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 the 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 .It Cm null
 123 Bitsink; all writes do nothing, all reads return zeroes.
 124 .El
 125 .It Fl f Ar file
 126 Filename to use for the vnode type memory disk.
 127 The
 128 .Fl a
 129 and
 130 .Fl t Ar vnode
 131 options are implied if not specified.
 132 .It Fl l
 133 List configured devices.
 134 If given with
 135 .Fl u ,
 136 display details about that particular device.
 137 If given with
 138 .Fl f Ar file ,
 139 display
 140 .Xr md 4
 141 device names of which
 142 .Ar file
 143 is used as the backing store.
 144 If both of
 145 .Fl u
 146 and
 147 .Fl f
 148 options are specified,
 149 display devices which match the two conditions.
 150 If the
 151 .Fl v
 152 option is specified, show all details.
 153 .It Fl n
 154 When printing
 155 .Xr md 4
 156 device names, print only the unit number without the
 157 .Xr md 4
 158 prefix.
 159 .It Fl s Ar size
 160 Size of the memory disk.
 161 .Ar Size
 162 is the number of 512 byte sectors unless suffixed with a
 163 .Cm b , k , m , g , t ,
 164 or
 165 .Cm p
 166 which
 167 denotes byte, kilobyte, megabyte, gigabyte, terabyte and petabyte respectively.
 168 When used without the
 169 .Fl r
 170 option, the
 171 .Fl a
 172 and
 173 .Fl t Ar swap
 174 options are implied if not specified.
 175 .It Fl S Ar sectorsize
 176 Sectorsize to use for the memory disk, in bytes.
 177 .It Fl x Ar sectors/track
 178 See the description of the
 179 .Fl y
 180 option below.
 181 .It Fl y Ar heads/cylinder
 182 For
 183 .Cm malloc
 184 or
 185 .Cm vnode
 186 backed devices, the
 187 .Fl x
 188 and
 189 .Fl y
 190 options can be used to specify a synthetic geometry.
 191 This is useful for constructing bootable images for later download to
 192 other devices.
 193 .It Fl L Ar label
 194 Associate a label (arbitrary string) with the new memory disk.
 195 The label can then be inspected with
 196 .Bd -literal -offset indent
 197 .Nm Fl l v
 198 .Ed
 199 .It Fl o Oo Cm no Oc Ns Ar option
 200 Set or reset options.
 201 .Bl -tag -width indent
 202 .It Oo Cm no Oc Ns Cm async
 203 For
 204 .Cm vnode
 205 backed devices: avoid
 206 .Dv IO_SYNC
 207 for increased performance but
 208 at the risk of deadlocking the entire kernel.
 209 .It Oo Cm no Oc Ns Cm reserve
 210 Allocate and reserve all needed storage from the start, rather than as needed.
 211 .It Oo Cm no Oc Ns Cm cluster
 212 Enable clustering on this disk.
 213 .It Oo Cm no Oc Ns Cm compress
 214 Enable/disable compression features to reduce memory usage.
 215 .It Oo Cm no Oc Ns Cm force
 216 Disable/enable extra sanity checks to prevent the user from doing something
 217 that might adversely affect the system.
 218 This can be used with the
 219 .Fl d
 220 flag to forcibly destroy an
 221 .Xr md 4
 222 disk that is still in use.
 223 .It Oo Cm no Oc Ns Cm readonly
 224 Enable/disable readonly mode.
 225 .It Oo Cm no Oc Ns Cm verify
 226 For
 227 .Cm vnode
 228 backed devices: enable/disable requesting verification of the
 229 file used for backing store.
 230 The type of verification depends on which security features are available.
 231 One example of verification is testing file integrity with
 232 checksums or cryptographic signatures.
 233 .El
 234 .It Fl u Ar unit
 235 Request a specific unit number or device name for the
 236 .Xr md 4
 237 device instead of automatic allocation.
 238 If a device name is specified, it must be start with
 239 .Dq md
 240 followed by the unit number.
 241 .El
 242 .Pp
 243 The last form,
 244 .Nm
 245 .Ar file ,
 246 is provided for convenience as an abbreviation of
 247 .Nm
 248 .Fl a
 249 .Fl t Ar vnode
 250 .Fl f Ar file .
 251 .Sh EXAMPLES
 252 Create a disk with
 253 .Pa /tmp/boot.flp
 254 as backing storage.
 255 The name of the allocated unit will be printed on stdout, such as
 256 .Dq Li md0 :
 257 .Bd -literal -offset indent
 258 mdconfig /tmp/boot.flp
 259 .Ed
 260 .Pp
 261 Create a 1 gigabyte swap backed memory disk named
 262 .Dq Li md3 :
 263 .Bd -literal -offset indent
 264 mdconfig -s 1g -u md3
 265 .Ed
 266 .Pp
 267 Detach and free all resources used by
 268 .Pa /dev/md3 :
 269 .Bd -literal -offset indent
 270 mdconfig -du md3
 271 .Ed
 272 .Pp
 273 Show detailed information on current memory disks:
 274 .Bd -literal -offset indent
 275 mdconfig -lv
 276 .Ed
 277 .Pp
 278 Resize the
 279 .Dq Li md3
 280 memory disk to 2 gigabytes:
 281 .Bd -literal -offset indent
 282 mdconfig -rs 2g -u md3
 283 .Ed
 284 .Pp
 285 Create a 1 gigabyte swap backed disk, initialize an
 286 .Xr ffs 7
 287 file system on it, and mount it on
 288 .Pa /tmp :
 289 .Bd -literal -offset indent
 290 mdconfig -s 1g -u md10
 291 newfs -U /dev/md10
 292 mount /dev/md10 /tmp
 293 chmod 1777 /tmp
 294 .Ed
 295 .Pp
 296 Create a memory disk out of an ISO 9660 CD image file,
 297 using the first available
 298 .Xr md 4
 299 device, and then mount it:
 300 .Bd -literal -offset indent
 301 mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt
 302 .Ed
 303 .Pp
 304 Create a file-backed device from a hard disk image that begins
 305 with 512K of raw header information.
 306 .Xr gnop 8
 307 is used to skip over the header information, positioning
 308 .Pa md1.nop
 309 to the start of the filesystem in the image.
 310 .Bd -literal -offset indent
 311 mdconfig -u md1 -f diskimage.img
 312 gnop create -o 512K md1
 313 mount /dev/md1.nop /mnt
 314 .Ed
 315 .Sh SEE ALSO
 316 .Xr open 2 ,
 317 .Xr md 4 ,
 318 .Xr ffs 7 ,
 319 .Xr gpart 8 ,
 320 .Xr mdmfs 8 ,
 321 .Xr malloc 9
 322 .Sh HISTORY
 323 The
 324 .Nm
 325 utility first appeared in
 326 .Fx 5.0
 327 as a cleaner replacement for the
 328 .Xr vn 4
 329 and
 330 .Xr vnconfig 8
 331 combo.
 332 .Sh AUTHORS
 333 The
 334 .Nm
 335 utility was written by
 336 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .