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 27, 2021
  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 Cm 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 Cm 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 mustdealloc
 250 For
 251 .Cm vnode
 252 backed devices: detect whether hole-punching is supported by the underlying file
 253 system.
 254 If the file system supports hole-punching, then to handle a
 255 .Dv BIO_DELETE
 256 request, some or all of the request's operation range may be turned into a hole
 257 in the file used for backing store.
 258 Any parts which are not turned into holes are zero-filled in
 259 the file.
 260 If the file system does not support
 261 hole-punching,
 262 .Dv BIO_DELETE
 263 requests to the device are not handled and will fail with
 264 .Er EOPNOTSUPP .
 265 .Pp
 266 When
 267 .Cm mustdealloc
 268 is not specified or
 269 .Oo Cm no Oc Ns Cm mustdealloc
 270 is specified, for a
 271 .Dv BIO_DELETE
 272 request, if the file system supports hole-punching, some or all of the request's
 273 operation range may be turned into a hole in the file used for backing store.
 274 Any parts which are not turned into holes are zero-filled in the file.
 275 If the file system of the vnode type memory disk does not support hole-punching,
 276 the request's operation range is zero-filled in the file.
 277 .It Oo Cm no Oc Ns Cm readonly
 278 Enable/disable readonly mode.
 279 .It Oo Cm no Oc Ns Cm verify
 280 For
 281 .Cm vnode
 282 backed devices: enable/disable requesting verification of the
 283 file used for backing store.
 284 The type of verification depends on which security features are available.
 285 One example of verification is testing file integrity with
 286 checksums or cryptographic signatures.
 287 .El
 288 .It Fl u Ar unit
 289 Request a specific unit number or device name for the
 290 .Xr md 4
 291 device instead of automatic allocation.
 292 If a device name is specified, it must start with
 293 .Dq md
 294 followed by the unit number.
 295 .El
 296 .Pp
 297 The last form,
 298 .Nm
 299 .Ar file ,
 300 is provided for convenience as an abbreviation of
 301 .Nm
 302 .Fl a
 303 .Fl t Cm vnode
 304 .Fl f Ar file .
 305 .Sh EXAMPLES
 306 Create a disk with
 307 .Pa /tmp/boot.flp
 308 as backing storage.
 309 The name of the allocated unit will be printed on stdout, such as
 310 .Dq Li md0 :
 311 .Bd -literal -offset indent
 312 mdconfig /tmp/boot.flp
 313 .Ed
 314 .Pp
 315 Create a 1 gigabyte swap backed memory disk named
 316 .Dq Li md3 :
 317 .Bd -literal -offset indent
 318 mdconfig -s 1g -u md3
 319 .Ed
 320 .Pp
 321 Detach and free all resources used by
 322 .Pa /dev/md3 :
 323 .Bd -literal -offset indent
 324 mdconfig -du md3
 325 .Ed
 326 .Pp
 327 Show detailed information on current memory disks:
 328 .Bd -literal -offset indent
 329 mdconfig -lv
 330 .Ed
 331 .Pp
 332 Resize the
 333 .Dq Li md3
 334 memory disk to 2 gigabytes:
 335 .Bd -literal -offset indent
 336 mdconfig -rs 2g -u md3
 337 .Ed
 338 .Pp
 339 Create a 1 gigabyte swap backed disk, initialize an
 340 .Xr ffs 7
 341 file system on it, and mount it on
 342 .Pa /tmp :
 343 .Bd -literal -offset indent
 344 mdconfig -s 1g -u md10
 345 newfs -U /dev/md10
 346 mount /dev/md10 /tmp
 347 chmod 1777 /tmp
 348 .Ed
 349 .Pp
 350 Create a memory disk out of an ISO 9660 CD image file,
 351 using the first available
 352 .Xr md 4
 353 device, and then mount it:
 354 .Bd -literal -offset indent
 355 mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt
 356 .Ed
 357 .Pp
 358 Create a file-backed device from a hard disk image that begins
 359 with 512K of raw header information.
 360 .Xr gnop 8
 361 is used to skip over the header information, positioning
 362 .Pa md1.nop
 363 to the start of the filesystem in the image.
 364 .Bd -literal -offset indent
 365 mdconfig -u md1 -f diskimage.img
 366 gnop create -o 512K md1
 367 mount /dev/md1.nop /mnt
 368 .Ed
 369 .Sh SEE ALSO
 370 .Xr fpathconf 2 ,
 371 .Xr fspacectl 2 ,
 372 .Xr open 2 ,
 373 .Xr md 4 ,
 374 .Xr ffs 7 ,
 375 .Xr gpart 8 ,
 376 .Xr mdmfs 8 ,
 377 .Xr malloc 9 ,
 378 .Xr vn_deallocate 9
 379 .Sh HISTORY
 380 The
 381 .Nm
 382 utility first appeared in
 383 .Fx 5.0
 384 as a cleaner replacement for the vn kernel module
 385 and the vnconfig utility combo.
 386 .Sh AUTHORS
 387 The
 388 .Nm
 389 utility was written by
 390 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .