git.gag.com Git - debian/amanda/blob - man/xml-source/amanda-match.7.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
   4 [
   5   <!-- entities files to use -->
   6   <!ENTITY % global_entities SYSTEM 'global.entities'>
   7   %global_entities;
   8 ]>
   9
  10 <refentry id='amanda-match.7'>
  11
  12 <refmeta>
  13 <refentrytitle>amanda-match</refentrytitle>
  14 <manvolnum>7</manvolnum>
  15 &rmi.source;
  16 &rmi.version;
  17 &rmi.manual.7;
  18 </refmeta>
  19 <refnamediv>
  20 <refname>amanda-match</refname>
  21 <refpurpose>Common Amanda Match Expression</refpurpose>
  22 </refnamediv>
  23 <refentryinfo>
  24 &author.dustin;
  25 </refentryinfo>
  26 <!-- body begins here -->
  27
  28 <refsect1><title>DESCRIPTION</title>
  29
  30 <para>Several Amanda commands allow the user to specify dumps using "match
  31 expressions".  This manual page describes the syntax of these
  32 expressions.</para>
  33
  34 <para>In some places, only certain match expressions are allowed.  However,
  35 several commands take a dump specification ("dumpspec") consisting of a
  36 sequence of several expressions intended to match particular dumps in the
  37 catalog.  Other applications take a DLE specification which indicates a set
  38 of DLEs to be operated on.  These formats are described below.</para>
  39
  40 <para>An expression can be disabled be preceding it with the '=' character,
  41 in that case, an exact match is used.</para>
  42 <para>Many program have an '--exact-match' argument that disable expression and exact match are used.</para>
  43 </refsect1>
  44
  45 <refsect1><title>HOST &amp; DISK EXPRESSIONS</title>
  46
  47 <para>The hosts and disks match by word. Each word is a glob expression, and words
  48 are separated by the character '.' for host expressions and '/' for disk expressions. You
  49 can anchor the expression on the left with a '^' or on the right with a '$'. The matcher
  50 is case insensitive for hosts but case sensitive for disks. A match
  51 succeeds if all words in the expression match contiguous words in
  52 the host or disk.</para>
  53
  54 <para>If the disk is a UNC ("\\windows\share") then all '\' are converted to
  55 '/' before the match.  Using '\' is complicated because of the extra
  56 quoting required by the shell and amanda. It's easier to use '/' because it
  57 requires less quoting ("//windows/share")</para>
  58
  59 <para>The special characters follow.  Note that the shell interprets some of
  60 these characters, so when used on the command line, they must be escaped
  61 appropriately for the shell.</para>
  62
  63 <variablelist remap='TP'>
  64
  65     <varlistentry>
  66     <term>dot (.)</term> <!-- troff gets confused by a plain dot -->
  67     <listitem><para>word separator for a host</para></listitem>
  68     </varlistentry>
  69
  70     <varlistentry>
  71     <term>/</term>
  72     <listitem><para>word separator for a disk</para></listitem>
  73     </varlistentry>
  74
  75     <varlistentry>
  76     <term>\</term>
  77     <listitem><para>word separator for a UNC disk</para></listitem>
  78     </varlistentry>
  79
  80     <varlistentry>
  81     <term>^</term>
  82     <listitem><para>anchor at left of word</para></listitem>
  83     </varlistentry>
  84
  85     <varlistentry>
  86     <term>$</term>
  87     <listitem><para>anchor at right of word</para></listitem>
  88     </varlistentry>
  89
  90     <varlistentry>
  91     <term>?</term>
  92     <listitem><para>match exactly one character except the separator</para></listitem>
  93     </varlistentry>
  94
  95     <varlistentry>
  96     <term>*</term>
  97     <listitem><para>match zero or more characters except the separator</para></listitem>
  98     </varlistentry>
  99
 100     <varlistentry>
 101     <term>**</term>
 102     <listitem><para>match zero or more characters including the separator</para></listitem>
 103     </varlistentry>
 104
 105     <varlistentry>
 106     <term>[...]</term>
 107     <listitem><para>match exactly one of the characters enclosed by the brackets.</para></listitem>
 108     </varlistentry>
 109
 110     <varlistentry>
 111     <term>[!...]</term>
 112     <listitem><para>match exactly one character that is not enclosed by the brackets.</para></listitem>
 113     </varlistentry>
 114
 115 </variablelist>
 116
 117 <refsect2><title>Examples</title>
 118
 119 <variablelist remap='TP'>
 120     <varlistentry>
 121     <term>hosta</term>
 122     <listitem><para>
 123     Will match <filename>hosta</filename>, <filename>foo.hosta.org</filename>, and
 124     <filename>hoSTA.dOMAIna.ORG</filename> but not <filename>hostb</filename>.
 125     </para></listitem>
 126     </varlistentry>
 127
 128     <varlistentry>
 129     <term>host</term>
 130     <listitem><para>
 131     Will match <filename>host</filename> but not <filename>hosta</filename>.
 132     </para></listitem>
 133     </varlistentry>
 134
 135     <varlistentry>
 136     <term>host?</term>
 137     <listitem><para>
 138     Will match <filename>hosta</filename> and <filename>hostb</filename>, but
 139     not <filename>host</filename> or <filename>hostabc</filename>.
 140     </para></listitem>
 141     </varlistentry>
 142
 143     <varlistentry>
 144     <term>ho*na</term>
 145     <listitem><para>
 146     Will match <filename>hoina</filename>
 147     but not <filename>ho.aina.org</filename>.
 148     </para></listitem>
 149     </varlistentry>
 150
 151     <varlistentry>
 152     <term>ho**na</term>
 153     <listitem><para>
 154     Will match <filename>hoina</filename>
 155     and <filename>ho.aina.org</filename>.
 156     </para></listitem>
 157     </varlistentry>
 158
 159     <varlistentry>
 160     <term>^hosta</term>
 161     <listitem><para>
 162     Will match <filename>hosta</filename>
 163     but not <filename>foo.hosta.org</filename>.
 164     </para></listitem>
 165     </varlistentry>
 166
 167     <varlistentry>
 168     <term>sda*</term>
 169     <listitem><para>
 170     Will match <filename>/dev/sda1</filename>
 171     and <filename>/dev/sda12</filename>.
 172     </para></listitem>
 173     </varlistentry>
 174
 175     <varlistentry>
 176     <term>/opt</term>
 177     <listitem><para>
 178     Will match the disk <filename>opt</filename>
 179     but not the host <filename>opt</filename>.
 180     </para></listitem>
 181     </varlistentry>
 182
 183     <varlistentry>
 184     <term>(note dots:) .opt.</term> <!-- nroff gets confused by dots -->
 185     <listitem><para>
 186     Will match the host <filename>opt</filename>
 187     but not the disk <filename>opt</filename>.
 188     </para></listitem>
 189     </varlistentry>
 190
 191     <varlistentry>
 192     <term>/</term>
 193     <listitem><para>
 194     Will match the disk <filename>/</filename>
 195     but no other disk.
 196     </para></listitem>
 197     </varlistentry>
 198
 199     <varlistentry>
 200     <term>/usr</term>
 201     <listitem><para>
 202     Will match the disks <filename>/usr</filename>
 203     and <filename>/usr/local</filename>.
 204     </para></listitem>
 205     </varlistentry>
 206
 207     <varlistentry>
 208     <term>/usr$</term>
 209     <listitem><para>
 210     Will match the disks <filename>/usr</filename>
 211     but not <filename>/usr/local</filename>.
 212     </para></listitem>
 213     </varlistentry>
 214
 215     <varlistentry>
 216     <term>share</term>
 217     <listitem><para>
 218     Will match the disks <filename>\\windows1\share</filename> and <filename>\\windows2\share</filename>.
 219     </para></listitem>
 220     </varlistentry>
 221
 222     <varlistentry>
 223     <term>share*</term>
 224     <listitem><para>
 225     Will match the disks <filename>\\windows\share1</filename> and <filename>\\windows\share2</filename>.
 226     </para></listitem>
 227     </varlistentry>
 228
 229     <varlistentry>
 230     <term>//windows/share</term>
 231     <listitem><para>
 232     Will match the disk <filename>\\windows\share</filename>.
 233     </para></listitem>
 234     </varlistentry>
 235
 236 </variablelist>
 237
 238 </refsect2>
 239
 240 </refsect1>
 241
 242 <refsect1><title>DATESTAMP EXPRESSIONS</title>
 243
 244 <para>A datestamp expression is either a prefix of the datestamp, or a range
 245 expression (separated by '-') matching several prefixes.  A leading ^ is
 246 removed, while arailing $ will force an exact match.</para>
 247
 248 <refsect2><title>Examples</title>
 249
 250 <variablelist remap="TP">
 251
 252     <varlistentry>
 253     <term>20001212-14</term>
 254     <listitem><para>match all dates beginning with 20001212, 20001213 or 20001214</para></listitem>
 255     </varlistentry>
 256
 257     <varlistentry>
 258     <term>20001212-4</term>
 259     <listitem><para>same as previous</para></listitem>
 260     </varlistentry>
 261
 262     <varlistentry>
 263     <term>20001212-24</term>
 264     <listitem><para>match all dates between 20001212 and 20001224</para></listitem>
 265     </varlistentry>
 266
 267     <varlistentry>
 268     <term>2000121</term>
 269     <listitem><para>match all dates that start with 2000121 (20001210-20001219)</para></listitem>
 270     </varlistentry>
 271
 272     <varlistentry>
 273     <term>2</term>
 274     <listitem><para>match all dates that start with 2 (20000101-29991231)</para></listitem>
 275     </varlistentry>
 276
 277     <varlistentry>
 278     <term>2000-10</term>
 279     <listitem><para>match all dates between 20000101-20101231</para></listitem>
 280     </varlistentry>
 281
 282     <varlistentry>
 283     <term>200010$</term>
 284     <listitem><para>match only 200010</para></listitem>
 285     </varlistentry>
 286
 287 </variablelist>
 288
 289 </refsect2>
 290
 291 </refsect1>
 292
 293 <refsect1><title>LEVEL EXPRESSIONS</title>
 294
 295 <para>Level expressions are either prefix matches e.g., "1", which matches "1",
 296 "10", and "123", absolute matches e.g., "3$" which only matches "3", or a
 297 range e.g., "3-5" which only matches levels 3, 4, and 5.</para>
 298
 299 </refsect1>
 300
 301 <refsect1><title>DUMP SPECIFICATIONS</title>
 302
 303 <para>A dump specification is used to select one or more dumps from the
 304 catalog.  It consists of a sequence of match expressions in the order host,
 305 disk, datestamp, and level.  Note that some commands do not take a level
 306 argument, out of historical accident.  Note, too, that the datestamp
 307 expression matches the time that the dump was made on the Amanda client,
 308 rather than the date it was moved to tape.</para>
 309
 310 <refsect2><title>Examples</title>
 311
 312 <variablelist remap='TP'>
 313     <varlistentry>
 314     <term>amtool MyConfig ^vpdesktop$</term>
 315     <listitem><para>all dumps of host "vpdesktop"</para></listitem>
 316     </varlistentry>
 317
 318     <varlistentry>
 319     <term>amtool MyConfig '*' /var/stage</term>
 320     <listitem><para>All dumps of <filename>/var/stage</filename> on any host</para></listitem>
 321     </varlistentry>
 322
 323     <varlistentry>
 324     <term>amtool MyConfig www1 /var/www '*' www2 /var/www '*'</term>
 325     <listitem><para>All dumps of /var/www on www1 and www2 (assuming amtool does not
 326             require a level argument)</para></listitem>
 327     </varlistentry>
 328 </variablelist>
 329
 330 </refsect2>
 331
 332 </refsect1>
 333
 334 <refsect1><title>DLE SPECIFICATIONS</title>
 335
 336 <para>A DLE specification is used to select one or more DLEs.  It consists of a
 337     sequence of match expressions.  The first must be a host, and subsequent
 338     expressions will be experimentally matched against both hosts and disks in
 339     the &disklist;, preferring hosts.  This dynamic matching process can lead
 340     to odd behavior in extreme cases (e.g., where a disk and a host have the
 341     same name), but for most uses does exactly what is expected.</para>
 342
 343 <refsect2><title>Examples</title>
 344
 345 <variablelist remap='TP'>
 346     <varlistentry>
 347     <term>amtool MyConfig vpdesktop /home/anderson</term>
 348     <listitem><para><filename>/home/anderson</filename> on host vpdesktop</para></listitem>
 349     </varlistentry>
 350
 351     <varlistentry>
 352         <term>amtool MyConfig '*' ^/etc '*' ^/var</term>
 353         <listitem><para>All DLEs matching <filename>^/var</filename> or
 354                 <filename>^/etc</filename> on any host</para></listitem>
 355     </varlistentry>
 356
 357     <varlistentry>
 358         <term>amtool MyConfig web1 www web2 www</term>
 359         <listitem><para>If no host matches "www", all DLEs matching
 360         <filename>www</filename> on hosts web1 and web2.  If a host
 361         matches "www", then all DLEs on hosts www, web1, and web2.
 362         </para></listitem>
 363     </varlistentry>
 364 </variablelist>
 365
 366 </refsect2>
 367
 368 </refsect1>
 369
 370 <seealso>
 371 <manref name="amanda" vol="8"/>,
 372 <manref name="amfetchdump" vol="8"/>,
 373 <manref name="amrestore" vol="8"/>,
 374 <manref name="amadmin" vol="8"/>,
 375 <manref name="amvault" vol="8"/>
 376 <manref name="amflush" vol="8"/>
 377 <manref name="amdump" vol="8"/>
 378 </seealso>
 379
 380 </refentry>