# SPDX-License-Identifier: GPL-2.0+
[suite misma]
	caption = Subcommands
	mansect = 8
	manual_title = System Manager's Manual
[supercommand misma]
	[description]
		DESCRIPTION1()

		DESCRIPTION2()

		DESCRIPTION3()
	[/description]
	synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
	purpose = SLOGAN()

	[option title-text]
		summary = General options
		flag ignored
	[option help]
		summary = print help and exit
		short_opt = h
	[option detailed-help]
		summary = print help, including all details, and exit
	[option version]
		summary = print version and exit
		short_opt = V
	[option loglevel]
		summary = control amount of logging
		short_opt = l
		arg_info = required_arg
		arg_type = string
		typestr = severity
		values = {
			LSGLL_DEBUG = "debug",
			LSGLL_INFO = "info",
			LSGLL_NOTICE = "notice",
			LSGLL_WARNING = "warning",
			LSGLL_ERROR = "error",
			LSGLL_CRIT = "crit",
			LSGLL_EMERG = "emerg"
		}
		default_val = warning
		[help]
			Log only messages with severity greater or equal than the given
			value. Possible values:

			debug: produces really noisy output.
			info: still noisy, but won't fill up the disk quickly.
			notice: indicates normal, but significant event.
			warning: unexpected events that can be handled.
			error: unhandled error condition.
			crit: system might be unreliable.
			emerg: last message before exit.
		[/help]
	[option config-file]
		short_opt = c
		summary = use alternative config file (default: ~/.mismarc)
		typestr = path
		arg_info = required_arg
		arg_type = string
		[help]
			Options may be given at the command line or in the configuration
			file. As usual, if an option is given both at the command line and
			in the configuration file, the command line option takes precedence.

			The config file may contain global options as well as options for
			any subcommand, but subcommand specific options must be placed in a
			separate section. See the Examples section of the man page.
		[/help]

	[option title-text]
		summary = LVM options
		flag ignored
	[option origin]
		summary = the VG and the thin LV to snapshot
		typestr = vg/tlv
		arg_info = required_arg
		arg_type = string
		flag multiple
		[help]
			The named volume group must exist and it must contain the named thin
			logical volume. This option may be given multiple times where each
			instance corresponds to one origin to snapshot.
		[/help]
[introduction]
	Misma supports the subcommands described below. If no subcommand is
	given, the list of available subcommands is shown and the program
	terminates successfully without performing any further action.
[/introduction]

[subcommand run]
	purpose = create and prune snapshots, discard unused blocks
	[description]
		This is the main mode of operation. Snapshots are created and pruned
		periodically, the thin pool utilization is monitored and filesystem
		trims are scheduled as configured. The subcommand terminates only on
		fatal errors or after a terminating signal was received.
	[/description]
	[option daemon]
		short_opt = d
		summary = run as background daemon
		[help]
			If this option is given, the process detaches from the console and
			continues to run in the background.
		[/help]
	[option logfile]
		short_opt = l
		summary = where to write log output
		arg_info = required_arg
		arg_type = string
		typestr = path
		default_val = /dev/null
		[help]
			This option is only honored if --daemon is given, in which case
			log messages go to the given file. Otherwise the option is silently
			ignored and log output is written to stderr.
		[/help]
	[option create-interval]
		summary = Time span between two subsequent snapshots
		typestr = [lvmspec:]timespec
		arg_info = required_arg
		arg_type = string
		flag multiple
		default_val = 6h
		[help]
			The lvm specifier determines to which origins this instance of the
			option applies. If no specifier is given, the option applies to all
			origins. Otherwise the specifier may be in one of the following forms:
			<vg>: applies to all origins in VG vg, <vg|pool>: applies to all
			origins in thin pool <pool> of VG vg, or <vg/tlv>: applies to origin
			tlv of vg only. If more than one specifier match a particular origin,
			the narrowest scoped one applies. The order of precedence is therefore
			<vg/tlv>, <vg|pool>, <vg>, <global>.

			The time specifier is an unsigned integer which is followed by a time
			unit, a single character of the set {s,m,h,d,y} for seconds, minutes,
			hours, days, and years.
		[/help]
	[option max-age]
		summary = age of the oldest snapshot to keep
		typestr = [lvmspec:]timespec
		arg_info = required_arg
		arg_type = string
		flag multiple
		default_val = 1y
		[help]
			See --create-interval for the format of the lvm and time specifiers.
		[/help]
	[option check-interval]
		summary = the time period between two utilization checks
		typestr = timespec
		arg_info = required_arg
		arg_type = string
		default_val = 1m
		[help]
			The utilization of all thin pools which contain at least one thin
			logical volume specified as an argument to --origin are checked
			periodically. See --create-interval for the format of the time
			specifier.
		[/help]
	[option threshold]
		summary = high watermarks for snapshot removal (1-99)
		typestr = [lvmspec:]data_threshold,meta_threshold
		arg_info = required_arg
		arg_type = string
		flag multiple
		default_val = 95,95
		[help]
			The threshold part of the argument is a comma-separated pair of
			percentages between 1 and 99, inclusively. If the percentage of used
			space in the data/metadata logical volume of the thin pool exceeds
			the corresponding threshold value, forced snapshot removal kicks in
			to bring back the utilization below the thresholds.

			The format of the lvm specifier is described in the help text of
			--create-interval. However, since the utilization is a property
			of the pool, arguments of the form <vg/tlv> make no sense and are
			therefore rejected.
		[/help]
	[option trim-interval]
		summary = discard unused blocks periodically
		typestr = [lvmspec:]timespec
		arg_info = required_arg
		arg_type = string
		flag multiple
		default_val = 0
		[help]
			The argument specifies the duration between two successive trims. The
			default value of zero deactivates this feature.

			Trimming is performed in the same way as for the trim subcommand.
			Errors related to trimming are logged but are otherwise ignored.

			See --create-interval for the format of the specifiers.
		[/help]
	[option exit-hook]
		summary = command to be executed before exit
		typestr = command
		arg_info = required_arg
		arg_type = string
		default_val = true
		[help]
			One possible application for this hook is to inform system manager
			that no more snapshots are going to be created.

			A (quoted) string which describes the error that caused the termination is
			appended to the given command and the resulting string is passed as a single
			argument to /bin/sh -c.
		[/help]
	[option suppress-lvm-warnings]
		summary = quieten lvcreate(8) and lvremove(8)
		[help]
			suppress
		[/help]
