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::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 45This API closely parallels the C API. 46 47=head1 INITIALIZATION 48 49The Amanda configuration is treated as a global state for the 50application. It is not possible to load two configurations 51simultaneously. 52 53All initialization-related symbols can be imported with the tag 54C<:init>. 55 56=head2 LOADING CONFIGURATION 57 58The Amanda configuration is loaded with the aptly named 59C<config_init($flags, $name)>. Because of the great variety in 60invocation method among Amanda applications, this function has a number 61of 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 66contain the name of a configuration to load. Note that if the parameter is 67C<".">, 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 70contains C<amanda.conf>, then that file is loaded. 71 72=item If C<CONFIG_INIT_CLIENT> is given, then a client configuration 73is loaded. 74 75=item If C<CONFIG_INIT_OVERLAY> is given, then any existing 76configuration is not reset. 77 78=back 79 80See C<conffile.h> for more detailed information on these flags and 81their interactions. 82 83C<config_uninit()> reverses the effects of C<config_init>. It is 84not often used. 85 86Once the configuration is loaded, the configuration name 87(e.g., "DailySet1"), directory (C</etc/amanda/DailySet1>), 88and filename (C</etc/amanda/DailySet1/amanda.conf>) are 89available from C<get_config_name()>, C<get_config_dir()>, and 90C<get_config_filename()>, respectively. 91 92=head3 CONFIG ERRORS 93 94This module collects configuration errors and warnings in a list, and also 95tracks the overall error level with an enumeration: C<$CFGERR_OK>, 96C<$CFGERR_WARNINGS>, and C<$CFGERR_ERRORS>. C<config_init> and 97C<apply_config_overrides> both return the current level. The level and the 98list of error messages are available from C<config_errors>: 99 100 my ($cfgerr_level, @errors) = Amanda::Config::config_errors(); 101 102As a convenience, C<config_print_errors> will print all error messages to 103stderr. The error state can be cleared with C<config_clear_errors>. 104 105=head2 CONFIG OVERWRITES 106 107Most Amanda applications accept the command-line option C<-o> 108to "overwrite" configuration values in C<amanda.conf>. In Perl 109applications, these options should be parsed with L<Getopt::Long|Getopt::Long>, with 110the 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 120C<new_config_overrides($size_estimate)> creates a new 121overwrites object, using the given size as an estimate of 122the number of items it will contain (C<$#ARGC/2> is a good 123estimate). Individual configuration options are then added via 124C<add_config_override($co, $key, $value)> (which takes a key/value 125pair) or C<add_config_override_opt($co, $optarg)>, which parses a 126string following C<-o> on the command line. 127 128Once the overwrites are gathered, they are applied with 129C<apply_config_overrides($co)>, which applies the overwrites to the 130active configuration. No further operations can be performed on the 131overwrites object after C<apply_config_overrides> has been called. 132 133The utility function C<get_config_options()> returns a list of 134command-line arguments to represent any overwrites that were used 135to generate the current configuration. (TODO: this function isn't 136available yet) 137 138=head1 PARAMETER ACCESS 139 140Amanda configurations consist of "global" parameters and several 141sets of "subsections" -- one set for dumptypes, one for tapetypes, 142and so on. 143 144All of the global parameters are represented by a constant beginning with 145C<$CNF_>, e.g., C<$CNF_LABELSTR>. The function C<getconf($cnf)> returns the 146value 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 148C<$cnf> was seen in the configuration file. If it was not seen, then it will 149have its default value. C<getconf_linenum($cnf)> returns the line number in 150the configuration file where it is set, 0 if it is not in a configuration file, 151or -2 if it is set in a command line argument. 152 153Some parameters have enumerated types. The values for those 154enumerations are available from this module with the same name as 155in C<conffile.h>. For example, C<$CNF_TAPERALGO> will yield a value 156from the enumeration C<taperalgo_t>, the constants for which all 157begin with C<$ALGO_>. See C<conffile.h> for the details. 158 159Each subsection type C<TYP> has the following functions: 160 161=over 162 163=item C<lookup_TYP($subsec_name)> 164 165which returns an opaque object 166(C<$ss>) representing the subsection, or C<undef> if no subsection 167with that name exists; 168 169=item C<TYP_name($ss)> 170 171returning the name of the subsection; 172 173=item C<TYP_getconf($ss, $cnf)> 174 175which fetches a parameter value from C<$ss>; and 176 177=item C<TYP_seen($ss, $cnf)> 178 179which returns a true value if <$cnf> was seen in the subsection. 180 181=back 182 183The subsections are: 184 185=over 186 187=item C<tapetype> 188 189with constants beginning with C<$TAPETYPE_> 190 191=item C<dumptype> 192 193with constants beginning with C<$DUMPTYPE_> 194 195=item C<interface> 196 197with constants beginning with C<$INTER_> 198 199=item C<holdingdisk> 200 201with constants beginning with C<$HOLDING_> 202 203=item C<application> 204 205with constants beginning with C<$APPLICATION_> 206 207=item C<script> 208 209with constants beginning with C<$PP_SCRIPT_> 210 211=item C<device> 212 213with constants beginning with C<$DEVICE_CONFIG_>. 214 215=item C<changer> 216 217with constants beginning with C<$CHANGER_CONFIG_>. 218 219=back 220 221See C<conffile.h> for the names of the constants themselves. 222 223=head2 DATA FORMATS 224 225Each configuration parameter has a "conftype", as assigned in 226C<common-src/conffile.c>. The translation of most of these types into Perl 227values 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 255Note that C<CONFTYPE_INTRANGE> and C<CONFTYPE_RATE> each return two values, not 256an array reference. 257 258Include and exclude lists with type C<CONFTYPE_EXINCLUDE> return a hash giving 259all listed filenames (in the C<list> key), include/exclude files (C<files>), 260and a boolean indicating that the list is optional (C<optional>): 261 262 { list => [ str, .. ], file => [ str, .. ], optional => Math::BigInt } 263 264Properties are represented as a hash of hashes. The keys are the property 265names, converted to ASCII lowercase. Each property has a C<values> array 266giving all values specified for this property, as well as booleans C<priority> 267and C<append> that are true if the corresponding keyword was supplied. 268 269 { prop1 => { values => [ str, .. ] priority => int, append => int }, 270 prop2 => { .. } .. } 271 272Note that integer types of all sizes become C<Math::BigInt> objects rather than 273Perl integers, as is the habit throughout Amanda. 274 275The 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 285Parameter values are available by name from C<getconf_byname($name)> and 286C<getconf_byname_strs($name, $str_needs_quotes)>. These functions implement 287the C<TYP:NAME:PARAM> syntax advertised by C<amgetconf> to access values in 288subsections. The first function returns a Perl value (see DATA FORMATS, 289above), while the second returns a list of strings suitable for use in 290C<amanda.conf>, including quotes around strings if C<$str_needs_quotes> is 291true. 292 293C<getconf_list($typ)> returns a list of the names of all subsections of the 294given type. C<%subsection_names> is a hash whose keys are allowed subsection 295names. 296 297=head2 DERIVED VALUES 298 299The C<$CNF_DISPLAYUNIT> implies a certain divisor to convert from 300kilobytes to the desired unit. This divisor is available from 301C<getconf_unit_divisor()>. Note carefully that it is a I<divisor> 302for a value in I<kilobytes>! 303 304Finally, various subsections of Amanda enable verbose debugging via 305configuration parameters. The status of each parameter is available 306a similarly-named variable, e.g., C<$debug_auth>. 307 308All parameter access functions and constants can be imported with 309the tag C<:getconf>. 310 311=head1 MISCELLANEOUS 312 313These functions defy categorization. 314 315The function C<config_dir_relative> will interpret a path relative to 316the current configuration directory. Absolute paths are passed through 317unchanged, while relative paths are converted to absolute paths. 318 319C<dump_configuration()> dumps the current configuration, in a format 320suitable for re-evaluation for this module, to standard output. 321This function may be revised to return a string. 322 323Several parts of Amanda need to convert unit modifier value like 324"gbytes" to a multiplier. The function C<find_multiplier($str)> 325returns the unit multiplier for such a string. For example, "mbytes" 326is converted to 1048576 (1024*1024). 327 328C<string_to_boolean()> takes a string and returns 0 if it matches any of 329Amanda's names for false, or 1 if matches a name for true. If it can't be 330interpreted, C<undef> is returned. 331 332C<amandaify_property_name()> converts a string into Amanda's property style: 333all lower-case and with "-" replacing "_". 334 335=head1 CONSTANTS 336 337This section lists all of the configuration parameter constants defined in this 338module. All of these constants are available with the C<:getconf> export tag. 339 340=cut 341 342%} 343