| 1 | .TH rsync-backup 8 "7 October 2012" rsync-backup |
| 2 | .SH SYNOPSIS |
| 3 | .B rsync-backup |
| 4 | .RB [ \-v ] |
| 5 | .RB [ \-c |
| 6 | .IR config-file ] |
| 7 | .SH DESCRIPTION |
| 8 | The |
| 9 | .B rsync-backup |
| 10 | script is a backup program of the currently popular |
| 11 | .RB ` rsync (1) |
| 12 | .BR \-\-link-dest ' |
| 13 | variety. It uses |
| 14 | .BR rsync 's |
| 15 | ability to create hardlinks from (apparently) similar existing local |
| 16 | trees to make incremental dumps efficient, even from remote sources. |
| 17 | Restoring files is easy because the backups created are just directories |
| 18 | full of files, exactly as they were on the source \(en and this is |
| 19 | verified using the |
| 20 | .BR fshash (1) |
| 21 | program. |
| 22 | .PP |
| 23 | The script does more than just running |
| 24 | .BR rsync . |
| 25 | It is also responsible for creating and removing snapshots of volumes to |
| 26 | be backed up, and expiring old dumps according to a user-specified |
| 27 | retention policy. |
| 28 | .SS Installation |
| 29 | The idea is that the |
| 30 | .B rsync-backup |
| 31 | script should be installed and run on a central backup server with local |
| 32 | access to the backup volumes. |
| 33 | .PP |
| 34 | The script should be run with full (root) privileges, so that it can |
| 35 | correctly record file ownership information. The server should also be |
| 36 | able to connect via |
| 37 | .BR ssh (1) |
| 38 | to the client machines, and run processes there as root. (This is not a |
| 39 | security disaster. Remember that the backup server is, in the end, |
| 40 | responsible for the integrity of the backup data. A dishonest backup |
| 41 | server can easily compromise a client which is being restored from |
| 42 | corrupt backup data.) |
| 43 | .PP |
| 44 | The |
| 45 | |
| 46 | |
| 47 | .SS Configuration commands |
| 48 | The configuration file is simply a Bash shell fragment: configuration |
| 49 | commands are shell functions. |
| 50 | .TP |
| 51 | .BI "backup " "fs\fR[:\fIfsarg\fR] ..." |
| 52 | Back up the named filesystems. The corresponding |
| 53 | .IR fsarg s |
| 54 | may be required by the snapshot type. |
| 55 | .TP |
| 56 | .BI "host " host |
| 57 | Future |
| 58 | .B backup |
| 59 | commands will back up filesystems on the named |
| 60 | .IR host . |
| 61 | This clears the |
| 62 | .B like |
| 63 | list. |
| 64 | .TP |
| 65 | .BI "like " "host\fR ..." |
| 66 | Declare that subsequent filesystems are `similar' to like-named |
| 67 | filesystems on the named |
| 68 | .IR host s, |
| 69 | and that |
| 70 | .B rsync |
| 71 | should use those trees as potential sources of hardlinkable files. Be |
| 72 | careful when using this option without |
| 73 | .BR rsync 's |
| 74 | .B \-\-checksum |
| 75 | option: an erroneous hardlink will cause the backup to fail. (The |
| 76 | backup won't be left silently incorrect.) |
| 77 | .TP |
| 78 | .BI "retain " frequency " " duration |
| 79 | Define part a backup retention policy: backup trees of the |
| 80 | .I frequency |
| 81 | should be kept for the |
| 82 | .IR duration . |
| 83 | The |
| 84 | .I frequency |
| 85 | can be |
| 86 | .BR daily , |
| 87 | .BR weekly , |
| 88 | .BR monthly , |
| 89 | or |
| 90 | .B annually |
| 91 | (or |
| 92 | .BR yearly , |
| 93 | which means the same); the |
| 94 | .I duration |
| 95 | may be any of |
| 96 | .BR week , |
| 97 | .BR month , |
| 98 | .BR year , |
| 99 | or |
| 100 | .BR forever . |
| 101 | Expiry considers each existing dump against the policy lines in order: |
| 102 | the last applicable line determines the dump's fate \(en so you should |
| 103 | probably write the lines in decreasing order of duration. |
| 104 | .TP |
| 105 | .BI "snap " type " " \fR[\fIargs\fR...] |
| 106 | Use the snapshot |
| 107 | .I type |
| 108 | for subsequent backups. Some snapshot types require additional |
| 109 | arguments, which may be supplied here. |
| 110 | .SS Configuration variables |
| 111 | The following shell variables may be overridden by the configuration |
| 112 | file. |
| 113 | .TP |
| 114 | .B MAXLOG |
| 115 | The number of log files to be kept for each filesystem. Old logfiles |
| 116 | are deleted to keep the total number below this bound. The default |
| 117 | value is 14. |
| 118 | .TP |
| 119 | .B RSYNCOPTS |
| 120 | Command-line options to pass to |
| 121 | .BR rsync (1) |
| 122 | in addition to the basic set: |
| 123 | .B \-\-archive \-\-hard-links \-\-numeric-ids \-\-del \-\-sparse |
| 124 | .B \-\-compress \-\-one-file-system \-\-partial |
| 125 | .B \-\-filter="dir-merge .rsync-backup" |
| 126 | The default is |
| 127 | .BR \-\-verbose . |
| 128 | .TP |
| 129 | .B SNAPDIR |
| 130 | LVM (and |
| 131 | .BR rfreezefs ) |
| 132 | snapshots are mounted on subdirectories below the |
| 133 | .B SNAPDIR |
| 134 | .IR "on backup clients" . |
| 135 | The default is |
| 136 | .IB mntbkpdir /snap |
| 137 | where |
| 138 | .I mntbkpdir |
| 139 | is the backup mount directory configured at build time. |
| 140 | .TP |
| 141 | .B SNAPSIZE |
| 142 | The volume size option to pass to |
| 143 | .BR lvcreate (8) |
| 144 | when creating a snapshot. The default is |
| 145 | .B \-l10%ORIGIN |
| 146 | which seems to work fairly well. |
| 147 | .TP |
| 148 | .B STOREDIR |
| 149 | Where the actual backup trees should be stored. See the section on |
| 150 | .B Archive structure |
| 151 | below. |
| 152 | The default is |
| 153 | .IB mntbkpdir /store |
| 154 | where |
| 155 | .I mntbkpdir |
| 156 | is the backup mount directory configured at build time. |
| 157 | .TP |
| 158 | .B HASH |
| 159 | The hash function to use for verifying archive integrity. This is |
| 160 | passed to the |
| 161 | .B \-H |
| 162 | option of |
| 163 | .BR fshash , |
| 164 | so it must name one of the hash functions supported by your Python's |
| 165 | .B hashlib |
| 166 | module. The default is |
| 167 | .BR sha256 . |
| 168 | .SS Hook functions |
| 169 | The configuration file may define shell functions to perform custom |
| 170 | actions at various points in the backup process. |
| 171 | .TP |
| 172 | .BI "backup_precommit_hook " host " " fs " " date |
| 173 | Called after a backup has been verified complete and about to be |
| 174 | committed. The backup tree is in |
| 175 | .B new |
| 176 | in the current directory, and the |
| 177 | .B fshash |
| 178 | manifest is in |
| 179 | .BR new.fshash . |
| 180 | A typical action would be to create a digital signature on the |
| 181 | manifest. |
| 182 | .TP |
| 183 | .BI "backup_commit_hook " host " " fs " " date |
| 184 | Called during the commit procedure. The backup tree and manifest have |
| 185 | been renamed into their proper places. Typically one would use this |
| 186 | hook to rename files created by the |
| 187 | .B backup_precommit_hook |
| 188 | function. |
| 189 | .TP |
| 190 | .BR "whine " [ \-n ] " " \fItext\fR... |
| 191 | Called to report `interesting' events when the |
| 192 | .B \-v |
| 193 | option is in force. The default action is to echo the |
| 194 | .I text |
| 195 | to (what was initially) standard output, followed by a newline unless |
| 196 | .B \-n |
| 197 | is given. |
| 198 | .SS Snapshot types |
| 199 | The following snapshot types are available. |
| 200 | .TP |
| 201 | .B live |
| 202 | A trivial snapshot type: attempts to back up a live filesystem. How |
| 203 | well this works depends on how active the filesystem is. If files |
| 204 | change while the dump is in progress then the |
| 205 | .B fshash |
| 206 | verification will likely fail. Backups using this snapshot type must |
| 207 | specify the filesystem mount point as the |
| 208 | .IR fsarg . |
| 209 | .TP |
| 210 | .B ro |
| 211 | A slightly less trivial snapshot type: make the filesystem read-only |
| 212 | while the dump is in progress. Backups using this snapshot type must |
| 213 | specify the filesystem mount point as the |
| 214 | .IR fsarg . |
| 215 | .TP |
| 216 | .BI "lvm " vg |
| 217 | Create snapshots using LVM. The snapshot argument is interpreted as the |
| 218 | relevant volume group. The filesystem name is interpreted as the origin |
| 219 | volume name; the snapshot will be called |
| 220 | .IB fs .bkp |
| 221 | and mounted on |
| 222 | .IB SNAPDIR / fs \fR; |
| 223 | space will be allocated to it according to the |
| 224 | .I SNAPSIZE |
| 225 | variable. |
| 226 | .TP |
| 227 | .BI "rfreezefs " client " " vg |
| 228 | This gets complicated. Suppose that a server has an LVM volume group, |
| 229 | and exports (somehow) a logical volume to a client. Examples are a host |
| 230 | providing a virtual disk to a guest, or a server providing |
| 231 | network-attached storage to a client. The server can create a snapshot |
| 232 | of the volume using LVM, but must synchronize with the client to ensure |
| 233 | that the filesystem image captured in the snapshot is clean. The |
| 234 | .BR rfreezefs (8) |
| 235 | program should be installed on the client to perform this rather |
| 236 | delicate synchronization. Declare the server using the |
| 237 | .B host |
| 238 | command as usual; pass the client's name as the |
| 239 | .I client |
| 240 | and the |
| 241 | server's volume group name as the |
| 242 | .I vg |
| 243 | snapshot arguments. Finally, backups using this snapshot type must |
| 244 | specify the filesystem mount point (or, actually, any file in the |
| 245 | filesystem) on the client, as the |
| 246 | .IR fsarg . |
| 247 | .PP |
| 248 | Additional snapshot types can be defined in the configuration file. A |
| 249 | snapshot type requires two shell functions. |
| 250 | .TP |
| 251 | .BI snap_ type " " snapargs " " fs " " fsarg |
| 252 | Create the snapshot, and write the mountpoint (on the client host) to |
| 253 | standard output, in a form suitable as an argument to |
| 254 | .BR rsync . |
| 255 | .TP |
| 256 | .BI unsnap_ type " " snapargs " " fs " " fsarg |
| 257 | Remove the snapshot. |
| 258 | .PP |
| 259 | There are a number of utility functions which can be used by snapshot |
| 260 | type handlers: please see the script for details. Please send the |
| 261 | author interesting snapshot handlers for inclusion in the main |
| 262 | distribution. |
| 263 | .SS Archive structure |