devmapper

README

devicemapper - a storage backend based on Device Mapper

Theory of operation

The device mapper graphdriver uses the device mapper thin provisioning module (dm-thinp) to implement CoW snapshots. The preferred model is to have a thin pool reserved outside of Docker, and passed to the daemon via the --storage-opt dm.thinpooldev option.

As a fallback if no thin pool is provided, loopback files will be created. Loopback is very slow, but can be used without any pre-configuration of storage. It is strongly recommended to not use loopback in production. Ensure your docker daemon has a --storage-opt dm.thinpooldev argument provided.

In loopback, each devicemapper graph location (typically /var/lib/docker/devicemapper, $graph below) a thin pool is created based on two block devices, one for data and one for metadata. By default these block devices are created automatically by using loopback mounts of automatically created sparse files.

The default loopback files used are $graph/devicemapper/data and $graph/devicemapper/metadata. Additional metadata required to map from docker entities to the corresponding devicemapper volumes is stored in the $graph/devicemapper/json file (encoded as Json).

In order to support multiple devicemapper graphs on a system, the thin pool will be named something like: docker-0:33-19478248-pool, where the 0:33 part is the minor/major device nr and 19478248 is the inode number of the $graph directory.

On the thin pool, docker automatically creates a base thin device, called something like docker-0:33-19478248-base of a fixed size. This is automatically formatted with an empty filesystem on creation. This device is the base of all docker images and containers. All base images are snapshots of this device and those images are then in turn used as snapshots for other images and eventually containers.

Information on docker info

As of docker-1.4.1, docker info when using the devicemapper storage driver will display something like:

$ sudo docker info
[...]
Storage Driver: devicemapper
 Pool Name: docker-253:1-17538953-pool
 Pool Blocksize: 65.54 kB
 Data file: /dev/loop4
 Metadata file: /dev/loop4
 Data Space Used: 2.536 GB
 Data Space Total: 107.4 GB
 Data Space Available: 104.8 GB
 Metadata Space Used: 7.93 MB
 Metadata Space Total: 2.147 GB
 Metadata Space Available: 2.14 GB
 Udev Sync Supported: true
 Data loop file: /home/docker/devicemapper/devicemapper/data
 Metadata loop file: /home/docker/devicemapper/devicemapper/metadata
 Library Version: 1.02.82-git (2013-10-04)
[...]

status items

Each item in the indented section under Storage Driver: devicemapper are status information about the driver.

• Pool Name name of the devicemapper pool for this driver.
• Pool Blocksize tells the blocksize the thin pool was initialized with. This only changes on creation.
• Data file blockdevice file used for the devicemapper data
• Metadata file blockdevice file used for the devicemapper metadata
• Data Space Used tells how much of Data file is currently used
• Data Space Total tells max size the Data file
• Data Space Available tells how much free space there is in the Data file. If you are using a loop device this will report the actual space available to the loop device on the underlying filesystem.
• Metadata Space Used tells how much of Metadata file is currently used
• Metadata Space Total tells max size the Metadata file
• Metadata Space Available tells how much free space there is in the Metadata file. If you are using a loop device this will report the actual space available to the loop device on the underlying filesystem.
• Udev Sync Supported tells whether devicemapper is able to sync with Udev. Should be true.
• Data loop file file attached to Data file, if loopback device is used
• Metadata loop file file attached to Metadata file, if loopback device is used
• Library Version from the libdevmapper used

About the devicemapper options

The devicemapper backend supports some options that you can specify when starting the docker daemon using the --storage-opt flags. This uses the dm prefix and would be used something like docker -d --storage-opt dm.foo=bar.

