Amanda::Config modules list
Amanda modules list
List of All Modules
All Amanda Releases



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);
    my ($cfgerr_level, @cfgerr_errors) = config_errors();
    if ($cfgerr_level >= $CFGERR_WARNINGS) {
        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.

If 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.
If CONFIG_INIT_USE_CWD is given, and if the current directory contains amanda.conf, then that file is loaded.
If CONFIG_INIT_CLIENT is given, then a client configuration is loaded.
If 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);
        # ...
        '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);

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:


which returns an opaque object ($ss) representing the subsection, or undef if no subsection with that name exists;


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:


with constants beginning with $TAPETYPE_


with constants beginning with $DUMPTYPE_


with constants beginning with $INTER_


with constants beginning with $HOLDING_


with constants beginning with $APPLICATION_


with constants beginning with $PP_SCRIPT_


with constants beginning with $DEVICE_CONFIG_.


with 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.













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.