Merge branch 'master' into squeeze
[debian/amanda] / perl / Amanda / Disklist.pod
diff --git a/perl/Amanda/Disklist.pod b/perl/Amanda/Disklist.pod
new file mode 100644 (file)
index 0000000..230c2cb
--- /dev/null
@@ -0,0 +1,184 @@
+/*
+ * Copyright (c) 2009 Zmanda, Inc.  All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 as published
+ * by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+ *
+ * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
+ * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
+ */
+
+%perlcode %{
+
+=head1 NAME
+
+Amanda::Disklist - interface to the Amanda disklist
+
+=head1 SYNOPSIS
+
+  use Amanda::Config qw( :init :getconf );
+  use Amanda::Disklist;
+
+  # .. call config_init()
+  my $cfgerr_level = Amanda::Disklist::read_disklist(
+    filename => $ARGV[0],
+    disk_class => "MyScript::Disk",
+  );
+  die("Config errors") if ($cfgerr_level >= $CFGERR_WARNINGS);
+  my $dle = Amanda::Disklist::get_disk($ARGV[1], $ARGV[2]);
+  die "No such DLE" unless defined($dle);
+
+  print "Diskname for this DLE: ", $dle->{name}, "\n";
+  print "Auth for this DLE's host: ", $dle->{host}->{auth}, "\n";
+  print "'record':", dumptype_getconf($dle->{config}, $DUMPTYPE_RECORD), "\n";
+
+=head1 OVERVIEW
+
+The Amanda disklist is a part of its configuration, so this module is
+similar in function to L<Amanda::Config>.  In particular,
+C<read_disklist> loads the disklist into process-global variables, and
+returns an error status similar to that of L<Amanda::Config>.  Those
+global variables are then used by the acces functions described below.
+
+Amanda parses all DLE's as a simple tuple (host, diskname, device,
+dumptype, interface, spindle), linked to a dumptype.  DLE's which
+specify additional dumptype parameters within the C<disklist> file
+result in the creation of a "hidden" dumptype with those parameters.
+Consequently, most configuration data about a particular disk is
+available in an C<Amanda::Config::dumptype_t> object, and that data is
+not reproduced by this package.
+
+This package differs from the underlying C code in that it separates
+I<disk> configuration from I<host> configuration.  Furthermore, the
+package does not provide storage for runtime parameters you might want
+to associate with hosts or disks.  However, the objects this packages
+creates are simple hashrefs that can be blessed with arbitrary class
+names, so you can add whatever data and behaviors you like to these
+objects.
+
+=head1 FUNCTIONS
+
+After calling C<Amanda::Config::config_init()>, call C<read_disklist>.
+The following parameters are available:
+
+=over 4
+
+=item filename
+
+Filename from which to read the disklist; defaults to the C<diskfile>
+configuration parameter.
+
+=item disk_class
+
+Class with which to bless disk objects; defaults to
+C<Amanda::Disklist::Disk>.
+
+=item host_class
+
+Class with which to bless host objects; defaults to
+C<Amanda::Disklist::Host>.
+
+=item interface_class
+
+Class with which to bless interface objects; defaults to
+C<Amanda::Disklist::Interface>.
+
+=back
+
+C<read_disklist> returns a config error level just like
+C<config_init>. Once the disklist is loaded, call one of the following
+functions to access the disklist.
+
+  get_host($host)          get the corresponding host object
+  all_hosts()              get a list of all host objects
+  get_disk($host, $disk)    get a specific disk object
+  all_disks()              get a list of all disk objects
+  get_interface($name)     get a specific interface object
+  all_interfaces()         get a list of all interface objects
+
+=head1 Objects
+
+=head2 Amanda::Disklist::Disk
+
+A disk object has the following keys:
+
+=over 4
+
+=item host
+
+Host object for this DLE
+
+=item name
+
+The disk name
+
+=item device
+
+The device, if one was specified separately from the disk name
+
+=item spindle
+
+The spindle specified in the disklist
+
+=item config
+
+An C<Amanda::Config::dumptype_t> object giving the configuration for
+the disk; use C<dumptype_getconf> and other functions from
+L<Amanda::Config> to examine it.
+
+=back
+
+=head2 Amanda::Disklist::Host
+
+Note that, because host configuration parameters are specified in
+dumptypes, there is no C<config> key for a host object.  Instead, the
+relevant parameters are available as attributes of the object.
+
+=over 4
+
+=item hostname
+
+hostname of this host
+
+=item amandad_path
+
+=item client_username
+
+=item ssh_keys
+
+=item auth
+
+=item maxdumps
+
+configuration parameters
+
+=item disks
+
+an array containing the names of all of the disks on this host.
+
+=back
+
+As a convenience, the C<Amanda::Disklist::Host> class also provides
+methods C<get_disk($disk)>, to get a disk object on the host, and
+C<all_disks()>, to get a list of all disk objects on this host.
+
+=head2 Amanda::Disklist::Interface
+
+Interface objects have only one key, C<config>, containing a
+C<Amanda::Config::interface_t> object; use C<interface_getconf> and
+other functions from L<Amanda::Config> to examine it.
+
+=cut
+
+
+%}