Configuration API

Introduction

Amanda gets its configuration from a number of configuration files - amanda.conf(5), amanda-client.conf(5) and disklist(5). This page describes the interface used to load this configuration.

Because all Amanda does not have a long-running daemon, and each Amanda application only runs for a limited time, the configuration API makes heavy use of global variables. The configuration is "loaded" at application initialization, and the resulting values are globablly available for the remainder of the application's lifetime.

Most Amanda applications take a "config name" (also variously described as a "backup set" or just "config"). This specifies a particular collection of configuration information, beginning with an amanda.conf. It is not possible to load more than one configuration simultaneously using this API.

Model

The Amanda configuration's model is quirky, at best.

amanda.conf and amanda-client.conf

There are nearly 100 "global" parameters which are specified at the top level. In addition, several types of named subsections are available. These define a named group of configuration values for later reference. For example, this subsection

 define dumptype mydumptype {
   program "APPLICATION"
   compress client best
 }

defines a new group of configuration values of type "dumptype", named "mydumptype". For the most part, an unused definition is harmless. There are a few shortcuts which define and use a group of parameters simultaneously. First, the holdingdisk subsection type is unique in that the define keyword can be omitted, with the effect of immediately using the defined holding disk. Next, disklist(5) entries can specify a dumptype inline, e.g.,

 darth-vader.amanda.org /deathstar/php {
   tar-best
   record no
 }

This implicitly defines a dumptype (with an automatically-generated name) and links that dumptype to the darth-vader.amanda.org:/deathstar/php DLE. Similarly, the application parameter can either name a previously-defined application, or can specify one inline, resulting in a new application with an automatically-generated name.

Parsing issues such as case-sensitivity, quoting, and confusion between "_" and "-" are all surprisingly complex, and are described in amanda.conf(5).

Disklist

The disklist serves to tie together disks, hosts, and interfaces. Because both host and disk parameters are specified in dumptype definitions, it is possible to write a configuration which specifies multiple values for a host-specific parameter (e.g., amandad_path). The results are undefined.

The model is that a disk belongs to exactly one host, and that host may be shared with other disks. Each disk also has a single interface, and that interface may be shared with other disks independently of the disks' hosts.

Implementation

The configuration API is implemented in common-src/conffile.c and defined in common-src/conffile.h. Amanda::Config, provides convenient full access to the implementation from Perl. See conffile.h for a full description of the C interface and for the list of all available configuration parameters. See Amanda::Config for details on the perl interface.

The C and Perl disklist interfaces differ markedly. The C interface, defined in server-src/diskfile.c,

Adding New Options

How to add a new global option

• Add a token in tok_t (CONF_*)
• Add a token in confparm_t (CNF_*)
• Add an entry in server_keytab
• Add an entry in server_var
• Change init_defaults(): Set default value for the option
• User should use the correct getconf_* function according to the data type given in server_var

How to add a dumptype option

• Add a token in tok_t (CONF_*)
• Add a token in dumptype_ee (DUMPTYPE_*)
• Add a macro to retrive the value (dumptype_get_*)
• Add an entry in server_keytab
• Add an entry in dumptype_var
• Change init_dumptype_defaults(): Set default value.
• The dumptype_get_* macro should return the correct field according to the type defined in dumptype_var

Adding a tapetype, holdingdisk or interface option is done similar to adding a dumptype option.

• For a dumptype, the value must also be copied to the disk_t structure.
  • Add a NEWVAR field in the disk_t struct with the type.
  • In diskfile.c(parse_diskline) you must add the following line:

   disk->NEWVAR = dumptype_get_NEWVAR(dtype);

You can then use disk->NEWVAR as you like.