[lvm-devel] master - man: add dmfilemapd.8
Bryn Reeves
bmr at sourceware.org
Thu Mar 9 18:54:03 UTC 2017
Gitweb: https://sourceware.org/git/?p=lvm2.git;a=commitdiff;h=044f92e466176e1ea29d1159361de5f5f3fc263a
Commit: 044f92e466176e1ea29d1159361de5f5f3fc263a
Parent: 8b78982297bb9c8484f8add7fdf96e93c8238769
Author: Bryn M. Reeves <bmr at redhat.com>
AuthorDate: Sat Dec 17 16:24:35 2016 +0000
Committer: Bryn M. Reeves <bmr at redhat.com>
CommitterDate: Thu Mar 9 18:50:15 2017 +0000
man: add dmfilemapd.8
---
man/Makefile.in | 3 +
man/dmfilemapd.8.in | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 215 insertions(+), 0 deletions(-)
diff --git a/man/Makefile.in b/man/Makefile.in
index 3ae00d9..6c799a5 100644
--- a/man/Makefile.in
+++ b/man/Makefile.in
@@ -45,6 +45,9 @@ MAN8GEN=lvm-config.8 lvm-dumpconfig.8 lvm-fullreport.8 lvm-lvpoll.8 \
vgimport.8 vgimportclone.8 vgmerge.8 vgmknodes.8 vgreduce.8 vgremove.8 \
vgrename.8 vgs.8 vgscan.8 vgsplit.8 \
lvmsar.8 lvmsadc.8 lvmdiskscan.8 lvmchange.8
+MAN8DM=dmsetup.8 dmstats.8 dmfilemapd.8
+MAN8CLUSTER=
+MAN8SYSTEMD_GENERATORS=lvm2-activation-generator.8
ifeq ($(MAKECMDGOALS),all_man)
MAN_ALL="yes"
diff --git a/man/dmfilemapd.8.in b/man/dmfilemapd.8.in
new file mode 100644
index 0000000..37c76c7
--- /dev/null
+++ b/man/dmfilemapd.8.in
@@ -0,0 +1,212 @@
+.TH DMFILEMAPD 8 "Dec 17 2016" "Linux" "MAINTENANCE COMMANDS"
+
+.de OPT_FD
+. RB [ file_descriptor ]
+..
+.
+.de OPT_GROUP
+. RB [ group_id ]
+..
+.de OPT_PATH
+. RB [ path ]
+..
+.
+.de OPT_MODE
+. RB [ mode ]
+..
+.
+.de OPT_DEBUG
+. RB [ foreground [ verbose ] ]
+..
+.
+.SH NAME
+.
+dmfilemapd \(em device-mapper filemap monitoring daemon
+.
+.SH SYNOPSIS
+.
+.de CMD_DMFILEMAPD
+. ad l
+. IR dmfilemapd
+. OPT_FD
+. OPT_GROUP
+. OPT_PATH
+. OPT_MODE
+. OPT_DEBUG
+. ad b
+..
+.CMD_DMFILEMAPD
+.
+.PD
+.ad b
+.
+.SH DESCRIPTION
+.
+The dmfilemapd daemon monitors groups of \fIdmstats\fP regions that
+correspond to the extents of a file, adding and removing regions to
+reflect the changing state of the file on-disk.
+
+The daemon is normally launched automatically by the \fPdmstats
+create\fP command, but can be run manually, either to create a new
+daemon where one did not previously exist, or to change the options
+previously used, by killing the existing daemon and starting a new
+one.
+.
+.SH OPTIONS
+.
+.HP
+.BR file_descriptor
+.br
+Specify the file descriptor number for the file to be monitored.
+The file descriptor must reference a regular file, open for reading,
+in a local file system that supports the FIEMAP ioctl, and that
+returns data describing the physical location of extents.
+
+The process that executes \fBdmfilemapd\fP is responsible for
+opening the file descriptor that is handed to the daemon.
+.
+.HP
+.BR group_id
+.br
+The \fBdmstats\fP group identifier of the group that \fBdmfilemapd\fP
+should update. The group must exist and it should correspond to
+a set of regions created by a previous filemap operation.
+.
+.HP
+.BR path
+.br
+The path to the file being monitored, at the time that it was
+opened. The use of \fBpath\fP by the daemon differs, depending
+on the filemap following mode in use; see \fBMODES\fP and the
+\fBmode\fP option for more information.
+
+.br
+.HP
+.BR mode
+.br
+The filemap monitoring mode the daemon should use: either "inode"
+(\fBDM_FILEMAP_FOLLOW_INODE\fP), or "path"
+(\fBDM_FILEMAP_FOLLOW_PATH\fP), to enable follow-inode or
+follow-path mode respectively.
+.
+.HP
+.BR [foreground]
+.br
+If set to 1, disable forking and allow the daemon to run in the
+foreground.
+.
+.HP
+.BR [verbose]
+Control daemon logging. If set to zero, the daemon will close all
+stdio streams and run silently. If \fBverbose\fP is a number
+between 1 and 3, stdio will be retained and the daemon will log
+messages to stdout and stderr that match the specified verbosity
+level.
+.
+.
+.SH MODES
+.
+The file map monitoring daemon can monitor files in two distinct
+ways: the mode affects the behaviour of the daemon when a file
+under monitoring is renamed or unlinked, and the conditions which
+cause the daemon to terminate.
+
+In both modes, the daemon will always shut down when the group
+being monitored is deleted.
+
+.P
+.B Follow inode
+.P
+The daemon follows the inode of the file, as it was at the time the
+daemon started. The file descriptor referencing the file is kept
+open at all times, and the daemon will exit when it detects that
+the file has been unlinked and it is the last holder of a reference
+to the file.
+
+This mode is useful if the file is expected to be renamed, or moved
+within the file system, while it is being monitored.
+
+.P
+.B Follow path
+.P
+The daemon follows the path that was given on the daemon command
+line. The file descriptor referencing the file is re-opened on each
+iteration of the daemon, and the daemon will exit if no file exists
+at this location (a tolerance is allowed so that a brief delay
+between removal and replacement is permitted).
+
+This mode is useful if the file is updated by unlinking the original
+and placing a new file at the same path.
+.
+.SH LIMITATIONS
+.
+The daemon attempts to maintain good synchronisation between the file
+extents and the regions contained in the group, however, since the
+daemon can only react to new allocations once they have been written,
+there are inevitably some IO events that cannot be counted when a
+file is growing, particularly if the file is being extended by a
+single thread writing beyond EOF (for example, the \fBdd\fP program).
+
+There is a further loss of events in that there is currently no way
+to atomically resize a \fBdmstats\fP region and preserve its current
+counter values. This affects files when they grow by extending the
+final extent, rather than allocating a new extent: any events that
+had accumulated in the region between any prior operation and the
+resize are lost.
+
+File mapping is currently most effective in cases where the majority
+of IO does not trigger extent allocation. Future updates may address
+these limitations when kernel support is available.
+.
+.SH EXAMPLES
+.
+Normally the daemon is started automatically by the \fBdmstats\fP
+\fBcreate\fP or \fBupdate_filemap\fP commands but it can be run
+manually for debugging or testing purposes.
+.P
+Start the daemon in the background, in follow-path mode
+.br
+#
+.B dmfilemapd 3 0 vm.img path 0 0 3< vm.img
+.br
+.P
+Start the daemon in follow-inode mode, disable forking and enable
+verbose logging
+.br
+#
+.B dmfilemapd 3 0 vm.img inode 1 3 3< vm.img
+.br
+Starting dmfilemapd with fd=3, group_id=0 mode=inode, path=vm.img
+.br
+dm version [ opencount flush ] [16384] (*1)
+.br
+dm info (253:0) [ opencount flush ] [16384] (*1)
+.br
+dm message (253:0) [ opencount flush ] @stats_list dmstats [16384] (*1)
+.br
+Read alias 'vm.img' from aux_data
+.br
+Found group_id 0: alias="vm.img"
+.br
+dm_stats_walk_init: initialised flags to 4000000000000
+.br
+starting stats walk with GROUP
+.br
+exiting _filemap_monitor_get_events() with deleted=0, check=0
+.br
+waiting for FILEMAPD_WAIT
+.br
+.P
+.
+.SH AUTHORS
+.
+Bryn M. Reeves <bmr at redhat.com>
+.
+.SH SEE ALSO
+.
+.BR dmstats (8)
+
+LVM2 resource page: https://www.sourceware.org/lvm2/
+.br
+Device-mapper resource page: http://sources.redhat.com/dm/
+.br
More information about the lvm-devel
mailing list