freebsd-nq/share/man/man4/md.4

.\" ----------------------------------------------------------------------------
.\" "THE BEER-WARE LICENSE" (Revision 42):
.\" <phk@FreeBSD.org> wrote this file.  As long as you retain this notice you
.\" can do whatever you want with this stuff. If we meet some day, and you think
.\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
.\" ----------------------------------------------------------------------------
.\"
.\" $FreeBSD$
.\"
.Dd November 5, 2017
.Dt MD 4
.Os
.Sh NAME
.Nm md
.Nd memory disk
.Sh SYNOPSIS
To compile this driver into the kernel,
place the following lines in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device md"
.Ed
.Pp
Alternatively, to load the driver as a
module at boot time, place the following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
geom_md_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides support for four kinds of memory backed virtual disks:
.Bl -tag -width preload
.It Cm malloc
Backing store is allocated using
.Xr malloc 9 .
Only one malloc-bucket is used, which means that all
.Nm
devices with
.Cm malloc
backing must share the malloc-per-bucket-quota.
The exact size of this quota varies, in particular with the amount
of RAM in the
system.
The exact value can be determined with
.Xr vmstat 8 .
.It Cm preload
A file loaded by
.Xr loader 8
with type
.Sq md_image
is used for backing store.
For backwards compatibility the type
.Sq mfs_root
is also recognized.
If the kernel is created with option
.Dv MD_ROOT
the first preloaded image found will become the root file system.
.It Cm vnode
A regular file is used as backing store.
This allows for mounting ISO images without the tedious
detour over actual physical media.
.It Cm swap
Backing store is allocated from buffer memory.
Pages get pushed out to the swap when the system is under memory
pressure, otherwise they stay in the operating memory.
Using
.Cm swap
backing is generally preferable over
.Cm malloc
backing.
.El
.Pp
For more information, please see
.Xr mdconfig 8 .
.Sh EXAMPLES
To create a kernel with a ramdisk or MD file system, your kernel config
needs the following options:
.Bd -literal -offset indent
options 	MD_ROOT			# MD is a potential root device
options		MD_ROOT_SIZE=8192	# 8MB ram disk
makeoptions	MFS_IMAGE=/h/foo/ARM-MD
options 	ROOTDEVNAME=\\"ufs:md0\\"
.Ed
.Pp
The image in
.Pa /h/foo/ARM-MD
will be loaded as the initial image each boot.
To create the image to use, please follow the steps to create a file-backed
disk found in the
.Xr mdconfig 8
man page.
Other tools will also create these images, such as NanoBSD.
.Sh SEE ALSO
.Xr gpart 8 ,
.Xr loader 8 ,
.Xr mdconfig 8 ,
.Xr mdmfs 8 ,
.Xr newfs 8 ,
.Xr vmstat 8
.Sh HISTORY
The
.Nm
driver first appeared in
.Fx 4.0
as a cleaner replacement
for the MFS functionality previously used in
.Tn PicoBSD
and in the
.Fx
installation process.
.Pp
The
.Nm
driver did a hostile takeover of the
.Xr vn 4
driver in
.Fx 5.0 .
.Sh AUTHORS
The
.Nm
driver was written by
.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.\" ----------------------------------------------------------------------------`
			`.\" "THE BEER-WARE LICENSE" (Revision 42):`
mdoc: consistently spell our email addresses <foo@FreeBSD.org> Reviewed by: ru 2010-05-19 08:57:53 +00:00			`.\" <phk@FreeBSD.org> wrote this file. As long as you retain this notice you`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.\" can do whatever you want with this stuff. If we meet some day, and you think`
			`.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp`
			`.\" ----------------------------------------------------------------------------`
			`.\"`
			`.\" $FreeBSD$`
			`.\"`
Extend the synopsis section of md(4) to look more like other manpages of this kind. Describe how to compile the driver into the kernel and how to load it as a module. This is useful for people using the MINIMAL kernel configuration file. PR: 218610 Submitted by: Harald Schmalzbauer (bugzilla.freebsd@omnilan.de) Reviewed by: noone (1 month inactivity) MFC after: 2 weeks Differential Revision: https://reviews.freebsd.org/D12271 2017-11-05 18:45:43 +00:00			`.Dd November 5, 2017`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Dt MD 4`
			`.Os`
			`.Sh NAME`
			`.Nm md`
			`.Nd memory disk`
			`.Sh SYNOPSIS`
