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:
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.
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
$CNF_TMPDIR
$CNF_REPORT_USE_MEDIA
$CNF_REPORT_NEXT_MEDIA
$CNF_REPORT_FORMAT
$CNF_STORAGE
$CNF_VAULT_STORAGE
$CNF_CMDFILE
$CNF_REST_API_PORT
$CNF_REST_SSL_CERT
$CNF_REST_SSL_KEY
$CNF_COMPRESS_INDEX
$CNF_SORT_INDEX
$CNF_SSL_DIR
$CNF_SSL_CHECK_FINGERPRINT
$CNF_SSL_CERT_FILE
$CNF_SSL_KEY_FILE
$CNF_SSL_CA_CERT_FILE
$CNF_SSL_CIPHER_LIST
$CNF_SSL_CHECK_HOST
$CNF_SSL_CHECK_CERTIFICATE_HOST
$CNF_HOSTNAME
$CNF_CATALOG
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_MAX_WARNINGS
$DUMPTYPE_RECOVERY_LIMIT
$DUMPTYPE_DUMP_LIMIT
$DUMPTYPE_RETRY_DUMP
$DUMPTYPE_TAG
Interface 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
Policy Parameters: $POLICY_COMMENT
$POLICY_RETENTION_TAPES
$POLICY_RETENTION_DAYS
$POLICY_RETENTION_RECOVER
$POLICY_RETENTION_FULL
Storage Parameters: $STORAGE_COMMENT
$STORAGE_TAPEDEV
$STORAGE_TPCHANGER
$STORAGE_POLICY
$STORAGE_LABELSTR
$STORAGE_AUTOLABEL
$STORAGE_META_AUTOLABEL
$STORAGE_TAPEPOOL
$STORAGE_RUNTAPES
$STORAGE_TAPERSCAN
$STORAGE_TAPETYPE
$STORAGE_MAX_DLE_BY_VOLUME
$STORAGE_TAPERALGO
$STORAGE_TAPER_PARALLEL_WRITE
$STORAGE_EJECT_VOLUME
$STORAGE_ERASE_VOLUME
$STORAGE_DEVICE_OUTPUT_BUFFER_SIZE
$STORAGE_AUTOFLUSH
$STORAGE_FLUSH_THRESHOLD_DUMPED
$STORAGE_FLUSH_THRESHOLD_SCHEDULED
$STORAGE_TAPERFLUSH
$STORAGE_REPORT_USE_MEDIA
$STORAGE_REPORT_NEXT_MEDIA
$STORAGE_INTERACTIVITY
$STORAGE_SET_NO_REUSE
$STORAGE_DUMP_SELECTION
$STORAGE_ERASE_ON_FAILURE
$STORAGE_ERASE_ON_FULL
Catalog Parameters: $CATALOG_COMMENT
$CATALOG_PLUGIN
$CATALOG_PROPERTY
This page was automatically generated Tue Mar 19 07:08:15 2019 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.