3.1.3

Amanda::NDMP

NAME

Amanda::NDMP - communicate via NDMP

SYNOPSIS

  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();

DESCRIPTION

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.

Constructor

  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.

Methods

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.

Error Handling

  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.

SCSI Interface

  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

Tape Interface

  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();

Constants

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 );

ABOUT THIS PAGE

This page was automatically generated Tue Nov 19 20:05:35 2013 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.

3.1.3