1 # SPDX-License-Identifier: GPL-2.0+
5 manual_title = System Manager's Manual
14 synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
18 summary = General options
21 summary = print help and exit
23 [option detailed-help]
24 summary = print help, including all details, and exit
26 summary = print version and exit
29 summary = control amount of logging
31 arg_info = required_arg
35 LSGLL_DEBUG = "debug",
37 LSGLL_NOTICE = "notice",
38 LSGLL_WARNING = "warning",
39 LSGLL_ERROR = "error",
45 Log only messages with severity greater or equal than the given
46 value. Possible values:
48 debug: produces really noisy output.
49 info: still noisy, but won't fill up the disk quickly.
50 notice: indicates normal, but significant event.
51 warning: unexpected events that can be handled.
52 error: unhandled error condition.
53 crit: system might be unreliable.
54 emerg: last message before exit.
58 summary = use alternative config file (default: ~/.mismarc)
60 arg_info = required_arg
63 Options may be given at the command line or in the configuration
64 file. As usual, if an option is given both at the command line and
65 in the configuration file, the command line option takes precedence.
67 The config file may contain global options as well as options for
68 any subcommand, but subcommand specific options must be placed in a
69 separate section. See the Examples section of the man page.
76 summary = the VG and the thin LV to snapshot
78 arg_info = required_arg
82 The named volume group must exist and it must contain the named thin
83 logical volume. This option may be given multiple times where each
84 instance corresponds to one origin to snapshot.
87 Misma supports the subcommands described below. If no subcommand is
88 given, the list of available subcommands is shown and the program
89 terminates successfully without performing any further action.
93 purpose = create and prune snapshots, discard unused blocks
95 This is the main mode of operation. Snapshots are created and pruned
96 periodically, the thin pool utilization is monitored and filesystem
97 trims are scheduled as configured. The subcommand terminates only on
98 fatal errors or after a terminating signal was received.
102 summary = run as background daemon
104 If this option is given, the process detaches from the console and
105 continues to run in the background.
109 summary = where to write log output
110 arg_info = required_arg
113 default_val = /dev/null
115 This option is only honored if --daemon is given, in which case
116 log messages go to the given file. Otherwise the option is silently
117 ignored and log output is written to stderr.
119 [option create-interval]
120 summary = Time span between two subsequent snapshots
121 typestr = [lvmspec:]timespec
122 arg_info = required_arg
127 The lvm specifier determines to which origins this instance of the
128 option applies. If no specifier is given, the option applies to all
129 origins. Otherwise the specifier may be in one of the following forms:
130 <vg>: applies to all origins in VG vg, <vg|pool>: applies to all
131 origins in thin pool <pool> of VG vg, or <vg/tlv>: applies to origin
132 tlv of vg only. If more than one specifier match a particular origin,
133 the narrowest scoped one applies. The order of precedence is therefore
134 <vg/tlv>, <vg|pool>, <vg>, <global>.
136 The time specifier is an unsigned integer which is followed by a time
137 unit, a single character of the set {s,m,h,d,y} for seconds, minutes,
138 hours, days, and years.
141 summary = age of the oldest snapshot to keep
142 typestr = [lvmspec:]timespec
143 arg_info = required_arg
148 See --create-interval for the format of the lvm and time specifiers.
150 [option check-interval]
151 summary = the time period between two utilization checks
153 arg_info = required_arg
157 The utilization of all thin pools which contain at least one thin
158 logical volume specified as an argument to --origin are checked
159 periodically. See --create-interval for the format of the time
163 summary = high watermarks for snapshot removal (1-99)
164 typestr = [lvmspec:]data_threshold,meta_threshold
165 arg_info = required_arg
170 The threshold part of the argument is a comma-separated pair of
171 percentages between 1 and 99, inclusively. If the percentage of used
172 space in the data/metadata logical volume of the thin pool exceeds
173 the corresponding threshold value, forced snapshot removal kicks in
174 to bring back the utilization below the thresholds.
176 The format of the lvm specifier is described in the help text of
177 --create-interval. However, since the utilization is a property
178 of the pool, arguments of the form <vg/tlv> make no sense and are
181 [option trim-interval]
182 summary = discard unused blocks periodically
183 typestr = [lvmspec:]timespec
184 arg_info = required_arg
189 The argument specifies the duration between two successive trims. The
190 default value of zero deactivates this feature.
192 Trimming is performed in the same way as for the trim subcommand.
193 Errors related to trimming are logged but are otherwise ignored.
195 See --create-interval for the format of the specifiers.
198 summary = command to be executed before exit
200 arg_info = required_arg
204 One possible application for this hook is to inform system manager
205 that no more snapshots are going to be created.
207 A (quoted) string which describes the error that caused the termination is
208 appended to the given command and the resulting string is passed as a single
209 argument to /bin/sh -c.
211 [option suppress-lvm-warnings]
212 summary = quieten lvcreate(8) and lvremove(8)
217 purpose = create a snapshot of each matching origin
218 non-opts-name = [<lvmspec>]...
220 This creates one snapshot of each origin which matches the given lvm
221 specifier, ignoring creation intervals, maximal age and utilization
222 thresholds. If no specifiers are given, all origins are regarded as
223 matching so that one snapshot of each configured origin is created.
225 The subcommand fails if another "run", "create", or "remove" command
226 is currently running.
230 summary = just print which snapshot would be created
232 purpose = remove one snapshot of each matching origin
233 non-opts-name = [<lvmspec>]...
235 The remarks stated in the description of the "create" subcommand apply
236 for this subcommand as well.
240 summary = just print which snapshot would get removed
242 purpose = print the snapshot list of each origin
243 non-opts-name = [<lvmspec>]...
245 The list is sorted by snapshot creation date.
249 summary = use long listing format
251 The default output mode lists only the sequence number and the age
252 of each snapshot as human readable text. This option adds additional
256 purpose = signal another misma process
258 This sends a signal to the misma "run" process.
262 summary = send the given signal rather than SIGTERM
263 typestr = signal_number
264 arg_info = required_arg
268 The standard Unix semantics apply if the specified signal number
269 is zero. That is, no signal is actually sent, and the subcommand
270 exits successfully only if a misma "run" process exists.
274 summary = wait until the signalled process has terminated
276 This option is handy for system shutdown scripts which would like
277 to terminate the misma daemon process.
279 Without --wait the misma process which executes the kill subcommand
280 exits right after the kill(2) system call returns. At this point the
281 signalled process might still be alive (even if SIGKILL was sent).
282 If --wait is given, the process waits until the signalled process
283 has terminated or the timeout expires.
285 If --wait is not given, the kill subcommand exits successfully if
286 and only if the signal was sent (i.e., if there exists another misma
287 process to receive the signal). With --wait it exits successfully
288 if, additionally, the signalled process has terminated before the
291 It makes only sense to use the option for signals which terminate
295 purpose = discard unused blocks of origin LVs
296 non-opts-name = [<lvmspec>]...
298 Each matching origin LV is expected to contain a mounted and writable
299 filesystem. The subcommand is equivalent to running fstrim(8) on
300 the mountpoints of these filesystems. The full block range of each
301 origin LV is taken into account and the default minimal block size for
302 discards is used. This corresponds to the default values of fstrim(8).
306 summary = print the mount points, but do not trim
308 In dry-run mode the mount points are determined as usual, but the
309 command exits without starting any trim operation.
312 purpose = list available subcommands or print subcommand-specific help
313 non-opts-name = [subcommand]
315 Without any arguments, help prints the list of available
316 subcommands. When called with a subcommand name argument, it prints
317 the help text of the given subcommand.
321 summary = show the long help text
323 If the optional argument is supplied, the long help text contains the
324 synopsis, the purpose and the description of the specified subcommand,
325 followed by the option list including summary and help text of each
326 option. Without --long, the short help is shown instead. This omits
327 the description of the subcommand and the option help.
329 If no subcommand is supplied but --long is given, the list contains the
330 purpose of each subcommand.
332 [subcommand utilization]
333 purpose = show thin pool utilization
335 This prints the percentage of used blocks in the data and metadata
336 logical volumes of each pool.
338 [subcommand configtest]
339 purpose = run a configuration file syntax test
341 This subcommand checks the command line options and the configuration
342 file for syntactic correctness. It either reports "Syntax Ok" and
343 exits successfully or prints information about the first syntax error
344 detected and terminates with exit code 1.
349 Snapshots created by misma are named
350 .IR misma-origin.seq ,
353 is the name of the thin logical volume (i.e., the second component
358 is a sequence number.
359 .SS Snapshot Replacement Strategy
360 Assume that the arguments
369 days, respectively. These two quantities determine the length
371 of a sequence of snapshots such that
373 the first two snapshots are
377 the difference of the creation times between two consecutive snapshots
378 doubles at each step,
380 the first and the last snapshot are at least
386 maps each existing snapshot to a slot in an array
389 When a new snapshot has to be created and not all slots are mapped
390 yet, the new snapshot is mapped to an unmapped slot. If all slots
391 are mapped, an existing snapshot is removed first and its slot is
392 reused. The slot number of the snapshot to be replaced is computed as
393 .B ffz(seq % (2^n - 1)),
396 is the sequence number of the new snapshot, and
399 the binary representation of
403 function, the frequency at which a slot gets reused halves at each
404 step: the snapshot in slot 0 gets reused (roughly) every second time,
405 the snapshot in slot one every fourth time, and so on.
406 .SS Forced Snapshot Removal
407 In addition to the normal snapshot removal which takes place when a
408 slot gets reused as described above, snapshots are
410 when the utilization of a thin pool exceeds its configured
411 thresholds. One snapshot is removed from each affected origin until
412 the utilization drops below the thresholds. If the utilization still
413 exceeds the thresholds after all snapshots have been removed, snapshot
414 creation is suspended.
417 reliably prevents data and metadata exhaustion if the pool is
418 not overbooked. That is, if the sum of the (virtual) sizes of the
419 non-snapshot logical volumes is smaller than the pool size.
421 The trim operation instructs a mounted filesystem to identify blocks
422 which are currently not in use and to pass this information to the
423 underlying block device driver. For a configured misma origin, this
426 which keeps track of the used and unused blocks of each thin pool.
427 The blocks which are freed by the trim operation become available
428 for subsequent snapshots.
430 A one-shot trim operation is started by invoking the
432 subcommand while periodic trims may be configured via the
438 Trimming is implemented by issuing the
440 ioctl on the mount point, which is identical to how the
442 command works. The mount point is determined from the major and minor
443 device numbers of the block special of the origin by parsing
444 .IR /proc/self/mountinfo .
445 .SS Activating and Mounting Snapshots
446 Since thin provisioned snapshots have the
448 flag set, one must first
450 the snapshot logical volume to create the corresponding device node.
452 Moreover, the XFS filesystem driver refuses to mount a block device
453 which contains a UUID that is identical to the UUID of an already
454 mounted filesystem. To mount a snapshot of an XFS filesystem, one
455 must therefore tell XFS to skip the UUID check.
457 See the examples below for suitable command line options for
462 Since logical volumes which contain a mounted filesystem cannot be
463 removed, a thin pool which is not overbooked may still run out of
464 space when one of its snapshot logical volumes is still mounted. It
465 is therefore good practice to activate and mount snapshots only for
466 as long as necessary.
471 Create a 1T large thin pool named
478 .B lvcreate \-\-type thin\-pool \-L 1T \-\-poolmetadatasize 16G \-n tp vg
482 Create the thin logical volume
484 of virtual size 100G in the thin pool
489 .B lvcreate \-\-thin \-n tlv \-\-virtualsize 100G \-\-thinpool vg/tp
495 to create snapshots of the logical volume
497 using default values:
501 .B misma \-\-origin vg/tlv run
505 Same as before, but run
507 as a background daemon to create a snapshot every hour:
511 .B misma \-\-origin vg/tlv \-\-create-interval 1h \-\- run \-d
515 List all snapshots created so far:
519 .B misma \-\-origin vg/tlv \-\- ls \-l
525 to print similar information:
530 .B lvs -o 'lv_path,lv_attr,lv_time,origin' \[rs]
531 .B \~ \-S \[dq]vg_name = $vg && origin = $o\[dq] \[rs]
532 .B \~ \-\-config \[dq]report/time_format='%F %R'\[dq]
536 Activate snapshot number 42:
540 .B lvchange \-\-ignoreactivationskip \-\-activate y vg/misma-tlv.42
544 Mount an active snapshot which contains an XFS filesystem:
548 .B mount /dev/vg/misma-tlv.42 \-o nouuid /mnt
558 .B misma \-\-origin vg/tlv kill
562 A simple config file:
569 # an option for the "run" subcommand
571 logfile /var/log/misma.log
580 Copyright (C) COPYRIGHT_YEAR() AUTHOR()
584 This is free software: you are free to change and redistribute it.
586 There is NO WARRANTY, to the extent permitted by law.