| 1 | <?xml version="1.0" encoding="iso-8859-1"?> |
|---|
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml"> |
|---|
| 4 | <head> |
|---|
| 5 | <meta http-equiv="content-type" content="text/html;charset=iso-8859-1" /> |
|---|
| 6 | <title>Box Backup client configuration</title> |
|---|
| 7 | <link rel="stylesheet" href="bbstyles.css" type="text/css" /> |
|---|
| 8 | </head> |
|---|
| 9 | <body> |
|---|
| 10 | <div align="center"> |
|---|
| 11 | <div id="header"> |
|---|
| 12 | <div id="logo"> |
|---|
| 13 | <img src="images/bblogo.png" alt="logo" height="65" width="331" border="0" vspace="5" align="middle" /> <img src="images/stepahead.png" alt="a step ahead in data security" width="182" height="11" hspace="10" vspace="20" border="0" align="middle" /></div> |
|---|
| 14 | </div> |
|---|
| 15 | <div id="page"> |
|---|
| 16 | |
|---|
| 17 | |
|---|
| 18 | <h1>Box Backup client configuration</h1> |
|---|
| 19 | |
|---|
| 20 | <h2>Before you start</h2> |
|---|
| 21 | |
|---|
| 22 | <p>Before you can do any configuration, you need to know the hostname of the server |
|---|
| 23 | you will be using, and your account number on that server.</p> |
|---|
| 24 | |
|---|
| 25 | <p>Later in the process, you will need to send a certificate request to the administrator |
|---|
| 26 | of that server for it to be signed.</p> |
|---|
| 27 | |
|---|
| 28 | <p>Installation is covered in the <a href="install.html">compiling and installing</a> section. |
|---|
| 29 | You only need the backup-client parcel.</p> |
|---|
| 30 | |
|---|
| 31 | <p><b>It is important that you read all the output of the config scripts.</b> See the end |
|---|
| 32 | of this page for an example.</p> |
|---|
| 33 | |
|---|
| 34 | <p>The backup client has to be run as root, because it needs to read all your files to |
|---|
| 35 | back them up, although it is possible to back up a single user's files by running it as that user. |
|---|
| 36 | (Tip: specify a directory other than /etc/box, and then give the alternate config file |
|---|
| 37 | as the first argument to bbackupd). However, it will fall over if you don't give yourself |
|---|
| 38 | read access to one of your files.</p> |
|---|
| 39 | |
|---|
| 40 | <h2>Step 1</h2> |
|---|
| 41 | |
|---|
| 42 | <p>Run the <tt>bbackupd-config</tt> script to generate the configuration files |
|---|
| 43 | and generate a private key and certificate request.</p> |
|---|
| 44 | |
|---|
| 45 | <pre> |
|---|
| 46 | /usr/local/bin/bbackupd-config /etc/box lazy <b>999</b> <b>hostname</b> /var/bbackupd <b>/home</b> |
|---|
| 47 | </pre> |
|---|
| 48 | |
|---|
| 49 | <p>(See <a href="openssl.html">OpenSSL notes</a> if you get an OpenSSL error)</p> |
|---|
| 50 | |
|---|
| 51 | <p>The items in bold need to be changed. In order, they are the account number, the hostname |
|---|
| 52 | of the server you're using, and finally, the directories you want backed up. You can include as |
|---|
| 53 | many you want here.</p> |
|---|
| 54 | |
|---|
| 55 | <p>However, the directories you specify <b>must not</b> contain other mounted file systems within them |
|---|
| 56 | at any depth. Specify them separately, one per mount point. No checks are currently made to |
|---|
| 57 | catch bad configuration of this nature!</p> |
|---|
| 58 | |
|---|
| 59 | <p>You may also want to consider changing the mode from <i>lazy</i> to <i>snapshot</i>, depending on |
|---|
| 60 | what your system is used for.</p> |
|---|
| 61 | |
|---|
| 62 | <dl> |
|---|
| 63 | <dt>lazy |
|---|
| 64 | <dd>This mode regularly scans the files, with only a rough schedule. It uploads files as and |
|---|
| 65 | when they are changed, if the latest version is more than a set age. This is good for backing up |
|---|
| 66 | user's documents stored on a server, and spreads the load out over the day. |
|---|
| 67 | <dt>snapshot |
|---|
| 68 | <dd>This mode emulates the traditional backup behaviour of taking a snapshot of the filesystem. |
|---|
| 69 | The backup daemon does absolutely nothing until it is instructed to make a backup using the |
|---|
| 70 | <tt>bbackupctl</tt> utility (probably as a cron job), at which point it uploads all files which |
|---|
| 71 | have been changed since the last time it uploaded. |
|---|
| 72 | </dl> |
|---|
| 73 | |
|---|
| 74 | <p>When you run the config script, it will tell you what you need to do next. Don't forget to read |
|---|
| 75 | all the output. An example is shown at the end of this page, but the instructions for your installation |
|---|
| 76 | may be different.</p> |
|---|
| 77 | |
|---|
| 78 | <h2>Step 2</h2> |
|---|
| 79 | |
|---|
| 80 | <p>After you have sent your certificate request off to the server administrator and received your |
|---|
| 81 | certificate and CA root back, install them where instructed by the <tt>bbackupd-config</tt> script in step 1.</p> |
|---|
| 82 | |
|---|
| 83 | <p>You can then run the daemon (as root) by typing <tt>/usr/local/bin/bbackupd</tt>, and of course, adding |
|---|
| 84 | it to your system's startup scripts. The first time it's run it will upload everything. Interrupting |
|---|
| 85 | it and restarting it will only upload files which were not uploaded before - it's very tolerant.</p> |
|---|
| 86 | |
|---|
| 87 | <p>If you run in snapshot mode, you will need to add a cron job to schedule backups. The config |
|---|
| 88 | script will tell you the exact command to use for your system.</p> |
|---|
| 89 | |
|---|
| 90 | <p>Please read the <a href="trouble.html">Troubleshooting</a> page if you have problems.</p> |
|---|
| 91 | |
|---|
| 92 | |
|---|
| 93 | <p><b>Remember</b> to make a traditional backup of the keys file, as instructed. You cannot restore |
|---|
| 94 | files without it.</p> |
|---|
| 95 | |
|---|
| 96 | <p>It is recommended that you backup up all of <tt>/etc/box</tt> as it will make things easier if you |
|---|
| 97 | need to restore files. But only the keys are absolutely essential.</p> |
|---|
| 98 | |
|---|
| 99 | <p>If you want to see what it's doing in more detail (probably a good idea), follow the instructions in the server setup |
|---|
| 100 | to create new log files with syslog.</p> |
|---|
| 101 | |
|---|
| 102 | |
|---|
| 103 | <h2>Adding and removing backed up locations</h2> |
|---|
| 104 | |
|---|
| 105 | <p>By editing the <tt>/etc/box/bbackupd.conf</tt> file, you can add and remove directories |
|---|
| 106 | to back up -- see comments in this file for help. Send <tt>bbackupd</tt> a HUP signal after you modify it.</p> |
|---|
| 107 | |
|---|
| 108 | <p>When you remove a location, it will not be marked as deleted immediately. Instead, |
|---|
| 109 | <tt>bbackupd</tt> waits about two days before doing so, just in case you change your mind. |
|---|
| 110 | After this, it will be eventually removed from the store by the housekeeping process.</p> |
|---|
| 111 | |
|---|
| 112 | |
|---|
| 113 | <h2>Run as root</h2> |
|---|
| 114 | |
|---|
| 115 | <p>The backup client is designed to be run as root. It is possible to |
|---|
| 116 | <a href="nonroot.html">run without root</a>, but this is not recommended.</p> |
|---|
| 117 | |
|---|
| 118 | |
|---|
| 119 | <h2>Clock synchronisation for file servers</h2> |
|---|
| 120 | |
|---|
| 121 | <p>If you are using the backup client to backup a filesystem served from a fileserver, |
|---|
| 122 | you should ideally ensure that the fileserver clocks are synchronised with the fileserver.</p> |
|---|
| 123 | |
|---|
| 124 | <p><tt>bbackupd</tt> will cope perfectly well if the clocks are not synchronised. Errors up |
|---|
| 125 | to about half an hour cause no problems. Larger discrepancies cause a loss of efficiency |
|---|
| 126 | and the potential to back up a file during a write process.</p> |
|---|
| 127 | |
|---|
| 128 | <p>There is a configuration parameter <tt>MaxFileTimeInFuture</tt>, which specifies how far |
|---|
| 129 | in the future a file must be for it to be uploaded as soon as it is seen. You should not need |
|---|
| 130 | to adjust this (default is 2 days). Instead, get those clocks synchronised.</p> |
|---|
| 131 | |
|---|
| 132 | |
|---|
| 133 | <h2>Excluding files and directories from the backup</h2> |
|---|
| 134 | |
|---|
| 135 | <p>Within the <tt>bbackupd.conf</tt> file, there is a section named |
|---|
| 136 | <tt>BackupLocations</tt> which specifies which locations on disc should be backed up. |
|---|
| 137 | It has subsections, each of which is in the format</p> |
|---|
| 138 | |
|---|
| 139 | <pre> |
|---|
| 140 | <i>name</i> |
|---|
| 141 | { |
|---|
| 142 | Path = <i>/path/of/directory</i> |
|---|
| 143 | <i>(optional exclude directives)</i> |
|---|
| 144 | } |
|---|
| 145 | </pre> |
|---|
| 146 | |
|---|
| 147 | <p><i>name</i> is derived from the Path by the config script, but should merely be |
|---|
| 148 | unique.</p> |
|---|
| 149 | |
|---|
| 150 | <p>The exclude directives are of the form</p> |
|---|
| 151 | |
|---|
| 152 | <pre> |
|---|
| 153 | [Exclude|AlwaysInclude][File|Dir][|sRegex] = regex or full pathname |
|---|
| 154 | </pre> |
|---|
| 155 | |
|---|
| 156 | <p>(The regex suffix is shown as 'sRegex' to make File or Dir plural)</p> |
|---|
| 157 | |
|---|
| 158 | <p>For example:</p> |
|---|
| 159 | |
|---|
| 160 | <pre> |
|---|
| 161 | ExcludeDir = /home/guest-user |
|---|
| 162 | ExcludeFilesRegex = *.(mp3|MP3)\$ |
|---|
| 163 | AlwaysIncludeFile = /home/username/veryimportant.mp3 |
|---|
| 164 | </pre> |
|---|
| 165 | |
|---|
| 166 | <p>This excludes the directory /home/guest-user from the backup along with all mp3 |
|---|
| 167 | files, except one MP3 file in particular.</p> |
|---|
| 168 | |
|---|
| 169 | <p>In general, Exclude excludes a file or directory, unless the directory is |
|---|
| 170 | explicitly mentioned in a AlwaysInclude directive.</p> |
|---|
| 171 | |
|---|
| 172 | <p>If a directive ends in Regex, then it is a regular expression rather than a |
|---|
| 173 | explicit full pathname. See</p> |
|---|
| 174 | |
|---|
| 175 | <pre> |
|---|
| 176 | man 7 re_format |
|---|
| 177 | </pre> |
|---|
| 178 | |
|---|
| 179 | <p>for the regex syntax on your platform.</p> |
|---|
| 180 | |
|---|
| 181 | |
|---|
| 182 | |
|---|
| 183 | |
|---|
| 184 | <h2>Example configuration output</h2> |
|---|
| 185 | |
|---|
| 186 | <p>This is an example of output from the bbstored-config script. <b>Important:</b> |
|---|
| 187 | Follow the instructions output by your script, not the ones here -- they may be different |
|---|
| 188 | for your system.</p> |
|---|
| 189 | |
|---|
| 190 | <pre> |
|---|
| 191 | # /usr/local/bin/bbackupd-config /etc/box lazy 51 server.example.com /var/bbackupd /home /etc/samba |
|---|
| 192 | |
|---|
| 193 | Setup bbackupd config utility. |
|---|
| 194 | |
|---|
| 195 | Configuration: |
|---|
| 196 | Writing configuration file: /etc/box/bbackupd.conf |
|---|
| 197 | Account: 51 |
|---|
| 198 | Server hostname: server.example.com |
|---|
| 199 | Directories to back up: |
|---|
| 200 | /home |
|---|
| 201 | /etc/samba |
|---|
| 202 | |
|---|
| 203 | Note: If other file systems are mounted inside these directories, then problems may occur |
|---|
| 204 | with files on the store server being renamed incorrectly. This will cause efficiency |
|---|
| 205 | problems, but not affect the integrity of the backups. |
|---|
| 206 | |
|---|
| 207 | WARNING: Directories not checked against mountpoints. Check mounted filesystems manually. |
|---|
| 208 | |
|---|
| 209 | Creating /etc/box... |
|---|
| 210 | Creating /etc/box/bbackupd |
|---|
| 211 | Generating private key... |
|---|
| 212 | [OpenSSL output omitted] |
|---|
| 213 | |
|---|
| 214 | Generating keys for file backup |
|---|
| 215 | Writing notify script /etc/box/bbackupd/NotifyStoreFull.sh |
|---|
| 216 | Writing configuration file /etc/box/bbackupd.conf |
|---|
| 217 | |
|---|
| 218 | =================================================================== |
|---|
| 219 | |
|---|
| 220 | bbackupd basic configuration complete. |
|---|
| 221 | |
|---|
| 222 | What you need to do now... |
|---|
| 223 | |
|---|
| 224 | 1) Make a backup of /etc/box/bbackupd/51-FileEncKeys.raw |
|---|
| 225 | This should be a secure offsite backup. |
|---|
| 226 | Without it, you cannot restore backups. Everything else can |
|---|
| 227 | be replaced. But this cannot. |
|---|
| 228 | KEEP IT IN A SAFE PLACE, OTHERWISE YOUR BACKUPS ARE USELESS. |
|---|
| 229 | |
|---|
| 230 | 2) Send /etc/box/bbackupd/51-csr.pem |
|---|
| 231 | to the administrator of the backup server, and ask for it to |
|---|
| 232 | be signed. |
|---|
| 233 | |
|---|
| 234 | 3) The administrator will send you two files. Install them as |
|---|
| 235 | /etc/box/bbackupd/51-cert.pem |
|---|
| 236 | /etc/box/bbackupd/serverCA.pem |
|---|
| 237 | after checking their authenticity. |
|---|
| 238 | |
|---|
| 239 | 4) You may wish to read the configuration file |
|---|
| 240 | /etc/box/bbackupd.conf |
|---|
| 241 | and adjust as appropraite. |
|---|
| 242 | |
|---|
| 243 | There are some notes in it on excluding files you do not |
|---|
| 244 | wish to be backed up. |
|---|
| 245 | |
|---|
| 246 | 5) Review the script |
|---|
| 247 | /etc/box/bbackupd/NotifyStoreFull.sh |
|---|
| 248 | and check that it will email the right person when the store |
|---|
| 249 | becomes full. This is important -- when the store is full, no |
|---|
| 250 | more files will be backed up. You want to know about this. |
|---|
| 251 | |
|---|
| 252 | 6) Start the backup daemon with the command |
|---|
| 253 | /usr/local/bin/bbackupd |
|---|
| 254 | in /etc/rc.local, or your local equivalent. |
|---|
| 255 | Note that bbackupd must run as root. |
|---|
| 256 | |
|---|
| 257 | =================================================================== |
|---|
| 258 | |
|---|
| 259 | Remember to make a secure, offsite backup of your backup keys, |
|---|
| 260 | as described in step 1 above. If you do not, you have no backups. |
|---|
| 261 | </pre> |
|---|
| 262 | |
|---|
| 263 | <p> </p> |
|---|
| 264 | <p>© Ben Summers, 2003, 2004</p> |
|---|
| 265 | <p> </p> |
|---|
| 266 | </div> |
|---|
| 267 | </div> |
|---|
| 268 | </body> |
|---|
| 269 | </html> |
|---|
| 270 | |
|---|
