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 December 21, 2018
  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 cache
 210 For
 211 .Cm vnode
 212 backed devices: enable/disable caching of data in system caches.
 213 The default is to not cache.
 214 .Pp
 215 Accesses via the device are converted to accesses via the vnode.
 216 The caching policy for the vnode is used initially.
 217 This is normally to cache.
 218 This caching policy is retained if the
 219 .Cm cache
 220 option is used.
 221 Otherwise, caching is limited
 222 by releasing data from caches soon after each access.
 223 The release has the same semantics as the
 224 .Dv POSIX_FADV_DONTNEED
 225 feature of
 226 .Xr posix_fadvise 2 .
 227 The result is that with normal (non-zfs) caching,
 228 buffers are released from the buffer cache soon after they are constructed,
 229 but their data is kept in the page cache at lower priority.
 230 .Pp
 231 The
 232 .Cm cache
 233 option tends to waste memory by giving unwanted double caching,
 234 but it saves time if there is memory to spare.
 235 .It Oo Cm no Oc Ns Cm reserve
 236 Allocate and reserve all needed storage from the start, rather than as needed.
 237 .It Oo Cm no Oc Ns Cm cluster
 238 Enable clustering on this disk.
 239 .It Oo Cm no Oc Ns Cm compress
 240 Enable/disable compression features to reduce memory usage.
 241 .It Oo Cm no Oc Ns Cm force
 242 Disable/enable extra sanity checks to prevent the user from doing something
 243 that might adversely affect the system.
 244 This can be used with the
 245 .Fl d
 246 flag to forcibly destroy an
 247 .Xr md 4
 248 disk that is still in use.
 249 .It Oo Cm no Oc Ns Cm readonly
 250 Enable/disable readonly mode.
 251 .It Oo Cm no Oc Ns Cm verify
 252 For
 253 .Cm vnode
 254 backed devices: enable/disable requesting verification of the
 255 file used for backing store.
 256 The type of verification depends on which security features are available.
 257 One example of verification is testing file integrity with
 258 checksums or cryptographic signatures.
 259 .El
 260 .It Fl u Ar unit
 261 Request a specific unit number or device name for the
 262 .Xr md 4
 263 device instead of automatic allocation.
 264 If a device name is specified, it must be start with
 265 .Dq md
 266 followed by the unit number.
 267 .El
 268 .Pp
 269 The last form,
 270 .Nm
 271 .Ar file ,
 272 is provided for convenience as an abbreviation of
 273 .Nm
 274 .Fl a
 275 .Fl t Ar vnode
 276 .Fl f Ar file .
 277 .Sh EXAMPLES
 278 Create a disk with
 279 .Pa /tmp/boot.flp
 280 as backing storage.
 281 The name of the allocated unit will be printed on stdout, such as
 282 .Dq Li md0 :
 283 .Bd -literal -offset indent
 284 mdconfig /tmp/boot.flp
 285 .Ed
 286 .Pp
 287 Create a 1 gigabyte swap backed memory disk named
 288 .Dq Li md3 :
 289 .Bd -literal -offset indent
 290 mdconfig -s 1g -u md3
 291 .Ed
 292 .Pp
 293 Detach and free all resources used by
 294 .Pa /dev/md3 :
 295 .Bd -literal -offset indent
 296 mdconfig -du md3
 297 .Ed
 298 .Pp
 299 Show detailed information on current memory disks:
 300 .Bd -literal -offset indent
 301 mdconfig -lv
 302 .Ed
 303 .Pp
 304 Resize the
 305 .Dq Li md3
 306 memory disk to 2 gigabytes:
 307 .Bd -literal -offset indent
 308 mdconfig -rs 2g -u md3
 309 .Ed
 310 .Pp
 311 Create a 1 gigabyte swap backed disk, initialize an
 312 .Xr ffs 7
 313 file system on it, and mount it on
 314 .Pa /tmp :
 315 .Bd -literal -offset indent
 316 mdconfig -s 1g -u md10
 317 newfs -U /dev/md10
 318 mount /dev/md10 /tmp
 319 chmod 1777 /tmp
 320 .Ed
 321 .Pp
 322 Create a memory disk out of an ISO 9660 CD image file,
 323 using the first available
 324 .Xr md 4
 325 device, and then mount it:
 326 .Bd -literal -offset indent
 327 mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt
 328 .Ed
 329 .Pp
 330 Create a file-backed device from a hard disk image that begins
 331 with 512K of raw header information.
 332 .Xr gnop 8
 333 is used to skip over the header information, positioning
 334 .Pa md1.nop
 335 to the start of the filesystem in the image.
 336 .Bd -literal -offset indent
 337 mdconfig -u md1 -f diskimage.img
 338 gnop create -o 512K md1
 339 mount /dev/md1.nop /mnt
 340 .Ed
 341 .Sh SEE ALSO
 342 .Xr open 2 ,
 343 .Xr md 4 ,
 344 .Xr ffs 7 ,
 345 .Xr gpart 8 ,
 346 .Xr mdmfs 8 ,
 347 .Xr malloc 9
 348 .Sh HISTORY
 349 The
 350 .Nm
 351 utility first appeared in
 352 .Fx 5.0
 353 as a cleaner replacement for the
 354 .Xr vn 4
 355 and
 356 .Xr vnconfig 8
 357 combo.
 358 .Sh AUTHORS
 359 The
 360 .Nm
 361 utility was written by
 362 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .