--- /dev/null
+/*
+ * Copyright (c) 2009, 2010 Zmanda, Inc. All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 as published
+ * by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
+ * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
+ */
+
+%perlcode %{
+
+=head1 NAME
+
+Amanda::Config - access to Amanda configuration parameters
+
+=head1 SYNOPSIS
+
+ use Amanda::Config qw( :init :getconf );
+
+ my $config_name = shift @ARGV;
+ config_init($CONFIG_INIT_EXPLICIT_NAME, $config_name);
+ apply_config_overrides($config_overrides);
+ my ($cfgerr_level, @cfgerr_errors) = config_errors();
+ if ($cfgerr_level >= $CFGERR_WARNINGS) {
+ config_print_errors();
+ if ($cfgerr_level >= $CFGERR_ERRORS) {
+ die("errors processing config file");
+ }
+ }
+
+ print "tape device is ", getconf($CNF_TAPEDEV), "\n";
+
+This API closely parallels the C API.
+
+=head1 INITIALIZATION
+
+The Amanda configuration is treated as a global state for the
+application. It is not possible to load two configurations
+simultaneously.
+
+All initialization-related symbols can be imported with the tag
+C<:init>.
+
+=head2 LOADING CONFIGURATION
+
+The Amanda configuration is loaded with the aptly named
+C<config_init($flags, $name)>. Because of the great variety in
+invocation method among Amanda applications, this function has a number
+of flags that affect its behavior. These flags can be OR'd together.
+
+=over
+
+=item If C<CONFIG_INIT_EXPLICIT_NAME> is given, then the C<$name> parameter can
+contain the name of a configuration to load. Note that if the parameter is
+C<".">, this is equivalent to C<CONFIG_INIT_USE_CWD>.
+
+=item If C<CONFIG_INIT_USE_CWD> is given, and if the current directory
+contains C<amanda.conf>, then that file is loaded.
+
+=item If C<CONFIG_INIT_CLIENT> is given, then a client configuration
+is loaded.
+
+=item If C<CONFIG_INIT_OVERLAY> is given, then any existing
+configuration is not reset.
+
+=back
+
+See C<conffile.h> for more detailed information on these flags and
+their interactions.
+
+C<config_uninit()> reverses the effects of C<config_init>. It is
+not often used.
+
+Once the configuration is loaded, the configuration name
+(e.g., "DailySet1"), directory (C</etc/amanda/DailySet1>),
+and filename (C</etc/amanda/DailySet1/amanda.conf>) are
+available from C<get_config_name()>, C<get_config_dir()>, and
+C<get_config_filename()>, respectively.
+
+=head3 CONFIG ERRORS
+
+This module collects configuration errors and warnings in a list, and also
+tracks the overall error level with an enumeration: C<$CFGERR_OK>,
+C<$CFGERR_WARNINGS>, and C<$CFGERR_ERRORS>. C<config_init> and
+C<apply_config_overrides> both return the current level. The level and the
+list of error messages are available from C<config_errors>:
+
+ my ($cfgerr_level, @errors) = Amanda::Config::config_errors();
+
+As a convenience, C<config_print_errors> will print all error messages to
+stderr. The error state can be cleared with C<config_clear_errors>.
+
+=head2 CONFIG OVERWRITES
+
+Most Amanda applications accept the command-line option C<-o>
+to "overwrite" configuration values in C<amanda.conf>. In Perl
+applications, these options should be parsed with L<Getopt::Long|Getopt::Long>, with
+the action being a call to C<add_config_override_opt>. For example:
+
+ my $config_overrides = new_config_overrides($#ARGV+1);
+ GetOptions(
+ # ...
+ 'o=s' => sub { add_config_override_opt($config_overrides, $_[1]); },
+ ) or usage();
+ my $cfg_ok = config_init($CONFIG_INIT_EXPLICIT_NAME | $CONFIG_INIT_USE_CWD, $config_name);
+ apply_config_overrides($config_overrides);
+
+C<new_config_overrides($size_estimate)> creates a new
+overwrites object, using the given size as an estimate of
+the number of items it will contain (C<$#ARGC/2> is a good
+estimate). Individual configuration options are then added via
+C<add_config_override($co, $key, $value)> (which takes a key/value
+pair) or C<add_config_override_opt($co, $optarg)>, which parses a
+string following C<-o> on the command line.
+
+Once the overwrites are gathered, they are applied with
+C<apply_config_overrides($co)>, which applies the overwrites to the
+active configuration. No further operations can be performed on the
+overwrites object after C<apply_config_overrides> has been called.
+
+The utility function C<get_config_options()> returns a list of
+command-line arguments to represent any overwrites that were used
+to generate the current configuration. (TODO: this function isn't
+available yet)
+
+=head1 PARAMETER ACCESS
+
+Amanda configurations consist of "global" parameters and several
+sets of "subsections" -- one set for dumptypes, one for tapetypes,
+and so on.
+
+All of the global parameters are represented by a constant beginning with
+C<$CNF_>, e.g., C<$CNF_LABELSTR>. The function C<getconf($cnf)> returns the
+value of parameter C<$cnf>, in whatever format is appropriate for the parameter
+(see DATA FORMATS, below). C<getconf_seen($cnf)> returns a true value if
+C<$cnf> was seen in the configuration file. If it was not seen, then it will
+have its default value. C<getconf_linenum($cnf)> returns the line number in
+the configuration file where it is set, 0 if it is not in a configuration file,
+or -2 if it is set in a command line argument.
+
+Some parameters have enumerated types. The values for those
+enumerations are available from this module with the same name as
+in C<conffile.h>. For example, C<$CNF_TAPERALGO> will yield a value
+from the enumeration C<taperalgo_t>, the constants for which all
+begin with C<$ALGO_>. See C<conffile.h> for the details.
+
+Each subsection type C<TYP> has the following functions:
+
+=over
+
+=item C<lookup_TYP($subsec_name)>
+
+which returns an opaque object
+(C<$ss>) representing the subsection, or C<undef> if no subsection
+with that name exists;
+
+=item C<TYP_name($ss)>
+
+returning the name of the subsection;
+
+=item C<TYP_getconf($ss, $cnf)>
+
+which fetches a parameter value from C<$ss>; and
+
+=item C<TYP_seen($ss, $cnf)>
+
+which returns a true value if <$cnf> was seen in the subsection.
+
+=back
+
+The subsections are:
+
+=over
+
+=item C<tapetype>
+
+with constants beginning with C<$TAPETYPE_>
+
+=item C<dumptype>
+
+with constants beginning with C<$DUMPTYPE_>
+
+=item C<interface>
+
+with constants beginning with C<$INTER_>
+
+=item C<holdingdisk>
+
+with constants beginning with C<$HOLDING_>
+
+=item C<application>
+
+with constants beginning with C<$APPLICATION_>
+
+=item C<script>
+
+with constants beginning with C<$PP_SCRIPT_>
+
+=item C<device>
+
+with constants beginning with C<$DEVICE_CONFIG_>.
+
+=item C<changer>
+
+with constants beginning with C<$CHANGER_CONFIG_>.
+
+=back
+
+See C<conffile.h> for the names of the constants themselves.
+
+=head2 DATA FORMATS
+
+Each configuration parameter has a "conftype", as assigned in
+C<common-src/conffile.c>. The translation of most of these types into Perl
+values is straightforward:
+
+ CONFTYPE_INT Math::BigInt
+ CONFTYPE_INT64 Math::BigInt
+ CONFTYPE_REAL floating-point value
+ CONFTYPE_STR string
+ CONFTYPE_IDENT string
+ CONFTYPE_TIME Math::BigInt (epoch value)
+ CONFTYPE_SIZE Math::BigInt
+ CONFTYPE_BOOLEAN Math::BigInt
+ CONFTYPE_COMPRESS Math::BigInt
+ CONFTYPE_ENCRYPT Math::BigInt
+ CONFTYPE_HOLDING Math::BigInt
+ CONFTYPE_ESTIMATELIST [ Math::BigInt, .. ]
+ CONFTYPE_STRATEGY Math::BigInt
+ CONFTYPE_TAPERALGO Math::BigInt
+ CONFTYPE_PRIORITY Math::BigInt
+ CONFTYPE_RATE float, float
+ CONFTYPE_INTRANGE Math::BigInt, Math::BigInt
+ CONFTYPE_APPLICATION string
+ CONFTYPE_EXECUTE_ON string
+ CONFTYPE_EXECUTE_WHERE Math::BigInt
+ CONFTYPE_SEND_AMREPORT_ON Math::BigInt
+ CONFTYPE_IDENTLIST [ string, .. ]
+ CONFTYPE_PART_CACHE_TYPE Math::BigInt
+ CONFTYPE_RECOVERY_LIMIT [ string, .. ] (undef if not specified;
+ undef in the list means same-host)
+
+Note that C<CONFTYPE_INTRANGE> and C<CONFTYPE_RATE> each return two values, not
+an array reference.
+
+Include and exclude lists with type C<CONFTYPE_EXINCLUDE> return a hash giving
+all listed filenames (in the C<list> key), include/exclude files (C<files>),
+and a boolean indicating that the list is optional (C<optional>):
+
+ { list => [ str, .. ], file => [ str, .. ], optional => Math::BigInt }
+
+Properties are represented as a hash of hashes. The keys are the property
+names, converted to ASCII lowercase. Each property has a C<values> array
+giving all values specified for this property, as well as booleans C<priority>
+and C<append> that are true if the corresponding keyword was supplied.
+
+ { prop1 => { values => [ str, .. ] priority => int, append => int },
+ prop2 => { .. } .. }
+
+Note that integer types of all sizes become C<Math::BigInt> objects rather than
+Perl integers, as is the habit throughout Amanda.
+
+The C<CNF_AUTOLABEL> value is a hash with the following keys
+
+ template label template, or undef
+ other_config boolean
+ non_amanda boolean
+ volume_error boolean
+ empty boolean
+
+=head2 OTHER ACCESS
+
+Parameter values are available by name from C<getconf_byname($name)> and
+C<getconf_byname_strs($name, $str_needs_quotes)>. These functions implement
+the C<TYP:NAME:PARAM> syntax advertised by C<amgetconf> to access values in
+subsections. The first function returns a Perl value (see DATA FORMATS,
+above), while the second returns a list of strings suitable for use in
+C<amanda.conf>, including quotes around strings if C<$str_needs_quotes> is
+true.
+
+C<getconf_list($typ)> returns a list of the names of all subsections of the
+given type. C<%subsection_names> is a hash whose keys are allowed subsection
+names.
+
+=head2 DERIVED VALUES
+
+The C<$CNF_DISPLAYUNIT> implies a certain divisor to convert from
+kilobytes to the desired unit. This divisor is available from
+C<getconf_unit_divisor()>. Note carefully that it is a I<divisor>
+for a value in I<kilobytes>!
+
+Finally, various subsections of Amanda enable verbose debugging via
+configuration parameters. The status of each parameter is available
+a similarly-named variable, e.g., C<$debug_auth>.
+
+All parameter access functions and constants can be imported with
+the tag C<:getconf>.
+
+=head1 MISCELLANEOUS
+
+These functions defy categorization.
+
+The function C<config_dir_relative> will interpret a path relative to
+the current configuration directory. Absolute paths are passed through
+unchanged, while relative paths are converted to absolute paths.
+
+C<dump_configuration()> dumps the current configuration, in a format
+suitable for re-evaluation for this module, to standard output.
+This function may be revised to return a string.
+
+Several parts of Amanda need to convert unit modifier value like
+"gbytes" to a multiplier. The function C<find_multiplier($str)>
+returns the unit multiplier for such a string. For example, "mbytes"
+is converted to 1048576 (1024*1024).
+
+C<string_to_boolean()> takes a string and returns 0 if it matches any of
+Amanda's names for false, or 1 if matches a name for true. If it can't be
+interpreted, C<undef> is returned.
+
+C<amandaify_property_name()> converts a string into Amanda's property style:
+all lower-case and with "-" replacing "_".
+
+=head1 CONSTANTS
+
+This section lists all of the configuration parameter constants defined in this
+module. All of these constants are available with the C<:getconf> export tag.
+
+=cut
+
+%}
projects / debian / amanda / blobdiff