├── .gitignore
├── CHANGELOG.md
├── README.md
└── btrfs-snap


/.gitignore:
--------------------------------------------------------------------------------
1 | *~
2 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # btrfs-snap Changelog
 2 | ## v1.7.4 (Apr 02 2023)
 3 | * Minor bugfix to work with btrfs-progs 5.10
 4 | 
 5 | # btrfs-snap Changelog
 6 | ## v1.7.3 (Jul 25 2017)
 7 | * Removed perl dependency (replaced perl regex by bash regex)
 8 | 
 9 | ## v1.7.2 (Feb 11 2017)
10 | * Added new switch -q which makes output cron-compatible: silent unless an error occurs.
11 | * Regex fix: correctly remove trailing slashes on mount-points
12 | 
13 | ## v1.7.1 (Mar 16 2016)
14 | * Fixed timestamp-bug (introduced in v1.6.1)
15 | 
16 | ## v1.7.0 (Mar 14 2016)
17 | * Added new switch -E which treats omitting a snapshot as an error.
18 | 
19 | ## v1.6.1 (Mar 14 2016)
20 | * Bugfix: touch to update the timestamp is only needed for option '-t'.
21 |   For '-T' it is counter-productive and therefore disabled.
22 | 
23 | ## v1.6.0 (Mar 09 2016)
24 | * Added new flag -T which uses the transaction ids of btrfs to decide if new data is present.
25 | 
26 | ## v1.5.0 (Mar 09 2016)
27 | * Added new flag -p to use the <prefix> as a postfix.
28 | 
29 | ## v1.4.2 (Feb 19 2016)
30 | * Bugfix for prefix VFS: Removed an unneccessary $-sign which broke the code. (Thanks to 'clawes' for reporting.)
31 | 
32 | ## v1.4.1 (Aug 31 2015)
33 | * Bugfix for switch -t: Force update of source timestamp to prevent outdated timestamps on the folders
34 | 
35 | ## v1.4.0 (Aug 28 2015)
36 | * Added checks for existing snapshots and use pattern to search for existing snapshots
37 | * Added a switch -B to specify the full path snapshot path
38 | * Added a switch -t time to create only a snapshot if the newest already existing snapshot is older than 'time' seconds.
39 | * Added PATH since script is most likely called by crontab with reduced PATH-settings
40 | 
41 | ## v1.3.2 (Jan 10 2015)
42 | * added switch to generate more compatible snapshot names
43 |   (no colons in file names: this confuses SAMBA/Windows clients)
44 | 
45 | ## v1.3.1 (Jan 05 2015)
46 | 
47 | * added switch to override default snapshot directory name ".snapshot"
48 | * cleanup
49 | 
50 | ## v1.2.2 (Sept 24 2013)
51 | 
52 | * trailing slash removal failed on multipart paths due to missing line
53 |   terminator.  Time for a bats test suite.
54 | 
55 | ## v1.2.1 (Sept 24 2013)
56 | 
57 | * fix trailing slash removal so that it works when the mountpoint is '/'.
58 |   This required a change to perl from sed (standard sed doesn't have negated
59 |   character classes)
60 | 
61 | ## v1.2.0 (Sept 21 2013)
62 | 
63 | * added VFS snapshot naming support courtesy of gitmopp
64 | 
65 | ## v1.1.0 (July 30 2013)
66 | 
67 | * add README
68 | * add readonly snapshot and base directory features
69 | 
70 | ## v1.0.0 (July 20 2013)
71 | 
72 | * Initial version written by Birger Monsen <birger@birger.sh>
73 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | btrfs-snap
 2 | ==========
 3 | 
 4 | btrfs-snap creates and maintains the history of snapshots of btrfs filesystems.
 5 | 
 6 | Features:
 7 | 
 8 | * can snapshot inside of the filesystem or rooted in a base directory
 9 | * can purge old snapshots when too many exist
