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. The model is that a disk belongs to exactly one host, and that host may be shared with other disks. Each host is connected via exactly one interface, and that interface may be shared with other disks independently of the disks' hosts.

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), or multiple interfaces for the same host. The results are undefined.

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, creates a heavily interlinked set of disk_t objects, amhost_t objects, and netif_t objects, all linked into disklist_t doubly-linked lists. The objects contain the most frequently-used configuration parameters as member variables, Memory-management for movement between lists is a tricky, undocumented dance. Caveat Coder.

In Perl, the three object types are separated, and Interface and Disk objects just point to the relevant objects from Amanda::Config. See Amanda::Disklist for details.

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 and/or client_keytab
• Add an entry in server_var and/or client_var
• Change init_defaults(): Set default value for the option
• Add the relevant symbols to perl/Amanda/Config.swg
• User should use the correct getconf_* function according to the data type given in server_var

How to add a subsection 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

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