2 * Copyright (c) 2009, 2010 Zmanda, Inc. All Rights Reserved.
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.
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
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
17 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
18 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
25 Amanda::NDMP - communicate via NDMP
29 use Amanda::NDMP qw( :constants );
31 my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
33 my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
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.
44 my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
46 if ($conn->err_code()) {
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"
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.
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.
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.
75 All methods return a boolean "ok" status, with false indicating an error.
79 my $code = $conn->err_code();
80 my $msg = $conn->err_msg();
82 Get the error code and message from the last method that returned false, or
83 after the constructor is invoked.
85 $conn->set_verbose(1);
87 This method will enable verbose logging of the NDMP transactions to the Amanda
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(
99 datain_len => $datain_len, # only if $flags == $NDMP9_SCSI_DATA_DIR_IN
100 dataout => $dataout # only if $flags == $NDMP9_SCSI_DATA_DIR_OUT
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.
112 The result is C<undef> for an error, or a hashref with the following keys:
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
119 =head3 Tape Interface
121 my $ok = $conn->tape_open($device, $mode);
122 my $ok = $conn->tape_close();
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.
128 my ($ok, $resid) = $conn->tape_mtio($op, $count);
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>.
134 To read and write blocks, use these methods:
136 my ($ok, $actual) = $conn->tape_write($data);
137 my ($ok, $data) = $conn->tape_read($bufsize);
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
142 my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
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
151 use Amanda::NDMP qw( :constants );