Repository: automorphism88/snapraid-btrfs
Branch: master
Commit: 6492a45ad55c
Files: 3
Total size: 124.1 KB
Directory structure:
gitextract_gsa4f61f/
├── LICENSE
├── README.md
└── snapraid-btrfs
================================================
FILE CONTENTS
================================================
================================================
FILE: LICENSE
================================================
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
{one line to give the program's name and a brief idea of what it does.}
Copyright (C) {year} {name of author}
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
{project} Copyright (C) {year} {fullname}
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
.
================================================
FILE: README.md
================================================
# snapraid-btrfs
`snapraid-btrfs` is a script for using [SnapRAID](http://www.snapraid.it/) with
data drives which are formatted with btrfs. It allows operations such as
`snapraid sync` or `snapraid scrub` which do not write to the data drives to be
done using read-only snapshots, and when running SnapRAID operations which do
write to the data drives (i.e., `snapraid fix` and `snapraid touch`) it creates
before and after snapshots. It aims to be a transparent wrapper around the
`snapraid` command, allowing you to replace, e.g., `snapraid sync` with
`snapraid-btrfs sync`, and works by creating a temporary SnapRAID configuration
file where the data paths are replaced with those of corresponding read-only
snapshots, then running `snapraid` using the temporary configuration file.
Options appearing before the command (e.g., `sync` or `scrub`) control the
behavior of `snapraid-btrfs`, while options appearing after the command are
passed through to `snapraid`, with the exception of `-c`/`--conf`, which is
reserved for use by `snapraid-btrfs` to point `snapraid` to its temporary
configuration file, and which can instead be specified as a `snapraid-btrfs`
option, before the command, so that it can be processed by `snapraid-btrfs`
when creating the temporary SnapRAID config file. For example,
`snapraid-btrfs -c /foo/snapraid.conf sync -v` would run
`snapraid sync -c /tmp/example -v`, where `/tmp/example` was generated using
`/foo/snapraid.conf` instead of `/etc/snapraid.conf`. `snapraid-btrfs` also
implements additional commands, such as `cleanup`, for managing its snapshots.
## Setup instructions
To start using `snapraid-btrfs`, you need to set up
[snapper](http://snapper.io/) configurations for each data drive that you want
`snapraid-btrfs` to make snapshots of. At runtime, `snapraid-btrfs` will follow
the following procedure to find snapper configs:
- If the `--snapper-configs` or `--snapper-configs-file` command-line options
are set, look at only the configs specified there, and no others.
- Else, look at filenames in `/etc/snapper/configs` (or an alternate directory
specified by setting the `SNAPPER_CONFIG_DIR` environment variable) to get
the names of snapper configs. This directory should be readable by the user
running `snapraid-btrfs`, but the files inside it need not be.
- For each config found, attempt to read the `SUBVOLUME` variable using
`snapper get-config`. If this command fails (generally because the user is
not included in `ALLOW_USERS` or `ALLOW_GROUPS`), skip the config.
- If successful in reading `SUBVOLUME`, attempt to find a matching data drive
in the SnapRAID configuration file.
- If configs are specified with `--snapper-configs` or `--snapper-configs-file`
then `snapraid-btrfs` expects them all to match data drives in the SnapRAID
configuration file, and will display an error message and exit if
`snapper get-config` fails or `SUBVOLUME` does not match.
`snapraid-btrfs` will ignore any data drives which it does not find
corresponding snapper configs for (in other words, the live filesystem will be
used for all operations and no snapshots will be created. Just like SnapRAID,
`snapraid-btrfs` will use `/etc/snapraid.conf` by default, but another
configuration file can be specified using the `-c`/`--conf` option, or by
setting the `SNAPRAID_CONFIG_FILE` environment variable.
All files on the data drives which are not excluded by the SnapRAID
configuration file must be in the same subvolume. **If any of the SnapRAID
"content" files are stored on data drives, create a dedicated subvolume for
them so that they are not snapshotted.** It is also recommended that you add
the line `exclude /.snapshots/` to your SnapRAID configuration file, so that if
you ever run `snapraid sync` instead of `snapraid-btrfs sync`, SnapRAID will
not try to sync both the live filesystem and the read-only snapshots, causing
it to display a warning message about the snapshots being in a different
filesystem (since SnapRAID sees subvolumes as different filesystems, it will
not try to sync the snapshots in any case, so actual behavior is unaffected).
See the FAQ below for more details. To verify that snapper has been set up
correctly, you can use the `snapraid-btrfs ls` command, which will run
`snapper ls` for all of the snapper configurations that it recognizes as
matching data drives in your SnapRAID configuration file. If `snapraid-btrfs`
does not find all of the snapper configs you were expecting, try using the
`--verbose` option. Once you are satisfied that `snapraid-btrfs` has found all
of your configs, you are ready to run your first `snapraid-btrfs sync` which
will, by default, create new snapshots and use them for the sync. For more
details on using `snapraid-btrfs`, see the output of `snapraid-btrfs --help`.
## Dependencies
- [SnapRAID](http://www.snapraid.it/)
- [snapper](http://snapper.io/)
- [bash](https://www.gnu.org/software/bash/) (version 4.1+)
- awk, sed, grep, and coreutils (should all be installed by default in any
modern distro, and any POSIX-compliant versions should work, as nonportable
features are avoided)
All dependencies are checked on startup, and if any of them are not found,
`snapraid-btrfs` will display an error message and exit. Note that by default,
`snapraid-btrfs` will search for `snapraid` and `snapper` in the user's `PATH`,
but alternatively, the `--snapper-path` and/or `--snapraid-path` command line
options can be specified.
`#!/bin/bash` is used as the shebang (as the `#!/usr/bin/env bash` trick has
disadvantages), so if a compatible version of bash cannot be found there, one
of the following workarounds must be used:
- Create a symlink. This is generally already done on distros that have done
the `/usr` merge and install bash in `/usr/bin` instead of `/bin`.
- Run `snapraid-btrfs` using `/path/to/right/bash /path/to/snapraid-btrfs`,
possibly by creating a wrapper script or shell alias
- Manually edit the first line of the script to point to the correct location
## FAQ
### Q: Why use snapraid-btrfs?
A: A major disadvantage of SnapRAID is that the parity files are not updated in
realtime. This not only means that new files are not protected until after
running `snapraid sync`, but also creates a form of "write hole" where if files
are modified or deleted, some protection of other files which share the same
parity block(s) is lost until another sync is completed, since if other files
need to be restored using the `snapraid fix` command, the deleted or modified
files will not be available, just as if the disk had failed, or developed a bad
sector. This problem can be mitigated by adding additional parities, since
SnapRAID permits up to six, or worked around by temporarily moving files into a
directory that is excluded in your SnapRAID config file, then completing a sync
to remove them from the parity before deleting them. However, this problem is a
textbook use case for btrfs snapshots.
By using read-only snapshots when we do a `snapraid sync`, we ensure that if we
modify or delete files during or after the sync, we can always restore the
array to the state it was in at the time the read-only snapshots were created,
so long as the snapshots are not deleted until another sync is completed with
new snapshots. This use case for btrfs snapshots is similar to using
`btrfs send/receive` to back up a live filesystem, where the use of read-only
snapshots guarantees the consistency of the result, while using `dd` would
require that the entire filesystem be mounted read-only to prevent corruption
caused by writes to the live filesystem during the backup.
### Q: Are all SnapRAID commands supported?
A: Only the ones which either read from or write to the data drives, since for
the others (e.g. `snapraid smart`), there is no benefit to using btrfs
snapshots. Note that `snapraid-btrfs` does not interfere with the ability to
invoke SnapRAID directly, allowing you to use these commands, or any other
SnapRAID command, with `snapraid-btrfs` temporarily disabled.
### Q: Do I need to use btrfs for all of the data drives?
A: No. Any drives that don't have a corresponding snapper configuration will be
ignored (meaning that the live filesystem will be used). This allows you to
format data drives with any filesystem supported by SnapRAID. However, the
protection offered by `snapraid-btrfs` will not be available for writes made to
any data drives that it does not manage.
### Q: What about the parity drives?
A: Since the parity files are (or, at least, should be) only written to during
`snapraid sync` operations, there is no need to snapshot them, as the parity
files will always correspond with the read-only snapshots they were created
from. If a sync is interrupted, different sets of snapshots will correspond
with different portions of the parity file(s), and both sets of snapshots
should be retained until a sync is completed, at which point all previous
snapshots can be safely cleaned up. A snapper userdata key is used to keep
track of whether a `snapraid sync` run on a set of snapshots completes
successfully (i.e., returns exit status 0) to ensure that
`snapraid-btrfs cleanup` can handle this situation properly.
It is recommended that you use ext4 for the parity drives, since the metadata
overhead is extremely small with the right mkfs settings (minimum possible
number of inodes, minimum journal size (or journaling disabled), and no space
reserved for root - see `man mke2fs` for more details), and because for the
parity drives, there is no real use for any of the features which btrfs
offers over ext4.
### Q: What about the SnapRAID "content" files?
A: Just like the parity files, these do not need to be snapshotted. If they are
stored on the data drives, they should be in a dedicated subvolume, separate
from the one where the data is stored.
### Q: What about the space consumed by the snapshots?
A: Running out of parity space is not an issue (at least, no more of an issue
than it is without the use of snapshots), since only one snapshot at a time is
used for a sync. You may temporarily run out of space on the data drives if you
replace existing files with new data, but you can always free up that space by
doing a new sync with new snapshots, and then deleting the old snapshots using
the `snapraid-btrfs cleanup` command.
In the worst case (which occurs when the array is almost full), as changes are
made to the array, the use of snapshots will double the time spent syncing the
changes into the parity, but the capacity of the array will not be affected.
To the extent you do not have extra space to spare, after deleting files, you
will have to sync them out of the parity before the space they occupy can be
freed using `snapraid-btrfs cleanup`, allowing you to add new files, following
which a second sync operation would be required to add them to the parity.
If you have enough space to spare, you can add the new data before the initial
sync instead of waiting until after the post-sync cleanup, in which case the
speed of syncing is no different than without `snapraid-btrfs`. And you can
reduce the amount of free space required to avoid the worst-case behavior by
syncing more frequently, before the live filesystem diverges too much from the
snapshots, and always running `snapraid-btrfs cleanup` after each successful
sync.
This is an unavoidable limitation of the protection provided by
`snapraid-btrfs`, and the same price would be paid for any solution to the
problem `snapraid-btrfs` aims to solve - e.g. moving files to a directory which
is excluded in the SnapRAID config file before deleting them. To preserve the
ability to restore the array to the state it was in at the time of the last
sync even if files are modified or deleted, those files must be saved somewhere
until the parity has been brought up to date.
### Q: Does snapraid-btrfs need to be run as root?
A: No, and it is recommended that you do not do so, just as you should not run
SnapRAID as root.
### Q: Is there a snapraid-btrfs configuration file?
A: No. An explicit design goal of `snapraid-btrfs` is to not require a
configuration file of its own. Nor does it require a file to store state
information and keep track of its snapshots, because that information is stored
as snapper userdata.
### Q: How do I make sure my user (or group) has the necessary permissions?
A: Assuming you already have a working SnapRAID configuration, you just need to
configure snapper correctly. See "How do I set up snapper for use with
`snapraid-btrfs`?" below.
### Q: How do I configure snapper for use with snapraid-btrfs?
A: Create a snapper configuration for each data drive you want to use
`snapraid-btrfs` for, and make sure to set `SYNC_ACL=yes` in addition to
`ALLOW_USERS` or `ALLOW_GROUPS` for the user(s) and/or group(s) which will run
snapraid-btrfs in your snapper configurations. You may wish to make a snapper
template with the options you want to use for your SnapRAID drive
configurations and set these variables at that level. For further details, see
the snapper documentation.
### Q: What about my snapraid.conf file? Do I need to do anything there?
A: `snapraid-btrfs` is designed to work with your existing SnapRAID
configuration without requiring further changes. However, you may wish to add
the line `exclude /.snapshots/` to your config file. If you ever plan to sync
your SnapRAID configuration without using `snapraid-btrfs` (or disable it for
specific drives using the command-line options), SnapRAID will see the
`.snapshots` subvolume as a separate filesystem and warn you that it won't be
included in the parity. Excluding it explicitly will prevent you from receiving
this warning message from SnapRAID.
When using `snapraid-btrfs` to sync, the `.snapshots` subvolume will appear as
an empty directory in the read-only snapshots, so excluding it in the SnapRAID
config file is unnecessary, but harmless. (The `.snapshots` directory is
excluded relative to the root of the data drives, so if your data drive is
mounted at `/foo/bar` then if using snapshot n it will exclude
`/foo/bar/.snapshots/n/snapshot/.snapshots`, and if using the live filesystem
it will exclude `/foo/bar/.snapshots`.)
Similarly, if you store any of your content files in subvolumes which have
mountpoints underneath the data subvolume, you should `exclude` those paths to
avoid receiving warnings from SnapRAID. For instance, if data is stored in
`/path/to/snapraid/1/data` and content in `/path/to/snapraid/1/content` then
no `exclude` would be required, but if the content subvolume is mounted
underneath the data subvolume, e.g. at `/path/to/snapraid/1/data/content`, then
an `exclude` statement would be needed to avoid a warning from SnapRAID. See
"What about the SnapRAID content files?" below.
### Q: Can I have multiple subvolumes on a single data drive?
A: `snapraid-btrfs` only uses one subvolume per data drive, which should
contain all the data which is to be protected by SnapRAID, and should have a
snapper config with the `SUBVOLUME` variable matching the path in the SnapRAID
config file. **Any files stored in other subvolumes on the data drives will NOT
be protected by the parity, even if those subvolumes are mounted below the path
specified in the SnapRAID config file.** This is because syncs will be done
using a read-only snapshot, where the subvolume mount point will appear to
SnapRAID as an empty directory. Also, SnapRAID currently sees separate btrfs
subvolumes as separate filesystems, so this wouldn't work even without
using snapshots.
In any case, it's desirable to have all the SnapRAID data files in a single
subvolume, since this makes snapshotting atomic, ensuring that after a
successful sync, the parity corresponds to a single snapshot of each data
drive.
### Q: What about the SnapRAID content files?
The SnapRAID "content" files should be stored in a separate subvolume to
prevent them from being snapshotted. `snapraid-btrfs` will display an error
message and refuse to run if this is not done.
### Q: Can I also manage snapshots manually with snapper?
A: Yes. `snapraid-btrfs` keeps track of its own snapshots using a snapper
userdata key, and will ignore any snapshots without that userdata key defined.
If you delete `snapraid-btrfs` snapshots using snapper, parity protection may
be lost, so it is recommended that you use the `snapraid-btrfs cleanup` command
instead, which will only delete snapshots when it is safe to do so (and will
ignore any snapshots without that userdata key specified). If you need to free
up space by deleting old snapshots, it is recommended that you complete a new
sync with a fresh set of snapshots (which will initially require no space since
they will be identical to the live filesystem), then run the
`snapraid-btrfs cleanup` command to delete the old ones.
### Q: Can I change the snapper userdata key that is used to track snapshots?
A: Yes. If the `SNAPRAID_USERDATA_KEY` environment variable is set,
`snapraid-btrfs` will use that as its userdata key. Otherwise, it will default
to `snapraid-btrfs`. Beware that if you change this, snapshots created before
the change will no longer be identified as having been created by
`snapraid-btrfs`.
### Q: Can I restore a previous snapshot?
A: Just like with "vanilla" SnapRAID, a fix can only restore the array to the
state that it was in at the time of the last sync. This is because the parity
files can only correspond to one snapshot at a time, and is a fundamental
limitation of SnapRAID due to its file-based nature.
The purpose of `snapraid-btrfs` is simply to ensure that modifying the array
after a sync doesn't delete any of the data that would be required for the
fix operation. If you want multiple snapshots protected by parity, you'll
need to use another solution such as mdadm or btrfs RAID that operates at
the filesystem or block device level.
The above only refers to what is possible with `snapraid fix` (whether or not
invoked via `snapraid-btrfs fix`). Of course, you can still revert individual
data disks, or the entire array, to a previous state, just as with any btrfs
filesystem. You just won't be able to make use of the parity to reconstruct
data in older snapshots if a disk fails.
### Q: What is the 'dsync' command and what is it for?
A: Short for `diff-sync`, this command creates a set of read-only snapshots,
runs a `snapraid diff`, and then asks for confirmation before running a
`snapraid sync` with the same snapshots. Since SnapRAID can only restore the
array to the state it was in at the time of the last sync, syncing is a
destructive action, and the `dsync` command allows the user to make sure the
new snapshots are okay before continuing with the sync. Since the sync will
only be run after the user has approved the diff, the `--force-empty` option is
passed through to `snapraid`. The behavior of this command is equivalent to
running `snapraid-btrfs diff` followed by
`snapraid-btrfs --interactive --use-snapshot-all=diff sync --force-empty`,
except that `snapraid-btrfs dsync` will only run the sync if `snapraid diff`
indicates that there have been changes since the last sync. Otherwise,
`snapraid-btrfs dsync` will simply exit after the diff.
### Q: What about pooling?
A: If you run `snapraid-btrfs pool` the symlinks created in your pool directory
(or in the directory specified with the `--pool-dir` option) will be to the
read-only snapshots instead of the live filesystem. This may or may not be what
you want; if you want the symlinks to point to the live filesystem, you can
still use the `snapraid pool` command as normal, or you can even have both in
different directories by making use of the `--pool-dir` option. If you do use
`snapraid-btrfs pool` you should re-run it after each sync. This will not only
keep the symlinks up to date with any changes, but also ensures that a
`snapraid-btrfs cleanup` operation doesn't result in broken symlinks that point
to deleted snapshots.
### Q: How do I stop using snapraid-btrfs?
A: Just complete a full sync, invoking SnapRAID directly and not via
`snapraid-btrfs`. Then your parity files will be up to date with the live
filesystem, and you can safely delete all snapshots using
`snapraid-btrfs cleanup-all` and have a regular SnapRAID configuration.
## Known issues
* SnapRAID won't be able to properly detect the UUID when using a snapshot, so
it won't be able to use inodes to detect move operations. As a workaround, you
can temporarily disable `snapraid-btrfs`, either globally by doing a regular
`snapraid sync`, or for specific drives by doing a `snapraid-btrfs sync` using
the `-U` option to select snapshot 0 (i.e., the live filesystem, in snapper
terminology) for the drives in question, moving the files, doing another sync
with `snapraid-btrfs` disabled, and then reenabling `snapraid-btrfs` by doing a
normal `snapraid-btrfs sync`.
## License
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
================================================
FILE: snapraid-btrfs
================================================
#!/bin/bash -
# Copyright (C) 2017-2023 Alex deBeus
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
readonly COPYRIGHT_YEARS='2017-2023'
readonly DEFAULT_CONFIG_FILE=/etc/snapraid.conf
readonly DEFAULT_SNAPPER_CONFIG_DIR=/etc/snapper/configs
readonly DEFAULT_TMPDIR=/tmp
readonly DEFAULT_USERDATA_KEY=snapraid-btrfs
readonly E_MISSING_DEPENDENCY=63
readonly E_INTERNAL_ERROR=64
readonly E_INVALID_ARGUMENT=65
readonly E_INVALID_CONFIG=66
readonly E_NO_PERMISSION=67
readonly E_SNAPSHOT_NOT_FOUND=68
readonly E_INTERACTIVE_NO=69
# for use with awk
# mawk versions < 1.3.4 don't support [:lower:],
# so we use [$LOWER] instead for portability
readonly LOWER=abcdefghijklmnopqrstuvwxyz
readonly MY_VERSION='0.14.1+git'
# snapraid short options, sorted by whether or not they accept arguments
readonly SNAPRAID_OPTS_ARG=BCLScdfilop
readonly SNAPRAID_OPTS_NOARG=DEFGHLNRTUVZaehmqv
# bash version 4+ required for associative arrays, coprocesses, and
# ;& and ;;& terminators in case statements
# 4.1+ required for ACL support, <{var} fd variable assignment, and
# BASH_XTRACEFD
if [ -z "${BASH_VERSION-}" ] ||
! { ((BASH_VERSINFO[0] > 4)) ||
{ ((BASH_VERSINFO[0] == 4)) && ((BASH_VERSINFO[1] >= 1)) ; } ; }
then
echo 'bash version 4.1+ is required to use this script' >&2
exit ${E_MISSING_DEPENDENCY:-63}
fi
set -o errexit
set -o errtrace
set -o functrace
set -o noglob
set -o nounset
set -o pipefail
set +o noclobber
set +o posix
shopt -s dotglob
shopt -s extglob
shopt -s extquote
shopt -s nullglob
# Use lastpipe if available (bash 4.2+) since it's faster,
# but we don't need the behavior
shopt -s lastpipe &> /dev/null || true
# Add $1 to snapper_configs_specified array if not duplicate
add_snapper_config() {
[[ "${snapper_configs_specified_seen[$1]+x}" ]] ||
snapper_configs_specified+=( "$1" )
snapper_configs_specified_seen[$1]=1
}
# Apply the --pre-post and --no-pre-post command line options
apply_pre_post_options() {
local i j
if ((${#pre_post_option[@]} > 0)) ; then
for i in "${pre_post_option[@]}" ; do
config_must_exist "$i"
done
pre_post_configs=( "${pre_post_option[@]}" )
else
pre_post_configs=( "${snapper_configs[@]}" )
fi
if ((${#no_pre_post_option[@]} > 0)) ; then
local -a temp_array
for i in "${no_pre_post_option[@]}" ; do
config_must_exist "$i"
temp_array=()
for j in "${pre_post_configs[@]}" ; do
[[ "$j" = "$i" ]] || temp_array+=( "$j" )
done
pre_post_configs=( "${temp_array[@]}" )
done
fi
}
# apply the --snapper-configs-file command line option
apply_snapper_configs_file_option() {
[[ -r "$1" ]] ||
error $E_INVALID_CONFIG "$1 is not a readable file"
local config=
while IFS= read -r config || [[ "$config" ]] ; do
add_snapper_config "$config"
done < "$1"
}
# apply the --snapper-configs command line option
apply_snapper_configs_option() {
local -a configs
IFS=',' read -r -a configs <<< "$1"
local i
for i in "${configs[@]}" ; do
add_snapper_config "$i"
done
}
# Set use_snapshot from comma-separated key=value pairs specified in $1
apply_use_snapshot_option() {
local -a args
local config config_using i
IFS=',' read -r -a args <<< "$1"
for i in "${args[@]}" ; do
IFS='=' read -r config config_using <<< "$i"
config_must_exist "$config"
use_snapshot[$config]="$config_using"
done
}
# Prints a function call stack, not including itself
call_stack() {
local func line script
local -i frame=1
echo 'Call stack:'
while IFS=' ' read -r line func script ; do
printf -- '%s: %s: %s\n' "$script" "$func" "$line"
done < <(while caller $frame ; do ((++frame)) ; done)
}
# Sanity checks to run after reading configuration from
# snapraid.conf and snapper list-configs
check_config() {
if ((${#snapper_configs[@]} > 0)) ; then
check_content_files
check_snapper_configs
else
error_nonshell "$1" $E_INVALID_CONFIG \
"No snapper configs found for any data drives in $config_file"
fi
}
# Sanity checks to run before reading snapraid.conf file
check_config_file() {
if ! [[ -r "$config_file" ]] ; then
error_nonshell "$1" $E_INVALID_ARGUMENT \
"Could not read snapraid config file at $config_file"
return 0
fi
verbose "Using snapraid config file $config_file"
# check for trailing newline in snapraid.conf
# Lack of a trailing newline will cause problems.
# Therefore, if there is no trailing newline, create a
# temporary config file with a newline added and use that instead.
if [[ "$(tail -c 1 "$config_file")" ]] ; then
warn "No newline at end of $config_file"
local new_config_file
new_config_file="$(mktemp -- "$temp_dir/$my_name.XXXXXX")"
rm_on_exit+=( "$new_config_file" )
cat < "$config_file" > "$new_config_file"
echo >> "$new_config_file"
config_file="$new_config_file"
fi
}
# We don't want to snapshot the content files. So, check the
# directories of the content files, and compare their mount points with
# those of the subvolumes we are snapshotting, to see if any match
check_content_files() {
local field1 field2 content_dir content_mount i
while IFS=$' \t' read -r field1 field2 ; do
if [[ "$field1" = content ]] ; then
if [[ -f "$field2" ]] ; then
content_dir="$(dirname -- "$field2")"
if [[ -d "$content_dir" ]] ; then
content_mount="$(stat --format=%m -- "$content_dir")"
for i in "${snapper_configs[@]}" ; do
if [[ "$content_mount" -ef \
"${snapper_subvols[$i]}" ]]
then
error $E_INVALID_CONFIG \
"$field2 found in subvolume" \
"${snapper_subvols[$i]}" \
'- content files must be in separate subvolume'
fi
done
else
warn "content directory $content_dir not found"
fi
else
warn "content file $field2 not found"
fi
fi
done < "$config_file"
}
# Make sure all external binaries in $@ can be found
check_dependencies() {
while (($# > 0)) ; do
if ! type "$1" &> /dev/null ; then
error $E_MISSING_DEPENDENCY "Could not find dependency $1"
fi
shift
done
}
check_snapper_configs() {
local i
for i in "${snapper_configs[@]}" ; do
# Check that .snapshots subvolume exists
if ! is_btrfs_subvolume "${snapper_subvols[$i]}/.snapshots" ; then
error $E_INVALID_CONFIG "${snapper_subvols[$i]}/.snapshots" \
'is not a valid btrfs subvolume'
# Check that we have read permission for the .snapshots subvolume
# If not, try running snapper ls, in case ACLs need to be synced
elif ! { [[ -r "${snapper_subvols[$i]}/.snapshots" ]] ||
{ snapper_ls_sync_acl "$i" &&
[[ -r "${snapper_subvols[$i]}/.snapshots" ]] ; } ; }
then
error $E_NO_PERMISSION 'No read permission for' \
"${snapper_subvols[$i]}/.snapshots" \
'- is SYNC_ACL set in snapper configuration?'
fi
done
}
# Make sure the user hasn't tried to pass through the -c option to snapraid
check_snapraid_arguments() {
while (($# > 0)) ; do
case $1 in
--)
break ;;
--conf|-*(["$SNAPRAID_OPTS_NOARG"])c*)
error $E_INVALID_ARGUMENT \
"The -c/--conf option can't be passed through to snapraid"
;;
esac
if snapraid_opt_has_arg "$@" ; then
shift 2
else
shift
fi
done
}
cleanup_coproc_debug() {
[[ "${debug_fd}" ]] || return 0
trap - DEBUG
eval "${debug_fd:+exec ${debug_fd}>&-}"
eval "${sed_escape_debug[1]:+exec ${sed_escape_debug[1]}>&-}"
# shellcheck disable=2154
# Shellcheck doesn't understand named coprocesses
# See https://github.com/koalaman/shellcheck/issues/1066
eval "${sed_escape_debug_PID:+wait $sed_escape_debug_PID}"
debug_fd=
}
cleanup_coproc_xtrace() {
[[ "${xtrace_fd}" ]] || return 0
set +o xtrace
BASH_XTRACEFD="${xtrace_fd_old:-2}"
eval "${xtrace_fd:+exec ${xtrace_fd}>&-}"
eval "${sed_escape_xtrace[1]:+exec ${sed_escape_xtrace[1]}>&-}"
# shellcheck disable=2154
# Shellcheck doesn't understand named coprocesses
# See https://github.com/koalaman/shellcheck/issues/1066
eval "${sed_escape_xtrace_PID:+wait $sed_escape_xtrace_PID}"
xtrace_fd=
xtrace_fd_old=
}
cleanup_coprocs() {
cleanup_coproc_debug
cleanup_coproc_xtrace
}
# Run snapper rm on config $1, with $2, $3, ... specifying snapshots to delete
cleanup_snapshots() {
if (($# < 2)) ; then
return 0
fi
local config="$1"
shift
local -i ret
if ((interactive > 0)) ; then
snapper_ls_wrapper "$config" >&2
echo >&2
fi
verbose_command_run "$my_snapper" -c "$config" \
rm${sync:+ --sync} "$@" && true
ret=$?
if ((interactive > 0)) ; then
echo >&2
fi
return $ret
}
# Check that the user didn't specify a nonexistent snapper config by ensuring
# that a subvolume is set for the config name
config_must_exist() {
[[ "${snapper_subvols[$1]-}" ]] ||
error $E_INVALID_ARGUMENT "Invalid snapper configuration $1"
}
# Calling once creates pre snapshots, calling again creates corresponding post
create_pre_post_snapshots() {
local -a snapper_cmd
local post_snapshot i
for i in "${pre_post_configs[@]}" ; do
# skip configs where we're using a readonly snapshot
[[ "${use_snapshot[$i]}" = 0 ]] || continue
snapper_cmd=( "$my_snapper" -c "$i" create )
if [[ "$snapper_cleanup" ]] ; then
snapper_cmd+=( -c "$snapper_cleanup" )
fi
# Check if we've already done a pre snapshot
if [[ "${pre_snapshot[$i]-}" ]] ; then
# We've already done pre snapshots, so create corresponding post
if [[ "$snapper_description" ]] ; then
snapper_cmd+=( -d "$snapper_description" )
else
snapper_cmd+=( -d "$my_name post-$1" )
fi
snapper_cmd+=(
-u "$snapper_userdata$snapper_userdata_key=post-$1"
-t post
--pre-number "${pre_snapshot[$i]}"
-p
)
if post_snapshot="$("${snapper_cmd[@]}")" ; then
verbose "Created post snapshot" \
"${snapper_subvols[$i]}/.snapshots/$post_snapshot"
else
warn "Failed to create post snapshot for pre snapshot" \
"${snapper_subvols[$i]}/.snapshots/${pre_snapshot[$i]}"
fi
else
# We haven't created pre snapshots yet, so create them and store
# the snapshot numbers from snapper -p option in ${pre_snapshot[@]}
if [[ "$snapper_description" ]] ; then
snapper_cmd+=( -d "$snapper_description" )
else
snapper_cmd+=( -d "$my_name pre-$1" )
fi
snapper_cmd+=(
-u "$snapper_userdata$snapper_userdata_key=pre-$1"
-t pre
-p
)
pre_snapshot[$i]="$("${snapper_cmd[@]}")"
verbose "Created pre snapshot" \
"${snapper_subvols[$i]}/.snapshots/${pre_snapshot[$i]}"
fi
done
}
# display current state of variables
# DEBUG is trapped in enable_debug_mode()
debug_trap() {
local -r div='----------------------------------------'
printf -- '%s\n%s: %s%s\n' "$div" "$1" "$3" "$2"
shift 3
call_stack
printf -- '%s\n%s' "$div" 'set -- '
print_array "$@"
declare -p "${debug_vars[@]}"
printf -- '%s\n' "$div"
} >&"$debug_fd"
# get variable names to pass as arguments to declare -p
declare-p_vars() {
declare -p | declare-p_vars_awk "$@"
}
declare-p_vars_awk() {
local args
printf -v args -- '%s|' "$@"
args="${args%|}"
awk -f <(cat <<_EOF_
BEGIN {
FS = "[ \t=]+"
ORS = " "
}
/^declare -[-Aair]+ ($args)/ {
print \$3
}
_EOF_
)
}
declare-p_vars_debug() {
declare-p_vars "[$LOWER]" 'BASH' \
'(DEBUG_FD|FUNCNAME|IFS|MY_VERSION|PIPESTATUS|TMPDIR)='
}
declare-p_vars_shell() {
declare-p_vars "[_$LOWER]" 'LOWER=' '(COPYRIGHT|DEFAULT|E|MY|SNAPRAID)_'
}
# In each config, delete snapshots with userdata key $snapper_userdata_key
# older than use_snapshot[$i], or all such snapshots if use_snapshot[$i]=0
do_cleanup() {
local i j
local -i ret=0
local -i snapper_ret
local -a snapshots_to_consider snapshots_to_delete
for i in "${snapper_configs[@]}" ; do
# skip this config if we couldn't find a synced snapshot
if [[ -z "${use_snapshot[$i]}" ]] ; then
warn "No synced snapshot found for config $i - skipping"
continue
fi
IFS=' ' read -r -a snapshots_to_consider \
<<< "$(snapper_ls_wrapper "$i" 'C' |
parse_snapper_ls "$snapper_userdata_key" '' ' ')"
snapshots_to_delete=()
for j in "${snapshots_to_consider[@]}" ; do
if [[ "${use_snapshot[$i]}" -gt "$j" ]] ||
[[ "${use_snapshot[$i]}" = 0 ]]
then
snapshots_to_delete+=( "$j" )
fi
done
cleanup_snapshots "$i" "${snapshots_to_delete[@]}" && true
snapper_ret=$?
if ((snapper_ret != 0)) ; then
ret=$snapper_ret
fi
done
return $ret
}
# start interactive shell in context of script
do_shell() {
cleanup_coprocs
(
# shellcheck disable=2030
rm_on_exit=()
local _funcs _vars
local -a _funcs_arr _vars_arr
_funcs="$(declare -F |
awk -v ORS=' ' "/^declare -f [$LOWER]/{print \$3}")"
IFS=' ' read -r -a _funcs_arr <<< "$_funcs"
IFS=' ' read -r -a _vars_arr <<< "$(declare-p_vars_shell)"
_vars="$(declare -p "${_vars_arr[@]}")"
export BASHOPTS SHELLOPTS _funcs _vars
export -f "${_funcs_arr[@]}"
set +o errexit
set +o nounset
exec "$BASH" --rcfile \
<(cat <<'_EOF_'
eval "$_vars"
export -fn "${_funcs_arr[@]}"
export -n BASHOPTS SHELLOPTS
unset -v _funcs _vars _funcs_arr _vars_arr
trap 'exit_trap' EXIT
exit() {
printf -- 'Hooked exit command with status %s\n' "${1:-$?}"
printf -- 'Use quit to exit the %s interactive shell\n' "$my_name"
}
quit() {
command exit "${@:-0}"
}
vars() {
local -a _vars_arr
IFS=' ' read -r -a _vars_arr <<< "$(declare-p_vars_debug)"
declare -p "${_vars_arr[@]}"
}
if [[ -e "$HOME/.bashrc" ]] ; then
source "$HOME/.bashrc"
fi
if ((verbose >= 0)) ; then
cat <<__EOF__
Started interactive bash session in $my_name context.
Commands:
quit - exit the interactive shell
vars - display variable values
__EOF__
fi
_EOF_
) -O extglob -i "$@"
)
}
# run the specified snapper command on each config
do_snapper() {
local i
for i in "${snapper_configs[@]}" ; do
if [[ "${use_snapshot[$i]}" = 0 ]] ; then
continue
else
verbose_command_run "$my_snapper" -c "$i" "$@"
fi
done
}
# Set DEBUG trap to display variables with each command
enable_debug_mode() {
IFS=' ' read -r -a debug_vars <<< "$(declare-p_vars_debug)"
cleanup_coproc_debug
local debug_out_fd
if [[ "$debug_file" ]] ; then
exec {debug_out_fd}>"$debug_file"
else
debug_out_fd="${DEBUG_FD:-2}"
fi
coproc sed_escape_debug {
sed_escape_output
} >&"${debug_out_fd}"
exec {debug_fd}<&"${sed_escape_debug[1]}"
# shellcheck disable=1004
trap 'debug_trap "$LINENO" "$BASH_COMMAND" \
"${FUNCNAME[0]:+${FUNCNAME[0]}(): }" "$@"' DEBUG
}
enable_debug_modes() {
if ((debug_mode > 0)) ; then
enable_debug_mode
fi
if ((xtrace_mode > 0)) ; then
enable_xtrace_mode
fi
}
# Use sed coproc to escape BASH_XTRACEFD
enable_xtrace_mode() {
cleanup_coproc_xtrace
local xtrace_out_fd
if [[ "$xtrace_file" ]] ; then
exec {xtrace_out_fd}>"$xtrace_file"
else
xtrace_out_fd="${BASH_XTRACEFD:-2}"
fi
xtrace_fd_old="${BASH_XTRACEFD:-2}"
coproc sed_escape_xtrace {
sed_escape_output
} >&"${xtrace_out_fd}"
exec {xtrace_fd}<&"${sed_escape_xtrace[1]}"
BASH_XTRACEFD="$xtrace_fd"
set -o xtrace
}
# Intended to be called by ERR trap. Accepts the following arguments:
# $1 - Line number where ERR condition occurred
# $2 - Command that caused the ERR condition
# $3 - Exit status that caused the ERR condition
err_trap() {
trap - DEBUG
printf -- '%s: %s: %s failed%s\n' "$my_name" "${1:-0}" \
"${2:-unknown command}" "${3:+ with exit status $3}"
call_stack
exit "${3:-$E_INTERNAL_ERROR}"
} >&2
# $1 - exit status to exit with
# $2,$3,... - error message to print as $* after shifting
error() {
local -i errno="${1-}"
if ((errno < 1)) || ((errno > 255)) ; then
printf -- 'error called with invalid exit status %s\n' "${1:-(none)}"
errno="$E_INTERNAL_ERROR"
fi
shift || true
printf -- '%s: ' "$my_name"
print_array "${@:-fatal error}"
case $errno in
"$E_INVALID_ARGUMENT")
printf -- 'Use %s -h for help\n' "$my_name" ;;
esac
exit "$errno"
} >&2
# error if not running the shell command, otherwise warning
# $1 - command being run
# $2,$3,... - args to pass to error() if $1 != shell
error_nonshell() {
if ! { [[ "$1" =~ ^[a-z-]*$ ]] && [[ "$2" =~ ^[0-9]*$ ]] ; } ; then
error $E_INTERNAL_ERROR \
'error_nonshell() called with invalid arguments'
elif [[ "$1" = 'shell' ]] ; then
shift 2
warn "$@" '- ignoring to start interactive shell'
else
shift
error "$@"
fi
}
# Intended to be called by EXIT trap
# Removes rm_on_exit if nonempty and cleans up coprocess if necessary
exit_trap() {
# shellcheck disable=2031
if ((${#rm_on_exit[@]} > 0)) ; then
rm -f -- "${rm_on_exit[@]}" || true
fi
cleanup_coprocs
}
# remove -h / --pre-hash from snapraid arguments
# used with diff-sync command since -h is only supported with sync command
filter_pre_hash_option() {
local args=()
local i
for i in "$@" ; do
if [[ "$i" =~ !(-h|--pre-hash) ]] ; then
args+=( "$i" )
fi
done
print_array "${args[@]}"
}
find_configs() {
if ((${#snapper_configs_specified[@]} > 0)) ; then
find_configs_specified
else
find_configs_snapper_get-config "$@"
fi
}
# if the user has specified --snapper-configs and/or --snapper-configs-file
# command line options, use them to find snapper configs
find_configs_specified() {
local i
for i in "${snapper_configs_specified[@]}" ; do
find_configs_try "$i" && true
case $? in
1)
error $E_INVALID_CONFIG \
"SUBVOLUME for config $i not found in $config_file" ;;
2)
error $E_INVALID_CONFIG \
"Failed to run snapper get-config for config $i" ;;
esac
done
verbose
}
# try snapper get-config for all configs found in /etc/snapper/configs
# and look for SUBVOLUME matching /etc/snapraid.conf
find_configs_snapper_get-config() {
local config dir i
local -a files
dir="${SNAPPER_CONFIG_DIR-$DEFAULT_SNAPPER_CONFIG_DIR}"
if ! [[ -d "$dir" ]] ; then
error $E_INVALID_CONFIG "$dir is not a directory"
elif ! [[ -r "$dir" ]] ; then
error $E_NO_PERMISSION "No read permission for $dir"
fi
set +o noglob
files=( "$dir"/* )
set -o noglob
if (("${#files[@]}" == 0)) ; then
error_nonshell "$1" $E_INVALID_CONFIG "No files in $dir"
fi
for i in "${files[@]}" ; do
config="$(basename -- "$i")"
find_configs_try "$config" && true
case $? in
1)
verbose \
"SUBVOLUME for config $config not found in $config_file" ;;
2)
verbose \
"Failed to run snapper get-config for config $config" ;;
esac
done
verbose
}
# Try to find a match between the snapper config $1 and snapraid.conf and
# add it to snapper_configs array if successful
# return 0 if $1 matches snapraid.conf
# return 1 if $1 doesn't match snapraid.conf
# return 2 if we couldn't run snapper get-config for $1
find_configs_try() {
local config field1 field2 field3 found subvol
config="$1"
found=
if subvol="$("$my_snapper" -c "$config" get-config 2>/dev/null |
sed -e '/^SUBVOLUME /!d' -e 's/^SUBVOLUME[ ]*| //')"
then
while IFS=$' \t' read -r field1 field2 field3 ; do
if [[ "$field1" =~ ^(data|disk)$ ]] &&
[[ "$field3" -ef "$subvol" ]]
then
found=1
snapper_configs+=( "$config" )
snapper_subvols[$config]="$subvol"
snapraid_names[$config]="$field2"
fi
done < "$config_file"
if [[ "$found" ]] ; then
verbose \
"Found $subvol in $config_file - using snapper config $config"
return 0
else
return 1
fi
else
return 2
fi
}
# output the last snapshot number from config $1 matching userdata key $2
# (or any if $2 is undefined or empty)
find_snapshot() {
snapper_ls_wrapper "$1" 'C' |
parse_snapper_ls "$snapper_userdata_key" "${2:+$2}" |
tail -n 1
}
# replace keywords in use_snapshot with actual snapshot numbers, or with the
# empty string if a snapshot matching the keyword cannot be found
find_snapshots() {
local -i n=0
local i
for i in "${snapper_configs[@]}" ; do
use_snapshot_missing[$i]="${use_snapshot[$i]}"
case ${use_snapshot[$i]} in
0|'')
continue ;;
diff)
use_snapshot[$i]="$(find_snapshot "$i" 'diff')" ;;
last)
use_snapshot[$i]="$(find_snapshot "$i")" ;;
menu)
snapshot_menu "$i" "$1" ;;
new)
new_snapshot "$i" "$1" ;;
res?(ume))
use_snapshot[$i]="$(find_snapshot "$i" 'syncing,synced')" ;;
scrub)
use_snapshot[$i]="$(find_snapshot "$i" \
'syncing,synced,post-fix,post-touch')" ;;
sync)
use_snapshot[$i]="$(find_snapshot "$i" 'synced')" ;;
+([0123456789]))
if ! { snapper_ls_wrapper "$i" 'C' |
parse_snapper_ls |
grep -Fx "${use_snapshot[$i]}" > /dev/null ; }
then
use_snapshot[$i]=
fi ;;
*)
error $E_INVALID_ARGUMENT \
'Could not understand snapshot selection' \
"${use_snapshot[$i]} for config $i" ;;
esac
if [[ "${use_snapshot[$i]}" ]] ; then
((++n))
use_snapshot_missing[$i]=
if [[ "${use_snapshot[$i]}" = '0' ]] ; then
verbose "Using live filesystem for config $i"
else
verbose "Using snapshot ${use_snapshot[$i]} for config $i"
fi
fi
done
if ((n > 0)) ; then
verbose
fi
}
# generate sed script to replace subvolume paths with corresponding snapshots
# (and pool directory, if --pool-dir is specified) and run it on snapraid.conf
generate_temp_snapraid_conf() {
local match_line new_path sed_find sed_replace i
local sed_exps=()
# sed BRE matching data line up to the point where the path starts
local -r data_line=$'^[ \t]*data[ \t]\{1,\}[^ \t]\{1,\}[ \t]\{1,\}'
if [[ "$pool_dir" ]] ; then
sed_exps+=( $'/^[ \t]*pool[ \t]\{1,\}/d'
"\$apool $pool_dir" )
fi
for i in "${snapper_configs[@]}" ; do
if [[ "${use_snapshot[$i]}" != 0 ]] ; then
new_path="${snapper_subvols[$i]}/.snapshots/"
new_path+="${use_snapshot[$i]}/snapshot"
if ! is_btrfs_subvolume "$new_path" ; then
error $E_SNAPSHOT_NOT_FOUND "Invalid snapshot $new_path"
elif ! [[ -r "$new_path" ]] ; then
error $E_NO_PERMISSION "No read permission for $new_path"
fi
# Escape special characters in paths so that they can be
# passed to sed as literal strings
sed_find="$(sed_escape_bre <<< "${snapper_subvols[$i]}")"
sed_replace="$(sed_escape_replacement <<< "$new_path")"
match_line="$data_line$sed_find"'\/\{0,1\}$'
# also match the deprecated token 'disk' using separate sed
# expression to avoid depending on the GNU extension \|
sed_exps+=( "/$match_line/s/$sed_find/$sed_replace/"
"/${match_line/data/disk}/s/$sed_find/$sed_replace/" )
fi
done
if ((${#sed_exps[@]} == 0)) ; then
cat < "$config_file"
else
sed -f <(printf -- '%s\n' "${sed_exps[@]}") -- "$config_file"
fi
}
# given the snapraid.conf name for a disk (e.g. d1 in disk d1 /foo/bar),
# find the corresponding snapper config name, if any
get_snapper_config_name() {
local i
for i in "${snapper_configs[@]}" ; do
if [[ "$1" = "${snapraid_names[$i]}" ]] ; then
printf -- '%s\n' "$i"
break
fi
done
}
get_snapper_version() {
"$my_snapper" --version | sed -n '1s/^[^0123456789]*//p'
}
interactive_ask() {
echo 'About to run the following command:'
print_array "$@"
local choice
while true ; do
read -r -p 'Do it [Y/N]? ' choice
case $choice in
[Yy]?([Ee][Ss]))
break ;;
[Nn]?([Oo]))
exit $E_INTERACTIVE_NO ;;
*)
echo 'Invalid choice. Please enter y or n.' ;;
esac
done
} >&2
invalid_argument() {
error $E_INVALID_ARGUMENT "Invalid argument $1"
}
# Returns:
# 0 if $1 is a btrfs subvolume
# 1 if $1 is an "empty subvolume" inside a snapshot
# 2 if $1 is an ordinary directory
# 3 if $1 is not a directory
# 4 if we couldn't determine the inode number with stat
is_btrfs_subvolume() {
[[ -d "$1" ]] || return 3
case $(stat --format=%i -- "$1") in
256)
return 0 ;;
2)
return 1 ;;
'')
return 4 ;;
*)
return 2 ;;
esac
}
main() {
check_dependencies awk basename cat dirname grep mktemp rm sed stat tail
# Declare "global" variables as local to main since they will be
# accessible from any functions called from main
# These variables are set during processing of command line arguments and
# snapraid/snapper configurations and are initialized to defaults here
# snapraid config file location
local config_file="${SNAPRAID_CONFIG_FILE:-$DEFAULT_CONFIG_FILE}"
# fd to send debug output to if -X/--debug is enabled
local debug_fd=
# --debug-file option argument
local debug_file=
# indicates whether the -X/--debug option has been enabled
local -i debug_mode=0
# array storing variables to print in DEBUG trap
local debug_vars=()
# indicates whether the -i/--interactive option has been enabled
local -i interactive=0
# filename of script determined at runtime
local my_name
my_name="$(basename -- "${BASH_SOURCE[0]}")"
# snapper/snapraid commands to use, can be specified with the
# --snapper-path and --snapraid-path command line options
local my_snapper=snapper
local my_snapraid=snapraid
# --pool-dir option argument
local pool_dir=
# list of snapper configs to create pre/post snapshots for
local pre_post_configs=()
# --pre-post option argument, after splitting
local pre_post_option=()
# --no-pre-post option argument, after splitting
local no_pre_post_option=()
# names of temp files to rm upon exiting
local rm_on_exit=()
# snapper cleanup algorithm to specify when creating new snapshots
local snapper_cleanup=
# names of all snapper configs that match snapraid.conf
local snapper_configs=()
# These associative arrays are indexed by snapper configs in the
# snapper_configs array, and hold the following data:
# number of pre snapshot created, to use when creating post
local -A pre_snapshot
# subvolume corresponding to the snapper config
local -A snapper_subvols
# snapraid disk name corresponding to the snapper config
local -A snapraid_names
# which snapshot should be used for the snapper config
local -A use_snapshot
# values of use_snapshot not found by find_snapshots()
local -A use_snapshot_missing
# indexes are configs specified with either the
# --snapper-configs or --snapper-configs-file options
# associative array used to track duplicates,
# regular array to preserve the order configs were specified
local snapper_configs_specified=()
local -A snapper_configs_specified_seen
# description to specify to snapper when creating new snapshots
local snapper_description=
# variable to be set if snapper ls supports --disable-used-space
# (version 0.6.0 or newer) and --used-space option was not specified
local snapper_ls_quota_disable=
# variable to be set if snapper ls supports --disable-used-space
# (version 0.6.0 or newer)
local snapper_ls_quota_support=
# snapper userdata key that will be specified to track created snapshots
# can be changed by setting the SNAPRAID_USERDATA_KEY environment variable
local \
snapper_userdata_key="${SNAPRAID_USERDATA_KEY:-$DEFAULT_USERDATA_KEY}"
# additional userdata to set, specified with the --snapper-userdata option
local snapper_userdata=
# variable to be set if -s/--sync option is specified
local sync=
# location of temporary snapraid.conf
local temp_config_file=
# directory to create temporary snapraid.conf file in
local temp_dir="${TMPDIR:-$DEFAULT_TMPDIR}"
# --use-snapshot-all option argument
local use_snapshot_all_option=
# --use-snapshot option argument
local use_snapshot_option=
# variable to be set if --used-space option is specified
local -i used_space_option=0
# controls verbosity, incremented by -v/--verbose or
# decremented by -q/--quiet command line option
local -i verbose=0
# fd to send xtrace output to if -x/--xtrace is enabled
local xtrace_fd=
# backup of original BASH_XTRACEFD
local xtrace_fd_old=
# --xtrace-file option argument
local xtrace_file=
# indicates whether the -x/--xtrace option has been enabled
local -i xtrace_mode=0
trap 'err_trap $LINENO "$BASH_COMMAND" $?' ERR
trap 'exit_trap' EXIT
# Iterate through command line arguments and process snapraid-btrfs options
# until a command is reached, then run the specified command, passing
# through any remaining command line arguments appearing after the command
# These are genuinely local variables used for option processing
# and will be unset after use
local opt_str
local -i length i
local command=
while (($# > 0)) ; do
case $1 in
# matching a snapraid command means option processing is complete
# and any further options will be passed through to snapraid
check) ;&
diff) ;&
fix) ;&
pool) ;&
resume) ;&
scrub) ;&
?(diff-|d)sync) ;&
touch) ;&
# Option processing is also complete for other commands which
# accept arguments
ls|list) ;&
shell) ;&
snapper) ;&
undochange)
break ;;
# support options specified either before or after the command
# for commands which don't invoke snapraid or accept argument
cleanup?(-all)) ;&
config) ;&
create)
if [[ -z "$command" ]] ; then
command="$1"
shift
else
invalid_argument "$1 to command $command"
fi ;;
# snapraid-btrfs options specified before command
# long form options that don't take arguments
--debug) ;&
--help) ;&
--?(non)interactive) ;&
--quiet) ;&
--sync) ;&
--used-space) ;&
--verbose) ;&
--version) ;&
--xtrace)
set_option "$1"
shift ;;
# long form options that require arguments
--conf?(=*)) ;&
--cleanup?(=*)) ;&
--@(debug|xtrace)-file?(=*)) ;&
--description?(=*)) ;&
--pool-dir?(=*)) ;&
--?(no-)pre-post?(=*)) ;&
--snapper-configs?(-file)?(=*)) ;&
--snapper-@(path|userdata)?(=*)) ;&
--snapraid-path?(=*)) ;&
--use-snapshot?(-all)?(=*))
# allow POSIX --argument option or --argument=option formats
opt_str="${1%%=*}"
if [[ "$opt_str" = "$1" ]] ; then
set_option "$opt_str" "${2-}"
shift 2
else
set_option "$opt_str" "${1#"${opt_str}="}"
shift
fi ;;
--*)
invalid_argument "$1" ;;
# allow POSIX-style combining of short options
-*)
opt_str="${1#-}"
length="${#opt_str}"
for ((i=0;i 0)) ; then
setup_config "$@"
run_command "$@"
else
error $E_INVALID_ARGUMENT "No command specified"
fi
}
# set $snapper_userdata_key userdata key to $1
modify_userdata() {
local i
local -i ret=0
local -i snapper_ret
for i in "${snapper_configs[@]}" ; do
[[ "${use_snapshot[$i]}" = 0 ]] && continue
"$my_snapper" -c "$i" modify -u "$snapper_userdata_key=$1" \
"${use_snapshot[$i]}" && true
snapper_ret=$?
if ((snapper_ret != 0)) ; then
ret=$snapper_ret
fi
done
return $ret
}
must_be_executable() {
[[ -x "$1" ]] ||
error $E_INVALID_ARGUMENT "$1 is not an executable file"
}
must_be_writable_dir() {
[[ -d "$1" ]] ||
error $E_INVALID_ARGUMENT "$1 is not a directory${2:+ - $2}"
[[ -w "$1" ]] ||
error $E_NO_PERMISSION "No write permission for $1${2:+ - $2}"
}
must_be_writable_file() {
if [[ -d "$1" ]] ; then
error $E_INVALID_ARGUMENT "$1 is a directory, not a file"
elif [[ -f "$1" ]] && ! [[ -w "$1" ]] ; then
error $E_NO_PERMISSION "No write permission for $1"
else
local dir
dir="$(dirname "$1")"
must_be_writable_dir "$dir"
fi
}
new_snapshot() {
local snapper_create_opts=(
-u "$snapper_userdata$snapper_userdata_key=created"
)
if [[ "$snapper_cleanup" ]] ; then
snapper_create_opts+=( -c "$snapper_cleanup" )
fi
if [[ "$snapper_description" ]] ; then
snapper_create_opts+=( -d "$snapper_description" )
else
snapper_create_opts+=( -d "$my_name${2:+ $2}" )
fi
use_snapshot[$1]="$("$my_snapper" -c "$1" create -p \
"${snapper_create_opts[@]}")"
verbose "Created new snapshot ${use_snapshot[$1]} for config $1"
}
# call this to make sure $2 is defined when user specifies option requring it
option_requires_argument() {
[[ "${2-}" ]] ||
error $E_INVALID_ARGUMENT "Option $1 requires an argument"
}
# use awk to parse piped snapper ls output and find snapshot numbers
# matching the specified userdata constraints:
# if $1 and $2 are nonempty, match snapshots with userdata key $1=$2
# (multiple userdata values can be comma-separated in $2 to match any of them)
# else if $1 is nonempty, match snapshots with userdata key $1 defined
# else match all snapshots
# if multiple snapshots match, separate their numbers with $3, or
# if $3 is undefined or empty, separate the snapshot numbers with newlines
parse_snapper_ls() {
awk -F '|' \
-v key="${1-}" \
-v value="${2-}" \
-v ORS="${3:-$'\n'}" \
-f <(cat <<'_EOF_'
# create array of values to match from comma-separated variable
BEGIN {
if (value != "") {
split(value,values,",")
}
}
# read column titles in header, so as to work with different versions of
# snapper that reorder columns
NR==1 {
for (i=1;i<=NF;i++) {
# remove padding spaces, then store column number indexed by title
gsub(/[ ]+/,"",$i)
column[$i] = i
}
# check to make sure we found columns labelled "#" and "Userdata"
if (column["#"] == "" || column["Userdata"] == "") {
printf("error: expected snapper ls column names not found\n",
"/dev/stderr")
exit 1
}
}
# snapshot data begin on line 3
NR>=3 {
# remove nonnumeric characters (padding spaces, mount status) from #
gsub(/[^0123456789]+/,"",$column["#"])
if (key == "") {
# match all snapshots
print $column["#"]
} else {
# split userdata column into key=value pairs in case
# multiple userdata keys are defined for a snapshot
split($column["Userdata"],pairs,",")
# construct an array 'userdata' whose indices we will search in
for (i in pairs) {
# remove padding spaces
gsub(/^[ ]+/,"",pairs[i])
gsub(/[ ]+$/,"",pairs[i])
if (value == "") {
# we don't care about the value of the userdata key, so
# split key=value pairs and store only the key
split(pairs[i],keys,"=")
userdata[keys[1]]
} else {
# we care about both halves of the userdata key=value
# pair, so store the whole key=value string
userdata[pairs[i]]
}
}
# find and print our matches
if (value == "") {
# match key only
if (key in userdata) {
print $column["#"]
}
} else {
# match both key and value
for (i in values) {
if (key "=" values[i] in userdata) {
print $column["#"]
break
}
}
}
# (portably) clear userdata before moving on to next snapshot
split("",userdata)
}
}
_EOF_
)
}
print_array() {
local ret=
if [[ "$#" -gt 0 ]] ; then
printf -v ret -- '%s ' "$@"
ret="${ret% }"
fi
printf -- '%s\n' "$ret"
}
print_version() {
cat <<_EOF_
snapraid-btrfs $MY_VERSION
Copyright (C) $COPYRIGHT_YEARS Alex deBeus
License GPLv3+: GNU GPL version 3 or later
This is free software; you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
_EOF_
}
# Run the command given in $1
run_command() {
case $1 in
# Implementation of commands that don't invoke snapraid
cleanup?(-all))
do_cleanup ;;
config)
generate_temp_snapraid_conf ;;
ls|list)
shift
snapper_ls "$@" ;;
shell)
shift
do_shell "$@" ;;
snapper)
shift
do_snapper "$@" ;;
undochange)
shift
snapper_undochange "$@" ;;
# Implementation of commands that invoke snapraid
check|diff|fix|pool|scrub|sync|touch)
run_snapraid "$@" && true ;;
resume)
shift
run_snapraid sync "$@" && true ;;
@(d|diff-)sync)
if ((interactive < 0)) ; then
error $E_INVALID_ARGUMENT \
'diff-sync and --noninteractive are incompatible'
fi
shift
local -i diff_ret
# shellcheck disable=2046
run_snapraid diff $(filter_pre_hash_option "$@") && true
diff_ret=$?
# snapraid diff returns 2 if a sync is required
if ((diff_ret == 2)) ; then
((++interactive))
run_snapraid sync --force-empty "$@" && true
else
exit $diff_ret
fi ;;
esac
exit
}
# Returns exit status of snapraid, postfix calls with '&& true' to avoid
# triggering errexit if snapraid's return status is nonzero
# Because errexit will not trigger within this function, we postfix anything
# inside it which cannot fail with || err_trap to trigger ERR trap manually
run_snapraid() {
local -a snapraid_command
local -i ret
check_snapraid_arguments "$@"
if [[ -z "${temp_config_file}" ]] ; then
temp_config_file="$(mktemp -- "$temp_dir/$my_name.XXXXXX")" ||
err_trap $LINENO mktemp $?
rm_on_exit+=( "$temp_config_file" )
generate_temp_snapraid_conf > "$temp_config_file" ||
err_trap $LINENO generate_temp_snapraid_conf $?
show_temp_snapraid_conf \
"Using temporary snapraid config file ${temp_config_file}:" ||
err_trap $LINENO show_temp_snapraid_conf $?
elif ((verbose > 0)) ; then
show_temp_snapraid_conf \
"(Re)using temporary snapraid config file ${temp_config_file}:" ||
err_trap $LINENO show_temp_snapraid_conf $?
fi
snapraid_command=( "$my_snapraid" -c "$temp_config_file" "$@" )
verbose_command "${snapraid_command[@]}"
case $1 in
fix|touch)
create_pre_post_snapshots "$1" ||
err_trap $LINENO create_pre_post_snapshots $? ;;
sync)
modify_userdata syncing ||
err_trap $LINENO modify_userdata $?
# set up a trap to track whether snapraid sync returned exit status
# 0 because it completed successfully, or because it was
# interrupted with ctrl-C, but was able to clean up before exiting
local -i interrupted=0
trap '((++interrupted)) ; trap - INT TERM QUIT' INT TERM QUIT ;;
esac
# Run snapraid
"${snapraid_command[@]}"
ret=$?
case $1 in
fix|touch)
create_pre_post_snapshots "$1" ||
err_trap $LINENO create_pre_post_snapshots $? ;;
diff)
# snapraid diff returns 0 if no changes, 2 if sync needed
if ((ret == 0)) || ((ret == 2)) ; then
modify_userdata "$1" ||
err_trap $LINENO modify_userdata $?
fi ;;
sync)
trap - INT TERM QUIT
# don't mark sync as completed if INT/TERM/QUIT trap was triggered
if ((ret == 0)) && ((interrupted == 0)) ; then
modify_userdata synced ||
err_trap $LINENO modify_userdata $?
fi ;;
esac
return $ret
}
# make input suitable to be used in sed BRE as fixed string
# in sed BRE, outside a bracket expression, the following must be escaped:
# . * $ ^ [ / \
sed_escape_bre() {
sed 's/[.*$^/\[]/\\&/g'
}
# escape output containing the following literal nonprintable ASCII characters:
# \e \r \t
sed_escape_output() {
sed -e $'s/\e/\e[7m\\\\e\e[0m/g' \
-e $'s/\r/\e[7m\\\\r\e[0m/g' \
-e $'s/\t/\e[7m\\\\t\e[0m/g'
}
# make input suitable to be used in sed replacement text as fixed string
# in sed replacement text, the following must be escaped:
# & / \
sed_escape_replacement() {
sed 's/[&/\]/\\&/g'
}
# $1 is option being set, $2 is argument. If no argument,
# $2 can be either undefined or empty
set_option() {
case $1 in
--conf) ;&
--cleanup) ;&
--@(debug|xtrace)-file) ;&
--description) ;&
--pool-dir) ;&
--?(no-)pre-post) ;&
--snapper-@(path|userdata)) ;&
--snapraid-path) ;&
--use-snapshot?(-all)) ;&
-[CUcdu])
option_requires_argument "$@" ;;&
-c|--conf)
config_file="$2" ;;
-C|--cleanup)
snapper_cleanup="$2" ;;
-d|--description)
snapper_description="$2" ;;
-h|--help)
usage
exit ;;
-i|--interactive)
((++interactive)) || true ;;
-q|--quiet)
((--verbose)) || true ;;
-s|--sync)
sync=1 ;;
-u|--use-snapshot-all)
use_snapshot_all_option="$2" ;;
-U|--use-snapshot)
use_snapshot_option="$2" ;;
-v|--verbose)
((++verbose)) || true ;;
-V|--version)
print_version
exit ;;
-x|--xtrace)
((++xtrace_mode)) ;;
-X|--debug)
((++debug_mode)) ;;
--debug-file)
must_be_writable_file "$2"
debug_file="$2" ;;
--no-pre-post)
IFS=',' read -r -a no_pre_post_option <<< "$2" ;;
--noninteractive)
((--interactive)) || true ;;
--pool-dir)
must_be_writable_dir "$2"
pool_dir="$2" ;;
--pre-post)
IFS=',' read -r -a pre_post_option <<< "$2" ;;
--snapper-configs)
apply_snapper_configs_option "$2" ;;
--snapper-configs-file)
apply_snapper_configs_file_option "$2" ;;
--snapper-path)
must_be_executable "$2"
my_snapper="$2" ;;
--snapper-userdata)
use_snapper_userdata "$2" ;;
--snapraid-path)
must_be_executable "$2"
my_snapraid="$2" ;;
--used-space)
((++used_space_option)) ;;
--xtrace-file)
must_be_writable_file "$2"
xtrace_file="$2" ;;
*)
invalid_argument "$1" ;;
esac
}
# Called immediately after all command line options have been parsed to
# read snapraid configuration file and initialize the arrays local to main()
# which track the configuration
setup_config() {
must_be_writable_dir "$temp_dir" 'is TMPDIR set correctly?'
check_dependencies "$my_snapper" "$my_snapraid"
readonly my_snapper my_snapraid
if version_is_at_least "$(get_snapper_version)" '0.6.0' ; then
snapper_ls_quota_support=1
if ((used_space_option == 0)) ; then
snapper_ls_quota_disable=1
fi
fi
check_config_file "$@"
find_configs "$@"
show_configs
check_config "$@"
if [[ "$use_snapshot_option" ]] ; then
apply_use_snapshot_option "$use_snapshot_option"
fi
local i
if [[ "$use_snapshot_all_option" ]] ; then
for i in "${snapper_configs[@]}" ; do
[[ "${use_snapshot[$i]-}" ]] ||
use_snapshot[$i]="$use_snapshot_all_option"
done
fi
apply_pre_post_options
case $1 in
check|pool|scrub|undochange)
use_snapshot_default scrub ;;&
cleanup)
use_snapshot_all sync ;;&
cleanup-all|touch)
use_snapshot_all 0 ;;&
config)
use_snapshot_default last ;;&
create|diff|?(d|diff-)sync)
use_snapshot_default new ;;&
fix)
use_snapshot_fix "$@" ;;&
resume)
use_snapshot_default resume ;;&
shell|snapper)
use_snapshot_default '' ;;&
!(cleanup-all|ls|list|snapper|touch))
find_snapshots "$1" ;;&
!(cleanup?(-all)|ls|list|shell|snapper|touch))
use_snapshot_check "$1" ;;
esac
}
show_configs() {
((verbose > 0)) || return 0
local i
echo 'Snapper configs found:'
for i in "${snapper_configs[@]}" ; do
printf -- '%s %s\n' "$i" "${snapper_subvols[$i]}"
done
echo
} >&2
show_temp_snapraid_conf() {
((verbose >= 0)) || return 0
print_array "$@"
cat < "$temp_config_file" && echo
} >&2
# Do a snapper ls in all configs, and if argument(s) are specified,
# additionally identify which snapshots we found with userdata
# key $snapper_userdata_key matching the arguments
snapper_ls() {
local i j
for i in "${snapper_configs[@]}" ; do
printf -- '%s %s\n' "$i" "${snapper_subvols[$i]}"
snapper_ls_wrapper "$i"
for j in "$@" ; do
printf -- 'Snapshots with userdata key %s=%s:\n' \
"$snapper_userdata_key" "$j"
snapper_ls_wrapper "$i" 'C' |
parse_snapper_ls "$snapper_userdata_key" "$j" ' '
echo
done
echo
done
}
# Run snapper ls > /dev/null on config $1 to sync ACLs, using
# --disable-used-space option if supported by snapper version in use
snapper_ls_sync_acl() {
LC_ALL=C "$my_snapper" -c "$1" \
ls${snapper_ls_quota_support:+ --disable-used-space} > /dev/null ||
error $E_NO_PERMISSION 'Failed to sync ACLs with snapper ls'
}
# Run snapper ls on config $1, using --disable-used-space option if supported
# by snapper version in use and if --used-space option wasn't specified
# if $2 is set, use LC_ALL=$2
snapper_ls_wrapper() {
if [[ "${2-}" ]] ; then
LC_ALL="$2" "$my_snapper" -c "$1" \
ls${snapper_ls_quota_disable:+ --disable-used-space}
else
"$my_snapper" -c "$1" \
ls${snapper_ls_quota_disable:+ --disable-used-space}
fi
}
# Run snapper undochange in each snapper config to revert to the state at the
# time ${use_snapshot[$i]} was created, creating snapshots before and after
snapper_undochange() {
local i
local -i ret=0
local -i snapper_ret
local undochange_files=()
local undochange_opts=()
create_pre_post_snapshots undochange
# ensure that -i option, if specified, appears before snapshots
# and any other arguments specified (except --) appear after snapshots
while (($# > 0)) ; do
case $1 in
--)
shift
break ;;
-i|--input)
if (($# > 1)) ; then
undochange_opts+=( "$1" "$2" )
shift 2
else
undochange_files+=( "$1" )
shift
fi ;;
*)
undochange_files+=( "$1" )
shift ;;
esac
done
undochange_files+=( "$@" )
for i in "${snapper_configs[@]}" ; do
if [[ "${use_snapshot[$i]}" = 0 ]] ; then
continue
else
verbose_command_run "$my_snapper" -c "$i" undochange \
"${undochange_opts[@]}" "${use_snapshot[$i]}..0" -- \
"${undochange_files[@]}"
snapper_ret=$?
if ((snapper_ret != 0)) ; then
ret=$snapper_ret
fi
fi
done
create_pre_post_snapshots undochange
return $ret
}
# returns 0 if $2 is an argument to $1, and 1 if not
snapraid_opt_has_arg() {
if (($# < 2)) ; then
return 1
fi
case $1 in
# snapraid long-form options that require arguments
--count) ;&
--error-limit) ;&
--filter?(-disk)) ;&
--gen-conf) ;&
--import) ;&
--log) ;&
--older-than) ;&
--percentage) ;&
--plan) ;&
--test-fmt) ;&
--test-force-@(autosave|scrub)-at) ;&
--test-import-content) ;&
--test-io-cache) ;&
--test-parity-limit) ;&
--test-run) ;&
# snapraid short-form options that require arguments
-*(["$SNAPRAID_OPTS_NOARG"])["$SNAPRAID_OPTS_ARG"])
return 0 ;;
esac
return 1
}
# Display a menu of snapshots for config $1 using snapper ls, and
# let the user pick which one to use
snapshot_menu() {
if ((interactive < 0)) ; then
error $E_SNAPSHOT_NOT_FOUND \
'not displaying snapshot menu since --noninteractive'
fi
local choice
printf -- '%s %s\n' "$1" "${snapper_subvols[$1]}"
snapper_ls_wrapper "$1"
while true ; do
read -r -p 'Enter a snapshot (0 for none, n for new, q to quit): ' \
choice
case $choice in
[Qq]?([Uu][Ii][Tt]))
exit $E_INTERACTIVE_NO ;;
[Nn]?([Ee][Ww]))
new_snapshot "$1" "$2"
break ;;
+([0123456789]))
if [[ "$choice" = 0 ]] ||
{ snapper_ls_wrapper "$1" 'C' |
parse_snapper_ls |
grep -Fx "$choice" > /dev/null ; }
then
use_snapshot[$1]="$choice"
break
else
printf -- 'Snapshot %s not found\n' "$choice"
fi ;;
*)
printf -- 'Invalid selection %s\n' "$choice" ;;
esac
done
echo
}
#if snapshot not found for a config, prompt the user to choose a different one
snapshot_not_found() {
printf -- '%s: Snapshot %s not found for config %s at %s\n' "$my_name" \
"${use_snapshot_missing[$1]}" "$1" "${snapper_subvols[$1]}"
snapshot_menu "$1" "$2"
} >&2
usage() {
cat <<_EOF_
Usage: $my_name [options] [arguments]
Arguments appearing after the command are passed through to snapraid, while
the following options appearing before the command are interpreted by
$my_name:
-h, --help Show this help
-V, --version Show version info
-c, --conf FILE Specify location of snapraid config file
(default $DEFAULT_CONFIG_FILE)
-C, --cleanup ARG Specify snapper cleanup algorithm to set for
any snapshots created (default none)
-d, --description ARG Specify snapper description to set for any
snapshots created
-i, --interactive Ask before running snapraid or any potentially
destructive snapper commands (when using the
cleanup(-all), snapper, or undochange commands)
-q, --quiet Only show snapraid/snapper output and errors
-s, --sync Pass the --sync option to snapper rm (when
using the cleanup(-all) command)
-u, --use-snapshot-all ARG Use one of the following arguments:
diff - Use last snapshot a diff was
completed with
last - Use last snapshots created
menu - Select the snapshot to use
interactively from a menu
new - Create new snapshots
res - Resume using snapshots from an
interrupted sync, or last completed
sync if more recent
scrub - Same as res, unless a fix/touch was
done more recently than sync, then
use post-fix/touch snapshot
sync - Use last snapshots a successful
sync was completed with
or specify the snapshot number (0 for the live
filesystem, following snapper syntax)
Default is:
'new' for diff|dsync|sync
'last' for config
'scrub' for all other readonly commands
-U, --use-snapshot ARG Specify snapshots to use for specific snapper
configurations, using the snapper config name
followed by an equals sign. Multiple
configurations should be separated by commas,
e.g. 'config1=5,config2=last'. Overrides -u
-v, --verbose Increase verbosity of output
-x, --xtrace Enable bash xtrace
-X, --debug Enable debugging output
--debug-file FILE File to save -X/--debug output to
--no-pre-post ARG Don't create pre/post snapshots for the
specified snapper configuration(s). Multiple
configurations should be separated by commas.
--noninteractive Never prompt the user on error, instead fail
--pool-dir DIR Create pool symlinks in DIR (defaults to
directory specified in snapraid config file)
--pre-post ARG Create pre/post snapshots only for the
specified snapper configuration(s). Multiple
configurations should be separated by commas.
--snapper-configs ARG Comma-separated list of snapper configs to
try matching with snapraid.conf file instead
of looking in $DEFAULT_SNAPPER_CONFIG_DIR.
Can be specified multiple times.
--snapper-configs-file FILE Newline-separated list of snapper configs to
try matching with snapraid.conf file instead
of looking in $DEFAULT_SNAPPER_CONFIG_DIR.
Can be specified multiple times.
--snapper-path PATH Path to the snapper executable (defaults to
first found in PATH)
--snapper-userdata ARG Specify snapper userdata to set for any
snapshots created in addition to the
$my_name attribute, which is set by
default and cannot be changed. Argument should
be in key=value format accepted by snapper,
with multiple keys separated by commas (e.g.
key1=value1,key2=value2)
--snapraid-path PATH Path to the snapraid executable (defaults to
first found in PATH)
--used-space Don't pass the --disable-used-space option to
snapper ls.
--xtrace-file FILE File to save -x/--xtrace output to
NOTE: The snapraid -c/--conf option will not work unless placed before the
command, allowing it to be interpreted as a $my_name option. Snapraid
will be run with a temporary configuration file, generated using whatever
snapraid.conf file is specified using the $my_name -c/--conf option
($DEFAULT_CONFIG_FILE by default).
Commands are either one of the following snapraid commands:
'check'|'diff'|'pool'|'scrub'|'sync':
Run the snapraid command given, replacing data drives in snapraid
config file that have corresponding snapper configs with read-only
snapshots.
'fix'|'touch':
Run the snapraid command given, creating a set of pre/post snapshots
before and after (for fix, if the snapraid -d/--filter-disk option is
specified, create pre/post snapshots only for the specified disk(s),
and use the 'scrub' snapshot for the rest (see -u option above)).
or one of the following $my_name specific commands:
'config':
Show the modified snapraid config file that would be used, but don't
actually run snapraid.
'create':
Create a new snapshot for all snapper configs corresponding to data
drives found in snapraid config file.
'cleanup':
Delete all snapshots created by $my_name before the last one a
successful sync has been completed with.
'cleanup-all':
Delete all snapshots created by $my_name.
'dsync'|'diff-sync':
Create a new snapshot for all snapper configs found in snapraid config
file, do a snapraid diff, then sync. Implies --interactive option for
the sync operation. Uses --force-empty for the sync operation, since
the diff must be manually approved anyway.
'list'|'ls':
Run snapper ls for all snapper configs found in snapraid config file.
If an argument is given, also list which snapshots in each config were
identified as having snapper userdata key equal to the argument.
'resume':
Resume an interrupted sync, using the same set of snapshots.
'shell':
Start an interactive bash session in $my_name context. Useful for
testing and debugging.
'snapper':
Run the given snapper command in all configs, unless they are disabled
by --use-snapshot exampleconfig=0 - for example:
$my_name -U foo=0 snapper get-config
would run
snapper -c "\$i" get-config
substituting "\$i" for each snapper config matching the snapraid.conf
file, except foo.
'undochange':
Use snapper undochange to revert the array to the state it was in at
the time of the last successful sync (or another snapshot if the -u or
-U option is specified), creating pre/post snapshots. Arguments are
passed through to snapper undochange, including the snapper undochange
-i option.
Environment variables:
DEBUG_FD -
File descriptor to send debug output to if -X/--debug is used. For
example, running "DEBUG_FD=3 $my_name -Xh 3>/tmp/debug" would
send debug output to /tmp/debug while displaying only the normal output
of "$my_name -h" on the console. If unset, the default behavior
is to send debug output to stderr.
SNAPPER_CONFIG_DIR -
Location of snapper config files. If unset, it defaults to
$DEFAULT_SNAPPER_CONFIG_DIR.
SNAPRAID_CONFIG_FILE -
Default location of the snapraid.conf file if -c/--conf option is not
used. If unset, it defaults to $DEFAULT_CONFIG_FILE.
SNAPRAID_USERDATA_KEY -
Snapper userdata key that is used to track snapshots. If unset, it
defaults to $DEFAULT_USERDATA_KEY.
TMPDIR -
Directory to create temporary snapraid.conf file in. If unset, it
defaults to $DEFAULT_TMPDIR.
_EOF_
}
# Add key/value pairs from $1 to snapper_userdata, unless key is
# $snapper_userdata_key
use_snapper_userdata() {
local key value i
local -a args
IFS=',' read -r -a args <<< "$1"
for i in "${args[@]}" ; do
IFS='=' read -r key value <<< "$i"
if [[ "$key" = "$snapper_userdata_key" ]] ; then
error $E_INVALID_ARGUMENT \
"Cannot set reserved userdata key $key"
else
snapper_userdata+="$key=$value,"
fi
done
}
# Set use_snapshot to $1 for all configs, overriding any previous values
use_snapshot_all() {
local i
for i in "${snapper_configs[@]}" ; do
use_snapshot[$i]="$1"
done
}
# If use_snapshot[$i] is the empty string for any snapper config, indicating
# that find_snapshots did not find a match, handle the error
use_snapshot_check() {
local i
for i in "${snapper_configs[@]}" ; do
[[ "${use_snapshot[$i]}" ]] || snapshot_not_found "$i" "$1"
done
}
# For any configs where use_snapshot is undefined or empty, set it to $1
use_snapshot_default() {
local i
for i in "${snapper_configs[@]}" ; do
if [[ -z "${use_snapshot[$i]-}" ]] ; then
use_snapshot[$i]="$1"
fi
done
}
# When running a fix operation, parse the -d/--filter-disk snapraid option and
# set ${use_snapshot[@]} accordingly
use_snapshot_fix() {
if [[ "${1-}" = fix ]] ; then
shift
else
error $E_INTERNAL_ERROR \
'use_snapshot_fix() called with unexpected arguments:' "$@"
fi
local disk snapper_config_name
local -i disks_found=0
while (($# > 0)) ; do
disk=
case $1 in
--)
break ;;
--filter-disk=*)
disk="${1#--filter-disk=}"
shift ;;
--filter-disk|-*(["$SNAPRAID_OPTS_NOARG"])d)
option_requires_argument "$@"
disk="$2"
shift 2 ;;
-*(["$SNAPRAID_OPTS_NOARG"])d*)
disk="${1#*(["$SNAPRAID_OPTS_NOARG"])d}"
shift ;;
-*)
if snapraid_opt_has_arg "$@" ; then
shift 2
else
shift
fi ;;
*)
error $E_INVALID_ARGUMENT \
'The following could not be interpreted as valid' \
'snapraid arguments:' $'\n' "$@" ;;
esac
if [[ "$disk" ]] ; then
((++disks_found))
snapper_config_name="$(get_snapper_config_name "$disk")"
if [[ "$snapper_config_name" ]] ; then
# for disks we are fixing, use the live filesystem
if ! [[ "${use_snapshot[$snapper_config_name]-}" =~ ^0?$ ]]
then
error $E_INVALID_ARGUMENT \
"Must use live filesystem for $snapper_config_name" \
'since it is being fixed, but' \
"${use_snapshot[$snapper_config_name]} was specified"
fi
use_snapshot[$snapper_config_name]=0
fi
fi
done
if ((disks_found > 0)) ; then
# for disks we are not fixing, use the 'scrub' snapshot
use_snapshot_default scrub
else
# snapraid fix --filter-disk option was not specified
# snapraid will try to fix all disks, so use the live filesystem
use_snapshot_default 0
fi
}
verbose() {
((verbose > 0)) || return 0
print_array "$@"
}
verbose_command() {
if ((interactive > 0)) ; then
interactive_ask "$@"
elif ((verbose >= 0)) ; then
print_array "$@"
fi
} >&2
verbose_command_run() {
verbose_command "$@"
"$@" && true
}
# compares version numbers specified in $1 and $2
# returns 0 if $1 >= $2
version_is_at_least() {
local -i i
local -a ver1 ver2
IFS='.' read -r -a ver1 <<< "$1"
IFS='.' read -r -a ver2 <<< "$2"
# if ver1 contains fewer components than ver2, pad with zeroes
for ((i=${#ver1[@]};i<${#ver2[@]};i++)) ; do
ver1[i]=0
done
# ensure version components are suitable for numeric comparison
for ((i=0;i<${#ver1[@]};i++)) ; do
ver1[i]="${ver1[i]##*([^0123456789])}"
ver1[i]="${ver1[i]%%[^0123456789]*}"
done
# iterate through version components until we find the first difference
for ((i=0;i<${#ver2[@]};i++)) ; do
if ((ver1[i] > ver2[i])) ; then
return 0
elif ((ver1[i] < ver2[i])) ; then
return 1
fi
done
# if we reach this point, ver1 and ver2 are the same
# (possibly with ver1 having extra components)
return 0
}
warn() {
((verbose >= 0)) || return 0
printf -- '%s: WARNING: ' "$my_name"
print_array "$@"
} >&2
warn_if_root() {
[[ "$EUID" = 0 ]] || return 0
warn "Running $my_name as root is not recommended"
warn '(nor is running snapraid as root)'
}
if [[ "$0" = "${BASH_SOURCE[0]}" ]] ; then
main "$@"
fi