These options are currently documented both in the man page and in [the online documentation](https://docs.docker.com/reference/commandline/daemon/#docker- execdriver-option). If you add an options, update both the man page and the documentation.

Documentation

Index

• Variables
• func Init(home string, options []string) (graphdriver.Driver, error)
• func Mounted(mountpoint string) (bool, error)
• func ProbeFsType(device string) (string, error)
• type DevInfo
  • func (info *DevInfo) DevName() string
  • func (info *DevInfo) Name() string
• type DevStatus
• type DeviceMetadata
• type DeviceSet
  • func NewDeviceSet(root string, doInit bool, options []string) (*DeviceSet, error)
  • func (devices *DeviceSet) AddDevice(hash, baseHash string) error
  • func (devices *DeviceSet) DMLog(level int, file string, line int, dmError int, message string)
  • func (devices *DeviceSet) DataDevicePath() string
  • func (devices *DeviceSet) DeleteDevice(hash string) error
  • func (devices *DeviceSet) ExportDeviceMetadata(hash string) (*DeviceMetadata, error)
  • func (devices *DeviceSet) GetDeviceStatus(hash string) (*DevStatus, error)
  • func (devices *DeviceSet) HasActivatedDevice(hash string) bool
  • func (devices *DeviceSet) HasDevice(hash string) bool
  • func (devices *DeviceSet) List() []string
  • func (devices *DeviceSet) MetadataDevicePath() string
  • func (devices *DeviceSet) MountDevice(hash, path, mountLabel string) error
  • func (devices *DeviceSet) ResizePool(size int64) error
  • func (devices *DeviceSet) Shutdown() error
  • func (devices *DeviceSet) Status() *Status
  • func (devices *DeviceSet) UnmountDevice(hash string) error
• type DiskUsage
• type Driver
  • func (d *Driver) Cleanup() error
  • func (d *Driver) Create(id, parent string) error
  • func (d *Driver) Exists(id string) bool
  • func (d *Driver) Get(id, mountLabel string) (string, error)
  • func (d *Driver) GetMetadata(id string) (map[string]string, error)
  • func (d *Driver) Put(id string) error
  • func (d *Driver) Remove(id string) error
  • func (d *Driver) Status() [][2]string
  • func (d *Driver) String() string
• type MetaData
• type Status
• type Transaction

Variables

var (
	DefaultDataLoopbackSize     int64  = 100 * 1024 * 1024 * 1024
	DefaultMetaDataLoopbackSize int64  = 2 * 1024 * 1024 * 1024
	DefaultBaseFsSize           uint64 = 100 * 1024 * 1024 * 1024
	DefaultThinpBlockSize       uint32 = 128 // 64K = 128 512b sectors
	DefaultUdevSyncOverride     bool   = false
	MaxDeviceId                 int    = 0xffffff // 24 bit, pool limit
	DeviceIdMapSz               int    = (MaxDeviceId + 1) / 8
	// We retry device removal so many a times that even error messages
	// will fill up console during normal operation. So only log Fatal
	// messages by default.
	DMLogLevel                   int  = devicemapper.LogLevelFatal
	DriverDeferredRemovalSupport bool = false
	EnableDeferredRemoval        bool = false
	WarnOnLoopback               bool = true
	LoopbackInUse                bool
)

Functions

func Init

func Init(home string, options []string) (graphdriver.Driver, error)

func Mounted

func Mounted(mountpoint string) (bool, error)

func ProbeFsType

func ProbeFsType(device string) (string, error)

Types

type DevInfo

type DevInfo struct {
	Hash          string `json:"-"`
	DeviceId      int    `json:"device_id"`
	Size          uint64 `json:"size"`
	TransactionId uint64 `json:"transaction_id"`
	Initialized   bool   `json:"initialized"`
	// contains filtered or unexported fields
}

func (*DevInfo) DevName

func (info *DevInfo) DevName() string

func (*DevInfo) Name

func (info *DevInfo) Name() string

type DevStatus

type DevStatus struct {
	DeviceId            int
	Size                uint64
	TransactionId       uint64
	SizeInSectors       uint64
	MappedSectors       uint64
	HighestMappedSector uint64
}

type DeviceMetadata

type DeviceMetadata struct {
	// contains filtered or unexported fields
}

Structure used to export image/container metadata in docker inspect.

type DeviceSet

type DeviceSet struct {
	MetaData   `json:"-"`
	sync.Mutex `json:"-"` // Protects Devices map and serializes calls into libdevmapper

	TransactionId uint64 `json:"-"`
	NextDeviceId  int    `json:"next_device_id"`

	Transaction `json:"-"`

	BaseDeviceUUID string //save UUID of base device
	// contains filtered or unexported fields
}

func NewDeviceSet

func NewDeviceSet(root string, doInit bool, options []string) (*DeviceSet, error)

func (*DeviceSet) AddDevice

func (devices *DeviceSet) AddDevice(hash, baseHash string) error

func (*DeviceSet) DMLog

func (devices *DeviceSet) DMLog(level int, file string, line int, dmError int, message string)

func (*DeviceSet) DataDevicePath

func (devices *DeviceSet) DataDevicePath() string

DataDevicePath returns the path to the data storage for this deviceset, regardless of loopback or block device

func (*DeviceSet) DeleteDevice

func (devices *DeviceSet) DeleteDevice(hash string) error

func (*DeviceSet) ExportDeviceMetadata

func (devices *DeviceSet) ExportDeviceMetadata(hash string) (*DeviceMetadata, error)

Status returns the current status of this deviceset

func (*DeviceSet) GetDeviceStatus

func (devices *DeviceSet) GetDeviceStatus(hash string) (*DevStatus, error)

func (*DeviceSet) HasActivatedDevice

func (devices *DeviceSet) HasActivatedDevice(hash string) bool

func (*DeviceSet) HasDevice

func (devices *DeviceSet) HasDevice(hash string) bool

func (*DeviceSet) List

func (devices *DeviceSet) List() []string

func (*DeviceSet) MetadataDevicePath

func (devices *DeviceSet) MetadataDevicePath() string

MetadataDevicePath returns the path to the metadata storage for this deviceset, regardless of loopback or block device

func (*DeviceSet) MountDevice

func (devices *DeviceSet) MountDevice(hash, path, mountLabel string) error

func (*DeviceSet) ResizePool

func (devices *DeviceSet) ResizePool(size int64) error

func (*DeviceSet) Shutdown

func (devices *DeviceSet) Shutdown() error

func (*DeviceSet) Status

func (devices *DeviceSet) Status() *Status

Status returns the current status of this deviceset

func (*DeviceSet) UnmountDevice

func (devices *DeviceSet) UnmountDevice(hash string) error

type DiskUsage

type DiskUsage struct {
	Used      uint64
	Total     uint64
	Available uint64
}

type Driver

type Driver struct {
	*DeviceSet
	// contains filtered or unexported fields
}

func (*Driver) Cleanup

func (d *Driver) Cleanup() error

func (*Driver) Create

func (d *Driver) Create(id, parent string) error

func (*Driver) Exists

func (d *Driver) Exists(id string) bool

func (*Driver) Get

func (d *Driver) Get(id, mountLabel string) (string, error)

func (*Driver) GetMetadata

func (d *Driver) GetMetadata(id string) (map[string]string, error)

func (*Driver) Put

func (d *Driver) Put(id string) error

func (*Driver) Remove

func (d *Driver) Remove(id string) error

func (*Driver) Status

func (d *Driver) Status() [][2]string

func (*Driver) String

func (d *Driver) String() string

type MetaData

type MetaData struct {
	Devices map[string]*DevInfo `json:"Devices"`
	// contains filtered or unexported fields
}

type Status

type Status struct {
	PoolName              string
	DataFile              string // actual block device for data
	DataLoopback          string // loopback file, if used
	MetadataFile          string // actual block device for metadata
	MetadataLoopback      string // loopback file, if used
	Data                  DiskUsage
	Metadata              DiskUsage
	SectorSize            uint64
	UdevSyncSupported     bool
	DeferredRemoveEnabled bool
}

type Transaction

type Transaction struct {
	OpenTransactionId uint64 `json:"open_transaction_id"`
	DeviceIdHash      string `json:"device_hash"`
	DeviceId          int    `json:"device_id"`
}