[subcommand create]
	purpose = create a snapshot of each matching origin
	non-opts-name = [<lvmspec>]...
	[description]
		This creates one snapshot of each origin which matches the given lvm
		specifier, ignoring creation intervals, maximal age and utilization
		thresholds. If no specifiers are given, all origins are regarded as
		matching so that one snapshot of each configured origin is created.

		The subcommand fails if another "run", "create", or "remove" command
		is currently running.
	[/description]
	[option dry-run]
		short_opt = n
		summary = just print which snapshot would be created
[subcommand rm]
	purpose = remove one snapshot of each matching origin
	non-opts-name = [<lvmspec>]...
	[description]
		The remarks stated in the description of the "create" subcommand apply
		for this subcommand as well.
	[/description]
	[option dry-run]
		short_opt = n
		summary = just print which snapshot would get removed
[subcommand ls]
	purpose = print the snapshot list of each origin
	non-opts-name = [<lvmspec>]...
	[description]
		The list is sorted by snapshot creation date.
	[/description]
	[option long]
		short_opt = l
		summary = use long listing format
		[help]
			The default output mode lists only the sequence number and the age
			of each snapshot as human readable text. This option adds additional
			output.
		[/help]
[subcommand kill]
	purpose = signal another misma process
	[description]
		This sends a signal to the misma "run" process.
	[/description]
	[option signal]
		short_opt = s
		summary = send the given signal rather than SIGTERM
		typestr = signal_number
		arg_info = required_arg
		arg_type = uint32
		default_val = 15
		[help]
			The standard Unix semantics apply if the specified signal number
			is zero. That is, no signal is actually sent, and the subcommand
			exits successfully only if a misma "run" process exists.
		[/help]
	[option wait]
		short_opt = w
		summary = wait until the signalled process has terminated
		[help]
			This option is handy for system shutdown scripts which would like
			to terminate the misma daemon process.

			Without --wait the misma process which executes the kill subcommand
			exits right after the kill(2) system call returns. At this point the
			signalled process might still be alive (even if SIGKILL was sent).
			If --wait is given, the process waits until the signalled process
			has terminated or the timeout expires.

			If --wait is not given, the kill subcommand exits successfully if
			and only if the signal was sent (i.e., if there exists another misma
			process to receive the signal). With --wait it exits successfully
			if, additionally, the signalled process has terminated before the
			timeout expires.

			It makes only sense to use the option for signals which terminate
			the misma process.
		[/help]
