git.gag.com Git - debian/amanda/blob - perl/Amanda/Feature.pod

   1 /*
   2  * Copyright (c) 2009, 2010 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 as published
   6  * by the Free Software Foundation.
   7  *
   8  * This program is distributed in the hope that it will be useful, but
   9  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  10  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  16  *
  17  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  18  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  19  */
  20
  21 %perlcode %{
  22
  23 =head1 NAME
  24
  25 Amanda::Feature - interface to Amanda feature bitfields
  26
  27 =head1 SYNOPSIS
  28
  29     # set up features for this instance and print them
  30     my $features = Amanda::Feature::Set->mine();
  31     print "my features: $features\n";
  32
  33     # parse the other side's features
  34     my $client_feat = Amanda::Feature::Set->from_string($feat_str);
  35
  36     # or assume the other side's features are old
  37     my $client_feat = Amanda::Feature::Set->old()
  38
  39     # test for a feature
  40     if ($feat->has($Amanda::Feature::fe_options_bsd_auth)) {
  41         print "has BSD auth\n";
  42     }
  43
  44 =head1 DESCRIPTION
  45
  46 C<Amanda::Feature::Set> objects are fairly simple.  The three constructors are
  47 shown in the SYNOPSIS: C<mine> (all currently-supported features), C<old> (only
  48 the features present in versions of Amanda before features were invented), or
  49 C<from_string>.
  50
  51 An object has three methods to address specific bits:
  52
  53     # set a bit
  54     $feat->add($Amanda::Feature::fe_req_xml);
  55
  56     # clear a bit
  57     $feat->remove($Amanda::Feature::fe_req_xml);
  58
  59     # test a bit
  60     if ($feat->has($Amanda::Feature::fe_req_xml)) ..
  61
  62 And C<as_string> which converts the feature into a string.
  63
  64 All features are available in scalars of the same name in the
  65 C<Amanda::Feature> namespace.
  66
  67 =head1 FEATURE DOCUMENTATION
  68
  69 This section includes as much information as is available for each feature.
  70 Each subsection begins with a description of the protocols in
  71 which the feature is relevant, and the end on which the feature is relevant.
  72 Any known dependencies for the feature are also mentioned.  Assume that any
  73 omissions in this section are due to limited information.
  74
  75 =over 2
  76
  77 =item fe_recover_splits
  78
  79  PROTOCOL: amidxtaped
  80  FEATURE OF: client
  81
  82 If set, the recovery application supports a DATA connection on a separate TCP
  83 connection.
  84
  85 Dependencies: this feature is always set when amidxtaped is invoked via
  86 amandad.
  87
  88 =item fe_amidxtaped_exchange_features
  89
  90  PROTOCOL: amidxtaped
  91  FEATURE OF: server
  92
  93 If set, amidxtaped can process the FEATURES= line in the command.
  94 The flag is actually tested by amrecover on amindexd's feature matrix, due to
  95 ordering constraints, so it assumes that amindexd and amidxtaped have the same
  96 features.
  97
  98 =item fe_amrecover_FEEDME
  99
 100  PROTOCOL: amidxtaped
 101  FEATURE OF: client
 102
 103 If set, amrecover understands FEEDME lines on the control connection.
 104
 105 Dependencies: this feature can only be set if fe_recover_splits is set.
 106
 107 =item fe_amrecover_timestamp
 108
 109  PROTOCOL: amindexd
 110  FEATURE OF: client
 111
 112 If set, the recovery application supports full timestamps; otherwise, it can
 113 only process datestamps.
 114
 115 =item fe_amidxtaped_options_hostname
 116
 117 =item fe_amidxtaped_options_features
 118
 119 =item fe_amidxtaped_options_auth
 120
 121  PROTOCOL: amidxtaped
 122  FEATURE OF: server
 123
 124 These feature flags indicate what fields amidxtaped supports in the OPTIONS
 125 line.  Of course, the client would need to know these features before it
 126 received the OPTIONS line, which would necessitate sending a NOOP request
 127 first.  In practice, they are completely unused.
 128
 129 =item fe_amrecover_message
 130
 131  PROTOCOL: amidxtaped
 132  FEATURE OF: client
 133
 134 If set, the recovery applications understands MESSAGE lines on the control connection.
 135
 136 Dependencies: a control connection only exists if amidxtaped is launched from
 137 amandad or I<fe_recover_splits> is used.
 138
 139 =item fe_amrecover_feedme_tape
 140
 141  PROTOCOL: amidxtaped
 142  FEATURE OF: server
 143
 144 If set, amidxtaped recognizes the TAPE response to FEEDME.
 145
 146 =item fe_amrecover_dle_in_header
 147
 148 =item fe_amrecover_origsize_in_header
 149
 150  PROTOCOL: amidxtaped
 151  FEATURE OF: client
 152
 153 If set, amrecover can process a header containing the corresponding attribute.
 154 If not set, the attribute should be stripped from any headers sent to
 155 amrecover.
 156
 157  Feature                Header Attribute
 158  -------                ----------------
 159  dle_in_header          dle_str
 160  origsize_in_header     orig_size
 161
 162 =item fe_amidxtaped_abort
 163
 164  PROTOCOL: amidxtaped
 165  FEATURE OF: server
 166
 167 If set, amidxtaped can handle an ABORT message just before the datapath
 168 negotiation begins.
 169
 170 =item fe_amidxtaped_datapath
 171
 172  PROTOCOL: amidxtaped
 173  FEATURE OF: client and server
 174
 175 If set on the client, then amrecover expects the server to start a DATAPATH
 176 negotiation after the header is sent.  If set on the server, then amrecover can
 177 process a DATAPATH negotiation after the header is sent.  In other words, the
 178 feature must be present on both sides for this negotiation to take place.  The
 179 DATAPATH negotiation is a three-way handshake:
 180
 181   AVAIL-DATAPATH <datapath list>         # to amidxtaped
 182   USE-DATAPATH <datapath> [<ip:port> ..] # from amidxtaped
 183   DATAPATH-OK                            # to amidxtaped
 184
 185 No data may be transmitted until the handshake is complete.  See the wiki
 186 article entitled "amidxtaped protocol" for more detail.
 187
 188 =item fe_amidxtaped_fsf
 189
 190 =item fe_amidxtaped_label
 191
 192 =item fe_amidxtaped_device
 193
 194 =item fe_amidxtaped_host
 195
 196 =item fe_amidxtaped_disk
 197
 198 =item fe_amidxtaped_datestamp
 199
 200 =item fe_amidxtaped_header
 201
 202 =item fe_amidxtaped_config
 203
 204  PROTOCOL: amidxtaped
 205  FEATURE OF: server
 206
 207 If set, each feature means that amidxtaped can process the corresponding
 208 command line.  Note that I<fe_amidxtaped_label> does not indicate whether that
 209 field contains a label or a tapespec.
 210
 211 =item fe_amidxtaped_nargs
 212
 213  PROTOCOL: amidxtaped
 214  FEATURE OF: server
 215
 216 If set, then amidxtaped can handle the "nargs" form of a command: The first
 217 line was the number of arguments, folloewd by one argument by line.  Amidxtaped
 218 forked amrestore with these arguments.
 219
 220 This feature is no longer supported.
 221
 222 =item fe_amrecover_correct_disk_quoting
 223
 224  PROTOCOL: amidxtaped
 225  FEATURE OF: amrecover
 226
 227 Amrecovers that do not have this flag may send incorrectly-quoted DISK lines, so
 228 those DISK lines should be ignored.
 229
 230 =item fe_amindexd_quote_label
 231
 232  PROTOCOL: amindexd
 233  FEATURE OF: server
 234
 235 If set, amindexd quote the label (holdingdisk filename)
 236
 237 =back
 238
 239 =cut
 240
 241 %}
 242