misma.suite.m4

   1 # SPDX-License-Identifier: GPL-2.0+
   2 [suite misma]
   3         caption = Subcommands
   4         mansect = 8
   5         manual_title = System Manager's Manual
   6 [supercommand misma]
   7         [description]
   8                 DESCRIPTION1()
   9
  10                 DESCRIPTION2()
  11
  12                 DESCRIPTION3()
  13         [/description]
  14         synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
  15         purpose = SLOGAN()
  16
  17         [option title-text]
  18                 summary = General options
  19                 flag ignored
  20         [option help]
  21                 summary = print help and exit
  22                 short_opt = h
  23         [option detailed-help]
  24                 summary = print help, including all details, and exit
  25         [option version]
  26                 summary = print version and exit
  27                 short_opt = V
  28         [option loglevel]
  29                 summary = control amount of logging
  30                 short_opt = l
  31                 arg_info = required_arg
  32                 arg_type = string
  33                 typestr = severity
  34                 values = {
  35                         LSGLL_DEBUG = "debug",
  36                         LSGLL_INFO = "info",
  37                         LSGLL_NOTICE = "notice",
  38                         LSGLL_WARNING = "warning",
  39                         LSGLL_ERROR = "error",
  40                         LSGLL_CRIT = "crit",
  41                         LSGLL_EMERG = "emerg"
  42                 }
  43                 default_val = warning
  44                 [help]
  45                         Log only messages with severity greater or equal than the given
  46                         value. Possible values:
  47
  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.
  55                 [/help]
  56         [option config-file]
  57                 short_opt = c
  58                 summary = use alternative config file (default: ~/.mismarc)
  59                 typestr = path
  60                 arg_info = required_arg
  61                 arg_type = string
  62                 [help]
  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.
  66
  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.
  70                 [/help]
  71
  72         [option title-text]
  73                 summary = LVM options
  74                 flag ignored
  75         [option origin]
  76                 summary = the VG and the thin LV to snapshot
  77                 typestr = vg/tlv
  78                 arg_info = required_arg
  79                 arg_type = string
  80                 flag multiple
  81                 [help]
  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.
  85                 [/help]
  86 [introduction]
  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.
  90 [/introduction]
  91
  92 [subcommand run]
  93         purpose = create and prune snapshots, discard unused blocks
  94         [description]
  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.
  99         [/description]
 100         [option daemon]
 101                 short_opt = d
 102                 summary = run as background daemon
 103                 [help]
 104                         If this option is given, the process detaches from the console and
 105                         continues to run in the background.
 106                 [/help]
 107         [option logfile]
 108                 short_opt = l
 109                 summary = where to write log output
 110                 arg_info = required_arg
 111                 arg_type = string
 112                 typestr = path
 113                 default_val = /dev/null
 114                 [help]
 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.
 118                 [/help]
 119         [option create-interval]
 120                 summary = Time span between two subsequent snapshots
 121                 typestr = [lvmspec:]timespec
 122                 arg_info = required_arg
 123                 arg_type = string
 124                 flag multiple
 125                 default_val = 6h
 126                 [help]
 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>.
 135
 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.
 139                 [/help]
 140         [option max-age]
 141                 summary = age of the oldest snapshot to keep
 142                 typestr = [lvmspec:]timespec
 143                 arg_info = required_arg
 144                 arg_type = string
 145                 flag multiple
 146                 default_val = 1y
 147                 [help]
 148                         See --create-interval for the format of the lvm and time specifiers.
 149                 [/help]
 150         [option check-interval]
 151                 summary = the time period between two utilization checks
 152                 typestr = timespec
 153                 arg_info = required_arg
 154                 arg_type = string
 155                 default_val = 1m
 156                 [help]
 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
 160                         specifier.
 161                 [/help]
 162         [option threshold]
 163                 summary = high watermarks for snapshot removal (1-99)
 164                 typestr = [lvmspec:]data_threshold,meta_threshold
 165                 arg_info = required_arg
 166                 arg_type = string
 167                 flag multiple
 168                 default_val = 95,95
 169                 [help]
 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.
 175
 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
 179                         therefore rejected.
 180                 [/help]
 181         [option trim-interval]
 182                 summary = discard unused blocks periodically
 183                 typestr = [lvmspec:]timespec
 184                 arg_info = required_arg
 185                 arg_type = string
 186                 flag multiple
 187                 default_val = 0
 188                 [help]
 189                         The argument specifies the duration between two successive trims. The
 190                         default value of zero deactivates this feature.
 191
 192                         Trimming is performed in the same way as for the trim subcommand.
 193                         Errors related to trimming are logged but are otherwise ignored.
 194
 195                         See --create-interval for the format of the specifiers.
 196                 [/help]
 197         [option exit-hook]
 198                 summary = command to be executed before exit
 199                 typestr = command
 200                 arg_info = required_arg
 201                 arg_type = string
 202                 default_val = true
 203                 [help]
 204                         One possible application for this hook is to inform system manager
 205                         that no more snapshots are going to be created.
 206
 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.
 210                 [/help]
 211         [option suppress-lvm-warnings]
 212                 summary = quieten lvcreate(8) and lvremove(8)
 213                 [help]
 214                         suppress
 215                 [/help]
 216 [subcommand create]
 217         purpose = create a snapshot of each matching origin
 218         non-opts-name = [<lvmspec>]...
 219         [description]
 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.
 224
 225                 The subcommand fails if another "run", "create", or "remove" command
 226                 is currently running.
 227         [/description]
 228         [option dry-run]
 229                 short_opt = n
 230                 summary = just print which snapshot would be created
 231 [subcommand rm]
 232         purpose = remove one snapshot of each matching origin
 233         non-opts-name = [<lvmspec>]...
 234         [description]
 235                 The remarks stated in the description of the "create" subcommand apply
 236                 for this subcommand as well.
 237         [/description]
 238         [option dry-run]
 239                 short_opt = n
 240                 summary = just print which snapshot would get removed
 241 [subcommand ls]
 242         purpose = print the snapshot list of each origin
 243         non-opts-name = [<lvmspec>]...
 244         [description]
 245                 The list is sorted by snapshot creation date.
 246         [/description]
 247         [option long]
 248                 short_opt = l
 249                 summary = use long listing format
 250                 [help]
 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
 253                         output.
 254                 [/help]
 255 [subcommand kill]
 256         purpose = signal another misma process
 257         [description]
 258                 This sends a signal to the misma "run" process.
 259         [/description]
 260         [option signal]
 261                 short_opt = s
 262                 summary = send the given signal rather than SIGTERM
 263                 typestr = signal_number
 264                 arg_info = required_arg
 265                 arg_type = uint32
 266                 default_val = 15
 267                 [help]
 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.
 271                 [/help]
 272         [option wait]
 273                 short_opt = w
 274                 summary = wait until the signalled process has terminated
 275                 [help]
 276                         This option is handy for system shutdown scripts which would like
 277                         to terminate the misma daemon process.
 278
 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.
 284
 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
 289                         timeout expires.
 290
 291                         It makes only sense to use the option for signals which terminate
 292                         the misma process.
 293                 [/help]
 294 [subcommand trim]
 295         purpose = discard unused blocks of origin LVs
 296         non-opts-name = [<lvmspec>]...
 297         [description]
 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).
 303         [/description]
 304         [option dry-run]
 305                 short_opt = n
 306                 summary = print the mount points, but do not trim
 307                 [help]
 308                         In dry-run mode the mount points are determined as usual, but the
 309                         command exits without starting any trim operation.
 310                 [/help]
 311 [subcommand help]
 312         purpose = list available subcommands or print subcommand-specific help
 313         non-opts-name = [subcommand]
 314         [description]
 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.
 318         [/description]
 319         [option long]
 320                 short_opt = l
 321                 summary = show the long help text
 322                 [help]
 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.
 328
 329                         If no subcommand is supplied but --long is given, the list contains the
 330                         purpose of each subcommand.
 331                 [/help]
 332 [subcommand utilization]
 333         purpose = show thin pool utilization
 334         [description]
 335                 This prints the percentage of used blocks in the data and metadata
 336                 logical volumes of each pool.
 337         [/description]
 338 [subcommand configtest]
 339         purpose = run a configuration file syntax test
 340         [description]
 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.
 345         [/description]
 346
 347 [section Notes]
 348 .SS Naming
 349         Snapshots created by misma are named
 350         .IR misma-origin.seq ,
 351         where
 352         .I origin
 353         is the name of the thin logical volume (i.e., the second component
 354         of the argument to
 355         .I --origin)
 356         and
 357         .I seq
 358         is a sequence number.
 359 .SS Snapshot Replacement Strategy
 360         Assume that the arguments
 361         to
 362         .I --create-interval
 363         and
 364         .I --max-age
 365         correspond to
 366         .I d
 367         minutes and
 368         .I m
 369         days, respectively. These two quantities determine the length
 370         .I n
 371         of a sequence of snapshots such that
 372         .IP \(bu 2
 373                 the first two snapshots are
 374         .I d
 375         minutes apart,
 376         .IP \(bu 2
 377                 the difference of the creation times between two consecutive snapshots
 378                 doubles at each step,
 379         .IP \(bu 2
 380                 the first and the last snapshot are at least
 381         .I m
 382         days apart.
 383         .P
 384         At startup,
 385         .B misma
 386         maps each existing snapshot to a slot in an array
 387         of length
 388         .IR n .
 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)),
 394         where
 395         .I seq
 396         is the sequence number of the new snapshot, and
 397         .B ffz(x)
 398         is the first zero in
 399         the binary representation of
 400         .IR x .
 401         By properties of the
 402         .B ffz()
 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
 409         .I force-removed
 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.
 415         .P
 416         Forced removal
 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.
 420 .SS Trimming
 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
 424         driver is
 425         .BR dm-thin ,
 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.
 429
 430         A one-shot trim operation is started by invoking the
 431         .B trim
 432         subcommand while periodic trims may be configured via the
 433         .I --trim-interval
 434         option of the
 435         .B run
 436         subcommand.
 437
 438         Trimming is implemented by issuing the
 439         .I FITRIM
 440         ioctl on the mount point, which is identical to how the
 441         .BR fstrim (8)
 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
 447         .I activation-skip
 448         flag set, one must first
 449         .I activate
 450         the snapshot logical volume to create the corresponding device node.
 451
 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.
 456
 457         See the examples below for suitable command line options for
 458         .BR lvchange (8)
 459         and
 460         . BR mount (8).
 461
 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.
 467 [/section]
 468
 469 [section Examples]
 470         .IP \(bu 2
 471         Create a 1T large thin pool named
 472         .I tp
 473         in the volume group
 474         .IR vg :
 475
 476         .RS 6
 477         .EX
 478                 .B lvcreate \-\-type thin\-pool \-L 1T \-\-poolmetadatasize 16G \-n tp vg
 479         .EE
 480         .RE
 481         .IP \(bu 2
 482         Create the thin logical volume
 483         .I tlv
 484         of virtual size 100G in the thin pool
 485         .IR tp :
 486
 487         .RS 6
 488         .EX
 489                 .B lvcreate \-\-thin \-n tlv \-\-virtualsize 100G \-\-thinpool vg/tp
 490         .EE
 491         .RE
 492         .IP \(bu 2
 493         Run
 494         .B misma
 495         to create snapshots of the logical volume
 496         .IR tlv ,
 497         using default values:
 498
 499         .RS 6
 500         .EX
 501                 .B misma \-\-origin vg/tlv run
 502         .EE
 503         .RE
 504         .IP \(bu 2
 505         Same as before, but run
 506         .B misma
 507         as a background daemon to create a snapshot every hour:
 508
 509         .RS 6
 510         .EX
 511                 .B misma \-\-origin vg/tlv \-\-create-interval 1h \-\- run \-d
 512         .EE
 513         .RE
 514         .IP \(bu 2
 515         List all snapshots created so far:
 516
 517         .RS 6
 518         .EX
 519                 .B misma \-\-origin vg/tlv \-\- ls \-l
 520         .EE
 521         .RE
 522         .IP \(bu 2
 523         Run
 524         .B lvs
 525         to print similar information:
 526
 527         .RS 6
 528         .EX
 529                 .B vg=vg; o=tlv
 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]
 533         .EE
 534         .RE
 535         .IP \(bu 2
 536         Activate snapshot number 42:
 537
 538         .RS 6
 539         .EX
 540                 .B lvchange \-\-ignoreactivationskip \-\-activate y vg/misma-tlv.42
 541         .EE
 542         .RE
 543         .IP \(bu 2
 544         Mount an active snapshot which contains an XFS filesystem:
 545
 546         .RS 6
 547         .EX
 548                 .B mount /dev/vg/misma-tlv.42 \-o nouuid /mnt
 549         .EE
 550         .RE
 551         .IP \(bu 2
 552         Terminate the
 553         .B misma
 554         daemon process:
 555
 556         .RS 6
 557         .EX
 558                 .B misma \-\-origin vg/tlv kill
 559         .EE
 560         .RE
 561         .IP \(bu 2
 562         A simple config file:
 563
 564         .RS 6
 565         .EX
 566                 # global options
 567                 origin vg/tlv
 568                 loglevel info
 569                 # an option for the "run" subcommand
 570                 [run]
 571                     logfile /var/log/misma.log
 572         .EE
 573         .RE
 574
 575 [/section]
 576
 577 [section copyright]
 578         Written by AUTHOR()
 579         .br
 580         Copyright (C) COPYRIGHT_YEAR() AUTHOR()
 581         .br
 582         License: LICENSE()
 583         .br
 584         This is free software: you are free to change and redistribute it.
 585         .br
 586         There is NO WARRANTY, to the extent permitted by law.
 587         .P
 588         Web page:
 589         .UR URL()
 590         .UE
 591         .br
 592         Git clone `URL':
 593         .UR CLONE_URL()
 594         .UE
 595         .br
 596         Gitweb:
 597         .UR GITWEB_URL()
 598         .UE
 599         .br
 600         Author's home page:
 601         .UR HOME_URL()
 602         .UE
 603         .br
 604         Report bugs to
 605         .MT EMAIL()
 606         AUTHOR()
 607         .ME
 608 [/section]
 609 [section see also]
 610         .BR lvm (8),
 611         .BR fstrim (8),
 612         .BR lvmthin (7),
 613         .BR dss (1)
 614 [/section]