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