openafs/doc/xml/AdminReference/sect8/backup_addvolentry.xml

<?xml version="1.0" encoding="UTF-8"?>
<refentry id="backup_addvolentry8">
  <refmeta>
    <refentrytitle>backup addvolentry</refentrytitle>
    <manvolnum>8</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>backup addvolentry</refname>
    <refpurpose>Defines a volume entry in a volume set</refpurpose>
  </refnamediv>
  <refsect1>
    <title>Synopsis</title>
    <para><emphasis role="bold">backup addvolentry</emphasis> <emphasis role="bold">-name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;
        <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;
        <emphasis role="bold">-volumes</emphasis> &lt;<emphasis>volume name (regular expression)</emphasis>&gt;
        [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-help</emphasis>]</para>

    <para><emphasis role="bold">backup addvole</emphasis> <emphasis role="bold">-n</emphasis> &lt;<emphasis>volume set name</emphasis>&gt; <emphasis role="bold">-s</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
        <emphasis role="bold">-p</emphasis> &lt;<emphasis>partition name</emphasis>&gt; <emphasis role="bold">-v</emphasis> &lt;<emphasis>volume name (regular expression)</emphasis>&gt;
        [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-h</emphasis>]</para>

  </refsect1>
  <refsect1>
    <title>Description</title>
    <para>The <emphasis role="bold">backup addvolentry</emphasis> command adds a volume entry definition to the
    existing volume set named by the <emphasis role="bold">-name</emphasis> argument. A volume entry
    definition can match one or more volumes, depending on the combination of
    the <emphasis role="bold">-server</emphasis>, <emphasis role="bold">-partition</emphasis>, and <emphasis role="bold">-volumes</emphasis> arguments.</para>

    <para>For the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, provide either</para>

    <itemizedlist>
      <listitem>
        <para>The name of one machine or partition.</para>

      </listitem>
      <listitem>
        <para>The metacharacter expression .* (period and asterisk), which matches every
        machine name or partition name in the Volume Location Database (VLDB).</para>

      </listitem>
    </itemizedlist>
    <para>For the <emphasis role="bold">-volumes</emphasis> argument, specify a combination of alphanumeric
    characters and one or more metacharacters to wildcard part or all of the
    volume name. <link linkend="OPTIONS">OPTIONS</link> lists the acceptable metacharacters.</para>

  </refsect1>
  <refsect1>
    <title>Cautions</title>
    <para>It is best to issue this command in interactive mode. If issuing it at the
    shell prompt, enclose any strings containing metacharacters in double
    quotes, or escape the metacharacters with other delimiters, to prevent the
    shell from interpreting them. Adding volume entries to a temporary volume
    set is possible only within the interactive session in which the volume
    set was created.</para>

  </refsect1>
  <refsect1>
    <title>Options</title>
    <variablelist>
      <varlistentry>
        <term><emphasis role="bold">-name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;</term>
        <listitem>
          <para>Names the volume set to which to add this volume entry definition.  The
          volume set must already exist (use the <emphasis role="bold">backup addvolset</emphasis> command to
          create it).</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;</term>
        <listitem>
          <para>Defines the set of one or more file server machines that house the volumes
          in the volume entry. Provide either one fully-qualified hostname (such as
          <computeroutput>fs1.abc.com</computeroutput>) or the metacharacter expression <computeroutput>.*</computeroutput> (period and
          asterisk), which matches all machine names in the VLDB.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;</term>
        <listitem>
          <para>Defines the set of one or more partitions that house the volumes in the
          volume entry. Provide either one complete partition name (such as
          <computeroutput>/vicepa</computeroutput>) or the metacharacter expression <computeroutput>.*</computeroutput> (period and asterisk),
          which matches all partition names.</para>

        </listitem>
      </varlistentry>
      <varlistentry>
        <term><emphasis role="bold">-volumes</emphasis> &lt;<emphasis>volume name</emphasis>&gt;</term>
        <listitem>
          <para>Defines the set of one or more volumes included in the volume
          entry. Specify the volumes by name, by using any combination of regular
          alphanumeric characters and one or more of the following metacharacter
          expressions:</para>

          <variablelist>
            <varlistentry>
              <term>.</term>
              <listitem>
                <para>The period matches any single character.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>*</term>
              <listitem>
                <para>The asterisk matches zero or more instances of the preceding character.
                Combine it with any other alphanumeric character or metacharacter.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>[ ]</term>
              <listitem>
                <para>Square brackets around a list of characters match a single instance of any
                of the characters, but no other characters; for example, <computeroutput>[abc]</computeroutput> matches
                a single <computeroutput>a</computeroutput> or <computeroutput>b</computeroutput> or <computeroutput>c</computeroutput>, but not <computeroutput>d</computeroutput> or <computeroutput>A</computeroutput>. This expression can
                be combined with the asterisk.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>^</term>
              <listitem>
                <para>The caret, when used as the first character in a square-bracketed set,
                designates a match with any single character <emphasis>except</emphasis> the characters that
                follow it; for example, <computeroutput>[^a]</computeroutput> matches any single character except
                lowercase <computeroutput>a</computeroutput>. This expression can be combined with the asterisk.</para>

              </listitem>
            </varlistentry>
            <varlistentry>
              <term>\</term>
              <listitem>
                <para>A backslash preceding any of the metacharacters in this list makes it
                match its literal value only. For example, the expression <computeroutput>\.</computeroutput> (backslash
                and period) matches a single period, <computeroutput>\*</computeroutput> a single asterisk, and <computeroutput>\\</computeroutput> a
                single backslash.  Such expressions can be combined with the asterisk (for
                example, <computeroutput>\.*</computeroutput> matches any number of periods).</para>

              </listitem>
            </varlistentry>
          </variablelist>
          <para>Perhaps the most common metacharacter expression is the period followed by
          an asterisk (<computeroutput>.*</computeroutput>). This expression matches any string of any length,
          because the period matches any character and the asterisk means any number
          of that character. As mentioned, it is the only acceptable metacharacter
          expression for the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. In a volume
          definition it can stand alone (in which case it matches every volume
          listed in the VLDB), or can combine with regular characters. The following
          example matches any volume name that begins with the string <computeroutput>user</computeroutput> and
          ends with <computeroutput>backup</computeroutput>:</para>