Extend the synopsis section of md(4) to look more like other manpages of this kind. Describe how to compile the driver into the kernel and how to load it as a module. This is useful for people using the MINIMAL kernel configuration file. PR: 218610 Submitted by: Harald Schmalzbauer (bugzilla.freebsd@omnilan.de) Reviewed by: noone (1 month inactivity) MFC after: 2 weeks Differential Revision: https://reviews.freebsd.org/D12271 2017-11-05 18:45:43 +00:00			`To compile this driver into the kernel,`
			`place the following lines in your`
			`kernel configuration file:`
			`.Bd -ragged -offset indent`
			`.Cd "device md"`
			`.Ed`
			`.Pp`
			`Alternatively, to load the driver as a`
			`module at boot time, place the following line in`
			`.Xr loader.conf 5 :`
			`.Bd -literal -offset indent`
			`geom_md_load="YES"`
			`.Ed`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Sh DESCRIPTION`
			`The`
			`.Nm`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`driver provides support for four kinds of memory backed virtual disks:`
			`.Bl -tag -width preload`
			`.It Cm malloc`
			`Backing store is allocated using`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Xr malloc 9 .`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`Only one malloc-bucket is used, which means that all`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Nm`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`devices with`
			`.Cm malloc`
			`backing must share the malloc-per-bucket-quota.`
Add missing article. 2001-06-17 02:24:04 +00:00			`The exact size of this quota varies, in particular with the amount`
Removed whitespace at end-of-line; no content changes. I simply did cd src/share; find man[1-9] -type f\|xargs perl -pi -e 's/[ \t]+$//' BTW, what editors are the culprits? I'm using vim and it shows me whitespace at EOL in troff files with a thick blue block... Reviewed by: Silence from cvs diff -b MFC after: 7 days 2001-07-14 19:41:16 +00:00			`of RAM in the`
mdoc(7) police: o Update document date. o Remove hard sentence break. o Sort xrefs. 2001-03-12 09:14:22 +00:00			`system.`
			`The exact value can be determined with`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`.Xr vmstat 8 .`
			`.It Cm preload`
Removed whitespace at end-of-line; no content changes. I simply did cd src/share; find man[1-9] -type f\|xargs perl -pi -e 's/[ \t]+$//' BTW, what editors are the culprits? I'm using vim and it shows me whitespace at EOL in troff files with a thick blue block... Reviewed by: Silence from cvs diff -b MFC after: 7 days 2001-07-14 19:41:16 +00:00			`A file loaded by`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`.Xr loader 8`
Removed whitespace at end-of-line; no content changes. I simply did cd src/share; find man[1-9] -type f\|xargs perl -pi -e 's/[ \t]+$//' BTW, what editors are the culprits? I'm using vim and it shows me whitespace at EOL in troff files with a thick blue block... Reviewed by: Silence from cvs diff -b MFC after: 7 days 2001-07-14 19:41:16 +00:00			`with type`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Sq md_image`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`is used for backing store.`
			`For backwards compatibility the type`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Sq mfs_root`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`is also recognized.`
			`If the kernel is created with option`
mdoc(7) police: o Update document date. o Remove hard sentence break. o Sort xrefs. 2001-03-12 09:14:22 +00:00			`.Dv MD_ROOT`
Uniformly refer to a file system as "file system". Approved by: re 2002-12-12 17:26:04 +00:00			`the first preloaded image found will become the root file system.`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`.It Cm vnode`
			`A regular file is used as backing store.`
			`This allows for mounting ISO images without the tedious`
			`detour over actual physical media.`
			`.It Cm swap`
Talk more about swap backing PR: docs/78041 (inspired by) Submitted by: Lars Kristiansen <lars+lister.freebsd@adventuras.no> MFC after: 1 week 2007-05-12 15:33:18 +00:00			`Backing store is allocated from buffer memory.`
			`Pages get pushed out to the swap when the system is under memory`
			`pressure, otherwise they stay in the operating memory.`
			`Using`
			`.Cm swap`
			`backing is generally preferable over`
			`.Cm malloc`
			`backing.`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`.El`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Pp`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`For more information, please see`
mdoc(7) police: o Update document date. o Remove hard sentence break. o Sort xrefs. 2001-03-12 09:14:22 +00:00			`.Xr mdconfig 8 .`
Add instructions for creating a ramdisk root image. These likely need to be augmented with instructions for those platforms that have /boot/loader. 2006-11-24 18:53:45 +00:00			`.Sh EXAMPLES`
			`To create a kernel with a ramdisk or MD file system, your kernel config`
			`needs the following options:`
mdoc warning fixes: Use the correct syntax for .Bl -offset indent MFC after: 3 days 2007-10-30 16:02:49 +00:00			`.Bd -literal -offset indent`
Fix the example. 2009-05-17 12:21:11 +00:00			`options MD_ROOT # MD is a potential root device`
Add instructions for creating a ramdisk root image. These likely need to be augmented with instructions for those platforms that have /boot/loader. 2006-11-24 18:53:45 +00:00			`options MD_ROOT_SIZE=8192 # 8MB ram disk`
			`makeoptions MFS_IMAGE=/h/foo/ARM-MD`
Fix the example. 2009-05-17 12:21:11 +00:00			`options ROOTDEVNAME=\\"ufs:md0\\"`
Add instructions for creating a ramdisk root image. These likely need to be augmented with instructions for those platforms that have /boot/loader. 2006-11-24 18:53:45 +00:00			`.Ed`
Fix the example. 2009-05-17 12:21:11 +00:00			`.Pp`
Add instructions for creating a ramdisk root image. These likely need to be augmented with instructions for those platforms that have /boot/loader. 2006-11-24 18:53:45 +00:00			`The image in`
			`.Pa /h/foo/ARM-MD`
			`will be loaded as the initial image each boot.`
			`To create the image to use, please follow the steps to create a file-backed`
Remove trailing whitespace per mdoc lint warning Disussed with: gavin No objection from: doc Approved by: joel MFC after: 3 days 2012-03-29 05:02:12 +00:00			`disk found in the`
Add instructions for creating a ramdisk root image. These likely need to be augmented with instructions for those platforms that have /boot/loader. 2006-11-24 18:53:45 +00:00			`.Xr mdconfig 8`
			`man page.`
			`Other tools will also create these images, such as NanoBSD.`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Sh SEE ALSO`
It's 2015, and some people are still trying to use fdisk and then go asking what debug flags to set for GEOM to make it work. Advice them to use gpart(8) instead. Something similar should probably done with disklabel, but I need to rewrite the disklabel examples first. Reviewed by: wblock@ MFC after: 1 month Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D3315 2015-09-02 14:08:43 +00:00			`.Xr gpart 8 ,`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Xr loader 8 ,`
mdoc(7) police: o Update document date. o Remove hard sentence break. o Sort xrefs. 2001-03-12 09:14:22 +00:00			`.Xr mdconfig 8 ,`
Add .Xr's to mdmfs(8). Submitted by: Scot W. Hetzel <hetzels@westbend.net> 2003-04-27 01:46:56 +00:00			`.Xr mdmfs 8 ,`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Xr newfs 8 ,`
			`.Xr vmstat 8`
			`.Sh HISTORY`
			`The`
			`.Nm`
			`driver first appeared in`
			`.Fx 4.0`
			`as a cleaner replacement`
mdoc(7) police: o Update document date. o Remove hard sentence break. o Sort xrefs. 2001-03-12 09:14:22 +00:00			`for the MFS functionality previously used in`
			`.Tn PicoBSD`
Use Fx macro wherever possible. 2000-11-14 11:20:58 +00:00			`and in the`
			`.Fx`
			`installation process.`
Make md(4) more in line with reality. NB: probably contains mdoc mistakes, feel free to fix. 2001-03-09 20:07:37 +00:00			`.Pp`
			`The`
			`.Nm`
			`driver did a hostile takeover of the`
			`.Xr vn 4`
			`driver in`
			`.Fx 5.0 .`
Add phk's md(4) manual page, written by phk himself. 2000-07-07 11:52:03 +00:00			`.Sh AUTHORS`
			`The`
			`.Nm`
			`driver was written by`
use .Mt to mark up email addresses consistently (final part) PR: 191174 Submitted by: Franco Fichtner <franco at lastsummer.de> 2014-06-26 21:46:14 +00:00			`.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .`