git.gag.com Git - debian/amanda/blob - perl/Amanda/Disklist.pod

   1 /*
   2  * Copyright (c) 2009-2012 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  11  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12  * for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  17  *
  18  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  19  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  20  */
  21
  22 %perlcode %{
  23
  24 =head1 NAME
  25
  26 Amanda::Disklist - interface to the Amanda disklist
  27
  28 =head1 SYNOPSIS
  29
  30   use Amanda::Config qw( :init :getconf );
  31   use Amanda::Disklist;
  32
  33   # .. call config_init()
  34   my $cfgerr_level = Amanda::Disklist::read_disklist(
  35     filename => $ARGV[0],
  36     disk_class => "MyScript::Disk",
  37   );
  38   die("Config errors") if ($cfgerr_level >= $CFGERR_WARNINGS);
  39   my $dle = Amanda::Disklist::get_disk($ARGV[1], $ARGV[2]);
  40   die "No such DLE" unless defined($dle);
  41
  42   print "Diskname for this DLE: ", $dle->{name}, "\n";
  43   print "Auth for this DLE's host: ", $dle->{host}->{auth}, "\n";
  44   print "'record':", dumptype_getconf($dle->{config}, $DUMPTYPE_RECORD), "\n";
  45
  46 =head1 OVERVIEW
  47
  48 The Amanda disklist is a part of its configuration, so this module is
  49 similar in function to L<Amanda::Config>.  In particular,
  50 C<read_disklist> loads the disklist into process-global variables, and
  51 returns an error status similar to that of L<Amanda::Config>.  Those
  52 global variables are then used by the acces functions described below.
  53
  54 Amanda parses all DLE's as a simple tuple (host, diskname, device,
  55 dumptype, interface, spindle), linked to a dumptype.  DLE's which
  56 specify additional dumptype parameters within the C<disklist> file
  57 result in the creation of a "hidden" dumptype with those parameters.
  58 Consequently, most configuration data about a particular disk is
  59 available in an C<Amanda::Config::dumptype_t> object, and that data is
  60 not reproduced by this package.
  61
  62 This package differs from the underlying C code in that it separates
  63 I<disk> configuration from I<host> configuration.  Furthermore, the
  64 package does not provide storage for runtime parameters you might want
  65 to associate with hosts or disks.  However, the objects this packages
  66 creates are simple hashrefs that can be blessed with arbitrary class
  67 names, so you can add whatever data and behaviors you like to these
  68 objects.
  69
  70 =head1 FUNCTIONS
  71
  72 After calling C<Amanda::Config::config_init()>, call C<read_disklist>.
  73 The following parameters are available:
  74
  75 =over 4
  76
  77 =item filename
  78
  79 Filename from which to read the disklist; defaults to the C<diskfile>
  80 configuration parameter.
  81
  82 =item disk_class
  83
  84 Class with which to bless disk objects; defaults to
  85 C<Amanda::Disklist::Disk>.
  86
  87 =item host_class
  88
  89 Class with which to bless host objects; defaults to
  90 C<Amanda::Disklist::Host>.
  91
  92 =item interface_class
  93
  94 Class with which to bless interface objects; defaults to
  95 C<Amanda::Disklist::Interface>.
  96
  97 =back
  98
  99 C<read_disklist> returns a config error level just like
 100 C<config_init>. Once the disklist is loaded, call one of the following
 101 functions to access the disklist.
 102
 103   get_host($host)           get the corresponding host object
 104   all_hosts()               get a list of all host objects
 105   get_disk($host, $disk)    get a specific disk object
 106   all_disks()               get a list of all disk objects
 107   get_interface($name)      get a specific interface object
 108   all_interfaces()          get a list of all interface objects
 109
 110 =head1 Objects
 111
 112 =head2 Amanda::Disklist::Disk
 113
 114 A disk object has the following keys:
 115
 116 =over 4
 117
 118 =item host
 119
 120 Host object for this DLE
 121
 122 =item name
 123
 124 The disk name
 125
 126 =item device
 127
 128 The device, if one was specified separately from the disk name
 129
 130 =item spindle
 131
 132 The spindle specified in the disklist
 133
 134 =item config
 135
 136 An C<Amanda::Config::dumptype_t> object giving the configuration for
 137 the disk; use C<dumptype_getconf> and other functions from
 138 L<Amanda::Config> to examine it.
 139
 140 =back
 141
 142 =head2 Amanda::Disklist::Host
 143
 144 Note that, because host configuration parameters are specified in
 145 dumptypes, there is no C<config> key for a host object.  Instead, the
 146 relevant parameters are available as attributes of the object.
 147
 148 =over 4
 149
 150 =item hostname
 151
 152 hostname of this host
 153
 154 =item amandad_path
 155
 156 =item client_username
 157
 158 =item ssh_keys
 159
 160 =item auth
 161
 162 =item maxdumps
 163
 164 configuration parameters
 165
 166 =item disks
 167
 168 an array containing the names of all of the disks on this host.
 169
 170 =back
 171
 172 As a convenience, the C<Amanda::Disklist::Host> class also provides
 173 methods C<get_disk($disk)>, to get a disk object on the host, and
 174 C<all_disks()>, to get a list of all disk objects on this host.
 175
 176 =head2 Amanda::Disklist::Interface
 177
 178 Interface objects have only one key, C<config>, containing a
 179 C<Amanda::Config::interface_t> object; use C<interface_getconf> and
 180 other functions from L<Amanda::Config> to examine it.
 181
 182 =cut
 183
 184
 185 %}