Configuration API: Difference between revisions

From wiki.zmanda.com
Jump to navigation Jump to search
m (Reading amanda configuration moved to Configuration API: What's one more API, anyway?)
(partial)
Line 1: Line 1:
This section describes how Amanda reads configuration files.  
<div style="float: right">__TOC__</div>
{{XXX|Dustin|Needs to be updated to include perl, new C interface}}
= Introduction =
==Data Structures==
Amanda gets its configuration from a number of configuration files - {{man|5|amanda.conf}}, {{man|5|amanda-client.conf}} and {{man|5|disklist}}.  This page describes the interface used to load this configuration.


===common/util.h===
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.
; conftype_t : all possible types of config options.
; tok_t : tokens
; keytab_t : string to tok_t conversion.
; command_option_t : data structure to keep -o command line argument.
; val_t : Store the value of a configuration option. It has following fields:
**v  : value
**seen : If the value was seen on a config file
**type : the type of the value
; t_conf_var : structure for all configuration options with following fields:
** token : the internal token use.
** type : the type of the value
** read_function : the function to read that value
** parm : confparm_t, tapetype_ee, dumptype_ee, interface_ee or holdingdisk_ee
** validate : a function to validate the value


===server-src/conffile.h===
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 <tt>amanda.conf</tt>.  It is ''not'' possible to load more than one configuration simultaneously using this API.
; confparm_t : global option
; tapetype_ee, dumptype_ee, interface_ee,holdingdisk_ee : tapetype/dumptype/interface/holding options
; tapetype_t, dumptype_t, interface_t, holdingdisk_t: Data structures with following fields:
**seen:
**name: name of the option
**value: all value of that tapetype/dumptype/interface


There are lot of macros tapetype_*, dumptype_*, interface_*, holdingdisk_* to retrieve configuration values.
= Model =
The Amanda configuration's model is quirky, at best.


To retrieve global value,  use one of these functions: getconf_int, getconf_long, getconf_size, getconf_time, getconf_am64, getconf_real, getconf_str.
== 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


===server-src/conffile.c===
   define dumptype mydumptype {
; server_keytab : Keytab for the server configuration
    program "APPLICATION"
; server_var   : Array describing global server options
    compress client best
; holding_var  : Array describing holdingdisk options
  }
; dumptype_var : Array describing dumptype options
; tapetype_var : Array describing tapetype options
; interface_var : Array describing interface options


= Accessing Configuration =
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 <tt>holdingdisk</tt> subsection type is unique in that the <tt>define</tt> keyword can be omitted, with the effect of immediately using the defined holding disk.  Next, {{man|5|disklist}} entries can specify a dumptype inline, e.g.,
Accessing configuration values from Amanda applications is straightforward.  Global configuration options are accessed with ''getconf_xxx'' (depending on type):
  darth-vader.amanda.org /deathstar/php {
conf_tapetype = getconf_str(CNF_TAPETYPE);
    tar-best
run_tapes = getconf_int(CNF_RUNTAPES);
    record no
Note that ''getconf_str()'' returns a pointer to a string in the configuration data structures -- '''do not''' free the result!
  }
This implicitly defines a dumptype (with an automatically-generated name) and links that dumptype to the <tt>darth-vader.amanda.org:/deathstar/php</tt> DLE.  Similarly, the <tt>application</tt> parameter can either name a previously-defined application, or can specify one inline, resulting in a new application with an automatically-generated name.


To access one of the named configuration sections (dumptypes, holding disks, etc.), first look up the object you want:
Parsing issues such as case-sensitivity, quoting, and confusion between "_" and "-" are all surprisingly complex, and are described in {{man|5|amanda.conf}}.
tape = lookup_tapetype(getconf_str(CNF_TAPETYPE));
 
then use one of the macros for that object to get the actual value:
== Disklist ==
tt_blocksize_kb = (size_t)tapetype_get_blocksize(tape);
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., <tt>amandad_path</tt>).  The results are undefined.
See {{file|conffile.h}} for the full list of such macros.
 
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 <tt>common-src/conffile.c</tt> and defined in <tt>common-src/conffile.h</tt>.  {{pod|Amanda::Config}}, provides convenient full access to the implementation from Perl.  See <tt>conffile.h</tt> for a full description of the C interface and for the list of all available configuration parameters.  See {{pod|Amanda::Config}} for details on the perl interface.
 
The C and Perl disklist interfaces differ markedly.  The C interface, defined in <tt>server-src/diskfile.c</tt>,


= Adding New Options =
= Adding New Options =

Revision as of 16:42, 11 May 2009

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.
Retrieved from ‘http://wiki.zmanda.com/index.php?title=Configuration_API&oldid=6892’