path: root/docs/docbook/bbstoreaccounts.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>bbstoreaccounts</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>bbstoreaccounts</refname>

    <refpurpose>Box Backup store accounts manager</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>bbstoreaccounts</command>

      <arg>-c config-file</arg>

      <arg choice="plain">command</arg>

      <arg choice="plain">account-id</arg>

      <arg>command-specific arguments</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para><command>bbstoreaccounts</command> is the tool for managing accounts
    on the store server. It can be used to view information related to
    accounts, as well as create, change and delete accounts on the store
    server.</para>

    <para><command>bbstoreaccounts</command> always takes at least 2
    parameters: the command name and the account ID. Some commands require
    additional parameters, and some commands have optional parameters.</para>

    <refsection>
      <title>Options</title>

      <para><variablelist>
          <varlistentry>
            <term><option>-c config-file</option></term>

            <listitem>
              <para>The configfile to use for connecting to the store. Default
              is <filename>/etc/box/bbstored.conf</filename>.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>
    </refsection>

    <refsection>
      <title>Commands</title>

      <para>The commands tells bbstoreaccounts what action to perform.</para>

      <para><variablelist>
          <varlistentry>
            <term><command>check</command> <varname>account-id</varname>
            <optional>fix</optional></term>

            <listitem>
              <para>The <command>check</command> command verifies the
              integrity of the store account given, and optionally fixes any
              corruptions. <emphasis role="bold">Note</emphasis>: It is
              recommended to run the 'simple' check command (without
              <command>fix</command>) before using the <command>fix</command>
              option. This gives an overview of the extent of any problems,
              before attempting to fix them.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>create</command> <varname>account-id</varname>
            <varname>disc-set</varname> <varname>soft-limit</varname>
            <varname>hard-limit</varname></term>

            <listitem>
              <para>Creates a new store account with the parameters given. The
              parameters are as follows:</para>

              <para><variablelist>
                  <varlistentry>
                    <term><option>account-id</option></term>

                    <listitem>
                      <para>The ID of the new account to be created. A 32-bit
                      hexadecimal number. Cannot already exist on the
                      server.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><option>disc-set</option></term>

                    <listitem>
                      <para>The disc set from <citerefentry>
                          <refentrytitle>raidfile.conf</refentrytitle>

                          <manvolnum>5</manvolnum>
                        </citerefentry> where the backups for this client will
                      be stored. A number. Each RAID-file set has a number in
                      raidfile.conf. This number is what's used.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><option>soft-limit</option></term>

                    <listitem>
                      <para>The soft limit is the amount of storage that the
                      server will guarantee to be available for
                      storage.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><option>hard-limit</option></term>

                    <listitem>
                      <para>The amount of storage that the the server will
                      allow, before rejecting uploads, and starting to
                      eliminate old and deleted files to get back down to
                      soft-limit.</para>
                    </listitem>
                  </varlistentry>
                </variablelist></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>delete</command> <varname>account-id</varname>
            <optional>yes</optional></term>

            <listitem>
              <para>Deletes the account from the store server completely.
              Removes all backups and deletes all references to the account in
              the config files.</para>

              <para><command>delete</command> will ask for confirmation from
              the user, when called. Using the <option>yes</option> flag,
              eliminates that need. This is useful when deleting accounts from
              within a script or some other automated means. 0</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>info</command> <varname>account-id</varname></term>

            <listitem>
              <para>Display information about the given account.
              Example:<programlisting>[root]# bbstoreaccounts info 1
                  Account ID: 00000001
              Last object ID: 58757
                 Blocks used: 9864063 (38531.50Mb)
    Blocks used by old files: 62058 (242.41Mb)
