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

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