git.gag.com Git - debian/amanda/blob - perl/Amanda/NDMP.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::NDMP - communicate via NDMP
  27
  28 =head1 SYNOPSIS
  29
  30   use Amanda::NDMP qw( :constants );
  31
  32   my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
  33                                                $password, $auth);
  34   my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
  35
  36 =head1 DESCRIPTION
  37
  38 This package interfaces with the C class C<NDMPConnection> class declared in
  39 C<ndmp-src/ndmpconnobj.h>.  It is only available in builds that did not specify
  40 C<--without-ndmp>.  The C class, in turn, interfaces to the XDR code provided
  41 by NDMJOB, which sends and receives NDMP messages on a TCP socket.
  42
  43 =head2 Constructor
  44
  45   my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
  46                                                $password, $auth);
  47   if ($conn->err_code()) {
  48     # handle error..
  49   }
  50
  51 This gets a new connection object.  This will always return an object, but the
  52 result should be checked for errors as described in the "Error Handling"
  53 section, below.
  54
  55 The C<$host> and C<$port> give the NDMP server's host and port, respectively.
  56 The C<$auth> parameter defines the authentication mechanism to use: "md5" or
  57 "text"; "none" for no authentication; or "void" to not send any authentication
  58 packets at all.  For md5 or text modes, C<$username> and C<$password> specify
  59 the username and password for the NDMP server; these parameters must always be
  60 included, but can be blank for none or void.
  61
  62 The C<$ident> parameter deserves some explanation.  NDMP scopes many
  63 server-side variables to the NDMP connection - for example, the "current" tape
  64 and taper state are associated with the NDMP connection.  To facilitate this,
  65 the constructor returns the I<same connection> for any constructor invocation
  66 with the same host, port, and identifier.  In cases where multiple connections
  67 are required (e.g., when two tapes are in use simultaneously), callers should
  68 provide different identifiers for each connection.
  69
  70 =head2 Methods
  71
  72 Note that not all NDMPConnection methods are available.  All of these methods
  73 block until the appropriate reply is received.  The underlying C class provides
  74 appropriate locking fundamentals to prevent corrupted on-the-wire messages.
  75
  76 All methods return a boolean "ok" status, with false indicating an error.
  77
  78 =head3 Error Handling
  79
  80   my $code = $conn->err_code();
  81   my $msg = $conn->err_msg();
  82
  83 Get the error code and message from the last method that returned false, or
  84 after the constructor is invoked.
  85
  86   $conn->set_verbose(1);
  87
  88 This method will enable verbose logging of the NDMP transactions to the Amanda
  89 debug logs.
  90
  91 =head3 SCSI Interface
  92
  93   my $ok = $conn->scsi_open($device);       # NDMP_SCSI_OPEN
  94   my $ok = $conn->scsi_close();             # NDMP_SCSI_CLOSE
  95   # NDMP_SCSI_EXECUTE_CDB
  96   my $res = $conn->scsi_execute_cdb(
  97     flags => $flags,
  98     timeout => $timeout,
  99     cdb => $cdb,
 100     datain_len => $datain_len,      # only if $flags == $NDMP9_SCSI_DATA_DIR_IN
 101     dataout => $dataout             # only if $flags == $NDMP9_SCSI_DATA_DIR_OUT
 102   )
 103
 104 The first two methods are clear; the third uses keyword parameters to simplify
 105 a complex set of parameters.  The C<flags> argument can be
 106 C<$NDMP9_SCSI_DATA_DIR_IN>, to take data I<into> the server from the SCSI
 107 device, or C<$NDMP9_SCSI_DATA_DIR_OUT> to send data I<out> to the SCSI device.
 108 The C<timeout> is in milliseconds.  The C<cdb> should be a SCSI control block
 109 (the C<pack> function is useful here).  If the data direction is in, then
 110 C<datain_len> indicates the maximum amount of data to expect; otherwise,
 111 C<dataout> is the data to send to the device.
 112
 113 The result is C<undef> for an error, or a hashref with the following keys:
 114
 115   status            SCSI status byte
 116   ext_sense         SCSI extended sense data
 117   datain            data from the device
 118   dataout_len       number of bytes actually transmitted to the device
 119
 120 =head3 Tape Interface
 121
 122   my $ok = $conn->tape_open($device, $mode);
 123   my $ok = $conn->tape_close();
 124
 125 The first method opens a tape device, using the give mode -
 126 C<$NDMP9_TAPE_READ_MODE> or C<$NDMP9_TAPE_RDRW_MODE>.  The second method closes
 127 the tape device associated with this connection.
 128
 129   my ($ok, $resid) = $conn->tape_mtio($op, $count);
 130
 131 This method sends C<NDMP_TAPE_MTIO> with the given operation and count.
 132 Operations have the prefix C<$NDMP9_MTIO_>.  The number of incomplete
 133 operations is returned in C<$resid>.
 134
 135 To read and write blocks, use these methods:
 136
 137   my ($ok, $actual) = $conn->tape_write($data);
 138   my ($ok, $data) = $conn->tape_read($bufsize);
 139
 140 where C<$actual> and C<$bufsize> are byte counts, and C<$data> is a string of
 141 data.  Finally, to get the state of the tape agent, use
 142
 143   my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
 144
 145 =head2 Constants
 146
 147 The constants required for the interface exposed here are included in this
 148 package.  They all begin with the prefix C<$NDMP9_>, which is an implementation
 149 detail of the NDMJOB library.  The constants are available from the export tag
 150 C<constants>:
 151
 152   use Amanda::NDMP qw( :constants );
 153
 154 =cut
 155
 156
 157 %}