bss.help2man

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH BSS "1" "March 2024" "bss  (@@@VERSION@@@)" "User Commands"
.SH NAME
bss \- manual page for bss  (@@@VERSION@@@)
.SH DESCRIPTION
.SS "USAGE:"
.IP
bss [OPTIONS] SUBCOMMAND [PATH [ [ARG]...]
bss SUBCOMMAND [OPTIONS] [PATH [ [ARG]...]
.PP
"bss" is basically a "btrfs subvolume ..." command wrapper to create and
process historical snapshots with the intuitive snapshot subvolume name and
flexible data aging capabilities.
.PP
"bss" operates mostly on the btrfs subvolume pointed by the first optional
argument "PATH".  "PATH" can point to anywhere within this source btrfs
subvolume.  The default value for "PATH" is the current working directory (".")
when it is missing.  The internal variable "$FS_BASE" is the BASE directory of
this source btrfs subvolume.  (The use of tailing "/" in "PATH" is
insignificant and deprecated.)
.PP
"bss snapshot [PATH]" starts "snapshot" operation to create a btrfs readonly
snapshot of the source btrfs subvolume using "btrfs subvolume snapshot \fB\-r\fR ...".
The snapshot subvolume is named with ISO 8601 timestamp and TYPE specifier,
e.g.  '2020\-09\-02T11:51:50+00:00.single' and placed normally in the ".bss.d/"
directory relative to the "$FS_BASE" directory since BSS_SNAP_DEST" specified
in ".bss.conf" is null string.  This normal snapshot mode is intended to be
used for the user data.
.PP
"bss snapshot [PATH]" can place its snapshots outside of the "$FS_BASE"
directory by specifying "BSS_SNAP_DEST" in ".bss.conf" to point to somewhere on
the same btrfs but outside of the "$FS_BASE" directory.  This system snapshot
mode is intended to be used for the system data.
.PP
"bss process [PATH]" starts "process" operation to process existing snapshots
generated by "bss" according to their age.  "bss" checks the time interval
between them from the older ones to newer ones and makes them more sparse for
the older ones by removing some of them using parameters in ".bss.conf" in the
".bss.d/" directory.  This involves following actions:
.IP
* Secure minimum required free blocks (minimum FMIN %).
* Keep initial few (NMIN) snapshots unconditionally.
* Limit the maximum number of snapshots to NMAX.
.IP
* NMAX=0 is the special case and means no limit for number of snapshots.
.IP
* Before TMIN, keep snapshots unconditionally.
* Age snapshots with basically exponentially growing intervals with the
.IP
specified ratio (STEP 2%\-90%).
.IP
* After TMID, age snapshots more aggressively.
.IP
* Special handlings to keep some high priority snapshots stop.
* If TMID_ACTION=filter, content files of snapshots are filtered with the
.IP
script ".bss.fltr" at the ".bss.d/" directory.
.IP
* After TMAX, stop aging snapshots.
.IP
* TMAX=0 is the special case and means no limit for aging.
* If TMAX_ACTION=drop, drop subvolume after TMAX.
* If TMAX_ACTION=keep, keep subvolume after TMAX.
.PP
Subcommands such as "bss copy ...", "bss gather ..." which use "rsync" as
their backend tool work with non\-btrfs filesystem.
.PP
OPTIONS:
.TP
\fB\-t\fR,\-\-type TYPE
use TYPE instead of the default "single" for the snapshot
type.  If $BSS_TYPE is exported to bss, its value is used
as the default for TYPE instead. The automatic snapshot uses
"pre" (before APT), "post (after APT), "snap" (on systemd
timer), etc.. If "keep" is specified, the snapshot with it
will be kept forever under the normal aging process.
.TP
\fB\-c\fR,\-\-conf RC
use "RC.conf", "RC.fltr" etc. instead of their
default ".bss.conf", ".bss.fltr" etc.
.TP
\fB\-f\fR,\-\-force
force to reapply filter
.TP
\fB\-n\fR,\-\-noop
no file nor filesystem modification by prepending pertinent
internal commands with "echo __"
.TP
\fB\-h\fR,\-\-help
show this help
.TP
\fB\-\-version\fR
show version
.TP
\fB\-e\fR,\-\-echo
enable screen echo (default)
.TP
\fB\-E\fR,\-\-noecho
disable screen echo (default for bss under batch)
.TP
\fB\-l\fR,\-\-logger
enable systemd logger (default for active subcommands)
.TP
\fB\-L\fR,\-\-nologger
disable systemd logger (default for passive subcommands)
.TP
\fB\-m\fR,\-\-may
may execute snapshot or gather if possible
.TP
\fB\-q\fR,\-\-quiet
quiet (no notice messages, just warn/error messages)
.TP
\fB\-v\fR,\-\-verbose
verbose (with info messages)
.TP
\fB\-vv\fR
very verbose for debug (with info and debug messages)
.TP
\fB\-x\fR
trace on (trace shell code for debug)
.PP
SUBCOMMAND:
.TP
snapshot
make a readonly snapshot normally in the relative path ".bss.d/"
as "<ISO_8601_date>.<TYPE>"  (The default type is "single")
.TP
list
list all snapshots
.TP
age
assess aging status of all snapshots
.TP
overview
overview of all snapshots (wrapper for "bss \fB\-v\fR age >/dev/null")
.TP
process
process snapshots according to their aging status
.TP
copy
copy subvolume at the BASE directory (1st argument) to the
(remote) destination (2nd argument) using rsync
.TP
gather
gather listed local files in configuration files to the
".gather.dir" directory or to the ".gather.tar.gpg"
encrypted archive.
.TP
filter
create a filtered snapshot from the specified snapshot in
".bss.d/" as "<specified_subvol_name>_filter"
.TP
revert
make snapshot "<ISO_8601_date>.last" and replace the subvolume at
the BASE directory (1st argument) with the specified snapshot
"<ISO_8601_date>.<extension>" (2nd argument) found under
"BSS_SNAP_DEST" specified in ".bss.conf".  This is intended only
for the system snapshot mode. (This is experimental and untested
feature with limited capabilities.  Use with extra care!)
.TP
zap
zap (=delete) particular snapshot(s) specified by its arguments
("zap" is required to be typed in full text)
.TP
template
make template files in the ".bss.d/" directory:
.IP
* ".bss.conf" (aging rule)
* ".bss.fltr[.disabled]" (filtering rule)
.TP
batch FNB
change the current working directory to the user's home directory
and source the shell script found at:
.IP
* "$XDG_CONFIG_HOME/bss/FNB" (non\-root, $XDG_CONFIG_HOME set)
* "~/.config/bss/FNB" (non\-root, $XDG_CONFIG_HOME unset)
* "/etc/bss/FNB" (root)
.TP
BASE
print the BASE directory and its filesystem type for "bss"
.TP
jobs
list all systemd timer schedule jobs for bss
.PP
ARGUMENTS:
.PP
SUBCOMMANDs may be shortened to a single character.
.PP
For some SUBCOMMANDs, enxtra optional arguments after the explicit "PATH" may
be specified to provide arguments to them.
.PP
For "bss list", you may add the second argument to match snapshot "<TYPE>".
"bss list . '(s.*|u.*)' " should list snapshots with "single", "snap" and
"usb" types.
.PP
For "bss copy PATH DEST_PATH", this is a combination of "bss snapshot" to
create a snapshot of the "$FS_BASE" directory for "PATH" and a wrapper for
"rsync" command with its first argument "$FS_PATH" and the second argument
"DEST_PATH".  This command copy specified data recursively within filesystem
boundaries.  Thus subvolumes and mounted filesystems are excluded.  This
command is also smart enough to skip the ".bss.d/" directory on both the
"$FS_BASE" directory and "DEST_PATH" to allow independent snapshot management
of data using "bss" on both ends.  The use of "\-\-delete" option for "rsync"
is the intentional choice.  (The tailing "/" in "DEST_PATH" is removed.)
.PP
If "DEST_PATH" is a local path such as "/srv/backup", then
.IP
sudo rsync \fB\-aHxS\fR \fB\-\-delete\fR \fB\-\-mkpath\fR \fB\-\-filter=\fR"\- .bss.d/"
.PP
is used to have enough privilege and to save the CPU load.  If this local
"DEST_PATH" doesn't exist, it is created in advance as:
.IP
* a subvolume if it is on btrfs filesystem or,
* a subdirectory if it is on non\-btrfs filesystem.
.PP
If "DEST_PATH" is a local relative path without the leading  "/", then it is
treated as a relative path from the user's home directory.
.PP
If "DEST_PATH" is a remote path such as "[USER@]HOST:DEST_PATH", then
.IP
rsync \fB\-aHxSz\fR \fB\-\-delete\fR \fB\-\-mkpath\fR \fB\-\-filter=\fR"\- .bss.d/"
.PP
is used to limit privilege and to save the network load. Also, this allows
"bss copy" to use the SSH\-key stored by the user's home directory under
"~/.ssh/".
.PP
For "bss gather PATH", files and directories are gathered recursively using 4
configuration files found in the PATH directory (or more precisely in the
"$FS_BASE" directory).
.IP
* ".gather.dir.absrc" and ".gather.dir.relrc" gather files to the
.IP
".gather.dir" directory in the $FS_BASE directory.
.IP
* ".gather.gpg.absrc" and ".gather.gpg.relrc" gather files to the
.IP
".gather.tar.gpg" encrypted archive in the $FS_BASE directory.
.IP
* ".gather.dir.absrc" and ".gather.gpg.absrc" are for "/" directory
.IP
as the source.
.IP
* ".gather.dir.relrc" and ".gather.gpg.relrc" use the home
.IP
directory as the source.
.PP
This "bss gather" is essentially a wrapper for
.IP
rsync \fB\-aHS\fR \fB\-\-delete\-excluded\fR \fB\-\-mkpath\fR \fB\-\-filter=\fR"\- .bss.d/" \fB\-\-filter=\fR". .gather.*.*rc"
.PP
Unlike "bss copy", the recursive scope of "bss gather" is not limited within
filesystem volume nor subvolume.  The configuration files ".gather.*.*rc"
follow "FILTER RULES" in rsync(1) manpage.  If any of these are missing,
corresponding gather actions are skipped without error.  Even when error is
encountered, "bss gather" only emits logging messages and exits as success.
The use of "\-\-delete\-excluded" option for "rsync" is the intentional choice.
.PP
"bss zap" always operates on the current working directory as "PATH".  Thus
the first argument is not "PATH" but one of following action specifies:
.TP
new
zap (=delete) the newest snapshot subvolume
.TP
old
zap the oldest snapshot subvolume
.TP
half
zap the older half of snapshot subvolumes
.TP
<subvolume>
zap specified snapshot subvolume (path with or without
".../.bss.d/" such as "2020\-01\-01T00:00:00+00:00.single").
Multiple subvolumes may be specified.
.PP
Unless you have specific reasons to use "bss zap", you should consider to use
"bss process" to prune outdated snapshots.
.PP
For "bss revert PATH PATH_OLD", subvolume at PATH is replaced by the subvolume
at "PATH_OLD".  "PATH" can't be set to "/".
.PP
NOTE:
.PP
This "bss" command comes with examples for systemd scripts and apt hook script
to enable automatic "snapshot" operations.  This "bss" command also comes with
examples for systemd scripts to enable automatic daily "process" operation.
.PP
For some snapshots, different "TYPE" values may be used instead of its default
"single".  Notable ones are:
.TP
TYPE="pre"
automatic "snapshot" operation just before APT update
.TP
TYPE="post"
automatic "snapshot" operation just after  APT update
.TP
TYPE="copy"
automatic "snapshot" operation just before "bss copy"
.TP
TYPE="snap"
automatic "snapshot" operation on timer event
.TP
TYPE="usb"
automatic "snapshot" operation on mount event (USB Storage)
.TP
TYPE="last"
automatic "snapshot" operation just before "bss revert"
.PP
This "bss" calculates time values related to age in the second and prints them
in the DAYS.HH:MM:SS format (HH=hour, MM=minute, SS=second).
.PP
You can make a snapshot just by "bss" alone.
.PP
You can use verbose "bss \fB\-v\fR BASE" command to print current effective
configuration parameters without side effects.
.PP
This "bss" command can use systemd logger.  When used, the log of its
invocations can be viewed with:
.IP
\f(CW$ journalctl -a -b -t bss\fR
.br
\f(CW$ journalctl -f -t bss\fR
.PP
Although "bss" is focused on the snapshot operation for btrfs, subcommands
which use "rsync" as their backend can be used for backup operations from any
filesystem.  This design allows us to create nice snapshot backups to a btrfs
partition on USB or remote storage from any filesystem to ensure data
redundancies. For "bss template PATH" on non\-btrfs, ".bss.d/" directory and
related configuration files are created on "PATH" itself.  For "bss copy PATH
\&..." and "bss gather PATH" on non\-btrfs, the "$FS_BASE" directory is searched
from "PATH" and is set when ".bss.d/" is found.
.PP
CAVEAT:
.PP
The source filesystem must be btrfs for many subcommands.
.PP
The non\-root user who executes this command must be a member of "sudo".
.PP
"bss gather" may generate encrypted archive using GnuPG with the default key
normally set by "~/.gnupg/gpg.conf".  This GnuPG configuration file location
may be changed by the value of environment variable "$GNUPGHOME". You need to
have access to the corresponding secret key to decrypt such archived data.
Please ensure that you can decrypt the archive in advance.  Failing to do so
may cause you to lose data.  See gpg(1).
.PP
Running filter script ".bss.fltr" drains CPU and SSD resources but it may save
SSD usage size significantly.  If you are not interested in reducing SSD usage
size by this script, rename from ".bss.fltr" to ".bss.fltr.disabled" and set
BSS_TMID_ACTION="no_filter" in ".bss.conf".
.PP
The "revert" operation is supported only for the system snapshot mode which
sets BSS_SNAP_DEST in ".bss.conf" to non\-zero string.  APT updates can be
configured to create snapshots of the system using this system snapshot mode.
The "revert" operation can bring the system before the APT update operation.
This kind of "revert" operation must be performed from the secondary system on
another root filesystem and all subvolumes to be manipulated shouldn't be
accessed by other processes. You should manually mount using "/etc/fstab" for
all subvolumes under the subvolume to run "revert" operation and manage them
separately to keep the system recoverable since the snapshot operation isn't
recursive.
.SH AUTHOR
Written by Osamu Aoki.
.SH COPYRIGHT
Copyright 2022 \- 2024 Osamu Aoki <osamu@debian.org>, GPL 2+
.PP
.br
Copyright \(co 2021\-2024 Osamu Aoki <osamu@debian.org>
.PP
License GPLv2+: GNU GPL version 2 or later
<https://gnu.org/licenses/gpl\-2.0.html>.  This is free software: you are free
to change and redistribute it.  There is NO WARRANTY, to the extent permitted
by law.
.SH "SEE ALSO"
The full documentation for
.B bss
is maintained as a Texinfo manual.  If the
.B info
and
.B bss
programs are properly installed at your site, the command
.IP
.B info bss
.PP
should give you access to the complete manual.