[subcommand trim]
	purpose = discard unused blocks of origin LVs
	non-opts-name = [<lvmspec>]...
	[description]
		Each matching origin LV is expected to contain a mounted and writable
		filesystem. The subcommand is equivalent to running fstrim(8) on
		the mountpoints of these filesystems. The full block range of each
		origin LV is taken into account and the default minimal block size for
		discards is used. This corresponds to the default values of fstrim(8).
	[/description]
	[option dry-run]
		short_opt = n
		summary = print the mount points, but do not trim
		[help]
			In dry-run mode the mount points are determined as usual, but the
			command exits without starting any trim operation.
		[/help]
[subcommand help]
	purpose = list available subcommands or print subcommand-specific help
	non-opts-name = [subcommand]
	[description]
		Without any arguments, help prints the list of available
		subcommands. When called with a subcommand name argument, it prints
		the help text of the given subcommand.
	[/description]
	[option long]
		short_opt = l
		summary = show the long help text
		[help]
			If the optional argument is supplied, the long help text contains the
			synopsis, the purpose and the description of the specified subcommand,
			followed by the option list including summary and help text of each
			option. Without --long, the short help is shown instead. This omits
			the description of the subcommand and the option help.

			If no subcommand is supplied but --long is given, the list contains the
			purpose of each subcommand.
		[/help]
[subcommand utilization]
	purpose = show thin pool utilization
	[description]
		This prints the percentage of used blocks in the data and metadata
		logical volumes of each pool.
	[/description]
[subcommand configtest]
	purpose = run a configuration file syntax test
	[description]
		This subcommand checks the command line options and the configuration
		file for syntactic correctness. It either reports "Syntax Ok" and
		exits successfully or prints information about the first syntax error
		detected and terminates with exit code 1.
	[/description]

[section Notes]
.SS Naming
	Snapshots created by misma are named
	.IR misma-origin.seq ,
	where
	.I origin
	is the name of the thin logical volume (i.e., the second component
	of the argument to
	.I --origin)
	and
	.I seq
	is a sequence number.
