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