Amanda::NDMP - communicate via NDMP
use Amanda::NDMP qw( :constants );
my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
$password, $auth);
my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
This package interfaces with the C class NDMPConnection
class declared in ndmp-src/ndmpconnobj.h
. It is only available in builds that did not specify --without-ndmp
. The C class, in turn, interfaces to the XDR code provided by NDMJOB, which sends and receives NDMP messages on a TCP socket.
my $conn = Amanda::NDMP::NDMPConnection->new($host, $port, $ident, $username,
$password, $auth);
if ($conn->err_code()) {
# handle error..
}
This gets a new connection object. This will always return an object, but the result should be checked for errors as described in the "Error Handling" section, below.
The $host
and $port
give the NDMP server's host and port, respectively. The $auth
parameter defines the authentication mechanism to use: "md5" or "text"; "none" for no authentication; or "void" to not send any authentication packets at all. For md5 or text modes, $username
and $password
specify the username and password for the NDMP server; these parameters must always be included, but can be blank for none or void.
The $ident
parameter deserves some explanation. NDMP scopes many server-side variables to the NDMP connection - for example, the "current" tape and taper state are associated with the NDMP connection. To facilitate this, the constructor returns the same connection for any constructor invocation with the same host, port, and identifier. In cases where multiple connections are required (e.g., when two tapes are in use simultaneously), callers should provide different identifiers for each connection.
Note that not all NDMPConnection methods are available. All of these methods block until the appropriate reply is received. The underlying C class provides appropriate locking fundamentals to prevent corrupted on-the-wire messages.
All methods return a boolean "ok" status, with false indicating an error.
my $code = $conn->err_code();
my $msg = $conn->err_msg();
Get the error code and message from the last method that returned false, or after the constructor is invoked.
$conn->set_verbose(1);
This method will enable verbose logging of the NDMP transactions to the Amanda debug logs.
my $ok = $conn->scsi_open($device); # NDMP_SCSI_OPEN
my $ok = $conn->scsi_close(); # NDMP_SCSI_CLOSE
# NDMP_SCSI_EXECUTE_CDB
my $res = $conn->scsi_execute_cdb(
flags => $flags,
timeout => $timeout,
cdb => $cdb,
datain_len => $datain_len, # only if $flags == $NDMP9_SCSI_DATA_DIR_IN
dataout => $dataout # only if $flags == $NDMP9_SCSI_DATA_DIR_OUT
)
The first two methods are clear; the third uses keyword parameters to simplify a complex set of parameters. The flags
argument can be $NDMP9_SCSI_DATA_DIR_IN
, to take data into the server from the SCSI device, or $NDMP9_SCSI_DATA_DIR_OUT
to send data out to the SCSI device. The timeout
is in milliseconds. The cdb
should be a SCSI control block (the pack
function is useful here). If the data direction is in, then datain_len
indicates the maximum amount of data to expect; otherwise, dataout
is the data to send to the device.
The result is undef
for an error, or a hashref with the following keys:
status SCSI status byte
ext_sense SCSI extended sense data
datain data from the device
dataout_len number of bytes actually transmitted to the device
my $ok = $conn->tape_open($device, $mode);
my $ok = $conn->tape_close();
The first method opens a tape device, using the give mode - $NDMP9_TAPE_READ_MODE
or $NDMP9_TAPE_RDRW_MODE
. The second method closes the tape device associated with this connection.
my ($ok, $resid) = $conn->tape_mtio($op, $count);
This method sends NDMP_TAPE_MTIO
with the given operation and count. Operations have the prefix $NDMP9_MTIO_
. The number of incomplete operations is returned in $resid
.
To read and write blocks, use these methods:
my ($ok, $actual) = $conn->tape_write($data);
my ($ok, $data) = $conn->tape_read($bufsize);
where $actual
and $bufsize
are byte counts, and $data
is a string of data. Finally, to get the state of the tape agent, use
my ($ok, $blocksize, $file_num, $blockno) = $conn->tape_get_state();
The constants required for the interface exposed here are included in this package. They all begin with the prefix $NDMP9_
, which is an implementation detail of the NDMJOB library. The constants are available from the export tag constants
:
use Amanda::NDMP qw( :constants );
This page was automatically generated Tue Mar 19 07:08:16 2019 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.