.SS Snapshot Replacement Strategy
	Assume that the arguments
	to
	.I --create-interval
	and
	.I --max-age
	correspond to
	.I d
	minutes and
	.I m
	days, respectively. These two quantities determine the length
	.I n
	of a sequence of snapshots such that
	.IP \(bu 2
		the first two snapshots are
	.I d
	minutes apart,
	.IP \(bu 2
		the difference of the creation times between two consecutive snapshots
		doubles at each step,
	.IP \(bu 2
		the first and the last snapshot are at least
	.I m
	days apart.
	.P
	At startup,
	.B misma
	maps each existing snapshot to a slot in an array
	of length
	.IR n .
	When a new snapshot has to be created and not all slots are mapped
	yet, the new snapshot is mapped to an unmapped slot. If all slots
	are mapped, an existing snapshot is removed first and its slot is
	reused. The slot number of the snapshot to be replaced is computed as
	.B ffz(seq % (2^n - 1)),
	where
	.I seq
	is the sequence number of the new snapshot, and
	.B ffz(x)
	is the first zero in
	the binary representation of
	.IR x .
	By properties of the
	.B ffz()
	function, the frequency at which a slot gets reused halves at each
	step: the snapshot in slot 0 gets reused (roughly) every second time,
	the snapshot in slot one every fourth time, and so on.
.SS Forced Snapshot Removal
	In addition to the normal snapshot removal which takes place when a
	slot gets reused as described above, snapshots are
	.I force-removed
	when the utilization of a thin pool exceeds its configured
	thresholds. One snapshot is removed from each affected origin until
	the utilization drops below the thresholds. If the utilization still
	exceeds the thresholds after all snapshots have been removed, snapshot
	creation is suspended.
	.P
	Forced removal
	reliably prevents data and metadata exhaustion if the pool is
	not overbooked. That is, if the sum of the (virtual) sizes of the
	non-snapshot logical volumes is smaller than the pool size.
.SS Trimming
	The trim operation instructs a mounted filesystem to identify blocks
	which are currently not in use and to pass this information to the
	underlying block device driver. For a configured misma origin, this
	driver is
	.BR dm-thin ,
	which keeps track of the used and unused blocks of each thin pool.
	The blocks which are freed by the trim operation become available
	for subsequent snapshots.

	A one-shot trim operation is started by invoking the
	.B trim
	subcommand while periodic trims may be configured via the
	.I --trim-interval
	option of the
	.B run
	subcommand.

	Trimming is implemented by issuing the
	.I FITRIM
	ioctl on the mount point, which is identical to how the
	.BR fstrim (8)
	command works. The mount point is determined from the major and minor
	device numbers of the block special of the origin by parsing
	.IR /proc/self/mountinfo .
.SS Activating and Mounting Snapshots
	Since thin provisioned snapshots have the
	.I activation-skip
	flag set, one must first
	.I activate
	the snapshot logical volume to create the corresponding device node.

	Moreover, the XFS filesystem driver refuses to mount a block device
	which contains a UUID that is identical to the UUID of an already
	mounted filesystem. To mount a snapshot of an XFS filesystem, one
	must therefore tell XFS to skip the UUID check.

	See the examples below for suitable command line options for
	.BR lvchange (8)
	and
	. BR mount (8).

	Since logical volumes which contain a mounted filesystem cannot be
	removed, a thin pool which is not overbooked may still run out of
	space when one of its snapshot logical volumes is still mounted. It
	is therefore good practice to activate and mount snapshots only for
	as long as necessary.
[/section]

[section Examples]
	.IP \(bu 2
	Create a 1T large thin pool named
	.I tp
	in the volume group
	.IR vg :

	.RS 6
	.EX
		.B lvcreate \-\-type thin\-pool \-L 1T \-\-poolmetadatasize 16G \-n tp vg
	.EE
	.RE
	.IP \(bu 2
	Create the thin logical volume
	.I tlv
	of virtual size 100G in the thin pool
	.IR tp :

	.RS 6
	.EX
		.B lvcreate \-\-thin \-n tlv \-\-virtualsize 100G \-\-thinpool vg/tp
	.EE
	.RE
	.IP \(bu 2
	Run
	.B misma
	to create snapshots of the logical volume
	.IR tlv ,
	using default values:

	.RS 6
	.EX
		.B misma \-\-origin vg/tlv run
	.EE
	.RE
	.IP \(bu 2
	Same as before, but run
	.B misma
	as a background daemon to create a snapshot every hour:

	.RS 6
	.EX
		.B misma \-\-origin vg/tlv \-\-create-interval 1h \-\- run \-d
	.EE
	.RE
	.IP \(bu 2
	List all snapshots created so far:

	.RS 6
	.EX
		.B misma \-\-origin vg/tlv \-\- ls \-l
	.EE
	.RE
	.IP \(bu 2
	Run
	.B lvs
	to print similar information:

	.RS 6
	.EX
		.B vg=vg; o=tlv
		.B lvs -o 'lv_path,lv_attr,lv_time,origin' \[rs]
		.B \~ \-S \[dq]vg_name = $vg && origin = $o\[dq] \[rs]
		.B \~ \-\-config \[dq]report/time_format='%F %R'\[dq]
	.EE
	.RE
	.IP \(bu 2
	Activate snapshot number 42:

	.RS 6
	.EX
		.B lvchange \-\-ignoreactivationskip \-\-activate y vg/misma-tlv.42
	.EE
	.RE
	.IP \(bu 2
	Mount an active snapshot which contains an XFS filesystem:

	.RS 6
	.EX
		.B mount /dev/vg/misma-tlv.42 \-o nouuid /mnt
	.EE
	.RE
	.IP \(bu 2
	Terminate the
	.B misma
	daemon process:

	.RS 6
	.EX
		.B misma \-\-origin vg/tlv kill
	.EE
	.RE
	.IP \(bu 2
	A simple config file:

	.RS 6
	.EX
		# global options
		origin vg/tlv
		loglevel info
		# an option for the "run" subcommand
		[run]
		    logfile /var/log/misma.log
	.EE
	.RE

[/section]

[section copyright]
	Written by AUTHOR()
	.br
	Copyright (C) COPYRIGHT_YEAR() AUTHOR()
	.br
	License: LICENSE()
	.br
	This is free software: you are free to change and redistribute it.
	.br
	There is NO WARRANTY, to the extent permitted by law.
	.P
	Web page:
	.UR URL()
	.UE
	.br
	Git clone `URL':
	.UR CLONE_URL()
	.UE
	.br
	Gitweb:
	.UR GITWEB_URL()
	.UE
	.br
	Author's home page:
	.UR HOME_URL()
	.UE
	.br
	Report bugs to
	.MT EMAIL()
	AUTHOR()
	.ME
[/section]
[section see also]
	.BR lvm (8),
	.BR fstrim (8),
	.BR lvmthin (7),
	.BR dss (1)
[/section]