1/* 2 * Copyright (c) 2009-2013 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 26Amanda::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 38This package interfaces with the C class C<NDMPConnection> class declared in 39C<ndmp-src/ndmpconnobj.h>. It is only available in builds that did not specify 40C<--without-ndmp>. The C class, in turn, interfaces to the XDR code provided 41by 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 51This gets a new connection object. This will always return an object, but the 52result should be checked for errors as described in the "Error Handling" 53section, below. 54 55The C<$host> and C<$port> give the NDMP server's host and port, respectively. 56The C<$auth> parameter defines the authentication mechanism to use: "md5" or 57"text"; "none" for no authentication; or "void" to not send any authentication 58packets at all. For md5 or text modes, C<$username> and C<$password> specify 59the username and password for the NDMP server; these parameters must always be 60included, but can be blank for none or void. 61 62The C<$ident> parameter deserves some explanation. NDMP scopes many 63server-side variables to the NDMP connection - for example, the "current" tape 64and taper state are associated with the NDMP connection. To facilitate this, 65the constructor returns the I<same connection> for any constructor invocation 66with the same host, port, and identifier. In cases where multiple connections 67are required (e.g., when two tapes are in use simultaneously), callers should 68provide different identifiers for each connection. 69 70=head2 Methods 71 72Note that not all NDMPConnection methods are available. All of these methods 73block until the appropriate reply is received. The underlying C class provides 74appropriate locking fundamentals to prevent corrupted on-the-wire messages. 75 76All 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 83Get the error code and message from the last method that returned false, or 84after the constructor is invoked. 85 86 $conn->set_verbose(1); 87 88This method will enable verbose logging of the NDMP transactions to the Amanda 89debug 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 104The first two methods are clear; the third uses keyword parameters to simplify 105a complex set of parameters. The C<flags> argument can be 106C<$NDMP9_SCSI_DATA_DIR_IN>, to take data I<into> the server from the SCSI 107device, or C<$NDMP9_SCSI_DATA_DIR_OUT> to send data I<out> to the SCSI device. 108The 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 110C<datain_len> indicates the maximum amount of data to expect; otherwise, 111C<dataout> is the data to send to the device. 112 113The 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 125The first method opens a tape device, using the give mode - 126C<$NDMP9_TAPE_READ_MODE> or C<$NDMP9_TAPE_RDRW_MODE>. The second method closes 127the tape device associated with this connection. 128 129 my ($ok, $resid) = $conn->tape_mtio($op, $count); 130 131This method sends C<NDMP_TAPE_MTIO> with the given operation and count. 132Operations have the prefix C<$NDMP9_MTIO_>. The number of incomplete 133operations is returned in C<$resid>. 134 135To 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 140where C<$actual> and C<$bufsize> are byte counts, and C<$data> is a string of 141data. 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 147The constants required for the interface exposed here are included in this 148package. They all begin with the prefix C<$NDMP9_>, which is an implementation 149detail of the NDMJOB library. The constants are available from the export tag 150C<constants>: 151 152 use Amanda::NDMP qw( :constants ); 153 154=cut 155 156 157%} 158