doc/xml/AdminReference/sect8/backup_addvolentry.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="backup_addvolentry8">
   3   <refmeta>
   4     <refentrytitle>backup addvolentry</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>backup addvolentry</refname>
   9     <refpurpose>Defines a volume entry in a volume set</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">backup addvolentry</emphasis> <emphasis role="bold">-name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;
  14         <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;
  15         <emphasis role="bold">-volumes</emphasis> &lt;<emphasis>volume name (regular expression)</emphasis>&gt;
  16         [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-help</emphasis>]</para>
  17
  18     <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;
  19         <emphasis role="bold">-p</emphasis> &lt;<emphasis>partition name</emphasis>&gt; <emphasis role="bold">-v</emphasis> &lt;<emphasis>volume name (regular expression)</emphasis>&gt;
  20         [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-h</emphasis>]</para>
  21
  22   </refsect1>
  23   <refsect1>
  24     <title>Description</title>
  25     <para>The <emphasis role="bold">backup addvolentry</emphasis> command adds a volume entry definition to the
  26     existing volume set named by the <emphasis role="bold">-name</emphasis> argument. A volume entry
  27     definition can match one or more volumes, depending on the combination of
  28     the <emphasis role="bold">-server</emphasis>, <emphasis role="bold">-partition</emphasis>, and <emphasis role="bold">-volumes</emphasis> arguments.</para>
  29
  30     <para>For the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, provide either</para>
  31
  32     <itemizedlist>
  33       <listitem>
  34         <para>The name of one machine or partition.</para>
  35
  36       </listitem>
  37       <listitem>
  38         <para>The metacharacter expression .* (period and asterisk), which matches every
  39         machine name or partition name in the Volume Location Database (VLDB).</para>
  40
  41       </listitem>
  42     </itemizedlist>
  43     <para>For the <emphasis role="bold">-volumes</emphasis> argument, specify a combination of alphanumeric
  44     characters and one or more metacharacters to wildcard part or all of the
  45     volume name. <link linkend="OPTIONS">OPTIONS</link> lists the acceptable metacharacters.</para>
  46
  47   </refsect1>
  48   <refsect1>
  49     <title>Cautions</title>
  50     <para>It is best to issue this command in interactive mode. If issuing it at the
  51     shell prompt, enclose any strings containing metacharacters in double
  52     quotes, or escape the metacharacters with other delimiters, to prevent the
  53     shell from interpreting them. Adding volume entries to a temporary volume
  54     set is possible only within the interactive session in which the volume
  55     set was created.</para>
  56
  57   </refsect1>
  58   <refsect1>
  59     <title>Options</title>
  60     <variablelist>
  61       <varlistentry>
  62         <term><emphasis role="bold">-name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;</term>
  63         <listitem>
  64           <para>Names the volume set to which to add this volume entry definition.  The
  65           volume set must already exist (use the <emphasis role="bold">backup addvolset</emphasis> command to
  66           create it).</para>
  67
  68         </listitem>
  69       </varlistentry>
  70       <varlistentry>
  71         <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;</term>
  72         <listitem>
  73           <para>Defines the set of one or more file server machines that house the volumes
  74           in the volume entry. Provide either one fully-qualified hostname (such as
  75           <computeroutput>fs1.abc.com</computeroutput>) or the metacharacter expression <computeroutput>.*</computeroutput> (period and
  76           asterisk), which matches all machine names in the VLDB.</para>
  77
  78         </listitem>
  79       </varlistentry>
  80       <varlistentry>
  81         <term><emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;</term>
  82         <listitem>
  83           <para>Defines the set of one or more partitions that house the volumes in the
  84           volume entry. Provide either one complete partition name (such as
  85           <computeroutput>/vicepa</computeroutput>) or the metacharacter expression <computeroutput>.*</computeroutput> (period and asterisk),
  86           which matches all partition names.</para>
  87
  88         </listitem>
  89       </varlistentry>
  90       <varlistentry>
  91         <term><emphasis role="bold">-volumes</emphasis> &lt;<emphasis>volume name</emphasis>&gt;</term>
  92         <listitem>
  93           <para>Defines the set of one or more volumes included in the volume
  94           entry. Specify the volumes by name, by using any combination of regular
  95           alphanumeric characters and one or more of the following metacharacter
  96           expressions:</para>
  97
  98           <variablelist>
  99             <varlistentry>
 100               <term>.</term>
 101               <listitem>
 102                 <para>The period matches any single character.</para>
 103
 104               </listitem>
 105             </varlistentry>
 106             <varlistentry>
 107               <term>*</term>
 108               <listitem>
 109                 <para>The asterisk matches zero or more instances of the preceding character.
 110                 Combine it with any other alphanumeric character or metacharacter.</para>
 111
 112               </listitem>
 113             </varlistentry>
 114             <varlistentry>
 115               <term>[ ]</term>
 116               <listitem>
 117                 <para>Square brackets around a list of characters match a single instance of any
 118                 of the characters, but no other characters; for example, <computeroutput>[abc]</computeroutput> matches
 119                 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
 120                 be combined with the asterisk.</para>
 121
 122               </listitem>
 123             </varlistentry>
 124             <varlistentry>
 125               <term>^</term>
 126               <listitem>
 127                 <para>The caret, when used as the first character in a square-bracketed set,
 128                 designates a match with any single character <emphasis>except</emphasis> the characters that
 129                 follow it; for example, <computeroutput>[^a]</computeroutput> matches any single character except
 130                 lowercase <computeroutput>a</computeroutput>. This expression can be combined with the asterisk.</para>
 131
 132               </listitem>
 133             </varlistentry>
 134             <varlistentry>
 135               <term>\</term>
 136               <listitem>
 137                 <para>A backslash preceding any of the metacharacters in this list makes it
 138                 match its literal value only. For example, the expression <computeroutput>\.</computeroutput> (backslash
 139                 and period) matches a single period, <computeroutput>\*</computeroutput> a single asterisk, and <computeroutput>\\</computeroutput> a
 140                 single backslash.  Such expressions can be combined with the asterisk (for
 141                 example, <computeroutput>\.*</computeroutput> matches any number of periods).</para>
 142
 143               </listitem>
 144             </varlistentry>
 145           </variablelist>
 146           <para>Perhaps the most common metacharacter expression is the period followed by
 147           an asterisk (<computeroutput>.*</computeroutput>). This expression matches any string of any length,
 148           because the period matches any character and the asterisk means any number
 149           of that character. As mentioned, it is the only acceptable metacharacter
 150           expression for the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. In a volume
 151           definition it can stand alone (in which case it matches every volume
 152           listed in the VLDB), or can combine with regular characters. The following
 153           example matches any volume name that begins with the string <computeroutput>user</computeroutput> and
 154           ends with <computeroutput>backup</computeroutput>:</para>
 155
 156 <programlisting>
 157    user.*backup
 158
 159 </programlisting>
 160           </listitem>
 161         </varlistentry>
 162         <varlistentry>
 163           <term><emphasis role="bold">-localauth</emphasis></term>
 164           <listitem>
 165             <para>Constructs a server ticket using a key from the local
 166             <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">backup</emphasis> command interpreter presents
 167             it to the Backup Server, Volume Server and VL Server during mutual
 168             authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument. For
 169             more details, see <link linkend="backup8">backup(8)</link>.</para>
 170
 171           </listitem>
 172         </varlistentry>
 173         <varlistentry>
 174           <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
 175           <listitem>
 176             <para>Names the cell in which to run the command. Do not combine this argument
 177             with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="backup8">backup(8)</link>.</para>
 178
 179           </listitem>
 180         </varlistentry>
 181         <varlistentry>
 182           <term><emphasis role="bold">-help</emphasis></term>
 183           <listitem>
 184             <para>Prints the online help for this command. All other valid options are
 185             ignored.</para>
 186
 187           </listitem>
 188         </varlistentry>
 189       </variablelist>
 190     </refsect1>
 191     <refsect1>
 192       <title>Examples</title>
 193       <para>The following command adds a volume entry to the volume set called
 194       <computeroutput>sys</computeroutput>. The entry matches all volumes on any machine or partition whose
 195       names begin with the string <computeroutput>sun4x_56</computeroutput> followed by a period:</para>
 196
 197 <programlisting>
 198    backup&amp;gt; addvolentry sys .* .* sun4x_56\..*
 199
 200 </programlisting>
 201         <para>The following command adds a volume entry to the volume set called <computeroutput>fs2</computeroutput>,
 202         to match all volumes on the <replaceable>/vicepb</replaceable> partition of file server machine
 203         <computeroutput>fs2.abc.com</computeroutput>. Because it is issued at the shell prompt, double quotes
 204         surround the metacharacters in the <emphasis role="bold">-volumes</emphasis> argument. (The command is
 205         shown here on two lines only for legibility reasons.)</para>
 206
 207 <programlisting>
 208    % backup addvolentry -name fs2 -server fs2.abc.com \
 209                         -partition /vicepb -volumes ".*"
 210
 211 </programlisting>
 212           <para>The chapter in the <emphasis>IBM AFS Administration Guide</emphasis> about configuring the
 213           AFS Backup System presents additional examples as well as advice on
 214           grouping volumes.</para>
 215
 216         </refsect1>
 217         <refsect1>
 218           <title>Privilege Required</title>
 219           <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
 220           machine where the Backup Server is running, or must be logged onto a
 221           server machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
 222           included.</para>
 223
 224         </refsect1>
 225         <refsect1>
 226           <title>See Also</title>
 227           <para><link linkend="backup8">backup(8)</link>,
 228           <link linkend="backup_addvolset8">backup_addvolset(8)</link>,
 229           <link linkend="backup_delvolentry8">backup_delvolentry(8)</link>,
 230           <link linkend="backup_delvolset8">backup_delvolset(8)</link>,
 231           <link linkend="backup_listvolsets8">backup_listvolsets(8)</link></para>
 232
 233         </refsect1>
 234         <refsect1>
 235           <title>Copyright</title>
 236           <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 237
 238           <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 239           converted from HTML to POD by software written by Chas Williams and Russ
 240           Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 241
 242         </refsect1>
 243       </refentry>