3.3.1

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

Amanda::Config


NAME

Amanda::Config - access to Amanda configuration parameters


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.


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 :init.

LOADING CONFIGURATION

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.

CONFIG ERRORS

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.

CONFIG OVERWRITES

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)


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 $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:

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.

DATA FORMATS

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

OTHER ACCESS

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.

DERIVED VALUES

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.


MISCELLANEOUS

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 "_".


CONSTANTS

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


ABOUT THIS PAGE

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.


3.3.1