| 1 | <?xml version="1.0" encoding="UTF-8"?> |
|---|
| 2 | <refentry version="5.0" xmlns="http://docbook.org/ns/docbook" |
|---|
| 3 | xmlns:xlink="http://www.w3.org/1999/xlink" |
|---|
| 4 | xmlns:xi="http://www.w3.org/2001/XInclude" |
|---|
| 5 | xmlns:svg="http://www.w3.org/2000/svg" |
|---|
| 6 | xmlns:m="http://www.w3.org/1998/Math/MathML" |
|---|
| 7 | xmlns:html="http://www.w3.org/1999/xhtml" |
|---|
| 8 | xmlns:db="http://docbook.org/ns/docbook"> |
|---|
| 9 | <refmeta> |
|---|
| 10 | <refentrytitle>bbackupquery</refentrytitle> |
|---|
| 11 | |
|---|
| 12 | <manvolnum>8</manvolnum> |
|---|
| 13 | |
|---|
| 14 | <refmiscinfo class="manual">Box Backup</refmiscinfo> |
|---|
| 15 | |
|---|
| 16 | <refmiscinfo class="source">Box Backup</refmiscinfo> |
|---|
| 17 | |
|---|
| 18 | <refmiscinfo class="version">0.11</refmiscinfo> |
|---|
| 19 | </refmeta> |
|---|
| 20 | |
|---|
| 21 | <refnamediv> |
|---|
| 22 | <refname>bbackupquery</refname> |
|---|
| 23 | |
|---|
| 24 | <refpurpose>Box Backup store query and file retrieval</refpurpose> |
|---|
| 25 | </refnamediv> |
|---|
| 26 | |
|---|
| 27 | <refsynopsisdiv> |
|---|
| 28 | <cmdsynopsis> |
|---|
| 29 | <command>bbackupquery</command> |
|---|
| 30 | |
|---|
| 31 | <arg>-q</arg> |
|---|
| 32 | |
|---|
| 33 | <arg>-c configfile</arg> |
|---|
| 34 | |
|---|
| 35 | <arg>command ...</arg> |
|---|
| 36 | </cmdsynopsis> |
|---|
| 37 | </refsynopsisdiv> |
|---|
| 38 | |
|---|
| 39 | <refsection> |
|---|
| 40 | <title>Description</title> |
|---|
| 41 | |
|---|
| 42 | <para><command>bbackupquery</command> is the main way of interacting with |
|---|
| 43 | the backup store from a Box Backup client machine. It supports both |
|---|
| 44 | interactive and batch modes of operation.</para> |
|---|
| 45 | |
|---|
| 46 | <para>It can be used to reviewing the status of a client machine's backup |
|---|
| 47 | store, getting status from the store server. The main use is to retrieve |
|---|
| 48 | files and directories when needed.</para> |
|---|
| 49 | |
|---|
| 50 | <para><command>bbackupquery</command> supports interactive and batch modes |
|---|
| 51 | of operation. Interactive mode allows for interaction with the server much |
|---|
| 52 | like an interactive FTP client.</para> |
|---|
| 53 | |
|---|
| 54 | <para>Batch mode is invoked by putting commands into the invocation of |
|---|
| 55 | <command>bbackupquery</command>. Example:</para> |
|---|
| 56 | |
|---|
| 57 | <para><programlisting>bbackupquery "list home-dirs" quit</programlisting></para> |
|---|
| 58 | |
|---|
| 59 | <para>Note that commands that contain spaces are enclosed in double |
|---|
| 60 | quotes. If the <command>quit</command> command is omitted, after the |
|---|
| 61 | preceding commands are completed, <command>bbackupquery</command> will |
|---|
| 62 | enter interactive mode.</para> |
|---|
| 63 | </refsection> |
|---|
| 64 | |
|---|
| 65 | <refsection> |
|---|
| 66 | <title>Options</title> |
|---|
| 67 | |
|---|
| 68 | <para><variablelist> |
|---|
| 69 | <varlistentry> |
|---|
| 70 | <term><option>-q</option></term> |
|---|
| 71 | |
|---|
| 72 | <listitem> |
|---|
| 73 | <para>Quiet. Suppresses status output while running.</para> |
|---|
| 74 | </listitem> |
|---|
| 75 | </varlistentry> |
|---|
| 76 | |
|---|
| 77 | <varlistentry> |
|---|
| 78 | <term><option>-c</option> <option>configfile</option></term> |
|---|
| 79 | |
|---|
| 80 | <listitem> |
|---|
| 81 | <para>Use configfile instead of the default bbackupd.conf file. |
|---|
| 82 | Can be a relative or full path.</para> |
|---|
| 83 | </listitem> |
|---|
| 84 | </varlistentry> |
|---|
| 85 | </variablelist></para> |
|---|
| 86 | </refsection> |
|---|
| 87 | |
|---|
| 88 | <refsection> |
|---|
| 89 | <title>Commands</title> |
|---|
| 90 | |
|---|
| 91 | <para>The commands that can be used in bbackupquery are listed |
|---|
| 92 | below.</para> |
|---|
| 93 | |
|---|
| 94 | <variablelist> |
|---|
| 95 | <varlistentry> |
|---|
| 96 | <term><command>help</command></term> |
|---|
| 97 | |
|---|
| 98 | <listitem> |
|---|
| 99 | <para>Displays the basic help message, which gives information about |
|---|
| 100 | the commands available in <command>bbackupquery</command>. Use the |
|---|
| 101 | form <command>help command</command> to get help on a specific |
|---|
| 102 | command.</para> |
|---|
| 103 | </listitem> |
|---|
| 104 | </varlistentry> |
|---|
| 105 | |
|---|
| 106 | <varlistentry> |
|---|
| 107 | <term><command>quit</command></term> |
|---|
| 108 | |
|---|
| 109 | <listitem> |
|---|
| 110 | <para>End the session with the store server, and quit |
|---|
| 111 | bbackupquery.</para> |
|---|
| 112 | </listitem> |
|---|
| 113 | </varlistentry> |
|---|
| 114 | |
|---|
| 115 | <varlistentry> |
|---|
| 116 | <term><command>cd</command> <optional>options</optional> |
|---|
| 117 | <varname>directory-name</varname></term> |
|---|
| 118 | |
|---|
| 119 | <listitem> |
|---|
| 120 | <para>Change directory. Options: <variablelist> |
|---|
| 121 | <varlistentry> |
|---|
| 122 | <term><option>-d</option></term> |
|---|
| 123 | |
|---|
| 124 | <listitem> |
|---|
| 125 | <para>consider deleted directories for traversal</para> |
|---|
| 126 | </listitem> |
|---|
| 127 | </varlistentry> |
|---|
| 128 | |
|---|
| 129 | <varlistentry> |
|---|
| 130 | <term><option>-o</option></term> |
|---|
| 131 | |
|---|
| 132 | <listitem> |
|---|
| 133 | <para>consider old versions of directories for traversal. |
|---|
| 134 | This option should never be useful in a correctly formed |
|---|
| 135 | store.</para> |
|---|
| 136 | </listitem> |
|---|
| 137 | </varlistentry> |
|---|
| 138 | </variablelist></para> |
|---|
| 139 | </listitem> |
|---|
| 140 | </varlistentry> |
|---|
| 141 | |
|---|
| 142 | <varlistentry> |
|---|
| 143 | <term><command>lcd</command> |
|---|
| 144 | <varname>local-directory-name</varname></term> |
|---|
| 145 | |
|---|
| 146 | <listitem> |
|---|
| 147 | <para>Change directory on the client machine. To list the contents |
|---|
| 148 | of the local directory, type <command>sh ls</command> (on Unix-like |
|---|
| 149 | machines).</para> |
|---|
| 150 | </listitem> |
|---|
| 151 | </varlistentry> |
|---|
| 152 | |
|---|
| 153 | <varlistentry> |
|---|
| 154 | <term><command>list</command> <optional>options</optional> |
|---|
| 155 | <optional>directory-name</optional></term> |
|---|
| 156 | |
|---|
| 157 | <listitem> |
|---|
| 158 | <para>The list (or its synonym <command>ls</command>) command lists |
|---|
| 159 | the content of the current, or specified, directory. The options are |
|---|
| 160 | as follows:</para> |
|---|
| 161 | |
|---|
| 162 | <para><variablelist> |
|---|
| 163 | <varlistentry> |
|---|
| 164 | <term><option>-r</option></term> |
|---|
| 165 | |
|---|
| 166 | <listitem> |
|---|
| 167 | <para>recursively list all files</para> |
|---|
| 168 | </listitem> |
|---|
| 169 | </varlistentry> |
|---|
| 170 | |
|---|
| 171 | <varlistentry> |
|---|
| 172 | <term><option>-d</option></term> |
|---|
| 173 | |
|---|
| 174 | <listitem> |
|---|
| 175 | <para>list deleted files and directories</para> |
|---|
| 176 | </listitem> |
|---|
| 177 | </varlistentry> |
|---|
| 178 | |
|---|
| 179 | <varlistentry> |
|---|
| 180 | <term><option>-o</option></term> |
|---|
| 181 | |
|---|
| 182 | <listitem> |
|---|
| 183 | <para>list old versions of files and directories</para> |
|---|
| 184 | </listitem> |
|---|
| 185 | </varlistentry> |
|---|
| 186 | |
|---|
| 187 | <varlistentry> |
|---|
| 188 | <term><option>-I</option></term> |
|---|
| 189 | |
|---|
| 190 | <listitem> |
|---|
| 191 | <para>don't display object IDs</para> |
|---|
| 192 | </listitem> |
|---|
| 193 | </varlistentry> |
|---|
| 194 | |
|---|
| 195 | <varlistentry> |
|---|
| 196 | <term><option>-F</option></term> |
|---|
| 197 | |
|---|
| 198 | <listitem> |
|---|
| 199 | <para>don't display flags</para> |
|---|
| 200 | </listitem> |
|---|
| 201 | </varlistentry> |
|---|
| 202 | |
|---|
| 203 | <varlistentry> |
|---|
| 204 | <term><option>-t</option></term> |
|---|
| 205 | |
|---|
| 206 | <listitem> |
|---|
| 207 | <para>show file modification time (and attr mod time, if the |
|---|
| 208 | object has attributes).</para> |
|---|
| 209 | </listitem> |
|---|
| 210 | </varlistentry> |
|---|
| 211 | |
|---|
| 212 | <varlistentry> |
|---|
| 213 | <term><option>-s</option></term> |
|---|
| 214 | |
|---|
| 215 | <listitem> |
|---|
| 216 | <para>show file size in blocks used on server. Note that |
|---|
| 217 | this is only a very approximate indication of local file |
|---|
| 218 | size.</para> |
|---|
| 219 | </listitem> |
|---|
| 220 | </varlistentry> |
|---|
| 221 | </variablelist></para> |
|---|
| 222 | </listitem> |
|---|
| 223 | </varlistentry> |
|---|
| 224 | |
|---|
| 225 | <varlistentry> |
|---|
| 226 | <term><command>ls</command> <optional>options</optional> |
|---|
| 227 | <optional>directory-name</optional></term> |
|---|
| 228 | |
|---|
| 229 | <listitem> |
|---|
| 230 | <para>Synonym for <command>list</command>.</para> |
|---|
| 231 | </listitem> |
|---|
| 232 | </varlistentry> |
|---|
| 233 | |
|---|
| 234 | <varlistentry> |
|---|
| 235 | <term><command>pwd</command></term> |
|---|
| 236 | |
|---|
| 237 | <listitem> |
|---|
| 238 | <para>Print current directory, always relative to the backup store |
|---|
| 239 | root.</para> |
|---|
| 240 | </listitem> |
|---|
| 241 | </varlistentry> |
|---|
| 242 | |
|---|
| 243 | <varlistentry> |
|---|
| 244 | <term><command>sh</command> <varname>shell-command</varname></term> |
|---|
| 245 | |
|---|
| 246 | <listitem> |
|---|
| 247 | <para>Everything after the sh is passed to a shell and run. All |
|---|
| 248 | output from the command is displayed in the client.</para> |
|---|
| 249 | |
|---|
| 250 | <para>Example: to list the contents of the current directory on the |
|---|
| 251 | client machine type <command>sh ls</command>.</para> |
|---|
| 252 | </listitem> |
|---|
| 253 | </varlistentry> |
|---|
| 254 | |
|---|
| 255 | <varlistentry> |
|---|
| 256 | <term><command>compare -a</command></term> |
|---|
| 257 | |
|---|
| 258 | <listitem> |
|---|
| 259 | <para></para> |
|---|
| 260 | </listitem> |
|---|
| 261 | </varlistentry> |
|---|
| 262 | |
|---|
| 263 | <varlistentry> |
|---|
| 264 | <term><command>compare -l</command> |
|---|
| 265 | <varname>location-name</varname></term> |
|---|
| 266 | |
|---|
| 267 | <listitem> |
|---|
| 268 | <para></para> |
|---|
| 269 | </listitem> |
|---|
| 270 | </varlistentry> |
|---|
| 271 | |
|---|
| 272 | <varlistentry> |
|---|
| 273 | <term><command>compare</command> <varname>store-dir-name</varname> |
|---|
| 274 | <varname>local-dir-name</varname></term> |
|---|
| 275 | |
|---|
| 276 | <listitem> |
|---|
| 277 | <para>Compare the current data in the store with the data on the |
|---|
| 278 | disc. Please note that all the data will be downloaded from the |
|---|
| 279 | store, so this can be a very lengthy process depending on the size |
|---|
| 280 | of the store, and the size of the part you are comparing.</para> |
|---|
| 281 | |
|---|
| 282 | <para>Options:</para> |
|---|
| 283 | |
|---|
| 284 | <para><variablelist> |
|---|
| 285 | <varlistentry> |
|---|
| 286 | <term><option>-a</option></term> |
|---|
| 287 | |
|---|
| 288 | <listitem> |
|---|
| 289 | <para>compare all locations.</para> |
|---|
| 290 | </listitem> |
|---|
| 291 | </varlistentry> |
|---|
| 292 | |
|---|
| 293 | <varlistentry> |
|---|
| 294 | <term><option>-l</option></term> |
|---|
| 295 | |
|---|
| 296 | <listitem> |
|---|
| 297 | <para>compare one backup location as specified in the |
|---|
| 298 | configuration file. This compares one of the top level store |
|---|
| 299 | directories.</para> |
|---|
| 300 | </listitem> |
|---|
| 301 | </varlistentry> |
|---|
| 302 | |
|---|
| 303 | <varlistentry> |
|---|
| 304 | <term><option>-c</option></term> |
|---|
| 305 | |
|---|
| 306 | <listitem> |
|---|
| 307 | <para>set return code. The return code is set to the |
|---|
| 308 | following values, if quit is the next command. So, if |
|---|
| 309 | another command is run after the compare, the return code |
|---|
| 310 | will not refer to the compare. This option is very useful |
|---|
| 311 | for automating compares. Return code values:<itemizedlist> |
|---|
| 312 | <listitem> |
|---|
| 313 | <para><option>1</option> -- no differences were |
|---|
| 314 | found</para> |
|---|
| 315 | </listitem> |
|---|
| 316 | |
|---|
| 317 | <listitem> |
|---|
| 318 | <para><option>2</option> -- differences were |
|---|
| 319 | found</para> |
|---|
| 320 | </listitem> |
|---|
| 321 | |
|---|
| 322 | <listitem> |
|---|
| 323 | <para><option>3</option> -- an error occured</para> |
|---|
| 324 | </listitem> |
|---|
| 325 | </itemizedlist></para> |
|---|
| 326 | </listitem> |
|---|
| 327 | </varlistentry> |
|---|
| 328 | </variablelist></para> |
|---|
| 329 | </listitem> |
|---|
| 330 | </varlistentry> |
|---|
| 331 | |
|---|
| 332 | <varlistentry> |
|---|
| 333 | <term><command>get</command> <varname>object-filename</varname> |
|---|
| 334 | <optional>local-filename</optional></term> |
|---|
| 335 | |
|---|
| 336 | <listitem> |
|---|
| 337 | <para></para> |
|---|
| 338 | </listitem> |
|---|
| 339 | </varlistentry> |
|---|
| 340 | |
|---|
| 341 | <varlistentry> |
|---|
| 342 | <term><command>get -i</command> <varname>object-id</varname> |
|---|
| 343 | <varname>local-filename</varname></term> |
|---|
| 344 | |
|---|
| 345 | <listitem> |
|---|
| 346 | <para>Gets a file from the store. Object is specified as the |
|---|
| 347 | filename within the current directory. Local filename is optional. |
|---|
| 348 | Ignores old and deleted files when searching the directory for the |
|---|
| 349 | file to retrieve.</para> |
|---|
| 350 | |
|---|
| 351 | <para>To get an old or deleted file, use the <option>-i</option> |
|---|
| 352 | option and select the object as a hex object ID (first column in |
|---|
| 353 | listing). The local filename must be specified.</para> |
|---|
| 354 | </listitem> |
|---|
| 355 | </varlistentry> |
|---|
| 356 | |
|---|
| 357 | <varlistentry> |
|---|
| 358 | <term><command>getobject</command> <varname>object-id</varname> |
|---|
| 359 | <varname>local-filename</varname></term> |
|---|
| 360 | |
|---|
| 361 | <listitem> |
|---|
| 362 | <para>Gets the object specified by the object id (in hex) and stores |
|---|
| 363 | the raw contents in the local file specified. Note: This is only |
|---|
| 364 | useful for debugging as it does not decode files from the stored |
|---|
| 365 | format, which is encrypted and compressed.</para> |
|---|
| 366 | </listitem> |
|---|
| 367 | </varlistentry> |
|---|
| 368 | |
|---|
| 369 | <varlistentry> |
|---|
| 370 | <term><command>restore</command> <optional>-d</optional> |
|---|
| 371 | <varname>directory-name</varname> |
|---|
| 372 | <varname>local-directory-name</varname></term> |
|---|
| 373 | |
|---|
| 374 | <listitem> |
|---|
| 375 | <para></para> |
|---|
| 376 | </listitem> |
|---|
| 377 | </varlistentry> |
|---|
| 378 | |
|---|
| 379 | <varlistentry> |
|---|
| 380 | <term><command>restore -r</command></term> |
|---|
| 381 | |
|---|
| 382 | <listitem> |
|---|
| 383 | <para>Restores a directory to the local disc. The local directory |
|---|
| 384 | specified must not exist (unless a previous restore is being |
|---|
| 385 | restarted). The root cannot be restored -- restore locations |
|---|
| 386 | individually.</para> |
|---|
| 387 | |
|---|
| 388 | <para>Options:</para> |
|---|
| 389 | |
|---|
| 390 | <para><variablelist> |
|---|
| 391 | <varlistentry> |
|---|
| 392 | <term><option>-d</option></term> |
|---|
| 393 | |
|---|
| 394 | <listitem> |
|---|
| 395 | <para>restore a deleted directory</para> |
|---|
| 396 | </listitem> |
|---|
| 397 | </varlistentry> |
|---|
| 398 | |
|---|
| 399 | <varlistentry> |
|---|
| 400 | <term><option>-r</option></term> |
|---|
| 401 | |
|---|
| 402 | <listitem> |
|---|
| 403 | <para>resume an interrupted restore</para> |
|---|
| 404 | </listitem> |
|---|
| 405 | </varlistentry> |
|---|
| 406 | </variablelist>If a restore operation is interrupted for any |
|---|
| 407 | reason, it can be restarted using the <option>-r</option> switch. |
|---|
| 408 | Restore progress information is saved in a file at regular intervals |
|---|
| 409 | during the restore operation to allow restarts.</para> |
|---|
| 410 | </listitem> |
|---|
| 411 | </varlistentry> |
|---|
| 412 | |
|---|
| 413 | <varlistentry> |
|---|
| 414 | <term><command>usage</command> <optional>-m</optional></term> |
|---|
| 415 | |
|---|
| 416 | <listitem> |
|---|
| 417 | <para>Show space used on the server for this account. Display |
|---|
| 418 | fields:<itemizedlist> |
|---|
| 419 | <listitem> |
|---|
| 420 | <para><property>Used</property>: Total amount of space used on |
|---|
| 421 | the server</para> |
|---|
| 422 | </listitem> |
|---|
| 423 | |
|---|
| 424 | <listitem> |
|---|
| 425 | <para><property>Old files</property>: Space used by old |
|---|
| 426 | files</para> |
|---|
| 427 | </listitem> |
|---|
| 428 | |
|---|
| 429 | <listitem> |
|---|
| 430 | <para><property>Deleted files</property>: Space used by |
|---|
| 431 | deleted files</para> |
|---|
| 432 | </listitem> |
|---|
| 433 | |
|---|
| 434 | <listitem> |
|---|
| 435 | <para><property>Directories</property>: Space used by the |
|---|
| 436 | directory structure</para> |
|---|
| 437 | </listitem> |
|---|
| 438 | </itemizedlist></para> |
|---|
| 439 | |
|---|
| 440 | <para>When <property>Used</property> exceeds the soft limit, the |
|---|
| 441 | server will start to remove old and deleted files until the usage |
|---|
| 442 | drops below the soft limit. After a while, you should expect to see |
|---|
| 443 | the usage stay at just below the soft limit. You only need more |
|---|
| 444 | space if the space used by old and deleted files is near |
|---|
| 445 | zero.</para> |
|---|
| 446 | |
|---|
| 447 | <para>The <option>-m</option> option displays output in |
|---|
| 448 | machine-readable form.</para> |
|---|
| 449 | </listitem> |
|---|
| 450 | </varlistentry> |
|---|
| 451 | </variablelist> |
|---|
| 452 | </refsection> |
|---|
| 453 | |
|---|
| 454 | <refsection> |
|---|
| 455 | <title>Bugs</title> |
|---|
| 456 | |
|---|
| 457 | <para>If you find a bug in Box Backup and you want to let us know about |
|---|
| 458 | it, join the <link |
|---|
| 459 | xlink:href="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing |
|---|
| 460 | list</link> and send us a description of the problem there.</para> |
|---|
| 461 | |
|---|
| 462 | <para>To report a bug, give us at least the following information:</para> |
|---|
| 463 | |
|---|
| 464 | <itemizedlist> |
|---|
| 465 | <listitem> |
|---|
| 466 | <para>The version of Box Backup you are running</para> |
|---|
| 467 | </listitem> |
|---|
| 468 | |
|---|
| 469 | <listitem> |
|---|
| 470 | <para>The platform you are running on (hardware and OS), for both |
|---|
| 471 | client and server.</para> |
|---|
| 472 | </listitem> |
|---|
| 473 | |
|---|
| 474 | <listitem> |
|---|
| 475 | <para>If possible attach your config files (bbstored.conf, |
|---|
| 476 | bbackupd.conf) to the bug report.</para> |
|---|
| 477 | </listitem> |
|---|
| 478 | |
|---|
| 479 | <listitem> |
|---|
| 480 | <para>Also attach any log file output that helps shed light on the |
|---|
| 481 | problem you are seeing.</para> |
|---|
| 482 | </listitem> |
|---|
| 483 | |
|---|
| 484 | <listitem> |
|---|
| 485 | <para>And last but certainly not least, a description of what you are |
|---|
| 486 | seeing, in as much detail as possible.</para> |
|---|
| 487 | </listitem> |
|---|
| 488 | </itemizedlist> |
|---|
| 489 | </refsection> |
|---|
| 490 | |
|---|
| 491 | <refsection> |
|---|
| 492 | <title>Authors</title> |
|---|
| 493 | |
|---|
| 494 | <para><author> |
|---|
| 495 | <personname>Ben Summers</personname> |
|---|
| 496 | </author></para> |
|---|
| 497 | |
|---|
| 498 | <para><author> |
|---|
| 499 | <personname>Per Thomsen</personname> |
|---|
| 500 | </author></para> |
|---|
| 501 | |
|---|
| 502 | <para><author> |
|---|
| 503 | <personname>James O'Gorman</personname> |
|---|
| 504 | </author></para> |
|---|
| 505 | </refsection> |
|---|
| 506 | </refentry> |
|---|