Blocks used by deleted files: 34025 (132.91Mb)
  Blocks used by directories: 6679 (26.09Mb)
            Block soft limit: 11796480 (46080.00Mb)
            Block hard limit: 13107200 (51200.00Mb)
         Client store marker: 1139559852000000</programlisting></para>

              <para>Explanation:</para>

              <para><variablelist>
                  <varlistentry>
                    <term>Account ID</term>

                    <listitem>
                      <para>The account ID being displayed.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Last Object ID</term>

                    <listitem>
                      <para>A counter that keeps track of the objects that
                      have been backed up. This number refers to the last file
                      that was written to the store. The ID is displayed as a
                      decimal number, and the object ID can be converted to a
                      path name to a file as follows: convert the number to
                      hex (e.g.: 58757 =&gt; 0xE585); The last backed up file
                      will be (relative from the client's store root):
                      <filename>e5/o85.rfw</filename>. Longer numbers infer
                      more directories in the structure, so as an example
                      3952697264 as the last object ID gives 0xEB995FB0, which
                      translates to a backup pathname of
                      <filename>eb/99/5f/ob0.rfw</filename>.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Blocks used</term>

                    <listitem>
                      <para>The number of blocks used by the store. The size
                      in Mb depends on the number of blocks, as well as the
                      block size for the disc set given in <citerefentry>
                          <refentrytitle>raidfile.conf</refentrytitle>

                          <manvolnum>5</manvolnum>
                        </citerefentry>. In this case the block size is
                      4096.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Blocks used by old files</term>

                    <listitem>
                      <para>The number of blocks occupied by files that have
                      newer versions in the store. This data is at risk for
                      being removed during housekeeping.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Blocks used by deleted files</term>

                    <listitem>
                      <para>The number of blocks used by files that have been
                      deleted on the client. This data is at risk for being
                      removed during housekeeping.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Blocks used by directories</term>

                    <listitem>
                      <para>The number of blocks used by directories in the
                      store.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Block soft limit</term>

                    <listitem>
                      <para>The soft limit in blocks. The soft limit is the
                      maximum guaranteed storage space available to the
                      account. When housekeeping starts, and the old and
                      deleted files are removed, they are removed in
                      chronological order (oldest first), until the data used
                      is less than the soft limit.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Block hard limit</term>

                    <listitem>
                      <para>The hard limit in blocks. The hard limit is the
                      most amount of storage the server will allow in an
                      account. Any data above this amount will be rejected.
                      Housekeeping will reduce the storage use, so more data
                      can be uploaded.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>Client store marker</term>

                    <listitem>
                      <para><citerefentry>
                          <refentrytitle>bbstored</refentrytitle>

                          <manvolnum>8</manvolnum>
                        </citerefentry> uses this number to determine if it
                      needs to rescan the entire store. If this number is
                      different from the last time it checked, a rescan will
                      take place.</para>
                    </listitem>
                  </varlistentry>
                </variablelist></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><command>setlimit</command> <varname>account-id</varname>
            <varname>soft-limit</varname> <varname>hard-limit</varname></term>

            <listitem>
              <para>Changes the storage space allocation for the given
              account. No server restart is needed.</para>

              <para>Parameters:</para>

              <para><variablelist>
                  <varlistentry>
                    <term><option>account-id</option></term>

                    <listitem>
                      <para>The ID of the account to be modified.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><option>soft-limit</option></term>

                    <listitem>
                      <para>The soft limit is the amount of storage that the
                      server will guarantee to be available for
                      storage.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><option>hard-limit</option></term>

                    <listitem>
                      <para>The amount of storage that the the server will
                      allow before rejecting uploads and starting to eliminate
                      old and deleted files to get back down to
                      <option>soft-limit</option>.</para>
                    </listitem>
                  </varlistentry>
                </variablelist></para>
            </listitem>
          </varlistentry>
        </variablelist></para>
    </refsection>
  </refsection>

  <refsection>
    <title>Examples</title>

    <para>Create an account with ID 3af on disc set 0, with a 20GB soft-limit
    and a 22GB hard-limit:<programlisting>bbstoreaccounts create 3af 0 20G 22G</programlisting>Alter
    existing account ID 20 to have a 50GB soft-limit and a 55GB
    hard-limit:<programlisting>bbstoreaccounts setlimit 20 50G 55G</programlisting></para>
  </refsection>

  <refsection>
    <title>Files</title>

    <para><filename>/etc/box/bbstored/accounts.txt</filename></para>
  </refsection>

  <refsection>
    <title>See Also</title>

    <para><citerefentry>
        <refentrytitle>bbstored</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>bbstored-config</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry></para>
  </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>