Amanda::Config - access to Amanda configuration parameters
use Amanda::Config qw( :init :getconf );
config_init($CONFIG_INIT_EXPLICIT_NAME, $ARGV[1]) or die("errors processing config file " . $Amanda::Config::get_config_filename());
print "tape device is ", getconf($CNF_TAPEDEV), "\n";
This API closely parallels the C API. See conffile.h for details on the functions and constants available here.
Stable
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
:init
.
The Amanda configuration is loaded with the aptly named
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.
CONFIG_INIT_EXPLICIT_NAME
is given, then the $name
parameter can contain the name of a configuration to load.
CONFIG_INIT_USE_CWD
is given, and if the current directory
contains amanda.conf
, then that file is loaded.
CONFIG_INIT_CLIENT
is given, then a client configuration
is loaded.
CONFIG_INIT_OVERLAY
is given, then any existing
configuration is not reset.
See conffile.h
for more detailed information on these flags and
their interactions.
config_uninit()
reverses the effects of config_init
. It is
not often used.
Once the configuration is loaded, the configuration name
(e.g., ``DailySet1''), directory (/etc/amanda/DailySet1
),
and filename (/etc/amanda/DailySet1/amanda.conf
) are
available from get_config_name()
, get_config_dir()
, and
get_config_filename()
, respectively.
This module collects configuration errors and warnings in a list, and also
tracks the overall error level with an enumeration: $CFGERR_OK
,
$CFGERR_WARNINGS
, and $CFGERR_ERRORS
. config_init
and
apply_config_overwrites
both return the current level. The level and the
list of error messages are available from config_errors
:
my ($cfgerr_level, @errors) = Amanda::Configconfig_errors();
As a convenience, config_print_errors
will print all error messages to
stderr. The error state can be cleared with config_clear_errors
.
Most Amanda applications accept the command-line option -o
to ``overwrite'' configuration values in amanda.conf
. In Perl
applications, these options should be parsed with Getopt::Long, with
the action being a call to add_config_overwrite_opt
. For example:
my $config_overwrites = new_config_overwrites($#ARGV+1); GetOptions( # ... 'o=s' => sub { add_config_overwrite_opt($config_overwrites, $_[1]); }, ) or usage(); my $cfg_ok = config_init($CONFIG_INIT_EXPLICIT_NAME | $CONFIG_INIT_USE_CWD, $config_name); apply_config_overwrites($config_overwrites);
new_config_overwrites($size_estimate)
creates a new
overwrites object, using the given size as an estimate of
the number of items it will contain ($#ARGC/2
is a good
estimate). Individual configuration options are then added via
add_config_overwrite($co, $key, $value)
(which takes a key/value
pair) or add_config_overwrite_opt($co, $optarg)
, which parses a
string following -o
on the command line.
Once the overwrites are gathered, they are applied with
apply_config_overwrites($co)
, which applies the overwrites to the
active configuration. No further operations can be performed on the
overwrites object after apply_config_overwrites
has been called.
The utility function 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)
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 $CNF_
, e.g., $CNF_LABELSTR
. The function getconf($cnf)
returns the value of parameter $cnf
, in whatever format is
appropriate for the parameter. getconf_seen($cnf)
returns a true
value if $cnf
was seen in the configuration file. If it was not
seen, then it will have its default value.
Some parameters have enumerated types. The values for those
enumerations are available from this module with the same name as
in conffile.h
. For example, $CNF_TAPERALGO
will yield a value
from the enumeration taperalgo_t
, the constants for which all
begin with $ALGO_
. See conffile.h
for the details.
Each subsection type has the following functions:
lookup_TYP($subsec_name)
which returns an opaque object
($ss
) representing the subsection, or undef
if no subsection
with that name exists;
TYP_name($ss)
returning the name of the subsection;
TYP_getconf($ss, $cnf)
which fetches a parameter value from $ss
; and
TYP_seen($ss, $cnf)
which returns a true value if <$cnf> was seen in the subsection.
The subsections are:
tapetype
with constants beginning with $TAPETYPE_
dumptype
with constants beginning with $DUMPTYPE_
interface
with constants beginning with $INTER_
holdingdisk
with constants beginning with $HOLDING_
application
with constants beginning with $APPLICATION_
script
with constants beginning with $PP_SCRIPT_
device
with constants beginning with $DEVICE_CONFIG_
.
changer
with constants beginning with $CHANGER_CONFIG_
.
See conffile.h
for the names of the constants themselves.
Parameter values are available by name from getconf_byname($name)
and
getconf_byname_strs($name, $str_needs_quotes)
. These functions implement
the TYP:NAME:PARAM
syntax advertised by amgetconf
to access values in
subsections. The first function returns a perl value, while the second returns
a string suitable for use in amanda.conf
, including quotes around strings if
$str_needs_quotes
is true.
getconf_list($typ)
returns a list of the names of all subsections of the
given type. %subsection_names
is a hash whose keys are allowed subsection
names.
The $CNF_DISPLAYUNIT
implies a certain divisor to convert from
kilobytes to the desired unit. This divisor is available from
getconf_unit_divisor()
. Note carefully that it is a divisor
for a value in 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., $debug_auth
.
All parameter access functions and constants can be imported with
the tag :getconf
.
These functions defy categorization.
The function 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.
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 find_multiplier($str)
returns the unit multiplier for such a string. For example, ``mbytes''
is converted to 1048576 (1024*1024).
This page was automatically generated Fri Feb 5 19:41:21 2010 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.