/usr/share/doc/zfsnap/zfSnap.md.html is in zfsnap 1.11.1-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 | <h1 id="zfsnap">zfSnap</h1>
<p>zfSnap is a simple sh script to make rolling zfs snapshots with cron. The main advantage of zfSnap is it's written in 100% pure <em>/bin/sh</em> so it doesn't require any additional software to run.</p>
<p>zfSnap keeps all information about snapshot in snapshot name.</p>
<p>zfs snapshot names are in the format of <strong>Timestamp--TimeToLive</strong>.</p>
<p><strong>Timestamp</strong> includes the date and time when the snapshot was created and <strong>TimeToLive (TTL)</strong> is the amount of time for the snapshot to stay alive before it's ready for deletion.</p>
<h2 id="description-of-name-format">Description of Name Format</h2>
<p><strong>Timestamp</strong> is saved as <strong>year-month-day_hour.minute.second</strong></p>
<ul>
<li>Example: <strong>2010-08-02_18.45.00</strong></li>
</ul>
<p><strong>TimeToLive</strong> can contain numbers and modifiers and is calculated in seconds</p>
<ul>
<li>Example 1: <strong>1y6m5d2h</strong> - One year, six months, five days, and two hours</li>
<li>Example 2: <strong>2m</strong> - Two months</li>
<li>Example 3: <strong>216000s</strong> - Two hundred and sixteen thousand seconds (~2 months)</li>
<li>Example 4: <strong>216000</strong> - Two hundred and sixteen thousand seconds (the s for seconds is optional)</li>
</ul>
<h2 id="valid-ttl-modifiers">Valid TTL Modifiers</h2>
<ul>
<li><strong>y</strong> - years (equals 365 days)</li>
<li><strong>m</strong> - months (equals 30 days)</li>
<li><strong>w</strong> - weeks (equals 7 days)</li>
<li><strong>d</strong> - days</li>
<li><strong>h</strong> - hours</li>
<li><strong>M</strong> - minutes</li>
<li><strong>s</strong> - seconds</li>
</ul>
<p><strong>NOTE:</strong> You don't need to include all of these if you are not using them, but modifiers must be used in this ordering.</p>
<h1 id="command-line-options">Command line options</h1>
<p><strong>zfSnap</strong> [ <em>generic options</em> ] [[ -a <em>ttl</em> ] [ -r|-R ] <em>zpool/zfs1</em> ... ] ...</p>
<h2 id="generic-options">Generic options</h2>
<ul>
<li><strong>-d</strong> - deletes snapshots older than the TTL in the snapshot name</li>
<li><strong>-e</strong> - Return exit code return number of failed actions</li>
<li><strong>-F <em>age</em></strong> - Force delete all snapshots older than <em><strong>age</strong></em></li>
<li><strong>-o</strong> - Use old timestamp format (<strong>yyyy-mm-dd_hh:mm:ss--ttl</strong>) instead of new (<strong>yyyy-mm-dd_hh.mm.ss--ttl</strong>) (for compatibility with snapshots created before zfSnap v1.4.0)</li>
<li><strong>-s</strong> - Don't do anything on pools running resilver</li>
<li><strong>-S</strong> - Don't do anything on pools running scrub</li>
<li><strong>-z</strong> - round down seconds in the snapshot name to 00 (such as 18:06:15 to 18:06:00)</li>
<li><strong>-n</strong> - perform a test run with no changes made</li>
<li><strong>-v</strong> - verbose output</li>
<li><strong>-zpool28fix</strong> - Workaround for zpool v28 zfs destroy -r bug (See [[Misc info]])</li>
</ul>
<p><strong>NOTE:</strong> Generic options must be specified at beginning of command line</p>
<h2 id="options">Options</h2>
<ul>
<li><strong>-a <em>TTL</em></strong> - change default <strong>TTL</strong> (if TTL doesn't match TTL pattern, results may vary). Default TTL is 1m</li>
<li><strong>-r</strong> - create <strong>recursive</strong> snapshots for all zfs file systems that follow this switch</li>
<li><strong>-R</strong> - create <strong>non-recursive</strong> snapshots for all zfs file systems that follow this switch</li>
<li><strong>-p <em>prefix</em></strong> - use <strong>prefix</strong> for snapshots after this switch</li>
<li><strong>-P</strong> - <strong>don't use prefix</strong> for snapshots</li>
<li><strong>-D <em>zpool/dataset</em></strong> - delete all zfSnap snapshots of the specified <em><strong>zpool/dataset</strong></em> (Ignores TTL)</li>
</ul>
<h1 id="using-zfsnap-with-etccrontab">Using zfSnap with /etc/crontab</h1>
<p>zfSnap was designed to work with ''/etc/crontab''</p>
<h2 id="examples-of-rolling-snapshots-using-crontab">Examples of Rolling Snapshots Using Crontab</h2>
<p>Hourly recursive snapshots of an entire pool kept for 5 days</p>
<pre><code># Minute Hour Day of month Month Day of week Who Command
5 * * * * root /usr/local/sbin/zfSnap -a 5d -r zpool</code></pre>
<p>Snapshots created at 6:45 and 18:45 kept for 2 weeks of different datasets in different zpools</p>
<pre><code>45 6,18 * * * root /usr/local/sbin/zfSnap -a 2w zpool2/git zpool2/jails zpool2/templates -r zpool2/jails/main zpool2/jails/share1 zpool1/local zpool1/var</code></pre>
<p><strong>NOTE:</strong> You can use <strong>-a</strong>, <strong>-r</strong> and <strong>-R</strong> as much as you want in a single line</p>
<p>At 2:15 on the first of every month do</p>
<ul>
<li>zpool/var recursive and hold it for 1 year</li>
<li>zpool/home and hold it for 6 minutes</li>
<li>zpool/usr and hold it for 3 months</li>
<li>zpool/root non-recursive and hold it for 3 months</li>
</ul>
<p>The magic entry 15 2 1 * * root /usr/local/sbin/zfSnap -a 1y -r zpool/var -a 6M zpool/home -a 3m zpool/usr -R zpool/root</p>
<h2 id="delete-old-snapshots">Delete old snapshots</h2>
<p>It is probably better to delete old snapshots once a day (at least on servers), then adding <strong>-d</strong> switch to every crontab entry.</p>
<p>This is because deleting zfs snapshots is slower than creating them. Also who cares if few snapshots stay few hours longer?</p>
<p>This crontab entry will delete old zfs snapshots at 1:00</p>
<pre><code># Minute Hour Day of month Month Day of week Who Command
0 1 * * * root /usr/local/sbin/zfSnap -d</code></pre>
<h2 id="delete-old-snapshots-with-old-timestamp-format">Delete old snapshots with old timestamp format</h2>
<pre><code># Minute Hour Day of month Month Day of week Who Command
0 1 * * * root /usr/local/sbin/zfSnap -d -o</code></pre>
<p>Note that this only deletes snapshots with old timestamp format. If you need to delete snapshots with new timestamp format, you need to add another cron job (without <strong>-o</strong> flag)</p>
<h2 id="delete-old-snapshots-with-prefixes">Delete old snapshots with prefixes</h2>
<p>If you are creating snapshots with prefix (<strong>-p</strong> flag) and want to delete these snapshots (<strong>-d</strong>), then you need to run <strong>zfSnap -d</strong> and specify all prefixes with <strong>-p</strong> flags.</p>
<p>For example:</p>
<p>if you have create snapshots with <em>test_</em> and <em>test_me_</em> prefixes simply running</p>
<pre><code># zfSnap -d</code></pre>
<p>won't delete these snapshots.</p>
<p>What you need to run is</p>
<pre><code># zfSnap -d -p test_ -p test_me</code></pre>
<p>This will delete all old snapshots without prefix, and snapshots with <em>text_</em> and <em>test_me_</em> prefixes</p>
<h2 id="delete-all-zfsnap-snapshots-on-specific-filesystem">Delete all zfSnap snapshots on specific filesystem</h2>
<p>Since zfSnap v1.5.0 you can delete all zfSnap snapshots on specific filsystems</p>
<p>For example you make recursive zfSnap snapshots of your entire zpool,</p>
<p>but you don't want to keep snapshots of /tmp and /var/tmp,</p>
<p>because they obviously eat up space.</p>
<p>For this you can</p>
<pre><code># zfSnap -D zpool/tmp -D zpool/var/tmp</code></pre>
<p>this will delete all zfSnap snapshots of zpool/tmp and zpool/var/tmp ignoring ttl</p>
<p><strong>NOTE:</strong> -D option will only delete snapshots that match zfSnap snapshot name pattern (either old version, or new one)</p>
<p>You can also delete all zfSnap snapshots of specific filesytem recursively.</p>
<p>For example:</p>
<pre><code># zfSnap -r -D zpool/var</code></pre>
<p>Will delete all zfSnap snapshots of zpool/var and all it's sub-filesystems</p>
<h4 id="sample-snapshot-names">Sample snapshot names</h4>
<pre><code>$ zfs list -t snapshot | grep var
zpool/var@2010-08-02_12.06.00--1d 8,57M - 242M -
zpool/var@2010-08-02_13.06.00--1d 7,31M - 243M -
zpool/var@2010-08-02_14.06.00--1d 7,43M - 243M -
zpool/var@2010-08-02_15.06.00--1d 7,56M - 243M -
zpool/var@2010-08-02_16.06.00--1d 7,31M - 243M -
zpool/var@2010-08-02_17.06.00--1d 7,18M - 243M -
zpool/var@2010-08-02_18.45.00--1m 5,08M - 247M -
zpool/var@2010-08-02_19.06.00--1d 1,09M - 243M -
zpool/var@2010-08-02_20.06.00--1d 1,37M - 243M -
zpool/var@2010-08-02_21.06.00--1d 1,62M - 243M -
zpool/var@2010-08-02_22.06.00--1d 1,57M - 243M -
zpool/var@2010-08-02_23.06.00--1d 1,16M - 243M -
zpool/var@2010-08-03_00.06.00--5d 1,28M - 243M -
zpool/var@2010-08-03_01.06.00--5d 1,07M - 243M -
zpool/var@2010-08-03_02.06.00--5d 922K - 243M -
zpool/var@2010-08-03_03.06.00--5d 1,45M - 242M -
zpool/var@2010-08-03_04.06.00--5d 729K - 242M -
zpool/var@2010-08-03_05.06.00--5d 622K - 241M -
zpool/var@2010-08-03_06.06.00--5d 598K - 241M -
zpool/var@2010-08-03_06.45.00--2w 1,34M - 242M -
zpool/var@2010-08-03_07.06.00--5d 662K - 242M -
zpool/var@2010-08-03_08.06.00--5d 847K - 242M -
zpool/var@2010-08-03_09.06.00--5d 837K - 242M -
zpool/var@2010-08-03_10.06.00--5d 1,08M - 242M -
zpool/var@2010-08-03_11.06.00--5d 1,22M - 243M -
zpool/var@2010-08-03_12.06.00--5d 241K - 243M -</code></pre>
|