<programlisting>
   user.*backup

</programlisting>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-localauth</emphasis></term>
          <listitem>
            <para>Constructs a server ticket using a key from the local
            <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">backup</emphasis> command interpreter presents
            it to the Backup Server, Volume Server and VL Server during mutual
            authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument. For
            more details, see <link linkend="backup8">backup(8)</link>.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
          <listitem>
            <para>Names the cell in which to run the command. Do not combine this argument
            with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="backup8">backup(8)</link>.</para>

          </listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis role="bold">-help</emphasis></term>
          <listitem>
            <para>Prints the online help for this command. All other valid options are
            ignored.</para>

          </listitem>
        </varlistentry>
      </variablelist>
    </refsect1>
    <refsect1>
      <title>Examples</title>
      <para>The following command adds a volume entry to the volume set called
      <computeroutput>sys</computeroutput>. The entry matches all volumes on any machine or partition whose
      names begin with the string <computeroutput>sun4x_56</computeroutput> followed by a period:</para>

<programlisting>
   backup&amp;gt; addvolentry sys .* .* sun4x_56\..*

</programlisting>
        <para>The following command adds a volume entry to the volume set called <computeroutput>fs2</computeroutput>,
        to match all volumes on the <replaceable>/vicepb</replaceable> partition of file server machine
        <computeroutput>fs2.abc.com</computeroutput>. Because it is issued at the shell prompt, double quotes
        surround the metacharacters in the <emphasis role="bold">-volumes</emphasis> argument. (The command is
        shown here on two lines only for legibility reasons.)</para>

<programlisting>
   % backup addvolentry -name fs2 -server fs2.abc.com \
                        -partition /vicepb -volumes ".*"

</programlisting>
          <para>The chapter in the <emphasis>IBM AFS Administration Guide</emphasis> about configuring the
          AFS Backup System presents additional examples as well as advice on
          grouping volumes.</para>

        </refsect1>
        <refsect1>
          <title>Privilege Required</title>
          <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
          machine where the Backup Server is running, or must be logged onto a
          server machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
          included.</para>

        </refsect1>
        <refsect1>
          <title>See Also</title>
          <para><link linkend="backup8">backup(8)</link>,
          <link linkend="backup_addvolset8">backup_addvolset(8)</link>,
          <link linkend="backup_delvolentry8">backup_delvolentry(8)</link>,
          <link linkend="backup_delvolset8">backup_delvolset(8)</link>,
          <link linkend="backup_listvolsets8">backup_listvolsets(8)</link></para>

        </refsect1>
        <refsect1>
          <title>Copyright</title>
          <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>

          <para>This documentation is covered by the IBM Public License Version 1.0.  It was
          converted from HTML to POD by software written by Chas Williams and Russ
          Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>

        </refsect1>
      </refentry>