Amanda::Config - access to Amanda configuration parameters
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.
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. Note that if the parameter is
".", this is equivalent to CONFIG_INIT_USE_CWD.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_overrides both return the current level. The level and the
list of error messages are available from config_errors:
my ($cfgerr_level, @errors) = Amanda::Config::config_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_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);
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 ($#ARGC/2 is a good
estimate). Individual configuration options are then added via
add_config_override($co, $key, $value) (which takes a key/value
pair) or add_config_override_opt($co, $optarg), which parses a
string following -o on the command line.
Once the overwrites are gathered, they are applied with
apply_config_overrides($co), which applies the overwrites to the
active configuration. No further operations can be performed on the
overwrites object after apply_config_overrides 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
(see DATA FORMATS, below). 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. 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 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 TYP 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:
tapetypewith constants beginning with $TAPETYPE_
dumptypewith constants beginning with $DUMPTYPE_
interfacewith constants beginning with $INTER_
holdingdiskwith constants beginning with $HOLDING_
applicationwith constants beginning with $APPLICATION_
scriptwith constants beginning with $PP_SCRIPT_
devicewith constants beginning with $DEVICE_CONFIG_.
changerwith constants beginning with $CHANGER_CONFIG_.
See conffile.h for the names of the constants themselves.
Each configuration parameter has a "conftype", as assigned in
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 CONFTYPE_INTRANGE and CONFTYPE_RATE each return two values, not
an array reference.
Include and exclude lists with type CONFTYPE_EXINCLUDE return a hash giving
all listed filenames (in the list key), include/exclude files (files),
and a boolean indicating that the list is optional (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 values array
giving all values specified for this property, as well as booleans priority
and 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 Math::BigInt objects rather than
Perl integers, as is the habit throughout Amanda.
The 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
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 (see DATA FORMATS,
above), while the second returns a list of strings 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).
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, undef is returned.
amandaify_property_name() converts a string into Amanda's property style:
all lower-case and with "-" replacing "_".
This section lists all of the configuration parameter constants defined in this
module. All of these constants are available with the :getconf export tag.
Global Parameters: $CNF_ORG $CNF_CONF $CNF_AMDUMP_SERVER $CNF_INDEX_SERVER $CNF_TAPE_SERVER $CNF_AUTH $CNF_SSH_KEYS $CNF_AMANDAD_PATH $CNF_CLIENT_USERNAME $CNF_CLIENT_PORT $CNF_GNUTAR_LIST_DIR $CNF_AMANDATES $CNF_MAILER $CNF_MAILTO $CNF_DUMPUSER $CNF_TAPEDEV $CNF_DEVICE_PROPERTY $CNF_PROPERTY $CNF_CHANGERDEV $CNF_CHANGERFILE $CNF_LABELSTR $CNF_AUTOLABEL $CNF_META_AUTOLABEL $CNF_TAPELIST $CNF_DISKFILE $CNF_INFOFILE $CNF_LOGDIR $CNF_INDEXDIR $CNF_TAPETYPE $CNF_DUMPCYCLE $CNF_RUNSPERCYCLE $CNF_TAPECYCLE $CNF_NETUSAGE $CNF_INPARALLEL $CNF_DUMPORDER $CNF_BUMPPERCENT $CNF_BUMPSIZE $CNF_BUMPMULT $CNF_BUMPDAYS $CNF_TPCHANGER $CNF_RUNTAPES $CNF_MAX_DLE_BY_VOLUME $CNF_MAXDUMPS $CNF_ETIMEOUT $CNF_DTIMEOUT $CNF_CTIMEOUT $CNF_DEVICE_OUTPUT_BUFFER_SIZE $CNF_PRINTER $CNF_AUTOFLUSH $CNF_RESERVE $CNF_MAXDUMPSIZE $CNF_COLUMNSPEC $CNF_AMRECOVER_DO_FSF $CNF_AMRECOVER_CHECK_LABEL $CNF_AMRECOVER_CHANGER $CNF_TAPERALGO $CNF_FLUSH_THRESHOLD_DUMPED $CNF_FLUSH_THRESHOLD_SCHEDULED $CNF_TAPERFLUSH $CNF_DISPLAYUNIT $CNF_KRB5KEYTAB $CNF_KRB5PRINCIPAL $CNF_LABEL_NEW_TAPES $CNF_USETIMESTAMPS $CNF_REP_TRIES $CNF_CONNECT_TRIES $CNF_REQ_TRIES $CNF_DEBUG_AMANDAD $CNF_DEBUG_RECOVERY $CNF_DEBUG_AMIDXTAPED $CNF_DEBUG_AMINDEXD $CNF_DEBUG_AMRECOVER $CNF_DEBUG_AUTH $CNF_DEBUG_EVENT $CNF_DEBUG_HOLDING $CNF_DEBUG_PROTOCOL $CNF_DEBUG_PLANNER $CNF_DEBUG_DRIVER $CNF_DEBUG_DUMPER $CNF_DEBUG_CHUNKER $CNF_DEBUG_TAPER $CNF_DEBUG_SELFCHECK $CNF_DEBUG_SENDSIZE $CNF_DEBUG_SENDBACKUP $CNF_RESERVED_UDP_PORT $CNF_RESERVED_TCP_PORT $CNF_UNRESERVED_TCP_PORT $CNF_HOLDINGDISK $CNF_SEND_AMREPORT_ON $CNF_TAPER_PARALLEL_WRITE $CNF_RECOVERY_LIMIT $CNF_INTERACTIVITY $CNF_TAPERSCAN $CNF_EJECT_VOLUME
Tapetype Parameters: $TAPETYPE_COMMENT $TAPETYPE_LBL_TEMPL $TAPETYPE_BLOCKSIZE $TAPETYPE_READBLOCKSIZE $TAPETYPE_LENGTH $TAPETYPE_FILEMARK $TAPETYPE_SPEED $TAPETYPE_PART_SIZE $TAPETYPE_PART_CACHE_TYPE $TAPETYPE_PART_CACHE_DIR $TAPETYPE_PART_CACHE_MAX_SIZE
Dumptype Parameters: $DUMPTYPE_COMMENT $DUMPTYPE_PROGRAM $DUMPTYPE_SRVCOMPPROG $DUMPTYPE_CLNTCOMPPROG $DUMPTYPE_SRV_ENCRYPT $DUMPTYPE_CLNT_ENCRYPT $DUMPTYPE_AMANDAD_PATH $DUMPTYPE_CLIENT_USERNAME $DUMPTYPE_CLIENT_PORT $DUMPTYPE_SSH_KEYS $DUMPTYPE_AUTH $DUMPTYPE_EXCLUDE $DUMPTYPE_INCLUDE $DUMPTYPE_PRIORITY $DUMPTYPE_DUMPCYCLE $DUMPTYPE_MAXDUMPS $DUMPTYPE_MAXPROMOTEDAY $DUMPTYPE_BUMPPERCENT $DUMPTYPE_BUMPSIZE $DUMPTYPE_BUMPDAYS $DUMPTYPE_BUMPMULT $DUMPTYPE_STARTTIME $DUMPTYPE_STRATEGY $DUMPTYPE_ESTIMATELIST $DUMPTYPE_COMPRESS $DUMPTYPE_ENCRYPT $DUMPTYPE_SRV_DECRYPT_OPT $DUMPTYPE_CLNT_DECRYPT_OPT $DUMPTYPE_COMPRATE $DUMPTYPE_TAPE_SPLITSIZE $DUMPTYPE_FALLBACK_SPLITSIZE $DUMPTYPE_SPLIT_DISKBUFFER $DUMPTYPE_RECORD $DUMPTYPE_SKIP_INCR $DUMPTYPE_SKIP_FULL $DUMPTYPE_HOLDINGDISK $DUMPTYPE_KENCRYPT $DUMPTYPE_IGNORE $DUMPTYPE_INDEX $DUMPTYPE_APPLICATION $DUMPTYPE_SCRIPTLIST $DUMPTYPE_PROPERTY $DUMPTYPE_DATA_PATH $DUMPTYPE_ALLOW_SPLIT $DUMPTYPE_RECOVERY_LIMIT $DUMPTYPE_DUMP_LIMIT
Dumptype Parameters: $INTER_COMMENT $INTER_MAXUSAGE
Holdingdisk Parameters: $HOLDING_COMMENT $HOLDING_DISKDIR $HOLDING_DISKSIZE $HOLDING_CHUNKSIZE
Application Parameters: $APPLICATION_COMMENT $APPLICATION_PLUGIN $APPLICATION_PROPERTY $APPLICATION_CLIENT_NAME
Pre/Post-Script Parameters: $PP_SCRIPT_COMMENT $PP_SCRIPT_PLUGIN $PP_SCRIPT_PROPERTY $PP_SCRIPT_EXECUTE_ON $PP_SCRIPT_EXECUTE_WHERE $PP_SCRIPT_ORDER $PP_SCRIPT_SINGLE_EXECUTION $PP_SCRIPT_CLIENT_NAME
Pre/Post-Script Parameters: $DEVICE_CONFIG_COMMENT $DEVICE_CONFIG_TAPEDEV $DEVICE_CONFIG_DEVICE_PROPERTY
Pre/Post-Script Parameters: $CHANGER_CONFIG_COMMENT $CHANGER_CONFIG_TAPEDEV $CHANGER_CONFIG_TPCHANGER $CHANGER_CONFIG_CHANGERDEV $CHANGER_CONFIG_CHANGERFILE $CHANGER_CONFIG_PROPERTY $CHANGER_CONFIG_DEVICE_PROPERTY
Interactivity Parameters: $INTERACTIVITY_COMMENT $INTERACTIVITY_PLUGIN $INTERACTIVITY_PROPERTY
Taperscan Parameters: $TAPERSCAN_COMMENT $TAPERSCAN_PLUGIN $TAPERSCAN_PROPERTY
This page was automatically generated Tue Feb 21 19:14:01 2012 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.