2 * Copyright (c) 2009-2012 Zmanda, Inc. All Rights Reserved.
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.
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
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
18 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
19 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
26 Amanda::Config - access to Amanda configuration parameters
30 use Amanda::Config qw( :init :getconf );
32 my $config_name = shift @ARGV;
33 config_init($CONFIG_INIT_EXPLICIT_NAME, $config_name);
34 apply_config_overrides($config_overrides);
35 my ($cfgerr_level, @cfgerr_errors) = config_errors();
36 if ($cfgerr_level >= $CFGERR_WARNINGS) {
37 config_print_errors();
38 if ($cfgerr_level >= $CFGERR_ERRORS) {
39 die("errors processing config file");
43 print "tape device is ", getconf($CNF_TAPEDEV), "\n";
45 This API closely parallels the C API.
49 The Amanda configuration is treated as a global state for the
50 application. It is not possible to load two configurations
53 All initialization-related symbols can be imported with the tag
56 =head2 LOADING CONFIGURATION
58 The Amanda configuration is loaded with the aptly named
59 C<config_init($flags, $name)>. Because of the great variety in
60 invocation method among Amanda applications, this function has a number
61 of flags that affect its behavior. These flags can be OR'd together.
65 =item If C<CONFIG_INIT_EXPLICIT_NAME> is given, then the C<$name> parameter can
66 contain the name of a configuration to load. Note that if the parameter is
67 C<".">, this is equivalent to C<CONFIG_INIT_USE_CWD>.
69 =item If C<CONFIG_INIT_USE_CWD> is given, and if the current directory
70 contains C<amanda.conf>, then that file is loaded.
72 =item If C<CONFIG_INIT_CLIENT> is given, then a client configuration
75 =item If C<CONFIG_INIT_OVERLAY> is given, then any existing
76 configuration is not reset.
80 See C<conffile.h> for more detailed information on these flags and
83 C<config_uninit()> reverses the effects of C<config_init>. It is
86 Once the configuration is loaded, the configuration name
87 (e.g., "DailySet1"), directory (C</etc/amanda/DailySet1>),
88 and filename (C</etc/amanda/DailySet1/amanda.conf>) are
89 available from C<get_config_name()>, C<get_config_dir()>, and
90 C<get_config_filename()>, respectively.
94 This module collects configuration errors and warnings in a list, and also
95 tracks the overall error level with an enumeration: C<$CFGERR_OK>,
96 C<$CFGERR_WARNINGS>, and C<$CFGERR_ERRORS>. C<config_init> and
97 C<apply_config_overrides> both return the current level. The level and the
98 list of error messages are available from C<config_errors>:
100 my ($cfgerr_level, @errors) = Amanda::Config::config_errors();
102 As a convenience, C<config_print_errors> will print all error messages to
103 stderr. The error state can be cleared with C<config_clear_errors>.
105 =head2 CONFIG OVERWRITES
107 Most Amanda applications accept the command-line option C<-o>
108 to "overwrite" configuration values in C<amanda.conf>. In Perl
109 applications, these options should be parsed with L<Getopt::Long|Getopt::Long>, with
110 the action being a call to C<add_config_override_opt>. For example:
112 my $config_overrides = new_config_overrides($#ARGV+1);
115 'o=s' => sub { add_config_override_opt($config_overrides, $_[1]); },
117 my $cfg_ok = config_init($CONFIG_INIT_EXPLICIT_NAME | $CONFIG_INIT_USE_CWD, $config_name);
118 apply_config_overrides($config_overrides);
120 C<new_config_overrides($size_estimate)> creates a new
121 overwrites object, using the given size as an estimate of
122 the number of items it will contain (C<$#ARGC/2> is a good
123 estimate). Individual configuration options are then added via
124 C<add_config_override($co, $key, $value)> (which takes a key/value
125 pair) or C<add_config_override_opt($co, $optarg)>, which parses a
126 string following C<-o> on the command line.
128 Once the overwrites are gathered, they are applied with
129 C<apply_config_overrides($co)>, which applies the overwrites to the
130 active configuration. No further operations can be performed on the
131 overwrites object after C<apply_config_overrides> has been called.
133 The utility function C<get_config_options()> returns a list of
134 command-line arguments to represent any overwrites that were used
135 to generate the current configuration. (TODO: this function isn't
138 =head1 PARAMETER ACCESS
140 Amanda configurations consist of "global" parameters and several
141 sets of "subsections" -- one set for dumptypes, one for tapetypes,
144 All of the global parameters are represented by a constant beginning with
145 C<$CNF_>, e.g., C<$CNF_LABELSTR>. The function C<getconf($cnf)> returns the
146 value of parameter C<$cnf>, in whatever format is appropriate for the parameter
147 (see DATA FORMATS, below). C<getconf_seen($cnf)> returns a true value if
148 C<$cnf> was seen in the configuration file. If it was not seen, then it will
149 have its default value. C<getconf_linenum($cnf)> returns the line number in
150 the configuration file where it is set, 0 if it is not in a configuration file,
151 or -2 if it is set in a command line argument.
153 Some parameters have enumerated types. The values for those
154 enumerations are available from this module with the same name as
155 in C<conffile.h>. For example, C<$CNF_TAPERALGO> will yield a value
156 from the enumeration C<taperalgo_t>, the constants for which all
157 begin with C<$ALGO_>. See C<conffile.h> for the details.
159 Each subsection type C<TYP> has the following functions:
163 =item C<lookup_TYP($subsec_name)>
165 which returns an opaque object
166 (C<$ss>) representing the subsection, or C<undef> if no subsection
167 with that name exists;
169 =item C<TYP_name($ss)>
171 returning the name of the subsection;
173 =item C<TYP_getconf($ss, $cnf)>
175 which fetches a parameter value from C<$ss>; and
177 =item C<TYP_seen($ss, $cnf)>
179 which returns a true value if <$cnf> was seen in the subsection.
189 with constants beginning with C<$TAPETYPE_>
193 with constants beginning with C<$DUMPTYPE_>
197 with constants beginning with C<$INTER_>
201 with constants beginning with C<$HOLDING_>
205 with constants beginning with C<$APPLICATION_>
209 with constants beginning with C<$PP_SCRIPT_>
213 with constants beginning with C<$DEVICE_CONFIG_>.
217 with constants beginning with C<$CHANGER_CONFIG_>.
221 See C<conffile.h> for the names of the constants themselves.
225 Each configuration parameter has a "conftype", as assigned in
226 C<common-src/conffile.c>. The translation of most of these types into Perl
227 values is straightforward:
229 CONFTYPE_INT Math::BigInt
230 CONFTYPE_INT64 Math::BigInt
231 CONFTYPE_REAL floating-point value
233 CONFTYPE_IDENT string
234 CONFTYPE_TIME Math::BigInt (epoch value)
235 CONFTYPE_SIZE Math::BigInt
236 CONFTYPE_BOOLEAN Math::BigInt
237 CONFTYPE_COMPRESS Math::BigInt
238 CONFTYPE_ENCRYPT Math::BigInt
239 CONFTYPE_HOLDING Math::BigInt
240 CONFTYPE_ESTIMATELIST [ Math::BigInt, .. ]
241 CONFTYPE_STRATEGY Math::BigInt
242 CONFTYPE_TAPERALGO Math::BigInt
243 CONFTYPE_PRIORITY Math::BigInt
244 CONFTYPE_RATE float, float
245 CONFTYPE_INTRANGE Math::BigInt, Math::BigInt
246 CONFTYPE_APPLICATION string
247 CONFTYPE_EXECUTE_ON string
248 CONFTYPE_EXECUTE_WHERE Math::BigInt
249 CONFTYPE_SEND_AMREPORT_ON Math::BigInt
250 CONFTYPE_IDENTLIST [ string, .. ]
251 CONFTYPE_PART_CACHE_TYPE Math::BigInt
252 CONFTYPE_RECOVERY_LIMIT [ string, .. ] (undef if not specified;
253 undef in the list means same-host)
255 Note that C<CONFTYPE_INTRANGE> and C<CONFTYPE_RATE> each return two values, not
258 Include and exclude lists with type C<CONFTYPE_EXINCLUDE> return a hash giving
259 all listed filenames (in the C<list> key), include/exclude files (C<files>),
260 and a boolean indicating that the list is optional (C<optional>):
262 { list => [ str, .. ], file => [ str, .. ], optional => Math::BigInt }
264 Properties are represented as a hash of hashes. The keys are the property
265 names, converted to ASCII lowercase. Each property has a C<values> array
266 giving all values specified for this property, as well as booleans C<priority>
267 and C<append> that are true if the corresponding keyword was supplied.
269 { prop1 => { values => [ str, .. ] priority => int, append => int },
272 Note that integer types of all sizes become C<Math::BigInt> objects rather than
273 Perl integers, as is the habit throughout Amanda.
275 The C<CNF_AUTOLABEL> value is a hash with the following keys
277 template label template, or undef
285 Parameter values are available by name from C<getconf_byname($name)> and
286 C<getconf_byname_strs($name, $str_needs_quotes)>. These functions implement
287 the C<TYP:NAME:PARAM> syntax advertised by C<amgetconf> to access values in
288 subsections. The first function returns a Perl value (see DATA FORMATS,
289 above), while the second returns a list of strings suitable for use in
290 C<amanda.conf>, including quotes around strings if C<$str_needs_quotes> is
293 C<getconf_list($typ)> returns a list of the names of all subsections of the
294 given type. C<%subsection_names> is a hash whose keys are allowed subsection
297 =head2 DERIVED VALUES
299 The C<$CNF_DISPLAYUNIT> implies a certain divisor to convert from
300 kilobytes to the desired unit. This divisor is available from
301 C<getconf_unit_divisor()>. Note carefully that it is a I<divisor>
302 for a value in I<kilobytes>!
304 Finally, various subsections of Amanda enable verbose debugging via
305 configuration parameters. The status of each parameter is available
306 a similarly-named variable, e.g., C<$debug_auth>.
308 All parameter access functions and constants can be imported with
313 These functions defy categorization.
315 The function C<config_dir_relative> will interpret a path relative to
316 the current configuration directory. Absolute paths are passed through
317 unchanged, while relative paths are converted to absolute paths.
319 C<dump_configuration()> dumps the current configuration, in a format
320 suitable for re-evaluation for this module, to standard output.
321 This function may be revised to return a string.
323 Several parts of Amanda need to convert unit modifier value like
324 "gbytes" to a multiplier. The function C<find_multiplier($str)>
325 returns the unit multiplier for such a string. For example, "mbytes"
326 is converted to 1048576 (1024*1024).
328 C<string_to_boolean()> takes a string and returns 0 if it matches any of
329 Amanda's names for false, or 1 if matches a name for true. If it can't be
330 interpreted, C<undef> is returned.
332 C<amandaify_property_name()> converts a string into Amanda's property style:
333 all lower-case and with "-" replacing "_".
337 This section lists all of the configuration parameter constants defined in this
338 module. All of these constants are available with the C<:getconf> export tag.