path: root/docs/bbackupquery.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0" xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:m="http://www.w3.org/1998/Math/MathML"
          xmlns:html="http://www.w3.org/1999/xhtml"
          xmlns:db="http://docbook.org/ns/docbook">
  <refmeta>
    <refentrytitle>bbackupquery</refentrytitle>

    <manvolnum>8</manvolnum>

    <refmiscinfo class="manual">Box Backup</refmiscinfo>

    <refmiscinfo class="source">Box Backup</refmiscinfo>

    <refmiscinfo class="version">0.11</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>bbackupquery</refname>

    <refpurpose>Box Backup store query and file retrieval</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>bbackupquery</command>

      <arg>-q</arg>

      <arg>-c configfile</arg>

      <arg>command ...</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para><command>bbackupquery</command> is the main way of interacting with
    the backup store from a Box Backup client machine. It supports both
    interactive and batch modes of operation.</para>

    <para>It can be used to reviewing the status of a client machine's backup
    store, getting status from the store server. The main use is to retrieve
    files and directories when needed.</para>

    <para><command>bbackupquery</command> supports interactive and batch modes
    of operation. Interactive mode allows for interaction with the server much
    like an interactive FTP client.</para>

    <para>Batch mode is invoked by putting commands into the invocation of
    <command>bbackupquery</command>. Example:</para>

    <para><programlisting>bbackupquery "list home-dirs" quit</programlisting></para>

    <para>Note that commands that contain spaces are enclosed in double
    quotes. If the <command>quit</command> command is omitted, after the
    preceding commands are completed, <command>bbackupquery</command> will
    enter interactive mode.</para>
  </refsection>

  <refsection>
    <title>Options</title>

    <para><variablelist>
        <varlistentry>
          <term><option>-q</option></term>

          <listitem>
            <para>Quiet. Suppresses status output while running.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>-c</option> <option>configfile</option></term>

          <listitem>
            <para>Use configfile instead of the default bbackupd.conf file.
            Can be a relative or full path.</para>
          </listitem>
        </varlistentry>
      </variablelist></para>
  </refsection>

  <refsection>
    <title>Commands</title>

    <para>The commands that can be used in bbackupquery are listed
    below.</para>

    <variablelist>
      <varlistentry>
        <term><command>help</command></term>

        <listitem>
          <para>Displays the basic help message, which gives information about
          the commands available in <command>bbackupquery</command>. Use the
          form <command>help command</command> to get help on a specific
          command.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>quit</command></term>

        <listitem>
          <para>End the session with the store server, and quit
          bbackupquery.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>cd</command> <optional>options</optional>
        <varname>directory-name</varname></term>

        <listitem>
          <para>Change directory. Options: <variablelist>
              <varlistentry>
                <term><option>-d</option></term>

                <listitem>
                  <para>consider deleted directories for traversal</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-o</option></term>

                <listitem>
                  <para>consider old versions of directories for traversal.
                  This option should never be useful in a correctly formed
                  store.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>lcd</command>
        <varname>local-directory-name</varname></term>

        <listitem>
          <para>Change directory on the client machine. To list the contents
          of the local directory, type <command>sh ls</command> (on Unix-like
          machines).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>list</command> <optional>options</optional>
        <optional>directory-name</optional></term>

        <listitem>
          <para>The list (or its synonym <command>ls</command>) command lists
          the content of the current, or specified, directory. The options are
          as follows:</para>

          <para><variablelist>
              <varlistentry>
                <term><option>-r</option></term>

                <listitem>
                  <para>recursively list all files</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-d</option></term>

                <listitem>
                  <para>list deleted files and directories</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-o</option></term>

                <listitem>
                  <para>list old versions of files and directories</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-I</option></term>

                <listitem>
                  <para>don't display object IDs</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-F</option></term>

                <listitem>
                  <para>don't display flags</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-t</option></term>

                <listitem>
                  <para>show file modification time (and attr mod time, if the
                  object has attributes).</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-s</option></term>

                <listitem>
                  <para>show file size in blocks used on server. Note that
                  this is only a very approximate indication of local file
                  size.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>ls</command> <optional>options</optional>
        <optional>directory-name</optional></term>

        <listitem>
          <para>Synonym for <command>list</command>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>pwd</command></term>

        <listitem>
          <para>Print current directory, always relative to the backup store
          root.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>sh</command> <varname>shell-command</varname></term>

        <listitem>
          <para>Everything after the sh is passed to a shell and run. All
          output from the command is displayed in the client.</para>

          <para>Example: to list the contents of the current directory on the
          client machine type <command>sh ls</command>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>compare -a</command></term>

        <listitem>
          <para></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>compare -l</command>
        <varname>location-name</varname></term>

        <listitem>
          <para></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>compare</command> <varname>store-dir-name</varname>
        <varname>local-dir-name</varname></term>

        <listitem>
          <para>Compare the current data in the store with the data on the
          disc. Please note that all the data will be downloaded from the
          store, so this can be a very lengthy process depending on the size
          of the store, and the size of the part you are comparing.</para>

          <para>Options:</para>

          <para><variablelist>
              <varlistentry>
                <term><option>-a</option></term>

                <listitem>
                  <para>compare all locations.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-l</option></term>

                <listitem>
                  <para>compare one backup location as specified in the
                  configuration file. This compares one of the top level store
                  directories.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-c</option></term>

                <listitem>
                  <para>set return code. The return code is set to the
                  following values, if quit is the next command. So, if
                  another command is run after the compare, the return code
                  will not refer to the compare. This option is very useful
                  for automating compares. Return code values:<itemizedlist>
                      <listitem>
                        <para><option>1</option> -- no differences were
                        found</para>
                      </listitem>

                      <listitem>
                        <para><option>2</option> -- differences were
                        found</para>
                      </listitem>

                      <listitem>
                        <para><option>3</option> -- an error occured</para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>get</command> <varname>object-filename</varname>
        <optional>local-filename</optional></term>

        <listitem>
          <para></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>get -i</command> <varname>object-id</varname>
        <varname>local-filename</varname></term>

        <listitem>
          <para>Gets a file from the store. Object is specified as the
          filename within the current directory. Local filename is optional.
          Ignores old and deleted files when searching the directory for the
          file to retrieve.</para>

          <para>To get an old or deleted file, use the <option>-i</option>
          option and select the object as a hex object ID (first column in
          listing). The local filename must be specified.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>getobject</command> <varname>object-id</varname>
        <varname>local-filename</varname></term>

        <listitem>
          <para>Gets the object specified by the object id (in hex) and stores
          the raw contents in the local file specified. Note: This is only
          useful for debugging as it does not decode files from the stored
          format, which is encrypted and compressed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>restore</command> <optional>-d</optional>
        <varname>directory-name</varname>
        <varname>local-directory-name</varname></term>

        <listitem>
          <para></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>restore -r</command></term>

        <listitem>
          <para>Restores a directory to the local disc. The local directory
          specified must not exist (unless a previous restore is being
          restarted). The root cannot be restored -- restore locations
          individually.</para>

          <para>Options:</para>

          <para><variablelist>
              <varlistentry>
                <term><option>-d</option></term>

                <listitem>
                  <para>restore a deleted directory</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><option>-r</option></term>

                <listitem>
                  <para>resume an interrupted restore</para>
                </listitem>
              </varlistentry>
            </variablelist>If a restore operation is interrupted for any
          reason, it can be restarted using the <option>-r</option> switch.
          Restore progress information is saved in a file at regular intervals
          during the restore operation to allow restarts.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><command>usage</command> <optional>-m</optional></term>

        <listitem>
          <para>Show space used on the server for this account. Display
          fields:<itemizedlist>
              <listitem>
                <para><property>Used</property>: Total amount of space used on
                the server</para>
              </listitem>

              <listitem>
                <para><property>Old files</property>: Space used by old
                files</para>
              </listitem>

              <listitem>
                <para><property>Deleted files</property>: Space used by
                deleted files</para>
              </listitem>

              <listitem>
                <para><property>Directories</property>: Space used by the
                directory structure</para>
              </listitem>
            </itemizedlist></para>

          <para>When <property>Used</property> exceeds the soft limit, the
          server will start to remove old and deleted files until the usage
          drops below the soft limit. After a while, you should expect to see
          the usage stay at just below the soft limit. You only need more
          space if the space used by old and deleted files is near
          zero.</para>

          <para>The <option>-m</option> option displays output in
          machine-readable form.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Bugs</title>

    <para>If you find a bug in Box Backup and you want to let us know about
    it, join the <link
    xlink:href="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
    list</link> and send us a description of the problem there.</para>

    <para>To report a bug, give us at least the following information:</para>

    <itemizedlist>
      <listitem>
        <para>The version of Box Backup you are running</para>
      </listitem>

      <listitem>
        <para>The platform you are running on (hardware and OS), for both
        client and server.</para>
      </listitem>

      <listitem>
        <para>If possible attach your config files (bbstored.conf,
        bbackupd.conf) to the bug report.</para>
      </listitem>

      <listitem>
        <para>Also attach any log file output that helps shed light on the
        problem you are seeing.</para>
      </listitem>

      <listitem>
        <para>And last but certainly not least, a description of what you are
        seeing, in as much detail as possible.</para>
      </listitem>
    </itemizedlist>
  </refsection>

  <refsection>
    <title>Authors</title>

    <para><author>
        <personname>Ben Summers</personname>
      </author></para>

    <para><author>
        <personname>Per Thomsen</personname>
      </author></para>

    <para><author>
        <personname>James O'Gorman</personname>
      </author></para>
  </refsection>
</refentry>