10 | * can keep multiple snapshot schedules for the same filesystem
11 | 
12 | btrfs-snap is designed to be called from cron on a regular schedule.
13 | 
14 | Usage
15 | -----
16 | 
17 | btrfs-snap [-r] [-b basedir] mountpoint prefix count
18 | 
19 | * mountpoint is the filesystem to snapshot
20 | * prefix is the prefix, which usually corresponds to a schedule (e.g. 1m, 5m, 3h, 1d, 1w, 3mo)
21 | * count is the number of snapshots with the same prefix to keep
22 | * -r makes the snapshot readonly (requires btrfs-tools v0.20)
23 | * -c generates more compatible snapshot names
24 |      (ie. no colons that confuse SAMBA/Window$ clients)
25 | * -E treats omitting of snapshots as error
26 | * -p redefines the prefix to be used as postfix
27 | * -d dir places the snapshot in dir, relative to the mountpoint
28 | * -b basedir places the snapshot in basedir with a directory structure that mimics the mountpoint
29 | * -B basedir places the snapshots in basedir with NO additional subdirectory structure
30 | * -t/-T time creates only a snapshot if the newest already existing snapshot is older than 'time' seconds.
31 | * -q output becomes cron-compatible: silent unless an error occurs.
32 | 
33 | Without -b, -B, or -d, snapshots are placed in a directory called .snapshot at the top of the mountpoint.
34 | 
35 | mountpoint must be a mounted btrfs filesystem (i.e. appears in the output of
36 | "mount -t btrfs") or an unmounted btrfs subvolume (which must exit 0 when
37 | "btrfs su sh" is called on it).  Unmounted subvolumes require a recent
38 | version of btrfs-progs; see "OS Support" below for specifics.
39 | 
40 | Examples
41 | --------
42 | 
43 | ```cron
44 | */5   *   *   *   *   btrfs-snap -r / 5m 12
45 | 0     0   *   *   *   btrfs-snap -r -b /snapshots /home 1d 7
46 | ```
47 | 
48 | The above cronjob would
49 | 
50 | 1. create a snapshot of / every 5 minutes, keeping 12 generations in /.snapshot
51 | 1. create a snapshot of /home every day, keeping 7 generations in /snapshots/home
52 | 
53 | OS Support
54 | ----------
55 | 
56 | Tested on
57 | 
58 | * Ubuntu 12.04 with the raring kernel
59 | * Ubuntu 13.04
60 | * Debian 8
61 | * Debian 9
62 | * Debian 11 (bullseye)
63 | 
64 | Anything else, YMMV.  Reports of successful use on other operating systems
65 | is welcome
66 | 
67 | To snaphshot an unmounted btrfs subvolume, you need a version of btrfs-progs
68 | that supports the "btrfs subvolume show" command.
69 | 
70 | The version that comes with Ubuntu 13.04 is too old; the version that comes
71 | with Ubuntu 13.10 works.  You should be able to compile a working version
72 | from the sources (refer to
73 | https://btrfs.wiki.kernel.org/index.php/Btrfs_source_repositories for
74 | details).
75 | 
76 | License
77 | -------
78 | 
79 | This program is distributed under the GNU General Public License
80 | 
81 | http://www.gnu.org/licenses/gpl.txt
82 | 
83 | Authors
84 | -------
85 | 
86 | Originally by Birger Monsen <birger@birger.sh>
87 | 
88 | Readonly and basedir additions by James FitzGibbon <james@nadt.net>
89 | 
90 | VFS snapshot naming support by gitmopp (https://github.com/gitmopp)
91 | 
92 | Support for snapshotting unmounted btrfs subvolumes by Brian Kloppenborg (https://github.com/bkloppenborg)
93 | 
94 | Switches -c (for windows-combitible timestamps) and -d (for specifying the snapshot directory) by Lukas Pirl (btrfs-snap@lukas-pirl.de)
95 | 
96 | Switches -B (absolute path of snapshot directory) and -t/-T (time-dependent snapshot) by Michael Walz (btrfs-snap@serpedon.de)
97 | 
98 | 
99 | 


--------------------------------------------------------------------------------
/btrfs-snap:
--------------------------------------------------------------------------------
  1 | #!/bin/bash
  2 | 
  3 | # btrfs-snap - make periodic snapshots of btrfs filesystem
  4 | #
  5 | # Copyright (C) 2010 Birger Monsen birger@birger.sh
  6 | # Copyright (C) 2013 James FitzGibbon james@nadt.net
  7 | # Copyright (C) 2014 Brian Kloppenberg
  8 | # Copyright (C) 2015 Lukas Pirl btrfs-snap@lukas-pirl.de
  9 | # Copyright (C) 2015-2017 Michael Walz btrfs-snap@serpedon.de
 10 | # Copyright (C) 2017 Raimund Jacob-Bloedorn jacob@pinuts.de
 11 | 
 12 | # This program is distributed under the GNU General Public License
 13 | # http://www.gnu.org/licenses/gpl.txt
 14 | #
 15 | 
 16 | set -u
 17 | 
 18 | LOG_FACILITY=local0
 19 | VERSION="1.7.4"
 20 | prog=${0##*/}
 21 | PATH="$PATH:/usr/sbin:/usr/bin:/sbin:/bin"
 22 | 
 23 | USAGE="Usage: ${prog} -h for usage help
 24 |        ${prog} -V for version
 25 |        ${prog} [options] <mountpoint> <prefix> <count>"
 26 | SYNOPSIS="${prog} [options] <mountpoint> <prefix> <count>
 27 | <mountpoint> is the mountpoint of the btrfs file system to make a
 28 |              snapshot of
 29 | <prefix>     is the prefix to be used in the name of the snapshot.
 30 |              E.g. hourly, daily, weekly...
 31 |              If prefix=VFS a Samba vfs_shadow_copy snapshot naming convention
 32 |              will be used (@GMT-%Y.%m.%d-%H.%M.%S).
 33 | <count>      The number of snapshots with the given prefix to keep.
 34 | 
 35 | btrfs-snap / hourly 24
 36 | would make a snapshot in /.snapshot called hourly_<date>_<time>
 37 | where <date> is on the form YYYY-MM-DD and <time> is on the form
 38 | HH:MM:SS. This format makes shure snapshot names sort correctly in
 39 | cronological order even when sorted alphabetically. The 24 newest
 40 | snapshots matching the prefix are kept around. The rest are deleted.
 41 | 
 42 | if '-r' is given, snapshots are created read only
 43 | 
 44 | if '-c' is given, snapshots are created with more compatible names
 45 | (i.e. no colons in file names, so that SAMBA does not mangle the names)
 46 | 
 47 | if '-p' is given, the <prefix> will be used as a postfix, i.e. it is
 48 | appended which might be usefull for automatic chronological sorting.
 49 | 
 50 | if '-E' is given, omitting a snapshot (e.g. due to options -t/-T) is
 51 | treated as an error and a non-zero exit code is returned.
 52 | 
 53 | if '-d dir' is given, snapshots are created in dir, relative to
 54 | mountpoint (default: '.snapshot', conflicts with -b and -B).
 55 | 
 56 | if '-b dir' is given, snapshots are created in dir, with a directory
 57 | structure that mimics the source (conflicts with -d and -B).
 58 | 
 59 | if '-B dir' is given, snapshots are created in dir, with NO additional
 60 | subdirectory structure; choose <prefix> wisely to avoid conflicts
 61 | (conflicts with -d and -b).
 62 | 
 63 | if '-t time' is given, a snapshot will only be created if the newest already
 64 | existing snapshot is older than 'time' seconds. Additionally, no snapshot will
 65 | be made if <mountpoint> has identical timestamp as the newest snapshot.
 66 | (The modification timestamps of the subvolumes/folders are used for comparison
 67 |  which MIGHT NOT work in some scenarios.)
 68 | (conflicts with -T)
 69 | 
 70 | if '-T time' is given, a snapshot will only be created if the newest already
 71 | existing snapshot is older than 'time' seconds. Additonally, no snapshot will
 72 | be made if <mountpoint> has a lower or equal transition-id than newest snapshot.
 73 | (conflicts with -t)
 74 | 
 75 | if '-q' is given, output becomes cron-compatible: silent unless an error occurs.
 76 | 
 77 | Example usage for a system with 2 btrfs file systems mounted as
 78 | / and /home (remember to make these scripts executable):
 79 | 
 80 | /etc/cron.hourly/btrfs-snap
 81 | 
 82 | #!/bin/bash
 83 | ${0} / hourly 24
 84 | ${0} /home hourly 24
 85 | 
 86 | /etc/cron.daily/btrfs-snap
 87 | 
 88 | #!/bin/bash
 89 | ${0} / daily 7
 90 | ${0} /home daily 7
 91 | 
 92 | /etc/cron.weekly/btrfs-snap
 93 | 
 94 | #!/bin/bash
 95 | ${0} /home weekly 4
 96 | 
 97 | 
 98 | Alternative (more complicated) example for a system with 1 btrfs subvolume called /data.
 99 | These three commands should be run regularily (e.g. all 5 minutes) and
100 | test themselves if a snapshot is needed:
101 | ${0} -r -c -B <SNAPSHOT_PATH> -t   3600 /data data_hourly 24
102 | ${0} -r -c -B <SNAPSHOT_PATH> -t  86400 /data data_daily 7
103 | ${0} -r -c -B <SNAPSHOT_PATH> -t 604800 /data data_weekly 4
104 | "
105 | 
106 | base=""
107 | dir=""
108 | full_base=""
109 | readonly=""
110 | quiet=""
111 | use_as_prefix=true
112 | use_transid=false
113 | time_delim=":"
114 | ONE_OF_b_B_d_GIVEN=false
115 | OMITT_ERROR_CODE=0
116 | time_duration=0
117 | while getopts "hVrqpEb:d:B:ct:T:" arg; do
118 |     case "${arg}" in
119 |         h )
120 |             echo "$SYNOPSIS"
121 |             exit 0
122 |             ;;
123 |         r )
124 |             readonly="-r"
125 |             ;;
126 |         q )
127 |             quiet="1"
128 |             ;;
129 |         p )
130 |             use_as_prefix=false
131 |             ;;
132 |         E )
133 |             OMITT_ERROR_CODE=1
134 |             ;;
135 |         t )
136 |             time_duration=$((0+$OPTARG))
137 |             ;;
138 |         T )
139 |             time_duration=$((0+$OPTARG))
140 |             use_transid=true
141 |             ;;
142 |         b )
143 |             base=$OPTARG
144 |             if $ONE_OF_b_B_d_GIVEN; then echo "Error: the switches -b -B -d are mutually exclusive."; exit 1; fi
145 |             ONE_OF_b_B_d_GIVEN=true
146 |             ;;
147 |         B )
148 |             full_base=$OPTARG
149 |             if $ONE_OF_b_B_d_GIVEN; then echo "Error: the switches -b -B -d are mutually exclusive."; exit 1; fi
150 |             ONE_OF_b_B_d_GIVEN=true
151 |             ;;
152 |         d )
153 |             dir=$OPTARG
154 |             if $ONE_OF_b_B_d_GIVEN; then echo "Error: the switches -b -B -d are mutually exclusive."; exit 1; fi
155 |             ONE_OF_b_B_d_GIVEN=true
156 |             ;;
157 |         V )
158 |             echo "${prog} Version ${VERSION}"
159 |             exit 0
160 |             ;;
161 |         c )
162 |             time_delim="-"
163 |             ;;
164 |         * )
165 |             echo "$USAGE"
166 |             exit 1
167 |             ;;
168 |     esac
169 | done
170 | 
171 | shift $((OPTIND-1))
172 | 
173 | if [ $# -ne 3 ] ; then
174 |     echo "$USAGE"
175 |     exit 1
176 | fi
177 | 
178 | # Canonicalize the mountpoint path (strip trailing slashes, etc)
179 | mp=$(readlink -f $1)
180 | prefix=$2
181 | cnt=$(( $3+1 ))
182 | 
183 | function log.info() {
184 |     logger -p ${LOG_FACILITY}.info -t ${prog} "$1"
185 |     if test -z "$quiet"
186 |     then
187 |         echo "$1"
188 |     fi
189 | }
190 | 
191 | function log.error() {
192 |     logger -p ${LOG_FACILITY}.err -t ${prog} "$1"
193 |     echo "ERROR: $1" >&2
194 |     exit 1;
195 | }
196 | 
197 | # Verify that the path is either a valid btrfs mountpoint
198 | if ! findmnt -t btrfs -T "${mp}" &> /dev/null; then
199 |     # or a valid snapshot matching mp
200 |     btrfs subvolume show $mp > /dev/null
201 |     if [ $? -ne 0 ] ; then
202 |         log.error "${mp} is not a btrfs mountpoint (or old version of btrfs-progs, try >=5.10)"
203 |         exit 1;
204 |     fi
205 | fi
206 | 
207 | # set default for dir
208 | if [ "x$dir" == "x" ]
209 | then
210 |     dir=".snapshot"
211 | fi
212 | 
213 | if [ "x$base" == "x" ]
214 | then
215 |     base="${mp}/${dir}"
216 | else
217 |     base="${base}/${mp}"
218 | fi
219 | if [ "x$full_base" != "x" ]; then
220 |     base=$full_base
221 | fi
222 | if [ ! -d $base ]; then
223 |     log.info "Creating $base"
224 |     mkdir -p $base
225 | fi
226 | base=$(readlink -f $base)
227 | 
228 | if [ ${prefix} == VFS ]; then
229 |     snapname=$(TZ=GMT date +@GMT-%Y.%m.%d-%H.%M.%S)
230 |     snappattern="@GMT-????.??.??-??.??.??"
231 | else
232 |     if $use_as_prefix; then
233 |         snapname=${prefix}_$(date +%Y-%m-%d_%H${time_delim}%M${time_delim}%S)
234 |         snappattern="${prefix}_????-??-??_??${time_delim}??${time_delim}??"
235 |     else
236 |         snapname=$(date +%Y-%m-%d_%H${time_delim}%M${time_delim}%S)_${prefix}
237 |         snappattern="????-??-??_??${time_delim}??${time_delim}??_${prefix}"
238 |     fi
239 | fi
240 | if [ -e ${base}/${snapname} ]; then
241 |     log.error "cannot create snapshot in ${base}/${snapname} since a folder/file with that name already exists"
242 |     exit 1;
243 | fi
244 | 
245 | if [ $time_duration -gt 0 ]; then
246 |     newestSnapshot=`ls -dr $base/${snappattern} 2>/dev/null| head -n 1`
247 |     if [ ! -z "$newestSnapshot" -a -e "$newestSnapshot" ]; then
248 |         snap_time=`stat -c "%Y" "${newestSnapshot}"`
249 |         cur_time=`date +%s`
250 |         if $use_transid; then
251 |             # get transaction ids
252 |             id_snap=$(btrfs subvolume find-new "$newestSnapshot" 99999999| sed 's/[^0-9]//g')
253 |             id_mount=$(btrfs subvolume find-new "${mp}" 99999999| sed 's/[^0-9]//g')
254 |             if [ $id_mount -le $id_snap ]; then
255 |                 log.info "No snapshot created since no changes since last snapshot. (Transaction id of $newestSnapshot is newer or equal to $mp.)"
256 |                 exit $OMITT_ERROR_CODE
257 |             fi
258 |         else
259 |             mp_time=`stat -c "%Y" "${mp}"`
260 |             if [ $snap_time == $mp_time ]; then
261 |                 log.info "No snapshot created since timestamp of newest snapshot $newestSnapshot equal $mp."
262 |                 exit $OMITT_ERROR_CODE
263 |             fi
264 |         fi
265 | 
266 |         if [ $(($snap_time + $time_duration)) -gt $cur_time ]; then
267 |             log.info "No snapshot created since timestamp of newest snapshot $newestSnapshot is less than $time_duration seconds away."
268 |             exit $OMITT_ERROR_CODE
269 |         fi
270 |      fi
271 | 
272 |      # Force update of source timestamp to prevent outdated timestamps on the folders
273 |      touch "${mp}"
274 | fi
275 | 
276 | out=`btrfs subvol snapshot ${readonly} ${mp} ${base}/${snapname} 2>&1`
277 | if [ $? -eq 0 ] ; then
278 |     log.info "${out}"
279 | else
280 |     log.error "${out}"
281 |     exit 1;
282 | fi
283 | 
284 | ls -dr $base/${snappattern} | tail -n +${cnt} | while read snap ; do
285 |     out=`btrfs subvolume delete ${snap} 2>&1`
286 |     if [ $? -eq 0 ] ; then
287 |         log.info "${out}"
288 |     else
289 |         log.error "${out}"
290 |     fi
291 | done
292 | 


--------------------------------------------------------------------------------