git.gag.com Git - debian/amanda/blob - perl/Amanda/Config.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::Config - access to Amanda configuration parameters
  27
  28 =head1 SYNOPSIS
  29
  30     use Amanda::Config qw( :init :getconf );
  31
  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");
  40         }
  41     }
  42
  43     print "tape device is ", getconf($CNF_TAPEDEV), "\n";
  44
  45 This API closely parallels the C API.
  46
  47 =head1 INITIALIZATION
  48
  49 The Amanda configuration is treated as a global state for the
  50 application.  It is not possible to load two configurations
  51 simultaneously.
  52
  53 All initialization-related symbols can be imported with the tag
  54 C<:init>.
  55
  56 =head2 LOADING CONFIGURATION
  57
  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.
  62
  63 =over
  64
  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>.
  68
  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.
  71
  72 =item If C<CONFIG_INIT_CLIENT> is given, then a client configuration
  73 is loaded.
  74
  75 =item If C<CONFIG_INIT_OVERLAY> is given, then any existing
  76 configuration is not reset.
  77
  78 =back
  79
  80 See C<conffile.h> for more detailed information on these flags and
  81 their interactions.
  82
  83 C<config_uninit()> reverses the effects of C<config_init>.  It is
  84 not often used.
  85
  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.
  91
  92 =head3 CONFIG ERRORS
  93
  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>:
  99
 100   my ($cfgerr_level, @errors) = Amanda::Config::config_errors();
 101
 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>.
 104
 105 =head2 CONFIG OVERWRITES
 106
 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:
 111
 112   my $config_overrides = new_config_overrides($#ARGV+1);
 113     GetOptions(
 114         # ...
 115         'o=s' => sub { add_config_override_opt($config_overrides, $_[1]); },
 116     ) or usage();
 117   my $cfg_ok = config_init($CONFIG_INIT_EXPLICIT_NAME | $CONFIG_INIT_USE_CWD, $config_name);
 118   apply_config_overrides($config_overrides);
 119
 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.
 127
 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.
 132
 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
 136 available yet)
 137
 138 =head1 PARAMETER ACCESS
 139
 140 Amanda configurations consist of "global" parameters and several
 141 sets of "subsections" -- one set for dumptypes, one for tapetypes,
 142 and so on.
 143
 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.
 152
 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.
 158
 159 Each subsection type C<TYP> has the following functions:
 160
 161 =over
 162
 163 =item C<lookup_TYP($subsec_name)>
 164
 165 which returns an opaque object
 166 (C<$ss>) representing the subsection, or C<undef> if no subsection
 167 with that name exists;
 168
 169 =item C<TYP_name($ss)>
 170
 171 returning the name of the subsection;
 172
 173 =item C<TYP_getconf($ss, $cnf)>
 174
 175 which fetches a parameter value from C<$ss>; and
 176
 177 =item C<TYP_seen($ss, $cnf)>
 178
 179 which returns a true value if <$cnf> was seen in the subsection.
 180
 181 =back
 182
 183 The subsections are:
 184
 185 =over
 186
 187 =item C<tapetype>
 188
 189 with constants beginning with C<$TAPETYPE_>
 190
 191 =item C<dumptype>
 192
 193 with constants beginning with C<$DUMPTYPE_>
 194
 195 =item C<interface>
 196
 197 with constants beginning with C<$INTER_>
 198
 199 =item C<holdingdisk>
 200
 201 with constants beginning with C<$HOLDING_>
 202
 203 =item C<application>
 204
 205 with constants beginning with C<$APPLICATION_>
 206
 207 =item C<script>
 208
 209 with constants beginning with C<$PP_SCRIPT_>
 210
 211 =item C<device>
 212
 213 with constants beginning with C<$DEVICE_CONFIG_>.
 214
 215 =item C<changer>
 216
 217 with constants beginning with C<$CHANGER_CONFIG_>.
 218
 219 =back
 220
 221 See C<conffile.h> for the names of the constants themselves.
 222
 223 =head2 DATA FORMATS
 224
 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:
 228
 229   CONFTYPE_INT                        Math::BigInt
 230   CONFTYPE_INT64                      Math::BigInt
 231   CONFTYPE_REAL                       floating-point value
 232   CONFTYPE_STR                        string
 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)
 254
 255 Note that C<CONFTYPE_INTRANGE> and C<CONFTYPE_RATE> each return two values, not
 256 an array reference.
 257
 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>):
 261
 262   { list => [ str, .. ], file => [ str, .. ], optional => Math::BigInt }
 263
 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.
 268
 269   { prop1 => { values => [ str, .. ] priority => int, append => int },
 270     prop2 => { .. } .. }
 271
 272 Note that integer types of all sizes become C<Math::BigInt> objects rather than
 273 Perl integers, as is the habit throughout Amanda.
 274
 275 The C<CNF_AUTOLABEL> value is a hash with the following keys
 276
 277   template      label template, or undef
 278   other_config  boolean
 279   non_amanda    boolean
 280   volume_error  boolean
 281   empty         boolean
 282
 283 =head2 OTHER ACCESS
 284
 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
 291 true.
 292
 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
 295 names.
 296
 297 =head2 DERIVED VALUES
 298
 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>!
 303
 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>.
 307
 308 All parameter access functions and constants can be imported with
 309 the tag C<:getconf>.
 310
 311 =head1 MISCELLANEOUS
 312
 313 These functions defy categorization.
 314
 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.
 318
 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.
 322
 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).
 327
 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.
 331
 332 C<amandaify_property_name()> converts a string into Amanda's property style:
 333 all lower-case and with "-" replacing "_".
 334
 335 =head1 CONSTANTS
 336
 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.
 339
 340 =cut
 341
 342 %}