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