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 .Dd August 27, 2021
  39 .Dt MDCONFIG 8
  40 .Os
  41 .Sh NAME
  42 .Nm mdconfig
  43 .Nd create and control memory disks
  44 .Sh SYNOPSIS
  45 .Nm
  46 .Fl a
  47 .Fl t Ar type
  48 .Op Fl n
  49 .Oo Fl o Oo Cm no Oc Ns Ar option Oc ...
  50 .Op Fl f Ar file
  51 .Op Fl s Ar size
  52 .Op Fl S Ar sectorsize
  53 .Op Fl u Ar unit
  54 .Op Fl x Ar sectors/track
  55 .Op Fl y Ar heads/cylinder
  56 .Op Fl L Ar label
  57 .Nm
  58 .Fl d
  59 .Fl u Ar unit
  60 .Op Fl o Oo Cm no Oc Ns Ar force
  61 .Nm
  62 .Fl r
  63 .Fl u Ar unit
  64 .Fl s Ar size
  65 .Op Fl o Oo Cm no Oc Ns Ar force
  66 .Nm
  67 .Fl l
  68 .Op Fl n
  69 .Op Fl v
  70 .Op Fl f Ar file
  71 .Op Fl u Ar unit
  72 .Nm
  73 .Ar file
  74 .Sh DESCRIPTION
  75 The
  76 .Nm
  77 utility creates and controls
  78 .Xr md 4
  79 devices.
  80 .Pp
  81 Options indicate an action to be performed:
  82 .Bl -tag -width indent
  83 .It Fl a
  84 Attach a memory disk.
  85 This will configure and attach a memory disk with the
  86 parameters specified and attach it to the system.
  87 If the
  88 .Fl u Ar unit
  89 option is not provided, the newly created device name will be printed on stdout.
  90 .It Fl d
  91 Detach a memory disk from the system and release all resources.
  92 .It Fl r
  93 Resize a memory disk.
  94 .It Fl t Ar type
  95 Select the type of the memory disk.
  96 .Bl -tag -width "malloc"
  97 .It Cm malloc
  98 Storage for this type of memory disk is allocated with
  99 .Xr malloc 9 .
 100 This limits the size to the malloc bucket limit in the kernel.
 101 If the
 102 .Fl o Cm reserve
 103 option is not set, creating and filling a large
 104 malloc-backed memory disk is a very easy way to
 105 panic the system.
 106 .It Cm vnode
 107 A file specified with
 108 .Fl f Ar file
 109 becomes the backing store for this memory disk.
 110 .It Cm swap
 111 Storage for this type of memory disk is allocated from buffer
 112 memory.
 113 Pages get pushed out to swap when the system is under memory
 114 pressure, otherwise they stay in the operating memory.
 115 Using
 116 .Cm swap
 117 backing is generally preferred instead of using
 118 .Cm malloc
 119 backing.
 120 .It Cm null
 121 Bitsink; all writes do nothing, all reads return zeroes.
 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 Cm 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 , t ,
 162 or
 163 .Cm p
 164 which
 165 denotes byte, kilobyte, megabyte, gigabyte, terabyte and petabyte respectively.
 166 When used without the
 167 .Fl r
 168 option, the
 169 .Fl a
 170 and
 171 .Fl t Cm swap
 172 options are implied if not specified.
 173 .It Fl S Ar sectorsize
 174 Sectorsize to use for the memory disk, in bytes.
 175 .It Fl x Ar sectors/track
 176 See the description of the
 177 .Fl y
 178 option below.
 179 .It Fl y Ar heads/cylinder
 180 For
 181 .Cm malloc
 182 or
 183 .Cm vnode
 184 backed devices, the
 185 .Fl x
 186 and
 187 .Fl y
 188 options can be used to specify a synthetic geometry.
 189 This is useful for constructing bootable images for later download to
 190 other devices.
 191 .It Fl L Ar label
 192 Associate a label (arbitrary string) with the new memory disk.
 193 The label can then be inspected with
 194 .Bd -literal -offset indent
 195 .Nm Fl l v
 196 .Ed
 197 .It Fl o Oo Cm no Oc Ns Ar option
 198 Set or reset options.
 199 .Bl -tag -width indent
 200 .It Oo Cm no Oc Ns Cm async
 201 For
 202 .Cm vnode
 203 backed devices: avoid
 204 .Dv IO_SYNC
 205 for increased performance but
 206 at the risk of deadlocking the entire kernel.
 207 .It Oo Cm no Oc Ns Cm cache
 208 For
 209 .Cm vnode
 210 backed devices: enable/disable caching of data in system caches.
 211 The default is to not cache.
 212 .Pp
 213 Accesses via the device are converted to accesses via the vnode.
 214 The caching policy for the vnode is used initially.
 215 This is normally to cache.
 216 This caching policy is retained if the
 217 .Cm cache
 218 option is used.
 219 Otherwise, caching is limited
 220 by releasing data from caches soon after each access.
 221 The release has the same semantics as the
 222 .Dv POSIX_FADV_DONTNEED
 223 feature of
 224 .Xr posix_fadvise 2 .
 225 The result is that with normal (non-zfs) caching,
 226 buffers are released from the buffer cache soon after they are constructed,
 227 but their data is kept in the page cache at lower priority.
 228 .Pp
 229 The
 230 .Cm cache
 231 option tends to waste memory by giving unwanted double caching,
 232 but it saves time if there is memory to spare.
 233 .It Oo Cm no Oc Ns Cm reserve
 234 Allocate and reserve all needed storage from the start, rather than as needed.
 235 .It Oo Cm no Oc Ns Cm cluster
 236 Enable clustering on this disk.
 237 .It Oo Cm no Oc Ns Cm compress
 238 Enable/disable compression features to reduce memory usage.
 239 .It Oo Cm no Oc Ns Cm force
 240 Disable/enable extra sanity checks to prevent the user from doing something
 241 that might adversely affect the system.
 242 This can be used with the
 243 .Fl d
 244 flag to forcibly destroy an
 245 .Xr md 4
 246 disk that is still in use.
 247 .It Oo Cm no Oc Ns Cm mustdealloc
 248 For
 249 .Cm vnode
 250 backed devices: detect whether hole-punching is supported by the underlying file
 251 system.
 252 If the file system supports hole-punching, then to handle a
 253 .Dv BIO_DELETE
 254 request, some or all of the request's operation range may be turned into a hole
 255 in the file used for backing store.
 256 Any parts which are not turned into holes are zero-filled in
 257 the file.
 258 If the file system does not support
 259 hole-punching,
 260 .Dv BIO_DELETE
 261 requests to the device are not handled and will fail with
 262 .Er EOPNOTSUPP .
 263 .Pp
 264 When
 265 .Cm mustdealloc
 266 is not specified or
 267 .Oo Cm no Oc Ns Cm mustdealloc
 268 is specified, for a
 269 .Dv BIO_DELETE
 270 request, if the file system supports hole-punching, some or all of the request's
 271 operation range may be turned into a hole in the file used for backing store.
 272 Any parts which are not turned into holes are zero-filled in the file.
 273 If the file system of the vnode type memory disk does not support hole-punching,
 274 the request's operation range is zero-filled in the file.
 275 .It Oo Cm no Oc Ns Cm readonly
 276 Enable/disable readonly mode.
 277 .It Oo Cm no Oc Ns Cm verify
 278 For
 279 .Cm vnode
 280 backed devices: enable/disable requesting verification of the
 281 file used for backing store.
 282 The type of verification depends on which security features are available.
 283 One example of verification is testing file integrity with
 284 checksums or cryptographic signatures.
 285 .El
 286 .It Fl u Ar unit
 287 Request a specific unit number or device name for the
 288 .Xr md 4
 289 device instead of automatic allocation.
 290 If a device name is specified, it must start with
 291 .Dq md
 292 followed by the unit number.
 293 .El
 294 .Pp
 295 The last form,
 296 .Nm
 297 .Ar file ,
 298 is provided for convenience as an abbreviation of
 299 .Nm
 300 .Fl a
 301 .Fl t Cm vnode
 302 .Fl f Ar file .
 303 .Sh EXAMPLES
 304 Create a disk with
 305 .Pa /tmp/boot.flp
 306 as backing storage.
 307 The name of the allocated unit will be printed on stdout, such as
 308 .Dq Li md0 :
 309 .Bd -literal -offset indent
 310 mdconfig /tmp/boot.flp
 311 .Ed
 312 .Pp
 313 Create a 1 gigabyte swap backed memory disk named
 314 .Dq Li md3 :
 315 .Bd -literal -offset indent
 316 mdconfig -s 1g -u md3
 317 .Ed
 318 .Pp
 319 Detach and free all resources used by
 320 .Pa /dev/md3 :
 321 .Bd -literal -offset indent
 322 mdconfig -du md3
 323 .Ed
 324 .Pp
 325 Show detailed information on current memory disks:
 326 .Bd -literal -offset indent
 327 mdconfig -lv
 328 .Ed
 329 .Pp
 330 Resize the
 331 .Dq Li md3
 332 memory disk to 2 gigabytes:
 333 .Bd -literal -offset indent
 334 mdconfig -rs 2g -u md3
 335 .Ed
 336 .Pp
 337 Create a 1 gigabyte swap backed disk, initialize an
 338 .Xr ffs 7
 339 file system on it, and mount it on
 340 .Pa /tmp :
 341 .Bd -literal -offset indent
 342 mdconfig -s 1g -u md10
 343 newfs -U /dev/md10
 344 mount /dev/md10 /tmp
 345 chmod 1777 /tmp
 346 .Ed
 347 .Pp
 348 Create a memory disk out of an ISO 9660 CD image file,
 349 using the first available
 350 .Xr md 4
 351 device, and then mount it:
 352 .Bd -literal -offset indent
 353 mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt
 354 .Ed
 355 .Pp
 356 Create a file-backed device from a hard disk image that begins
 357 with 512K of raw header information.
 358 .Xr gnop 8
 359 is used to skip over the header information, positioning
 360 .Pa md1.nop
 361 to the start of the filesystem in the image.
 362 .Bd -literal -offset indent
 363 mdconfig -u md1 -f diskimage.img
 364 gnop create -o 512K md1
 365 mount /dev/md1.nop /mnt
 366 .Ed
 367 .Sh SEE ALSO
 368 .Xr fpathconf 2 ,
 369 .Xr fspacectl 2 ,
 370 .Xr open 2 ,
 371 .Xr md 4 ,
 372 .Xr ffs 7 ,
 373 .Xr gpart 8 ,
 374 .Xr mdmfs 8 ,
 375 .Xr malloc 9 ,
 376 .Xr vn_deallocate 9
 377 .Sh HISTORY
 378 The
 379 .Nm
 380 utility first appeared in
 381 .Fx 5.0
 382 as a cleaner replacement for the vn kernel module
 383 and the vnconfig utility combo.
 384 .Sh AUTHORS
 385 The
 386 .Nm
 387 utility was written by
 388 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .