.\"	$NetBSD: dm.4,v 1.7 2015/05/04 06:14:47 pgoyette Exp $
.\"
.\" Copyright (c) 1996, 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Adam Hamsik
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.Dd April 4, 2015
.Dt DM 4
.Os
.Sh NAME
.Nm dm
.Nd Device-mapper disk driver
.Sh SYNOPSIS
.Cd "pseudo-device dm"
.Sh DESCRIPTION
The
.Nm
driver provides the capability of creating one or more virtual disks
based on the target mapping.
.Pp
This document assumes that you're familiar with how to generate
kernels, how to properly configure disks and pseudo-devices in a
kernel configuration file, and how to partition disks.
This driver is used by the Linux lvm2tools to create and manage
lvm in
.Nx .
.Pp
Currently, the
.Pa linear , zero ,
and
.Pa error
targets are implemented.
Each component partition should be offset at least 2 sectors
from the beginning of the component disk.
This avoids potential conflicts between the component disk's
disklabel and
.Nm Ap s
disklabel.
In i386 it is offset by 65 sectors, where 63 sectors are the initial
boot sectors and 2 sectors are used for the disklabel which is set
to be read-only.
.Pp
In order to compile in support for
.Nm ,
you must add a line similar to the following to your kernel
configuration file:
.Bd -unfilled -offset indent
pseudo-device	dm	 #device-mapper disk device
.Ed
.Pp
.Nm
may create linear mapped devices, zero, and error block devices.
Zero and error block devices are used mostly for testing.
.Pa Linear
devices are used to create virtual disks with linearly mapped virtual
blocks to blocks on real disk.
.Nm
Device-mapper devices are controlled through the
.Pa /dev/mapper/control
device.
For controlling this device
.Xr ioctl 2
calls are used.
For the implementation of the communication channel,
the
.Xr proplib 3
library is used.
The protocol channel is defined as a proplib dictionary with needed
values.
For more details, look at
.Pa sys/dev/dm/netbsd-dm.h .
Before any device can be used, every device-mapper disk device must
be initialized.
For initialization one line must be passed to the kernel driver in
the form of a proplib dictionary.
Every device can have more than one table active.
An example for such a line is:
.Bd -unfilled -offset indent
0 10240 linear /dev/wd1a 384
.Ed
.Pp
The first parameter is the start sector for the table defined with
this line, the second is the length in sectors which is described
with this table.
The third parameter is the target name.
All other parts of this line depend on the chosen target.
.Pp
For the linear target, there are two additional parameters:
The fourth parameter describes the disk device to which the
device-mapper disk is mapped.
The fifth parameter is the offset on this disk from the start of
the disk/partition.
.Sh SEE ALSO
.Xr config 1 ,
.Xr proplib 3 ,
.Xr dmsetup 8 ,
.Xr fsck 8 ,
.Xr lvm 8 ,
.Xr MAKEDEV 8 ,
.Xr mount 8 ,
.Xr newfs 8
.Sh HISTORY
The device-mapper disk driver first appeared in
.Nx 6.0 .
.Sh AUTHORS
.An Adam Hamsik Aq Mt haad@NetBSD.org
implemented the device-mapper driver for
.Nx .
.Pp
.An Brett Lymn Aq Mt blymn@NetBSD.org ,
.An Reinoud Zandijk Aq Mt reinoud@NetBSD.org ,
and
.An Bill Stouder-Studenmund Aq Mt wrstuden@NetBSD.org
provided guidance and answered questions about the
.Nx
implementation.
.Sh BUGS
This driver is still a work-in-progress \(em there can be bugs.