1/*
2 * Copyright (c) 2009-2013 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
26Amanda::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
47C<Amanda::Feature::Set> objects are fairly simple.  The three constructors are
48shown in the SYNOPSIS: C<mine> (all currently-supported features), C<old> (only
49the features present in versions of Amanda before features were invented), or
50C<from_string>.
51
52An 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
63And C<as_string> which converts the feature into a string.
64
65All features are available in scalars of the same name in the
66C<Amanda::Feature> namespace.
67
68=head1 FEATURE DOCUMENTATION
69
70This section includes as much information as is available for each feature.
71Each subsection begins with a description of the protocols in
72which the feature is relevant, and the end on which the feature is relevant.
73Any known dependencies for the feature are also mentioned.  Assume that any
74omissions 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
83If set, the recovery application supports a DATA connection on a separate TCP
84connection.
85
86Dependencies: this feature is always set when amidxtaped is invoked via
87amandad.
88
89=item fe_amidxtaped_exchange_features
90
91 PROTOCOL: amidxtaped
92 FEATURE OF: server
93
94If set, amidxtaped can process the FEATURES= line in the command.
95The flag is actually tested by amrecover on amindexd's feature matrix, due to
96ordering constraints, so it assumes that amindexd and amidxtaped have the same
97features.
98
99=item fe_amrecover_FEEDME
100
101 PROTOCOL: amidxtaped
102 FEATURE OF: client
103
104If set, amrecover understands FEEDME lines on the control connection.
105
106Dependencies: 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
113If set, the recovery application supports full timestamps; otherwise, it can
114only 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
125These feature flags indicate what fields amidxtaped supports in the OPTIONS
126line.  Of course, the client would need to know these features before it
127received the OPTIONS line, which would necessitate sending a NOOP request
128first.  In practice, they are completely unused.
129
130=item fe_amrecover_message
131
132 PROTOCOL: amidxtaped
133 FEATURE OF: client
134
135If set, the recovery applications understands MESSAGE lines on the control connection.
136
137Dependencies: a control connection only exists if amidxtaped is launched from
138amandad or I<fe_recover_splits> is used.
139
140=item fe_amrecover_feedme_tape
141
142 PROTOCOL: amidxtaped
143 FEATURE OF: server
144
145If 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
154If set, amrecover can process a header containing the corresponding attribute.
155If not set, the attribute should be stripped from any headers sent to
156amrecover.
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
168If set, amidxtaped can handle an ABORT message just before the datapath
169negotiation begins.
170
171=item fe_amidxtaped_datapath
172
173 PROTOCOL: amidxtaped
174 FEATURE OF: client and server
175
176If set on the client, then amrecover expects the server to start a DATAPATH
177negotiation after the header is sent.  If set on the server, then amrecover can
178process a DATAPATH negotiation after the header is sent.  In other words, the
179feature must be present on both sides for this negotiation to take place.  The
180DATAPATH 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
186No data may be transmitted until the handshake is complete.  See the wiki
187article 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
208If set, each feature means that amidxtaped can process the corresponding
209command line.  Note that I<fe_amidxtaped_label> does not indicate whether that
210field contains a label or a tapespec.
211
212=item fe_amidxtaped_nargs
213
214 PROTOCOL: amidxtaped
215 FEATURE OF: server
216
217If set, then amidxtaped can handle the "nargs" form of a command: The first
218line was the number of arguments, folloewd by one argument by line.  Amidxtaped
219forked amrestore with these arguments.
220
221This feature is no longer supported.
222
223=item fe_amrecover_correct_disk_quoting
224
225 PROTOCOL: amidxtaped
226 FEATURE OF: amrecover
227
228Amrecovers that do not have this flag may send incorrectly-quoted DISK lines, so
229those DISK lines should be ignored.
230
231=item fe_amindexd_quote_label
232
233 PROTOCOL: amindexd
234 FEATURE OF: server
235
236If set, amindexd quote the label (holdingdisk filename)
237
238=item fe_amrecover_receive_unfiltered
239
240 PROTOCOL: amidxtaped
241 FEATURE OF: client
242
243If set, amidxtaped do not decompress/decrypt client compressed/decrypted stream.
244
245=item fe_application_client_name
246
247If set, add the 'client_name' for application in the xml code.
248
249=item fe_script_client_name
250
251If set, add the 'client_name' for script in the xml code.
252
253=item fe_dumptype_property
254
255If set, add the dumptype property in the xml code.
256
257=back
258
259=cut
260
261%}
262
263