Network Working Group                                   R. Stager, PDC


 Internet Draft                              D. Hitz, Network Appliance
 Category: Informational                                    August 1997


                     Network Data Management Protocol
                   <draft-stager-pdc-netapp-backup-04.txt>

 Status of this Memo


      This document is an Internet-Draft.  Internet-Drafts are working
      documents of the Internet Engineering Task Force (IETF), its
      areas, and its working groups.  Note that other groups can also
      distribute working documents as Internet-Drafts.


      Internet-Drafts are draft documents valid for a maximum of six
      months and may be updated, replaced, or obsoleted by other
      documents at any time.  It is inappropriate to use Internet-
      Drafts as reference material or to cite them other than as ``work
      in progress.''


      To learn the current status of any Internet-Draft, please check
      the ``1id-abstracts.txt'' listing in the Internet-Drafts Shadow
      Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
      munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
      ftp.isi.edu (US West Coast).


 Abstract


      The Network Data Management Protocol (NDMP) is an open protocol
      for enterprise-wide network based backup. The NDMP architecture
      allows network attached storage vendors  to ship NDMP compliant
      file servers which can be used by any NDMP-compliant backup
      administration application. This same architecture is also used
      for network-attached backup devices, such as tape drives and
      tape libraries.


 Filename:           <draft-stager-pdc-netapp-backup-03.txt >




                                                                       2
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Expires:            March 1998



















































                                                                       3
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 1. OVERVIEW ...............................................5

   1.1 MOTIVATION ..........................................5
   1.2 AUDIENCE ............................................5
   1.3 TERMINOLOGY .........................................6

 2. ARCHITECTURE ...........................................8

   2.1 ARCHITECTURAL MODEL .................................8
   2.2 COMPARISON ARCHITECTURES ...........................18
   2.3 STATE DESCRIPTION ..................................19
    2.3.1 The Data State Diagram ..........................19
    2.3.2 The Mover State Diagram .........................21
   2.4 PROTOCOL INTERFACES ................................26
    2.4.1 Messages from NDMP Client to NDMP Server ........26
    2.4.2 Messages from NDMP Server to NDMP Client ........28
   2.5 MESSAGING PROTOCOL .................................28
   2.6 HEADER .............................................29
   2.7 ERROR CODES ........................................32
   2.8 MESSAGE NUMBERS ....................................36
   2.9 MESSAGE DEFINITIONS ................................38

 3. NDMP SERVER INTERFACES ................................39

   3.1 CONNECT INTERFACE ..................................39
    3.1.1 Open Connection .................................40
    3.1.2 Authorization ...................................40
    3.1.3 Close Connection ................................46
   3.2 CONFIG INTERFACE ...................................46
    3.2.1 Get Host Info ...................................46
    3.2.2 Get Backup Type Attribute .......................48
    3.2.3 Get Mover Type ..................................50
    3.2.4 Get authentication Type Attribute ...............51
   3.3 SCSI INTERFACE .....................................53
    3.3.1 Open SCSI Device ................................53
    3.3.2 Close Device ....................................55
    3.3.3 Get SCSI State ..................................56
    3.3.4 Set SCSI Target .................................57
    3.3.5 Reset Device ....................................59
    3.3.6 Reset Bus .......................................60
    3.3.7 Execute CDB .....................................61
   3.4 TAPE INTERFACE .....................................64
    3.4.1 Open Tape Device ................................64
    3.4.2 Close Device ....................................66
    3.4.3 Get Tape State ..................................67
    3.4.4 MTIO ............................................69
    3.4.5 Write ...........................................72
    3.4.6 Read ............................................73
    3.4.7 Execute CDB .....................................75
   3.5 DATA INTERFACE .....................................75
    3.5.1 Get Data State ..................................75

                                                                       4
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    3.5.2 Backup ..........................................79
    3.5.3 Recover .........................................82
    3.5.4 Abort ...........................................85
    3.5.5 Stop ............................................87
    3.5.6 Get ENV .........................................86
   3.6 MOVER INTERFACE ....................................88
    3.6.1 Get Mover State .................................88
    3.6.2 Listen ..........................................92
    3.6.3 Set Record Size .................................95
    3.6.4 Set Window ......................................96
    3.6.5 Continue ........................................97
    3.6.6 Abort ...........................................98
    3.6.7 Stop ............................................99
    3.6.8 Read ...........................................100
    3.6.9 Close ..........................................101

 4. NDMP CLIENT INTERFACES ...............................103

   4.1 NOTIFY INTERFACE ..................................103
    4.1.1 Notify Data Halted .............................103
    4.1.2 Notify Connected ...............................104
    4.1.3 Notify Mover Halted ............................106
    4.1.4 Notify Mover Paused ............................107
    4.1.5 Notify DATA Read ...............................108
   4.2 LOGGING INTERFACE .................................109
    4.2.1 Log ............................................109
    4.2.2 Debug ..........................................109
    4.2.3 File Recovered .................................111
   4.3 FILE HISTORY INTERFACE ............................113
    4.3.1 Add Unix Path ..................................113
    4.3.2 Add Unix Dir ...................................116
    4.3.3 Add Unix Node ..................................117

 5. REFERENCES ...........................................119


 6. SECURITY .............................................119


 7. AUTHORS ..............................................119

 FIGURE 1. SIMPLE CONFIGURATION ...........................10
 FIGURE 2. TWO DRIVE CONFIGURATION ........................13
 FIGURE 3. JUKEBOX CONFIGURATION ..........................15
 FIGURE 4. BACKING UP NDMP HOST THROUGH THE NETWORK TO ANOTHER NDMP
    HOST ..................................................18
 FIGURE 5 - DATA STATE DIAGRAM ............................21
 FIGURE 6 - MOVER STATE DIAGRAM ...........................24




                                                                       5
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



 1. Overview

 1.1 Motivation

 The purpose of this protocol is to allow a network backup application
 to control the backup and retrieval of an NDMP-compliant server
 without installing third-party software on the server.


 The control and data transfer components of the backup/restore are
 separated. The separation allows complete interoperability at a
 network level. The file system vendors need only be concerned with
 maintaining compatibility with one, well-defined protocol. The backup
 vendors can place their primary focus on the sophisticated central
 backup administration software.


 The NDMP protocol is targeted towards the process of backup and
 restore. There are extensive references to these tasks.
 The protocol is specifically intended to support tape drives.
 However, the protocol can be used for other applications and
 support other media in the future.


 1.2 Audience

 This document is intended for use by software developers to implement
 Network Data Management Protocol. The reader is assumed to be familiar
 with network protocol specifications and with the general operation of
 backup software.  The user is not expected to have knowledge of
 internal backup software behavior.


 1.3 Terminology

 NDMP


      Network Data Management Protocol. An open protocol for
      enterprise-wide network-based backup.


 NDMP client


      The application that controls the NDMP server.


 NDMP host


                                                                       6
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


      The host that executes the NDMP server application. Data is
      backed up from the NDMP host to either a local tape drive or to a
      backup device on a remote NDMP host.


 NDMP server


      The virtual state machine on the NDMP host that is controlled
      using the NDMP protocol.  There is one of these for each
      connection to the NDMP host.  This term is used independent of
      implementation.








































                                                                       7
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



 2. Architecture

 2.1 Architectural Model

 The architecture is a client server model and backup management software
 is considered a client to the NDMP server. For every connection between
 the client on the backup management software host and the NDMP host,
 there is a  virtual state machine on the NDMP host that is controlled
 using NDMP.  This virtual state machine is referred to as the NDMP
 server. Each state machine controls at most one device used to run
 backups.  The protocol is a set of XDR-encoded messages that are
 exchanged over a bi-directional TCP/IP connection and are used to
 control and monitor the state of the NDMP server and to collect
 detailed information about the data that is backed up.


 In the most simple configuration, backup software will backup the data
 from the NDMP host to a backup device connected to the NDMP host.

































                                                                       8
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



                          Network Boundary
                               *
            BACKUP HOST        *        NDMP HOST
                               *
                               *
 ____________________          *            ____________________
|  NDMP Client       |         *           |    NDMP Server     |
|                    |<--NDMP Connection-->|                    |
|____________________|         *           |____________________|
                               *              ^             |
                               * Backup Data  | Backup data |
                               *       _______|__      _____V___
                               *      |          |    |  Tape   |
                               *      |  Disk    |    |  Drive  |
                               *      |          |    |         |
                               *      |          |    |_________|
                               *      |__________|
                               *
                               *
                          Network Boundary





























                                                                       9
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Figure 1. Simple configuration



















































                                                                      10
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 It is also possible to use NDMP to simultaneously back up to two
 backup devices physically attached to the NDMP host.  In this
 configuration, there are two instances of the NDMP server on the NDMP
 host.
















































                                                                      11
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97





                Network Boundary
                     *
BACKUP HOST          *       NDMP HOST
                     *
                     *
 __________          *            ____________
| NDMP     |         *           |NDMP Server |
| Client   |<--NDMP Connection-->|____________|     ___________
|          |<--NDMP Connection--------------------->| NDMP     |
|__________|         *            ^       |         | Server   |
                     *      Backup| Backup|         |__________|
                     *      Data  | Data  |   Backup ^ Backup|
                     *       _____|_   ___V___ Data  |  Data |
                     *      |       |  |      |      |       |
                     *      |       |  |Tape  |      |       |
                     *      |  Disk |  |Drive |  ____|_   ___V__
                     *      |       |  |      | |      | |      |
                     *      |_______|  |______| |      | |Tape  |
                     *                          |Disk  | |Drive |
                     *                          |      | |      |
                     *                          |______| |______|
                     *
                     *
                Network Boundary


























                                                                      12
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97





 Figure 2. Two drive configuration


 NDMP can be used to back up data to a backup device in a jukebox that
 is physically attached to the NDMP host. In this configuration, there
 is a separate instance of the NDMP server to control the robotics
 within the jukebox.










































                                                                      13
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




                Network Boundary
                     *
BACKUP HOST          *       NDMP HOST
                     *
                     *
 __________          *            ____________      ____________
| NDMP     |         *           |NDMP Server |    |            |
| Client   |<--NDMP Connection-->|____________|----|-> Robotics |
|          |         *            ____________     |   Control  |
|          |<--NDMP Connection-->| NDMP Server |   |            |
|__________|         *           |_____________|---|-> Tape     |
                     *            ^                |   Drive    |
                     *      Backup|                |            |
                     *      Data  |                |Tape Jukebox|
                     *       _____|___             |____________|
                     *      |         |
                     *      |         |
                     *      |  Disk   |
                     *      |         |
                     *      |_________|
                     *
                     *
                Network Boundary


























                                                                      14
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Figure 3. Jukebox configuration



















































                                                                      15
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 It is possible to back up a host that supports NDMP but does not have
 a locally attached backup device by sending the data through a raw
 TCP/IP connection to another NDMP host.

















































                                                                      16
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




                Network Boundary
                     *
BACKUP HOST          *       NDMP HOST
                     *
                     *
 __________          *            ____________
| NDMP     |         *           |NDMP Server |
| Client   |<--NDMP Connection-->|____________|
|          |         *            ^     |
|____^_____|         *            |     |
     |               *      Backup|     |
     |               *      Data  |     |
     |               *       _____|_    |
     |               *      |       |   |
     |               *      |       |   |
     |               *      |  Disk |   |
     |               *      |       |   | Backup Data Only
     |               *      |_______|   |
     |               *                  |
****************************************|************ Network Boundary
     |               *                  |
     |               *             _____v____
     --NDMP Connection----------->| NDMP     |
                     ^            | Server   |
                     *             ----------
                     *           Backup|
                     *           Data  |
                     *              ___V___
                     *             |      |
                     *             |Tape  |
                     *             |Drive |
                     *             |      |
                     *             |______|
                     *
                Network Boundary















                                                                      17
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Figure 4. Backing up NDMP host through the network to another NDMP
 host





 2.2 Comparison Architectures

 It is useful to compare the NDMP architecture to other architectures
 and note the similarities and differences.


 rmt


 The NDMP architecture is similar to the rmt architecture in that
 connection is made to a generic server and the server is instructed to
 open a specific tape device. NDMP differs in that it uses a
 TCP/IP connection to a dedicated port whereas  rmt uses the rsh  demon
 to launch a server.


 X11


 The NDMP architecture is similar to the X11 architecture in that it
 uses a single connection to a TCP/IP port. NDMP differs in that the
 NDMP server is not assigned to a device until the client opens a
 device and that there is only one client per NDMP server, whereas X11
 is assigned to a display device before the first client connects and
 accepts connections from many clients.


 RPC


 The NDMP architecture is similar to the RPC architecture in that it
 uses XDR encoding. NDMP differs in that it is only defined for a
 TCP/IP connection and that it is not a call-return model, but rather a
 bi-directional asynchronous messaging model.











                                                                      18
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97





 2.3 State Description

 Two interfaces have states associated with them: the Data interface
 and the Mover interface.


 2.3.1 The Data State Diagram

 The following defines the DATA state diagram.








































                                                                      19
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


   _____________________________________
  |                                     |
  |                                     |
  |                               ******V******
  |                               *   Idle    *
  |                               *           *
  |                               *************
  |                                |         |
  |                                |         |
  |                  DATA_start_recover    DATA_start_backup
  |                                |         |
  |                                 \       /
  |                                  \     /
  |                                   \   /
  |                                    \ /
  |                                     |
  |                                     |
  |                               ******V******
  |            ___________________*  Active   *
  |           |                   *           *
  |           |         __________*           *
DATA_stop     |        |          *************
  |           |        |            |        |
  |           |        |            |        |
  |           |        |       Successful  Connection
  |      Internal  DATA_abort   Completion  Error
  |      Error         |            |        |
  |           |        |            |        |
  |             \      |            |      /
  |               \    |            |    /
  |                 \  |            |  /
  |                   \              /
  |                     \          /
  |                       \      /
  |                    ****V****V****
  |                    *   Halted   *
  |____________________*            *
                       **************














                                                                      20
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Figure 5 - data state diagram


 The following defines the state machine for the data interface and the
 rules for transitions between states.


 2.3.1.1 Idle State

 This is the start state of the state machine.


      .  Transition to active state upon receipt of
         NDMP_DATA_START_BACKUP message.


      .  Transition to active state upon receipt of
         NDMP_DATA_START_RECOVER message.


 2.3.1.2 Active State

 The NDMP server remains in this state while a backup or restore is
 active.


      .  Transition to halted state upon detection of a backup/restore
         error.


      .  Transition to halted state upon receipt of NDMP_DATA_ABORT
         message.


      .  Transition to halted state upon completion of backup/restore.


 2.3.1.3 Halted State

 The NDMP server enters this state after a backup/restore has either
 completed or been aborted.


      .  Transition to idle state upon receipt of NDMP_DATA_STOP
         message.





 2.3.2 The Mover State Diagram

                                                                      21
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 The following defines the state diagram for the Mover interface.



















































                                                                      22
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



   _____________________________________
  |                                     |
  |                                     |
  |                               ******V******
  |                               *   Idle    *
  |                               *           *
  |                               *************
  |                                     |MOVER_listen
MOVER_stop                              |
  |                               ******V******
  |   ____________________________* Listening *
  |  |                            *           *
  |  |                            *************
  |  |                                   |______________________________
  |  |                                   |                              |
  |  |Mover_abort                  ******V******__ Media Error _|       |
  |  |          ___________________*  Active   *___Detect EOM__ |       |
  |  |         |                   *           *___Detect EOF___|       |
  |  |         |         __________*           *___Seek ________|       |
  |  |         |        |          *************                |       |
  |  |         |        |            |        |                 |       |
  |  |         |        |            |        |                 |       |
  |  |         |        |       Connection  Connection          | MOVER_|
  |  |    Internal  MOVER_abort   Closed     Error              |continue
  |  |    Error         |            |        |          *******V****** |
  |  |         |        |            |        |          *  Paused    *_|
  |  |           \      |            |      /            *            *
  |   \            \    |            |    /              **************
  |    \             \  |            |  /                  |       |
  |     \             \              /           Mover_abort       | Mover_close
  |      \              \          /                       v_______v
  |       \              \      /                                |
  |        \          ****V****V****                             |
  |         \-------->   Halted    *                             |
  |___________________*            *<----------------------------
                      **************













                                                                      23
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97

 Figure 6 - Mover state diagram




















































                                                                      24
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



 2.3.2.1 Idle State

 This is the start state of the state machine.


      .  Transition to listen state upon receipt of NDMP_MOVER_LISTEN
         message.


 2.3.2.2 Listen State

 The NDMP server remains in this state while waiting for a connection
 from either a local or remote NDMP data server.


      .  Transition to active state upon establishment of connection
         with NDMP data server.


      .  Transition to halted state upon receipt of NDMP_MOVER_ABORT
         message.


 2.3.2.3 Active State

 The NDMP server remains in this state while a backup or restore is
 active.


      .  Transition to halted state upon detection of an internal error.


      .  Transition to halted state upon receipt of NDMP_MOVER_ABORT
         message.


      .  Transition to halted state upon detection of a connection
         error.


      .  Transition to halted state upon detection of connection close.


      .  Transition to paused state upon detection of EOM.


      .  Transition to paused state upon detection of EOF.




                                                                      25
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


      .  Transition to paused state upon detection of media error.


      .  Transition to paused state upon reaching end of data window.


 2.3.2.4 Halted State

 The NDMP server enters this state after a backup/restore has either
 completed or been aborted.


      .  Transition to idle state upon receipt of NDMP_MOVER_STOP
         message.


 2.3.2.5 Paused State

 The NDMP server remains in this state while waiting for a tape to be
 changed.


      .  Transition to active state upon receipt of NDMP_MOVER_CONTINUE
         message.


      .  Transition to halted state upon receipt of NDMP_MOVER_ABORT
         message.


      .  Transition to halted state upon receipt of NDMP_MOVER_CLOSE
         message.


 2.4 Protocol Interfaces

 Messages are grouped together by functionality into several
 interfaces.


 2.4.1 Messages from NDMP Client to NDMP Server

 The NDMP server must implement the following interfaces:


 .  CONNECT interface

 This interface will be used after a client first establishes a
 connection to an NDMP server. The CONNECT interface allows the NDMP



                                                                      26
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 server to authenticate the client and negotiate the version of
 protocol used.


 .  CONFIG interface

 This interface allows an NDMP client to discover the configuration of
 the NDMP server. The CONFIG interface can be used to discover NDMP
 server configuration and attributes.


 .  SCSI interface

 This interface is used to pass SCSI CDBs through to a SCSI device and
 retrieve the resulting SCSI status. The NDMP client  will use the SCSI
 interface to control a locally attached jukebox. Software on the NDMP
 client will construct SCSI CDBs and will interpret the returned status
 and data.  The SCSI interface can also be used to exploit special
 features of SCSI backup devices.


 .  TAPE interface

 This interface will support both tape positioning and tape read/write
 operations. The NDMP client will typically use the TAPE interface to
 write tape volume header and trailer files. The NDMP client will also
 use the TAPE interface to position the tape during backups and
 restores.


 .  DATA interface

 This is the interface that actually deals with the format of the
 backup data. The NDMP client will initiate backups and restores using
 the DATA interface.   The NDMP client provides all of the parameters
 that may affect the backup or restore using the DATA interface.  The
 NDMP client does not place any constraints on the format of the backup
 data other than it must be a stream of data that can be written to the
 tape device.


 .  MOVER interface


 This interface is used to control the reading/writing of  backup data
 from/to a tape device. During a backup the MOVER reads data from the
 data connection, buffers the data into tape records, and writes the
 data to the tape device. During a restore the MOVER reads data from
 the tape device and writes the data to the data connection. The MOVER



                                                                      27
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 is responsible for handling tape exceptions and notifying the NDMP
 client.


 2.4.2 Messages from NDMP Server to NDMP Client

 The NDMP server's implementation might send the following messages to
 the NDMP client. All the messages that the NDMP client accepts are
 asynchronous.  None of these messages will generate a reply message.


 .  NOTIFY interface

 The NDMP server uses this message to notify the NDMP client that the
 NDMP server requires attention.



 .  FILE HISTORY interface

 These messages allow the NDMP server to make entries in the file
 history for the current backup. The file history will be used by the
 NDMP client to select files for retrieval.


 .  LOGGING interface

 These messages allow the NDMP server to make entries in the backup
 log. The operator uses the backup log to monitor the progress and
 completion status of the backup. The log is also used to diagnose
 problems.


 2.5 Messaging Protocol

 The NDMP protocol is based on XDR encoded messages transmitted over a
 TCP/IP connection.


 NDMP messages are asynchronous. Not all request messages have an
 associated reply message. An NDMP message consists of a message header
 optionally followed by a message body. Each message is identified by a
 message number that is sent as part of the message header. Each
 message (message header plus message body) will be XDR encoded and
 sent within a single XDR record.







                                                                      28
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Messages that cannot be parsed or have invalid sequence information
 can be logged on the receiving host but no response is returned to the
 sender.


 2.6 Header

 Each message is preceded by a message header.  The header is used to
 identify the message and defines how to deserialize the arguments and
 dispatch the message.










































                                                                      29
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



     ______________________________________
    | ndmp_header       | message_request  |
    |___________________|__________________|
     ______________________________________
    | ndmp_header       | message_reply    |
    |___________________|__________________|












































                                                                      30
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 The message headers are defined by the following XDR block



    enum ndmp_header_message_type
    {
        NDMP_MESSAGE_REQUEST,
        NDMP_MESSAGE_REPLY
    };
    struct ndmp_header
    {
        u_long                      sequence;
        u_long                      time_stamp;
        ndmp_header_message_type    message_type;
        enum ndmp_message           message;
        u_long                      reply_sequence;
        ndmp_error                  error;
    };







    Message header data definitions:


    sequence              The sequence number is a connection local
                          counter that starts at one and increases by
                          one for every message sent. The client and
                          the server both start with one and increase
                          independently.


    time_stamp            The time_stamp identifies the time, in
                          seconds since 00:00:00 GMT, Jan 1, 1970, that
                          the message was sent.


    message_type          The message_type enum identifies the message
                          as a request or a reply message.


    message               The message field identifies the message.


    reply_sequence        The reply_sequence field is 0 in a request
                          message. In reply messages, the
                          reply_sequence is the sequence number from


                                                                      31
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


                          the request message to which the reply is
                          associated.


    error                 The error field is 0 in request messages. In
                          reply messages, the error field identifies
                          any problem that occurred receiving or
                          decoding the message.  If the error value is
                          nonzero, no message body will  follow the
                          message header. The complete list of error
                          codes is in the next section.


 2.7 Error Codes

 The following error codes are defined:



    enum ndmp_error
    {
        NDMP_NO_ERR,
        NDMP_NOT_SUPPORTED_ERR,
        NDMP_DEVICE_BUSY_ERR,
        NDMP_DEVICE_OPENED_ERR,
        NDMP_NOT_AUTHORIZED_ERR,
        NDMP_PERMISSION_ERR,
        NDMP_DEV_NOT_OPEN_ERR,
        NDMP_IO_ERR,
        NDMP_TIMEOUT_ERR,
        NDMP_ILLEGAL_ARGS_ERR,
        NDMP_NO_TAPE_LOADED_ERR,
        NDMP_WRITE_PROTECT_ERR,
        NDMP_EOF_ERR,
        NDMP_EOM_ERR,
        NDMP_FILE_NOT_FOUND_ERR,
        NDMP_BAD_FILE_ERR,
        NDMP_NO_DEVICE_ERR,
        NDMP_NO_BUS_ERR,
        NDMP_XDR_DECODE_ERR,
        NDMP_ILLEGAL_STATE_ERR,
        NDMP_UNDEFINED_ERR,
        NDMP_XDR_ENCODE_ERR,
        NDMP_NO_MEM_ERR
    };







                                                                      32
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 NDMP_NO_ERR


      No error.


 NDMP_NOT_SUPPORTED_ERR


      Specified message not supported.  Some NDMP implementations might
      only support a subset of the NDMP protocol.


 NDMP_DEVICE_BUSY_ERR


      Specified device is in use. This error will be returned if an
      attempt is made to open a tape or SCSI device that is already in
      use.


 NDMP_DEVICE_OPENED_ERR


      A device is already open. NDMP connections are limited to having
      a single device opened at a time.


 NDMP_NOT_AUTHORIZED_ERR


      NDMP connection not yet authenticated. Prior to issuing most
      requests, the NDMP connection must first be authenticated via the
      connect_auth message. This error is returned if a message
      requiring connection authentication is received when the
      connection has not yet been authenticated.


 NDMP_PERMISSION_ERR


      The user that was used to authenticate the connection does not
      have the access permissions to execute this message.


 NDMP_DEV_NOT_OPEN_ERR


      Device not open. An attempt was made to access a device that was
      not open.


                                                                      33
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 NDMP_IO_ERR


      Device I/O error.


 NDMP_TIMEOUT_ERR


      Command timeout error.


 NDMP_ILLEGAL_ARGS_ERR


      Message received containing one or more invalid arguments.


 NDMP_NO_TAPE_LOADED_ERR


      Tape device could not be opened because no tape was loaded.


 NDMP_WRITE_PROTECT_ERR


      Tape device could not be opened in write mode because the tape is
      write protected.


 NDMP_EOF_ERR


      The tape command failed because end-of-file was encountered.


 NDMP_EOM_ERR


      The tape command failed because the end of media mark was
      encountered.


 NDMP_FILE_NOT_FOUND_ERR


      During a recover operation, a specified file was not found.




                                                                      34
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 NDMP_BAD_FILE_ERR


      Error due to invalid file descriptor.


 NDMP_NO_DEVICE_ERR


      Specified device does not exist.


 NDMP_NO_BUS_ERR


      Specified SCSI controller does not exist.


 NDMP_XDR_DECODE_ERR


      Error decoding message.


 NDMP_ILLEGAL_STATE_ERR


      Message cannot be processed in the current state.


 NDMP_UNDEFINED_ERR


      Undefined error.


 NDMP_XDR_ENCODE_ERR


      Error encoding reply message.


 NDMP_NO_MEM_ERR


      Memory allocation error.






                                                                      35
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 2.8 Message Numbers

 The following messages are defined:

















































                                                                      36
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    enum ndmp_message
    {
        /* Config Interface */
        NDMP_CONFIG_GET_HOST_INFO    = 0x100,
        NDMP_CONFIG_GET_BUTYPE_ATTR,
        NDMP_CONFIG_GET_MOVER_TYPE,
        NDMP_CONFIG_GET_AUTH_ATTR,


        /* SCSI Interface */
        NDMP_SCSI_OPEN               = 0x200,
        NDMP_SCSI_CLOSE,
        NDMP_SCSI_GET_STATE,
        NDMP_SCSI_SET_TARGET,
        NDMP_SCSI_RESET_DEVICE,
        NDMP_SCSI_RESET_BUS,
        NDMP_SCSI_EXECUTE_CDB,

        /* Tape Interface */
        NDMP_TAPE_OPEN               = 0x300,
        NDMP_TAPE_CLOSE,
        NDMP_TAPE_GET_STATE,
        NDMP_TAPE_MTIO,
        NDMP_TAPE_WRITE,
        NDMP_TAPE_READ,
        NDMP_TAPE_RESVD1,
        NDMP_TAPE_EXECUTE_CDB,

        /* Data Interface */
        NDMP_DATA_GET_STATE          = 0x400,
        NDMP_DATA_START_BACKUP,
        NDMP_DATA_START_RECOVER,
        NDMP_DATA_ABORT,
        NDMP_DATA_GET_ENV,
        NDMP_DATA_RESVD1,
        NDMP_DATA_RESVD2,
        NDMP_DATA_STOP,

        /* Notify Interface */

        NDMP_NOTIFY_RESVD1           = 0x500,
        NDMP_NOTIFY_HALTED,
        NDMP_NOTIFY_CONNECTED,
        NDMP_NOTIFY_MOVER_HALTED,
        NDMP_NOTIFY_MOVER_PAUSED,
        NDMP_NOTIFY_DATA_READ,


        /* Log Interface */

                                                                      37
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




        NDMP_LOG_LOG                 = 0x600,
        NDMP_LOG_DEBUG,
        NDMP_LOG_FILE,

        /* File History Interface */
        NDMP_FH_ADD_UNIX_PATH        = 0x700,
        NDMP_FH_ADD_UNIX_DIR,
        NDMP_FH_ADD_UNIX_NODE,

        /* Connect Interface */
        NDMP_CONNECT_OPEN            = 0x900,
        NDMP_CONNECT_AUTH,
        NDMP_CONNECT_CLOSE,

        /* Mover Interface */
        NDMP_MOVER_GET_STATE         = 0xA00,
        NDMP_MOVER_LISTEN,
        NDMP_MOVER_CONTINUE,
        NDMP_MOVER_ABORT,
        NDMP_MOVER_STOP,
        NDMP_MOVER_SET_WINDOW,
        NDMP_MOVER_READ,
        NDMP_MOVER_CLOSE,
        NDMP_MOVER_SET_RECORD_SIZE,

        /* Reserved for prototyping */
        /* 0xFF00 through 0xFFFF */
        NDMP_RESERVED               = 0xFF00
    };






 2.9 Message Definitions

 Each message is described using a block of XDR specification in the
 following format:











                                                                      38
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97





    struct message_name_request
    {
      type request_argument1;
      ...
      type request_argumentN;
    };

    struct message_name_reply
    {
      enum ndmp_error error;
      type reply_argument1;
      ...
      type reply_argumentN;
    };



 Each XDR specification conforms to rpcgen format. No XDR specification
 is provided for the request message if the request message does not
 contain any arguments. No XDR specification is provided for the reply
 message if the reply message does not contain any argument or if no
 reply message is defined. Not all request messages have an associated
 reply message. Following the XDR specification is a description of
 each request and reply argument. Each reply message contains an error
 code.  If an error code is returned that is not equal to NDMP_NO_ERR,
 some of the reply arguments might be meaningless. A list of errors
 that typically might be returned in the reply is provided for each
 message. Note that this is not an exhaustive list. Generic errors,
 such as NDMP_NO_MEM_ERR, are not listed.


 3. NDMP Server Interfaces

 This section defines the protocol interfaces implemented by the NDMP
 server.


 3.1 CONNECT Interface

 This interface is used to authenticate the client and negotiate the
 version of protocol which will be used.


 The NDMP client first connects to a well known port (10,000). The NDMP
 server accepts the connection and sends an NDMP_NOTIFY_CONNECTED message.
 The NDMP client then sends an NDMP_CONNECT_OPEN message, usually
 followed by an NDMP_CONNECT_AUTH message.


                                                                      39
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 3.1.1 Open Connection

 Used to negotiate the protocol version to be used between the NDMP
 client and server.


 Message XDR definition



    /* NDMP_CONNECT_OPEN */
    struct ndmp_connect_open_request
    {
        u_short     protocol_version;
    };

    struct ndmp_connect_open_reply
    {
        ndmp_error  error;
    };



 Request Arguments


    protocol_version      Protocol version suggested by the NDMP
                          client.


 Reply Errors


    NDMP_NO_ERR           Protocol version suggested by the client is
                          supported by the server.


    NDMP_ILLEGAL_ARGS_ERR Protocol version suggested by the client is
                          not supported by the server. The client
                          should retry the request with a lower
                          protocol version number.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


 3.1.2 Authorization

 Used to authenticate the NDMP connection.  Only request messages
 within the CONFIG and CONNECT interfaces may be processed on a
 connection that has
                                                                      40
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 not yet been authenticated. A reply message containing an
 NDMP_NOT_AUTHORIZED_ERR error will be returned in response to any
 other request message received when the connection has not yet been
 authenticated.


 NDMP servers must support at least one of the following authentication
 methods.


      .  NONE: no authentication required.


      .  TEXT: connection is authenticated using a user name and
         clear text password.


      .  MD5: connection is authenticated to both the client and the
         server using an MD5 algorithm.


 The MD5 method uses the MD5 message-digest algorithm described in
 RFC1321 to authenticate the client and the server using a shared
 secret (password). The message used to compute the MD5 digest
 is a concatenation of the password, null padding, the 64 byte fixed
 length challenge and a repeat of the password. The length of the null
 padding is chosen to result in a 128 byte fixed length message. The
 length of the padding can be computed as 64 - 2*(length of the password).
 Both the client_digest and server_digest use the same password.  The
 client_digest is computed using the server_challenge from the
 NDMP_CONFIG_GET_AUTH_ATTR reply. The server_digest is computed using
 the client_challenge from the NDMP_CONNECT_AUTH request.



     ___________________________________________________
    | Password  | Padding  | Challenge  | Password     |
    | __________|__________|____________|______________|

    <-------------------- 128 Bytes ------------------->










                                                                      41
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97

(This page is intended to be blank.)




















































                                                                      42
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97








 Message XDR definition













































                                                                      43
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_CONNECT_AUTH */
    enum ndmp_auth_type
    {
        NDMP_AUTH_NONE,
        NDMP_AUTH_TEXT,
        NDMP_AUTH_MD5
    };

    struct ndmp_auth_text
    {
        string      user <>;
        string      password<>;
    };

    struct ndmp_auth_md5
    {
        string      user <>;
        opaque      client_digest[16];
        opaque      client_challenge[64];
    };


    union ndmp_auth_data switch (enum ndmp_auth_type auth_type)
    {
        case NDMP_AUTH_NONE:
            void;
        case NDMP_AUTH_TEXT:
            struct ndmp_auth_text     auth_text;
        case NDMP_AUTH_MD5:
            struct ndmp_auth_md5     auth_md5;
    };

    union ndmp_auth_result switch (enum ndmp_auth_type auth_type)
    {
        case NDMP_AUTH_NONE:
            void;
        case NDMP_AUTH_TEXT:
            void;
        case NDMP_AUTH_MD5:
            opaque      server_digest[16];
    };

    struct ndmp_connect_auth_request
    {
        ndmp_auth_data     auth_data;
    };

    struct ndmp_connect_auth_reply
    {

                                                                      44
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




        ndmp_error      error;
        ndmp_auth_result auth_result;
    };






 Request Arguments


    auth_data             Authentication data. NDMP servers must
                          support at least one of the following
                          authentication methods:


                          .  NONE: no authentication required.


                          .  TEXT:  connection is authenticated using a
                             user name and non-encrypted password.


                          .  MD5: connection is authenticated using user
                             name and MD5 digest of the server_challenge
                             and the user password.


    Reply Arguments


    error                 Error code.


    auth_result           Authentication results. NDMP servers may
                          return information to the NDMP client to
                          authenticate the server to the client.


                          .  NONE: no authentication returned.


                          .  TEXT: no authentication returned.






                                                                      45
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


                          .  MD5: connection is authenticated using user
                             name and MD5 digest of the client_challenge
                             and the user password.


    Reply Errors


    NDMP_NO_ERR           Connection successfully authenticated.


    NDMP_NOT_AUTHORIZED_ERR    Incorrect authentication data.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


    NDMP_ ILLEGAL_ARGS _ERR    Specified authentication method not
                          supported.


 3.1.3 Close Connection

 This message is used when the client wants to close the NDMP
 connection. This message should be sent by the NDMP client before
 shutting down the TCP/IP connection.


 Message XDR definition



    /* NDMP_CONNECT_CLOSE */
    /* no request arguments */
    /* no reply message */



 3.2 CONFIG Interface

 This interface allows the NDMP client to discover the configuration of
 the NDMP server.


 3.2.1 Get Host Info

 This request is used to get information about the NDMP server.




                                                                      46
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Message XDR definition



    /* NDMP_CONFIG_GET_HOST_INFO */
    /* no request arguments */
    struct ndmp_config_get_host_info_reply
    {
        ndmp_error      error;
        string          hostname<>;
        string          os_type<>;
        string          os_vers<>;
        string          hostid<>;
        ndmp_auth_type  auth_type<>;
    };






 Request Arguments


    This request does not have a message body.


 Reply Arguments


    error                 Error code.


    hostname              Host name of the NDMP server


    os_type               Name of NDMP server operating system (for
                          example, Solaris).


    os_vers               Version of NDMP server operating system (for
                          example, 2.5).


    hostid                NDMP server host identifier.


    auth_types            Connection authentication types supported by
                          the NDMP server.



                                                                      47
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Errors


    NDMP_NO_ERR           Request successfully processed.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


 3.2.2 Get Backup Type Attribute

 This message is used to query the capability of the supported backup
 type.


 Message XDR definition



    /* NDMP_CONFIG_GET_BUTYPE_ATTR */
    const NDMP_NO_BACKUP_FILELIST =      0x0001;
    const NDMP_NO_BACKUP_FHINFO =        0x0002;
    const NDMP_NO_RECOVER_FILELIST =     0x0004;
    const NDMP_NO_RECOVER_FHINFO =       0x0008;
    const NDMP_NO_RECOVER_RESVD =        0x0010;
    const NDMP_NO_RECOVER_INC_ONLY =     0x0020;

    struct ndmp_config_get_butype_attr_request
    {
        string          name <>;
    };

    struct ndmp_config_get_butype_attr_reply
    {
        ndmp_error      error;
        u_long          attrs;
    };






 Request Arguments


    name                  Name of backup type for which attributes are
                          being requested  (such as dump, tar, cpio).



                                                                      48
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


                          Backup types are NDMP server implementation
                          dependent.


 Reply Arguments


    error                 Error code.


    attrs                 Backup attributes bit mask. The following
                          attribute bits are defined:





         NDMP_NO_BACKUP_FILELIST    NDMP server doesn't support
                               archiving of selective files as
                               specified by a file list. (only supports
                               dumping the entire specified
                               filesystem/directory.)


         NDMP_NO_BACKUP_FILEINFO    NDMP server doesn't support the
                               file history.


         NDMP_NO_RECOVER_FILELIST   NDMP server doesn't support
                               restoration of individual files.


         NDMP_NO_RECOVER_FHINFO     NDMP server doesn't support direct
                               access restore (positioning to the
                               offset of a backup image and restoring
                               the specified file).


         NDMP_NO_RECOVER_RESVD This value is reserved.


         NDMP_NO_RECOVER_INC_ONLY   NDMP server doesn't support
                               incremental-only restoration (a full
                               restore must be done before an
                               incremental restore).


 Reply Errors




                                                                      49
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NO_ERR           Attributes for specified backup type
                          successfully returned.


    NDMP_ILLEGAL_ARGS_ERR Specified backup type not supported.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


 3.2.3 Get Mover Type

 This request returns a list of the connection methods which NDMP
 server supports. LOCAL and TCP are the only types supported in the
 current version of the protocol.


 Message XDR definition



    /* NDMP_CONFIG_GET_MOVER_TYPE */
    /* no request arguments */
    enum ndmp_mover_addr_type
    {
        NDMP_ADDR_LOCAL,
        NDMP_ADDR_TCP
    };

    struct ndmp_config_get_mover_type_reply
    {
        ndmp_error              error;
        ndmp_mover_addr_type    methods<>;
    };



 Request Arguments


      This request does not have a message body.


 Reply Arguments


    error                 Error code.




                                                                      50
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    methods               Array of supported mover methods.


 Reply Errors


    NDMP_NO_ERR           Returned the supported mover type
                          successfully.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


 3.2.4 Get authentication Type Attribute

 This message is used to query the attributes of the supported
 authentication methods.


 Message XDR definition































                                                                      51
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_CONFIG_GET_AUTH_ATTR */

    union  ndmp_auth_client_attr
        switch (enum ndmp_auth_type auth_type){
        case NDMP_AUTH_NONE:
           void;
        case NDMP_AUTH_TEXT:
           void;
        case NDMP_AUTH_MD5:
           void;
    };
    union  ndmp_auth_server_attr
        switch (enum ndmp_auth_type auth_type){
        case NDMP_AUTH_NONE:
           void;
        case NDMP_AUTH_TEXT:
           void;
        case NDMP_AUTH_MD5:
           opaque    server_challenge[64];
    };

    struct ndmp_config_get_auth_attr_request
    {
        union ndmp_auth_client_attr client_attr;
    };

    struct ndmp_config_get_auth_attr_reply
    {
        ndmp_error      error;
        union ndmp_auth_server_attr server_attr;
    };






 Request Arguments


    client_attr           None of the currently defined authentication
                          schemes require arguments.


 Reply Arguments


    error                 Error code.


                                                                      52
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    server_attr           Return the attributes required for a specific
                          authentication scheme:


                          The following attribute is defined:


               server_challenge     For NDMP_AUTH_MD5 the NDMP server
                          will return a per session challenge.


 3.3 SCSI Interface

 The SCSI interface allows low level control of SCSI jukebox devices.


 3.3.1 Open SCSI Device

 Opens the specified SCSI device. This operation is required before any
 other SCSI requests can be executed. The open must be an exclusive
 open.  Only one NDMP server can open a SCSI device at a time.  The
 NDMP server can open only one SCSI or tape device at a time. An
 NDMP_DEVICE_BUSY_ERR is returned if the NDMP server already has a tape
 or SCSI device opened.


 For security reasons, NDMP_SCSI_OPEN should be supported only for the
 jukebox devices.


 Message XDR definition



    /* NDMP_SCSI_OPEN */
    struct ndmp_scsi_device
    {
      string name<>;
    };

    struct ndmp_scsi_open_request
    {
        ndmp_scsi_device        device;
    };

    struct ndmp_scsi_open_reply
    {
        ndmp_error      error;
    };



                                                                      53
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97





 Request Arguments


    name                  Name of SCSI interface device to open.  The
                          usage of this argument is NDMP-server
                          implementation dependent.  This argument can
                          be used to specify the name of an  actual
                          SCSI device but more typically the argument
                          will be used to specify the name of a  SCSI
                          pass-through driver pseudo device. The
                          specific device to be controlled is selected
                          through the set SCSI target request.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           SCSI interface device successfully opened.


    NDMP_DEVICE_OPENED_ERRThe connection already has a tape device or
                          SCSI device open.


    NDMP_DEVICE_BUSY_ERR  Another NDMP connection currently has the
                          specified device open.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized or device is
                          not a tape or jukebox.


    NDMP_NO_DEVICE_ERR    Invalid device specified.


    NDMP_IO_ERR           IO error while opening SCSI device.



                                                                      54
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97





 3.3.2 Close Device

 This request closes the currently open SCSI interface device.  No
 further requests can be made until another open request is
 successfully executed.


 Message XDR definition



    /* NDMP_SCSI_CLOSE */
    /* no request arguments */
    struct ndmp_scsi_close_reply
    {
        ndmp_error      error;
    };







 Request Arguments


    This request does not have a message body.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Device successfully closed.


    NDMP_DEV_NOT_OPEN_ERR No device currently open by the connection.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


                                                                      55
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.3.3 Get SCSI State

 This request returns the current state of the SCSI interface. The
 target information provides information about which SCSI device is
 controlled by this interface.


 Message XDR definition



    /* NDMP_SCSI_GET_STATE */
    /* no request arguments */
    struct ndmp_scsi_get_state_reply
    {
        ndmp_error      error;
        short           target_controller;
        short           target_id;
        short           target_lun;
    };






 Request Arguments


    This request does not have a message body.


 Reply Arguments


    error                 Error code.


    target_controller     Identifier of the SCSI controller to which
                          the currently targeted SCSI device is
                          attached.  -1 if no device currently is
                          targeted.


    target_id             SCSI target identifier. Specifies the SCSI
                          bus address of the targeted device. -1 if no
                          device currently is targeted.


                                                                      56
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    target_lun            Logic unit number of the targeted device. -1
                          if no device currently is targeted.


 Reply Errors


    NDMP_NO_ERR           Target device information successfully
                          returned.


    NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the
                          connection.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.3.4 Set SCSI Target

 This request selects or changes the SCSI target. When the SCSI
 interface is opened, it is not known if the NDMP server has opened a
 device file that can pass commands to a single SCSI target or to
 multiple SCSI targets. This request is used to pass the information
 describing the SCSI target to which to send commands. Additionally, if
 the target can talk to multiple targets, this allows _scanning_ the
 SCSI bus on the NDMP host for diagnostics or for  jukebox discovery.


 For security reasons this message should only be supported for tape or
 jukebox devices.


 Message XDR definition














                                                                      57
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_SCSI_SET_TARGET */
    struct ndmp_scsi_set_target_request
    {
        ndmp_scsi_device    device;
        u_short             target_controller;
        u_short             target_id;
        u_short             target_lun;
    };

    struct ndmp_scsi_set_target_reply
    {
        ndmp_error      error;
    };



 Request Arguments


    device                SCSI device name. This argument is NDMP
                          server implementation dependent. Some
                          implementations might support the targeting
                          of a device through a logical device name. If
                          this argument is used, the following
                          arguments might be ignored. If this argument
                          is not specified or supported, then the
                          following arguments must be specified.


    target_controller     Identifier of the SCSI controller to which
                          the targeted SCSI device is attached.


    target_id             SCSI target identifier. Specifies the SCSI
                          bus address of the targeted device.


    target_lun            Logic unit number of the targeted device.


 Reply Arguments


    error                 Error code.


 Reply Errors



                                                                      58
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NO_ERR           Specified SCSI device successfully targeted.


    NDMP_NO_BUS_ERR       No SCSI device currently open by the
                          connection.


    NDMP_NO_DEVICE_ERR    No device at this specified target.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized or device is
                          not a tape or jukebox.


 3.3.5 Reset Device

 This request sends a SCSI device reset message to the currently
 targeted SCSI device.


 Message XDR definition



    /* NDMP_SCSI_RESET_DEVICE */
    /* no request arguments */
    struct ndmp_scsi_reset_device_reply
    {
        ndmp_error      error;
    };




 Request Arguments


    This request does not have a message body.


 Reply Arguments


    error                 Error code.




                                                                      59
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Errors


    NDMP_NO_ERR           SCSI device successfully reset.


    NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the
                          connection.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.3.6 Reset Bus

 This request asserts a SCSI bus reset on the SCSI bus to which the
 SCSI device is attached.


 Message XDR definition



    /* NDMP_SCSI_RESET_BUS */
    /* no request arguments */
    struct ndmp_scsi_reset_bus_reply
    {
        ndmp_error      error;
    };



 Request Arguments


    This request does not have a message body.


 Reply Arguments


    error                 Error code.






                                                                      60
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Errors


    NDMP_NO_ERR           SCSI device successfully reset.


    NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the
                          connection.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.3.7 Execute CDB

 This request sends a SCSI Control Data Block to a SCSI device. If a
 check condition is generated, then the extended sense data is also
 retrieved. Data can be transferred to or from the SCSI device as part
 of the command.


 The server selects the SCSI target. The cdb is sent to the SCSI device
 in command mode. If DATA_OUT is set in the flags, then the dataout is
 sent to the SCSI device in data mode. Sometimes the host will
 disconnect from the target and wait for a reselect. If timeout is
 zero, the host will wait indefinitely for the target to reselect. If
 timeout is not zero, the host will wait timeout milliseconds for the
 target to reselect. If the reselect does not occur, an
 NDMP_TIMEOUT_ERR is returned. If the target reselects and the status
 is CHECK CONDITION, then the server executes a REQUEST SENSE cdb. If
 the DATA_IN flag is set, the server reads data from the target in data
 mode.  The SCSI status, the DATA_IN, and the extended sense data are
 returned.


 Message XDR definition












                                                                      61
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_SCSI_EXECUTE_CDB */
    const NDMP_SCSI_DATA_IN  = 0x00000001;
    const NDMP_SCSI_DATA_OUT = 0x00000002;

    struct ndmp_execute_cdb_request
    {
        u_long          flags;
        u_long          timeout;
        u_long          datain_len;
        opaque          cdb<>;
        opaque          dataout<>;
    };

    struct     ndmp_execute_cdb_reply
    {
        ndmp_error      error;
        u_char          status;
        u_long          dataout_len;
        opaque          datain<>;
        opaque          ext_sense<>;
    };




 Request Arguments


    flags                 Specifies the data transfer (if any)
                          direction. DATA_IN and DATA_OUT reference the
                          host. They refer to data from the SCSI device
                          into the host and data out of the host to the
                          SCSI device.


    timeout               Number of milliseconds to wait if a reselect
                          occurs. If timeout is zero, then the host
                          will wait  indefinitely for the target to
                          reselect.


    datain_len            If the data transfer direction is DATA_IN,
                          the expected number of data bytes to read.


    cdb                   The SCSI command data block.




                                                                      62
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    dataout               If the data transfer direction is DATA_OUT,
                          the data to be transfered to the SCSI device.


 Reply Arguments


    error                 Error code.


    status                SCSI status byte.


    dataout               If the data transfer direction is DATA_OUT,
                          the number of data bytes transfered to the
                          device.


    datain                If the data transfer direction is DATA_IN,
                          the data transfered from the SCSI device.


    ext_sense             Extended SCSI sense data.


 Reply Errors


    NDMP_NO_ERR           Message successfully processed. Does not
                          necessarily indicate that the SCSI command
                          was successfully executed. The returned SCSI
                          status byte must be used to determine if the
                          command was successful.


    NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the
                          connection.


    NDMP_IO_ERR           I/O error.


    NDMP_ILLEGAL_ARGS     Invalid argument in request message.


    NDMP_TIMEOUT_ERR      The SCSI command timed out.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


                                                                      63
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.4 TAPE Interface

 The TAPE interface provides complete control of a tape drive. If the
 tape drive is a SCSI tape drive, then the TAPE interface also
 provides low level CDB access to the tape drive. This interface is
 analogous to the rmt protocol.   The physical device is assigned when
 the server is started.


 3.4.1 Open Tape Device

 This request opens the tape device in the specified mode.  This
 operation is required before any other tape requests can be  executed.
 The device is opened exclusively; no other NDMP server can
 concurrently open the device.  Each tape device can be opened only by
 one NDMP server at a time. Each NDMP server can have only one tape or
 SCSI device open at a time. If the drive does not have a tape loaded,
 an error is returned. If the loaded media is write-protected, then the
 device can be opened only in read-only mode.


 Message XDR definition



    /* NDMP_TAPE_OPEN */
    struct ndmp_tape_device
    {
        string    name<>;
    };

    enum ndmp_tape_open_mode
    {
        NDMP_TAPE_READ_MODE,
        NDMP_TAPE_WRITE_MODE
    };

    struct ndmp_tape_open_request
    {
        ndmp_tape_device         device;
        ndmp_tape_open_mode      mode;
    };
    struct ndmp_tape_open_reply
    {
        ndmp_error      error;
    };



                                                                      64
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Request Arguments


    device                Name of tape device to open.


    mode                  Tape open mode.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Tape device successfully opened.


    NDMP_DEVICE_OPENED_ERRThe NDMP server already has a SCSI device or
                          tape device open.


    NDMP_NO_DEVICE_ERR    The specified device does not exist.


    NDMP_DEVICE_BUSY_ERR  The device is already open by another NDMP
                          server or system process.


    NDMP_IO_ERR           Device I/O error.


    NDMP_WRITE_PROTECT_ERRDevice cannot be opened in write mode because
                          the tape is write protected.


    NDMP_NO_TAPE_LOADED_ERR    No tape loaded in the tape device.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.





                                                                      65
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 3.4.2 Close Device

 This request closes the tape drive. No further tape requests can be
 processed until another tape open request is successfully executed.


 Message XDR definition



    /* NDMP_TAPE_CLOSE */
    /* no request arguments */
    struct ndmp_tape_close_reply
    {
        ndmp_error      error;
    };





 Request Arguments


    This message does not have a message body.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Tape device successfully closed.


    NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
                          connection.


    NDMP_IO_ERR           Device I/O error.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.




                                                                      66
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.4.3 Get Tape State

 This request returns the state of the tape drive interface.


 Message XDR definition



    /* NDMP_TAPE_GET_STATE */
    /* no request arguments */

    struct ndmp_u_quad
    {
        u_long    high;
        u_long    low;
    };

    const NDMP_TAPE_NOREWIND =      0x0008;
    const NDMP_TAPE_WR_PROT =       0x0010;
    const NDMP_TAPE_ERROR =         0x0020;
    const NDMP_TAPE_UNLOAD =        0x0040;

    struct ndmp_tape_get_state_reply
    {
        ndmp_error      error;
        u_long          flags;
        u_long          file_num;
        u_long          soft_errors;
        u_long          block_size;
        u_long          blockno;
        ndmp_u_quad     total_space;
        ndmp_u_quad     space_remain;
    };







 Request Arguments


    This message does not have a message body.




                                                                      67
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    error                 Error code.


    flags                 Bitmask of the following tape device mode
                          flags:


          NDMP_TAPE_NOREWIND   Upon device close, the tape will not be
                          rewound.


          NDMP_TAPE_WR_PROT    The loaded tape is write-protected.


          NDMP_TAPE_ERROR A media error was detected during the
                          previous tape operation. This bit is cleared
                          at the start of each tape operation.


          NDMP_TAPE_UNLOADThe currently loaded tape will be unloaded
                          automatically when the device is closed. Only
                          applies to media changer devices such as tape
                          stackers and jukeboxes.


    file_num              Current file position. First file on the tape
                          is file number 0.


    soft_errors           Total number of soft media errors detected
                          since the device was opened.


    block_size            Tape block size in bytes. 0 if the device is
                          in variable block size mode.


    blockno               Current tape block number. First tape block
                          is block number 0.


    total_space           Total tape capacity in bytes. 0 if this
                          feature not supported by the NDMP server
                          implementation.





                                                                      68
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    space_remain          Total remaining tape capacity in bytes. 0 if
                          this feature not supported by the NDMP server
                          implementation.


 Reply Errors


    NDMP_NO_ERR           Tape state successfully returned.


    NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
                          connection.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


    NDMP_IO_ERR           Device I/O error.


 3.4.4 MTIO

 This request provides access to the standard magnetic tape I/O
 operations. When spacing forward over a record, the tape head is
 positioned in the tape gap between the record just skipped and the
 next record. When spacing forward over file marks, the tape head is
 positioned in the tape gap between the next file mark and the record
 that follows it. When spacing backward over a record data, the tape
 head is positioned in the tape gap immediately preceding the tape
 record where the tape head is currently positioned.   When spacing
 backward over file marks, the tape head is positioned in the tape gap
 preceding the file mark. The next read would fetch the EOF.


 Message XDR definition












                                                                      69
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_TAPE_MTIO */
    enum ndmp_tape_mtio_op
    {
        NDMP_MTIO_FSF,
        NDMP_MTIO_BSF,
        NDMP_MTIO_FSR,
        NDMP_MTIO_BSR,
        NDMP_MTIO_REW,
        NDMP_MTIO_EOF,
        NDMP_MTIO_OFF
    };

    struct ndmp_tape_mtio_request
    {
        ndmp_tape_mtio_op   tape_op;
        u_long              count;
    };

    struct ndmp_tape_mtio_reply
    {
        ndmp_error          error;
        u_long              resid_count;
    };




 Request Arguments


    tape_op               One of the following tape operations:


      NDMP_MTIO_FSF       Forward space over file marks. The tape head
                          is positioned in the tape gap between the
                          file mark and the record that follows the
                          file mark.


      NDMP_MTIO_BSF       Backward space over file marks. The tape head
                          is positioned in the tape gap preceding the
                          file mark such that the next read encounters
                          EOF.


      NDMP_MTIO_FSR       Forward space over tape records. The tape
                          head is positioned in the tape gap between
                          the record just skipped and the next record.


                                                                      70
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


      NDMP_MTIO_BSR       Backward space over tape records. The tape
                          head is positioned in the tape gap preceding
                          the tape record just skipped.


      NDMP_MTIO_REW       Rewind the tape.


      NDMP_MTIO_EOF       Write end of file marks.


      NDMP_MTIO_OFF       Eject the tape from the device.


    count                 Number of operations to run.


 Reply Arguments


    error                 Error code.


    resid_count           Residual operation count. Represents the
                          number of operations that could not be done
                          due to encountering beginning of tape, end of
                          tape, end of written media, or a tape error.


 Reply Errors


    NDMP_NO_ERR           Tape operation successfully completed.


    NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
                          connection.


    NDMP_IO_ERR           Device I/O error.


    NDMP_ILLEGAL_ARGS_ERR Invalid tape operation specified.


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


                                                                      71
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_WRITE_PROTECT_ERRTape is write protected.


 3.4.5 Write

 Writes data to the tape device. The NDMP server writes the specified
 data as a single record. It is the responsibility of the NDMP client
 to ensure that the length of the data is a multiple of the tape device
 block size if the device is a fixed block device. The NDMP server does
 not buffer or pad the data. . This request is typically used by the
 NDMP client to write tape header and trailer file data.


 Message XDR definition



    /* NDMP_TAPE_WRITE */
    struct ndmp_tape_write_request
    {
        opaque              data_out<>;
    };

    struct ndmp_tape_write_reply
    {
        ndmp_error          error;
        u_long              count;
    };




 Request Arguments


    data_out              The data to be written to the tape device.


 Reply Arguments


    error                 Error code.


    count                 Number of data bytes written.


 Reply Errors




                                                                      72
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NO_ERR           All data successfully written to the tape
                          device.


    NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
                          connection.


    NDMP_IO_ERR           Device I/O error.


    NDMP_EOM_ERR          End of tape was encountered while writing.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


    NDMP_WRITE_PROTECT_ERRTape is write protected.


 3.4.6 Read

 This request reads the requested amount of data from the tape drive.
 The NDMP server always reads a complete record. If the specified
 number of bytes to read is not a multiple of the tape record size,
 then the NDMP server discards the bytes from the end of the record.
 The next read will return bytes starting from the beginning of the
 next record. To do contiguous reads, the number of bytes read must be
 a multiple of the tape record size. The client is responsible for
 ensuring that the data length is a multiple of the tape record size if
 the tape device is in fixed block size mode.


 Message XDR definition














                                                                      73
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_TAPE_READ */
    struct ndmp_tape_read_request
    {
        u_long              count;
    };

    struct ndmp_tape_read_reply
    {
        ndmp_error          error;
        opaque              data_in<>;
    };




 Request Arguments


    count                 Number of bytes to read.


 Reply Arguments


    error                 Error code.


    data_in               The data read from the tape drive.


 Reply Errors


    NDMP_NO_ERR           Requested number of bytes successfully read
                          from the tape device.


    NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
                          connection.


    NDMP_IO_ERR           Device I/O error during read.


    NDMP_EOF_ERR          End of file was encountered while reading.
                          The number of returned  data bytes can be
                          less than the number of bytes requested.



                                                                      74
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NOT_SUPPORTED_ERRThe request sequence is not supported for
                          this implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.4.7 Execute CDB

 This message behaves in exactly the same way as the SCSI_EXECUTE_CDB
 request except that it sends the cdb to the tape device. This request
 should not be used to change the state of the tape device (such as
 tape positioning).


 Message XDR definition



    /* NDMP_TAPE_EXECUTE_CDB   */
    typedef ndmp_scsi_execute_cdb_request
    ndmp_tape_execute_cdb_request;
    typedef ndmp_scsi_execute_cdb_reply ndmp_tape_execute_cdb_reply;



 3.5 DATA Interface

 This interface controls backup and recover operations.


 3.5.1 Get Data State




 This request returns data state information that can be used to
 monitor the progress of the current data operation.


 Message XDR definition











                                                                      75
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_DATA_GET_STATE */
    /* no request arguments */
    enum ndmp_data_operation
    {
        NDMP_DATA_OP_NOACTION,
        NDMP_DATA_OP_BACKUP,
        NDMP_DATA_OP_RESTORE
    };

    enum ndmp_data_state
    {
        NDMP_DATA_STATE_IDLE,
        NDMP_DATA_STATE_ACTIVE,
        NDMP_DATA_STATE_HALTED,

    };

    enum ndmp_data_halt_reason
    {
        NDMP_DATA_HALT_NA,
        NDMP_DATA_HALT_SUCCESSFUL,
        NDMP_DATA_HALT_ABORTED,
        NDMP_DATA_HALT_INTERNAL_ERROR,
        NDMP_DATA_HALT_CONNECT_ERROR,

    };

    struct ndmp_data_get_state_reply
    {
        ndmp_error              error;
        ndmp_data_operation     operation;
        ndmp_data_state         state;
        ndmp_data_halt_reason   halt_reason;
        ndmp_u_quad             bytes_processed;
        ndmp_u_quad             est_bytes_remain;
        u_long                  est_time_remain;
        ndmp_mover_addr         mover;
        ndmp_u_quad             read_offset;
        ndmp_u_quad             read_length;
    };



 Request Arguments


    This message does not have a message body.



                                                                      76
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    error                 Error code.


    operation             Data operation currently in progress.


      NDMP_DATA_OP_NOACTION  No data operation currently in progress.


      NDMP_DATA_OP_BACKUP Backup operation currently in progress.


      NDMP_DATA_OP_RESTORE   Restore operation currently in progress.


    state                 Current state of the NDMP server.


      NDMP_DATA_STATE_IDLE   No active data operation.


      NDMP_DATA_STATE_ACTIVE Data operation in progress.


      NDMP_DATA_STATE_HALTED Data operation completed.


    halt_reason           Reason the data operation is halted.


      NDMP_DATA_HALT_NA   Data operation not in progress or not in the
                          halt state.


      NDMP_DATA_HALT_SUCCESSFUL


                          Data operation completed successfully.


      NDMP_DATA_HALT_ABORTED


                          Data operation aborted by the NDMP client.


      NDMP_DATA_HALT_INTERNAL_ERROR


                                                                      77
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


                          Data operation halted due to unrecoverable
                          error incurred by the NDMP server data
                          backup/recover software.


      NDMP_DATA_HALT_CONNECT_ERROR


                          Error establishing connection to tape server.


    bytes_processed       Total number of bytes processed by the data
                          operation.


    est_bytes_remain      Estimated number of bytes processed remaining
                          to be processed by the  data operation. Can
                          be set to 0 to indicate that this feature is
                          not supported by the NDMP server.


    est_time_remain       Estimated number of seconds until the data
                          operation to completes. Can be set to 0 to
                          indicate that this feature is not supported
                          by the NDMP server.


    read_offset           Offset value specified in last
                          ndmp_notify_data_read request.


    read_len              Length value specified in last
                          ndmp_notify_data_read request.


 Reply Errors


    NDMP_NO_ERR           Data state successfully returned.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.






                                                                      78
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 3.5.2 Backup

 This request begins a backup. The id identifies the object to be
 backed up. The meaning of id is implementation dependent. The type of
 backup is also implementation dependent. The env is a list of
 parameters that might affect the behavior of the backup. The env
 returned by the DATA_GET_ENV will be saved and made available to the
 retrieval process.


 Message XDR definition



    /* NDMP_DATA_START_BACKUP */

    struct ndmp_data_start_backup_request
    {
        ndmp_mover_addr     mover;
        string              bu_type<>;
        ndmp_pval           env<>;
    };

    struct ndmp_data_start_backup_reply
    {
        ndmp_error          error;
    };







 Request Arguments


    bu_type               The name of the backup method. Backup methods
                          are NDMP-server implementation dependent.


    env                   List of parameter names and values for
                          configuring the backup method. Backup method
                          parameters are NDMP server implementation
                          dependent. See below for example parameters.


    mover                 The  mover to receive data.




                                                                      79
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Backup operation successfully started.


    NDMP_ILLEGAL_STATE_ERRA data operation is already in progress. Only
                          one data operation per connection is allowed
                          to be executing at a time.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_ILLEGAL_ARGS_ERR Invalid backup method, invalid backup method
                          parameter, or invalid backup method parameter
                          value specified.


    NDMP_ NOT_AUTHORIZED _ERR  Connection not authorized.


 The following are examples of generic environment variables that can
 be defined by the NDMP client.



 Variable Name      Meaning            Value



 PREFIX             prefix path for    path name
                    the request


 TYPE               the data type      (dump,tar,cpio)


 USER               user id to run     user name
                    backup





                                                                      80
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



 HIST               a flag to          y/n
                    maintain file
                    history






 The following are examples of environment variables that can be
 defined by dump type.



 Variable Name      Meaning            Value



 FILESYSTEM         device or file     file system or
                    system name to be  device name
                    backed up          (/dev/rsd0a)


 LEVEL              dump level         0 - 9


 EXTRACT            "y" specifies      y/n
                    to use -x option
                    for the
                    extraction, or -r
                    option for the
                    extraction.


 UPDATE             update the         TRUE/FALSE
                    dumpdates file






 The following are examples of environment variables that can be
 defined by tar type.



 Variable Name      Meaning            Value



                                                                      81
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



 FILES              list of files to   for example, ./*
                    be backed up       ./*.c ./*h






 The following are examples of environment variables that can be
 defined by cpio type.



 Variable Name      Meaning            Value



 CMD                command to         for example, find .
                    generate the file  -print
                    list for cpio.





 3.5.3 Recover

 This request recovers the files specified in nlist from the backup.
 The env is the list of parameters and values saved at the end of the
 backup.


 Message XDR definition


















                                                                      82
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_DATA_START_RECOVER */
    struct ndmp_name
    {
        string              name<>;
        string              dest<>;
        u_short             resvd;
        ndmp_u_quad         fh_info;
    };

    struct ndmp_data_start_recover_request
    {
        ndmp_mover_addr     mover;
        ndmp_pval           env<>;
        ndmp_name           nlist<>;
        string              bu_type<>;
    };

    struct ndmp_data_start_recover_reply
    {
        ndmp_error          error;
    };





























                                                                      83
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97






 Request Arguments


    mover                 The mover from which to receive data.


    env                   The backup environment that was returned from
                          a data get environment request made prior to
                          notifying the NDMP server that the backup was
                          complete through a data stop message.


    nlist                 List of files to be recovered and the
                          location to which each file is to be
                          recovered. Definition of list entry:


      name                Name of a file/directory to be recovered. The
                          name is the original backup path name and is
                          relative to the backup root directory.


      dest                Full destination pathname to be used when
                          recovering the file.


      resvd               Reserved.


      fh_info             File history tape positioning data recorded
                          when the file was backed up. This data may be
                          used by the restore method to position tape
                          for direct access data retrieval. The
                          positioning data is NDMP-server dependent.
                          Typically it will be the byte or record
                          offset from the beginning of the tape of the
                          file to be recovered. This field is ignored
                          by data method  implementations that do not
                          support this feature.


    bu_type               Name of the recover method. Recover methods
                          are NDMP server implementation dependent.


 Reply Arguments


                                                                      84
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Recover operation successfully started.


    NDMP_ILLEGAL_STATE_ERRA data operation is already in progress. Only
                          one data operation per connection is allowed
                          to execute at a time.


    NDMP_ILLEGAL_ARGS_ERR Invalid recover method, invalid recover
                          method parameter, invalid recover method
                          parameter value, or invalid name list entry
                          specified.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_ NOT_AUTHORIZED _ERR  Connection not authorized.


 3.5.4 Abort

 This request sends a message to abort the current backup or restore
 operation. The operation should be terminated as soon as possible.


 Message XDR definition



    /* NDMP_DATA_ABORT */
    /* no request arguments */
    struct ndmp_data_abort_reply
    {
        ndmp_error          error;
    };



 Request Arguments


    This message does not have a request body.


                                                                      85
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Data operation successfully terminated.


    NDMP_ILLEGAL_STATE_ERRNo data operation in progress.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.5.5 Stop

 This request sends a message to inform the NDMP server that the
 current backup is complete. The NDMP server will change to idle state
 and be ready to process another request.


 Message XDR definition



    /* NDMP_DATA_STOP */
    /* no request arguments */
    struct ndmp_data_stop_reply
    {
        ndmp_error          error;
    };



 Request Arguments


    This message does not have a message body.


 Reply Arguments


    error                 Error code.




                                                                      86
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Errors


    NDMP_NO_ERR           Message successfully processed.


    NDMP_ILLEGAL_STATE_ERRThe request cannot be run in the current
                          state.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.5.6 Get ENV

 This request gets the backup environment.  Returns the environment
 included in the data_start_backup request along with any additional
 parameters added or modified by the backup method.  The returned
 environment should be saved and passed in the data_start_recover
 request whenever data from the backup is to be recovered.


 Message XDR definition



    /* NDMP_DATA_GET_ENV */
    /* no request arguments */
    struct ndmp_data_get_env_reply
    {
        ndmp_error          error;
        ndmp_pval           env<>;
    };



 Request Arguments


 This message does not have a message body.


 Reply Arguments


    error                 Error code.


    env                   The backup method environment parameters and
                          values.


                                                                      87
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Errors


    NDMP_NO_ERR           Environment successfully returned.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_ILLEGAL_STATE_ERRIllegal state. A data operation is not
                          currently in progress.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.6 MOVER Interface

 During a backup, the mover accepts data from the data connection and
 writes the data to tape using fixed size records. During restores, the
 mover accepts requests to read portions of the data from tape. If the
 requested data is not a multiple of the record size, the mover will do
 a full record read and only return the requested amount of data. If
 the mover encounters end-of-file (EOF), media error, or reaches the
 end-of-the-data window while reading, it halts and notifies the NDMP
 client.


 3.6.1 Get Mover State

 This request returns the state of the mover.


 Message XDR definition

















                                                                      88
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_MOVER_GET_STATE */
    enum ndmp_mover_state
    {
        NDMP_MOVER_STATE_IDLE,
        NDMP_MOVER_STATE_LISTEN,
        NDMP_MOVER_STATE_ACTIVE,
        NDMP_MOVER_STATE_PAUSED,
        NDMP_MOVER_STATE_HALTED
    };

    enum ndmp_mover_pause_reason
    {
        NDMP_MOVER_PAUSE_NA,
        NDMP_MOVER_PAUSE_EOM,
        NDMP_MOVER_PAUSE_EOF,
        NDMP_MOVER_PAUSE_SEEK,
        NDMP_MOVER_PAUSE_MEDIA_ERROR
    };

    enum ndmp_mover_halt_reason
    {
        NDMP_MOVER_HALT_NA,
        NDMP_MOVER_HALT_CONNECT_CLOSED,
        NDMP_MOVER_HALT_ABORTED,
        NDMP_MOVER_HALT_INTERNAL_ERROR,
        NDMP_MOVER_HALT_CONNECT_ERROR
    };

    /* no request arguments */
    struct ndmp_mover_get_state_reply
    {
        ndmp_error              error;
        ndmp_mover_state        state;
        ndmp_mover_pause_reason pause_reason;
        ndmp_mover_halt_reason  halt_reason;
        u_long                  record_size;
        u_long                  record_num;
        ndmp_u_quad             data_written;
        ndmp_u_quad             seek_position;
        ndmp_u_quad             bytes_left_to_read;
        ndmp_u_quad             window_offset;
        ndmp_u_quad             window_length;
    };




 Request Arguments


                                                                      89
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    This message does not have a message body.


 Reply Arguments


    error                 Error code.


    state                 Current state of the NDMP server.


      NDMP_MOVER_STATE_IDLE  No active data operation.


      NDMP_MOVER_STATE_LISTEN  Awaiting connection for backup or
                             restore.


      NDMP_MOVER_STATE_ACTIVE  Data operation in progress.


      NDMP_MOVER_STATE_PAUSED  Operation paused awaiting operator
                             attention.


      NDMP_MOVER_STATE_HALTED  Operation completed.


    pause_reason          Reason the operation is paused.


      NDMP_MOVER_PAUSE_NA Operation not in progress or not in the pause
                          state.


      NDMP_MOVER_PAUSE_EOM     Operation encountered end of media. NDMP
                          client attention required.


      NDMP_MOVER_PAUSE_EOF     Operation encountered end of file. NDMP
                          client attention required.


      NDMP_MOVER_PAUSE_SEEK    Data operation requested a seek that
                          requires NDMP client intervention.


      NDMP_MOVER_PAUSE_MEDIA_ERROR  Error while reading/writing tape.



                                                                      90
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    halt_reason           Reason the operation is halted.


      NDMP_MOVER_HALT_NA  Operation not in progress or not in the halt
                          state.


      NDMP_MOVER_HALT_CONNECTION_CLOSED       Connection to data server
                          close detected.


      NDMP_MOVER_HALT_ABORTED  Operation aborted by the NDMP client.


      NDMP_MOVER_HALT_INTERNAL_ERROR     Operation halted due to
                          unrecoverable error incurred by the mover.


      NDMP_MOVER_HALT_CONNECT_ERROR Error establishing connection to
                          data server.


    record_size           Size of tape data record.


    record_num            Current tape record number.


    data_written          Total number of bytes written to tape.


    seek_position         Offset value from last ndmp_mover_read
                          request.


    bytes_left_to_read    Number of bytes remaining to be read to
                          satisfy the last ndmp_mover_read request.


    window_offset         Offset value from last ndmp_mover_set_window
                          request.


    window_length         Length value from last ndmp_mover_set_window
                          request.


 Reply Errors




                                                                      91
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_NO_ERR           Data state successfully returned.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_ NOT_AUTHORIZED _ERR  Connection not authorized.


 3.6.2 Listen

 The mover should begin listening for a data connection from a data
 server. The mover returns an address that may be used by a data server
 to connect to the mover.


 Message XDR definition


































                                                                      92
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_MOVER_LISTEN */
    enum ndmp_mover_mode
    {
        NDMP_MOVER_MODE_READ,
        NDMP_MOVER_MODE_WRITE
    };

    struct ndmp_mover_tcp_addr
    {
        u_long      ip_addr;
        u_short     port;
    };
    union ndmp_mover_addr switch (ndmp_mover_addr_type addr_type)
    {
        case NDMP_ADDR_LOCAL:
            void;
        case NDMP_ADDR_TCP:
            ndmp_mover_tcp_addr addr;
    };

    struct ndmp_mover_listen_request
    {
        ndmp_mover_mode         mode;
        ndmp_mover_addr_type    addr_type;
    };

    struct ndmp_mover_listen_reply
    {
        ndmp_error              error;
        ndmp_mover_addr         mover;
    };






 Request Arguments


    mode                  One of the following:


      NDMP_MOVER_MODE_READ     The mover should read data from the data
                          connection and write the data to tape. This
                          mode is used for  backup operations.




                                                                      93
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_MOVER_MODE_WRITE The mover should read data from tape and
                          write the data to the data connection. This
                          mode is used for restore operations.


    addr_type             One of the following:


      NDMP_ADDR_LOCAL     Mover should listen for a connection from a
                          data server that is colocated with the mover.
                          This means that the data server and mover are
                          controlled via the same NDMP client
                          connection. The communication mechanism is
                          implementation dependent.


      NDMP_ADDR_TCP       Mover should listen for a connection from a
                          remote data server using a TCP/IP port.





 Reply Arguments


    error                 Error code.


    mover                 Address on which the mover is listening for a
                          connection. If the address type is TCP, then
                          the returned address contains the IP address
                          and port number that the mover is listening
                          on.


 Reply Errors


    NDMP_NO_ERR           Listen successful.


    NDMP_ILLEGAL_STATE_ERRMover not currently in idle state.


    NDMP_ILLEGAL_ARGS_ERR Invalid mode or address type specified.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


                                                                      94
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_ NOT_AUTHORIZED _ERR  Connection not authorized.


 3.6.3 Set Record Size

 This request sets the record size used by the mover for all tape reads
 and writes. When writing to tape, the mover will buffer data until a
 full record has been buffered before writing the record to tape. The
 client is responsible for setting the record size to a multiple of the
 tape block size if the tape device being used is a fixed block size
 device.


 Message XDR definition



    /* NDMP_MOVER_SET_RECORD_SIZE */
    struct ndmp_mover_set_record_size_request
    {
        u_long                  len;
    };

    struct ndmp_mover_set_record_size_reply
    {
        ndmp_error              error;
    };




 Request Arguments


    len                   Record size in bytes.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Record size successfully set.





                                                                      95
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_ILLEGAL_ARGS_ERR Invalid record size specified.  The maximum
                          record size is implementation dependent


    NDMP_ILLEGAL_STATE_ERRIllegal state. The record size may only be
                          set when in the idle state.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_ NOT_AUTHORIZED _ERR  Connection not authorized.


 3.6.4 Set Window

 This request defines the valid data window. The window begins at the
 first record of the current tape file and extends for the specified
 number of bytes.  After reading all data specified by the window, the
 mover will notify the NDMP client that a tape change/seek is required.



    Message XDR definition
    /* NDMP_MOVER_SET_WINDOW */
    struct ndmp_mover_set_window_request
    {
        ndmp_u_quad             offset;
        ndmp_u_quad             length;
    };

    struct ndmp_mover_set_window_reply
    {
        ndmp_error              error;
    };






 Request Arguments


    offset                The data stream byte offset of the first byte
                          in the window.


    length                Number of bytes in the window.


                                                                      96
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Window successfully set.


    NDMP_ILLEGAL_ARGS_ERR Invalid window specified.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_ILLEGAL_STATE_ERRIllegal state. A window can be set only when
                          in the listen or paused state.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.6.5 Continue

 This request notifies the mover to continue reading/writing tape data.
 This request is sent after the NDMP client has completed a tape change
 or tape positioning.


 Message XDR definition



    /* NDMP_MOVER_CONTINUE */
    /* no request arguments */
    struct ndmp_mover_continue_reply
    {
        ndmp_error              error;
    };



 Request Arguments


    This message does not have a message body.


                                                                      97
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Mover successfully continued.


    NDMP_NOT_SUPPORTED_ERRThe request is not supported for this
                          implementation.


    NDMP_ILLEGAL_STATE_ERRIllegal state. Mover not currently in the
                          paused state.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.6.6 Abort

 This request aborts the mover. The mover stops reading or writing data
 from/to tape and closes the data connection.


 Message XDR definition



    /* NDMP_MOVER_ABORT */
    /* no request arguments */
    struct ndmp_mover_abort_reply
    {
            ndmp_error          error;
    };



 Request Arguments


    This message does not have a message body.


 Reply Arguments



                                                                      98
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Mover successfully aborted.


    NDMP_ILLEGAL_STATE_ERRIllegal state. Mover not currently in the
                          listen, active, or paused state.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.6.7 Stop

 This request frees any resources associated with the mover and returns
 the mover to the idle state.



    Message XDR definition
    /* NDMP_MOVER_STOP */
    /* no request arguments */
    struct ndmp_mover_stop_reply
    {
            ndmp_error          error;
    };



 Request Arguments


    This message does not have a message body.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Mover successfully stopped.



                                                                      99
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    NDMP_ILLEGAL_STATE_ERRIllegal state. Mover not currently in the
                          halted state.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.6.8 Read

 This request notifies  the mover to begin reading backup data from the
 tape drive and write the data to the data connection.  The mover will
 continue to write data to the data connection until the requested
 number of bytes have been read from tape and written to the data
 connection.  If EOF or the end-of-the-data window is encountered, the
 mover will  notify the NDMP client and then enter the paused state.
 While fulfilling this request, the mover should continue to accept
 messages from the NDMP client. It is invalid to issue another read
 request while the current request is in progress.


 Message XDR definition



    /* NDMP_MOVER_READ */
    struct ndmp_mover_read_request
    {
        ndmp_u_quad             offset;
        ndmp_u_quad             length;
    };

    struct ndmp_mover_read_reply
    {
            ndmp_error          error;
    };




 Request Arguments


    offset                Offset within the data stream of the first
                          byte to be sent to the data connection. The
                          mover should seek the tape to the record
                          containing the requested offset and then read
                          and discard data until the offset has been
                          reached. If the offset is outside of the
                          currently set data window, the mover should



                                                                     100
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


                          notify the NDMP client that a seek is
                          required.


    length                Number of data bytes to be read and send to
                          the data connection.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Read successfully started.


    NDMP_ILLEGAL_STATE_ERRIllegal state. Mover not currently in the
                          paused state.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.


 3.6.9 Close

 This request notifies the mover to close the data connection. The NDMP
 client will send this request after a backup operation has completed
 or after all data for a restore operation has been read.


 Message XDR definition



    /* NDMP_MOVER_CLOSE */
    /* no request arguments */
    struct ndmp_mover_close_reply
    {
            ndmp_error          error;
    };




 Request Arguments



                                                                     101
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    This message does not have a message body.


 Reply Arguments


    error                 Error code.


 Reply Errors


    NDMP_NO_ERR           Data connection successfully closed.


    NDMP_ILLEGAL_STATE_ERRIllegal state. Data connection not open.


    NDMP_NOT_AUTHORIZED_ERR    Connection not authorized.

































                                                                     102
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



 4. NDMP Client Interfaces

 This section defines the protocol interfaces implemented by the NDMP
 client.


 4.1 NOTIFY Interface

 This interface is used by the NDMP server to let the NDMP client know
 that the NDMP server requires attention.


 4.1.1 Notify Data Halted

 This message is used to notify the NDMP client that the NDMP data
 server has halted


 Message XDR definition



    /* NDMP_NOTIFY_DATA_HALTED */
    struct ndmp_notify_data_halted_request
    {
        ndmp_data_halt_reason   reason;
        string                  text_reason<>;
    };




 Request Arguments


    reason                Reason the data operation halted.


      NDMP_HALT_NA        Data operation not in progress or not in the
                          halt state.


      NDMP_HALT_SUCCESSFUL     Data operation completed successfully.


      NDMP_HALT_ABORTED   Data operation aborted by the NDMP client.





                                                                     103
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


      NDMP_HALT_MEDIA_ERROR    Data operation halted due to
                          unrecoverable media error.


      NDMP_HALT_INTERNAL_ERROR Data operation halted due to
                          unrecoverable error incurred by the NDMP
                          server or the data backup/recover method.


      NDMP_HALT_RESVD1    Reserved.


    text_reason           Diagnostic error message. NDMP server
                          implementation dependent.


 Reply Arguments


    This message does not have a message body.


 4.1.2 Notify Connected

 This message is sent in response to a connection establishment
 attempt. This message is always the first message sent on a new
 connection. It is also used prior to NDMP server shutdown to inform
 the client that the server is shutting down.


 Message XDR definition



    /* NDMP_NOTIFY_CONNECTED */
    enum ndmp_connect_reason
    {
        NDMP_CONNECTED,  /* Connect sucessfully */
        NDMP_SHUTDOWN,   /* Connection shutdown */
        NDMP_REFUSED     /* reach the maximum number of connections */
    };
    struct ndmp_notify_connected_request
    {
        ndmp_connect_reason reason;
        u_short             protocol_version;
        string              text_reason<>;
    };





                                                                     104
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Request Arguments


    reason                Reason code describing the current connection
                          state.


      NDMP_CONNECTED      NDMP connection successfully established.
                          This code will be returned in a message sent
                          immediately after successful connection
                          establishment.


      NDMP_SHUTDOWN       The NDMP server is shutting down the NDMP
                          connection. Will typically used  when
                          shutting down the NDMP host to gracefully
                          close down the NDMP  connection.


      NDMP_REFUSED        NDMP connection refused by the NDMP server.
                          This code will be returned in a message sent
                          immediately after a connection establishment
                          attempt to notify the NDMP client that the
                          NDMP server is not able to accept the
                          connection at the current time. This will
                          typically be used if the  NDMP-server
                          implementation limits the total number of
                          concurrent NDMP connections, when NDMP
                          services on the NDMP host are disabled, or
                          when the NDMP host is in the process of
                          shutting down.


    protocol_version      Version of protocol being used.


    text_reason           NDMP-server implementation dependent message
                          indicating why the connection is being
                          shutdown or refused.


 Reply Arguments


    This message does not have a message body.







                                                                     105
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 4.1.3 Notify Mover Halted

 This message is used to notify the NDMP client that the NDMP mover has
 entered the halted state.


 Message XDR definition



    /* NDMP_NOTIFY_MOVER_HALTED */
    struct  ndmp_notify_mover_halted_request
    {
        ndmp_mover_halt_reason  reason;
        string                  text_reason<>;
    };




 Request Arguments


    reason                Reason the mover halted.


      NDMP_MOVER_HALT_NA            Operation not in progress or not in
                                    the halt state.


      NDMP_MOVER_HALT_CONNECTION_CLOSED   Connection to data server
                                    close detected.


      NDMP_MOVER_HALT_ABORTED       Operation aborted by the NDMP
                                    client.


      NDMP_MOVER_HALT_INTERNAL_ERROR     Operation halted due to
                                    unrecoverable error incurred by the
                                    mover.


      NDMP_MOVER_HALT_CONNECT_ERROR Error establishing connection to
                                    data server.


    text reason           Message providing additional diagnostic
                          information. NDMP server implementation
                          dependent.


                                                                     106
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    This message does not have a message body.


 4.1.4 Notify Mover Paused

 This message is used to notify the NDMP client that the NDMP mover has
 paused.


 Message XDR definition



    /* NDMP_NOTIFY_MOVER_PAUSED */
    struct ndmp_notify_mover_paused_request
    {
        ndmp_mover_pause_reason reason;
        ndmp_u_quad             seek_position;
    };




 Request Arguments


    reason                Reason the mover paused.


      NDMP_MOVER_PAUSE_NA Operation not in progress or not in the pause
                          state.


      NDMP_MOVER_PAUSE_EOM     Operation encountered end of media. NDMP
                          client attention required.


      NDMP_MOVER_PAUSE_EOF     Operation encountered end of file. NDMP
                          client attention required.


      NDMP_MOVER_PAUSE_SEEK    Data operation requested a seek that is
                          outside of the current data window. NDMP
                          client attention required.


      NDMP_MOVER_PAUSE_MEDIA_ERROR  Error while reading/writing tape.


                                                                     107
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    seek_position         If reason is NDMP_MOVER_PAUSE_SEEK, indicates
                          the desired data stream seek position. The
                          NDMP client should load the tape containing
                          the requested seek_position, position the
                          tape appropriately, set a new data window,
                          and then continue the mover.


 Reply Arguments


    This message does not have a message body.


 4.1.5 Notify DATA Read

 This message is used to notify the NDMP client that the NDMP server
 wants to read data from a remote mover. The NDMP server must send at
 least one NOTIFY_DATA_READ message to the NDMP client if the mover is
 remote. In response to this message, the NMDP client will sent an
 NDMP_MOVER_READ message to the remote mover.


 Message XDR definition



    /* NDMP_NOTIFY_DATA_READ */
    struct  ndmp_notify_data_read_request
    {
        ndmp_u_quad             offset;
        ndmp_u_quad             length;
    };




 Request Arguments


    offset                Data stream offset of first byte that should
                          be sent to the data connection.


    length                Number of data bytes the mover should read
                          from tape and sent to the data connection.


 Reply Arguments



                                                                     108
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    This message does not have a message body.


 4.2 LOGGING Interface

 This interface is used by the NDMP server to send informational and
 diagnostic data to the NDMP client. This data is used by the client to
 monitor the progress of the currently running data operation and to
 diagnose problems.


 4.2.1 Log

 This request sends an informational message to the NDMP client. It is
 typically used to send log messages generated by the backup or recover
 method.


 Message XDR definition



    /* NDMP_LOG_LOG */
    struct ndmp_log_log_request
    {
        string              entry<>;
    };



 Request Arguments


    entry                 Text message.


 Reply Arguments


    This message does not have a message body.


 4.2.2 Debug

 This request sends a diagnostic message to the NDMP client. This
 message is typically used to diagnose NDMP server problems. The
 mechanism used to enable/disable diagnostic messages is NDMP server
 dependent. This feature is primarily intended to be used during
 software development and when troubleshooting.



                                                                     109
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Message XDR definition



    /* NDMP_LOG_DEBUG */
    enum ndmp_debug_level
    {
        NDMP_DBG_USER_INFO,
        NDMP_DBG_USER_SUMMARY,
        NDMP_DBG_USER_DETAIL,
        NDMP_DBG_DIAG_INFO,
        NDMP_DBG_DIAG_SUMMARY,
        NDMP_DBG_DIAG_DETAIL,
        NDMP_DBG_PROG_INFO,
        NDMP_DBG_PROG_SUMMARY,
        NDMP_DBG_PROG_DETAIL
    };

    struct ndmp_log_debug_request
    {
        ndmp_debug_level    level;
        string              message<>;
    };



 Request Arguments


    level                 The level is divided into two components. The
                          first component is  the intended audience.
                          The audience can be the end user (user),  the
                          technical support personnel (diag), or  the
                          development engineer (prog). The second
                          component is the level of  detail requested.
                          The level of  detail is specified as info,
                          summary, and detail.  There are no specific
                          guidelines on the use of level of  detail,
                          but a message that typically is encountered
                          less that 10 times during  a backup should be
                          an info level; a message that is encountered
                          more  than 100 times should be at a detail
                          level.


    message               Diagnostic text message


 Reply Arguments



                                                                     110
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    This message does not have a message body.


 4.2.3 File Recovered

 This request sends a file recover message to the NDMP client. Used
 during recovery to notify the NDMP client that a file from the
 recovery list sent in the ndmp_data_start_recover request has or has
 not been recovered. This message should not be sent for every
 recovered or failed file, just files having a name that matches a name
 in the recovery list.


 Message XDR definition



    /* NDMP_LOG_FILE */
    struct ndmp_log_file_request
    {
        string              name<>;
        u_short             reserved;
        ndmp_error          error;
    };



 Request Arguments


    name                  File name.


    reserved              Reserved.


    error                 Error code.


      NDMP_NO_ERR              File successfully recovered.


      NDMP_PERMISSION_ERR      Some sort of permission problem.


      NDMP_FILE_NOT_FOUND_ERR  File not found during restore.


 Reply Arguments


                                                                     111
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    This message does not have a message body.



















































                                                                     112
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




 4.3 FILE HISTORY Interface

 The NDMP server uses this interface to send file history entries to
 the NDMP client. The file history entries provide a file by file
 record of every file backed up by the backup method.  The file history
 data is defined using a UNIX filesystem  compatible format. There are
 two sets of messages for sending file history data. The first set
 consists of the add path message. The first set is for use by filename
 based backup methods  (such as the UNIX tar and cpio commands)  for
 which the full pathname and file attributes are available at the time
 each file is backed up. The second set consists of the add directory
 and add node messages. The second set is for use by inode based backup
 methods (such as the UNIX dump command) for which the full pathname is
 not necessarily available at the time each file is backed up. Some
 backup methods might not support the sending of file history data.


 4.3.1 Add Unix Path

 This request adds a list of file paths with the corresponding
 attribute entries to the file history. The name could be the full
 pathname or the relative pathname to the backup root directory.


 Message XDR definition

























                                                                     113
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97




    /* NDMP_FH_ADD_UNIX_PATH */
    typedef string          ndmp_unix_path<>;
    enum ndmp_unix_file_type
    {
        NDMP_FILE_DIR,
        NDMP_FILE_FIFO,
        NDMP_FILE_CSPEC,
        NDMP_FILE_BSPEC,
        NDMP_FILE_REG,
        NDMP_FILE_SLINK,
        NDMP_FILE_SOCK
    };

    struct ndmp_unix_file_stat
    {
        ndmp_unix_file_type     ftype;
        u_long                  mtime;
        u_long                  atime;
        u_long                  ctime;
        u_long                  uid;
        u_long                  gid;
        u_long                  mode;
        ndmp_u_quad             size;
        ndmp_u_quad             fh_info;
    };

    struct ndmp_fh_unix_path
    {
        ndmp_unix_path          name;
        ndmp_unix_file_stat     fstat;
    };

    struct ndmp_fh_add_unix_path_request
    {
        ndmp_fh_unix_path       paths<>;
    };



 Request Arguments


    paths                 Array of file history path entries. Each
                          entry contains:


    name                  The full pathname of the backed up file, or
                          relative to the backup root directory.


                                                                     114
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


    fstat                 File attribute data consisting of:


      ftype               File type.


      mtime               Time the file was last modified (in seconds
                          since 00:00:00 GMT, Jan 1, 1970).


      atime               Time the file was last accessed (in seconds
                          since 00:00:00 GMT, Jan 1, 1970).


      ctime               Time the file status was last modified  (in
                          seconds since 00:00:00 GMT, Jan 1, 1970).
                          Indicates the last time that either the file
                          data or the file attributes were modified.


      uid                 File owner identifier.


      gid                 File group identifier.


      mode                File mode flags.


      size                File size.


      fh_info             File history tape positioning data
                          representing the tape position  at the time
                          the file was written to tape. This data may
                          be used by the restore method to perform tape
                          positioning for direct access file retrieval.
                          The positioning data is NDMP server
                          dependent. Typically it will be the byte or
                          record offset from the beginning of the tape
                          of the file to be recovered. This field is
                          ignored by data method  implementations that
                          do not support this feature.


 Reply Arguments


    This message does not have a message body.



                                                                     115
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 4.3.2 Add Unix Dir

  This message is used to support directory/inode types of backup
 formats.  The node number can be any  unique number that matches a
 corresponding fh_add_unix_node message.


 Message XDR definition



    /* NDMP_FH_ADD_UNIX_DIR */
    struct ndmp_fh_unix_dir
    {
        ndmp_unix_path      name;
        u_long              node;
        u_long              parent;
    };

    struct ndmp_fh_add_unix_dir_request
    {
        ndmp_fh_unix_dir    dirs<>;
    };



 Request Arguments


    dirs                  Array of directory entries. Each entry
                          contains:


      name                Node file name. This is not a full pathname;
                          just the basename relative to the node's
                          parent directory.


      node                Node identifier that matches a node in a
                          corresponding add node message. NDMP-server
                          implementation dependent but will typically
                          be the inode number of the file.


      parent              Node identifier of the node's parent
                          directory. NDMP-server implementation
                          dependent but will typically be the inode
                          number of the file.




                                                                     116
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    This message does not have a message body.


 4.3.3 Add Unix Node

 This request adds a list of file attribute entries to the file
 history.  These entries must match a corresponding node number from a
 previous add directory message. For each file, this message must be
 sent after the corresponding ndmp_fh_add_unix_dir message.


 Message XDR definition



    /* NDMP_FH_ADD_UNIX_NODE */
    struct ndmp_fh_unix_node
    {
        ndmp_unix_file_stat     fstat;
        u_long                  node;
    };

    struct ndmp_fh_add_unix_node_request
    {
        ndmp_fh_unix_node       nodes<>;
    };






 Request Arguments


    nodes                 Array of file history node entries. Each
                          entry contains:


      fstat               File attribute data.


      node                Node identifier that matches a node in a
                          corresponding add directory message. NDMP-
                          server implementation dependent but will
                          typically be the inode number of the file.



                                                                     117
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97


 Reply Arguments


    This message does not have a message body.
















































                                                                     118
 Stager,Hitz

 Internet Draft Network Data Management Protocol      09/04/97



 5. References

 [1] RFC 1832 , "XDR: External Data Representation Standard", R.
 Srinivasan, Sun Microsystems, August 1995


 [2] RFC 1321 , "The MD5 Message-Digest Algorithm", R. Rivest, MIT
 Laboratory for Computer Science and RSA Data Security, Inc. , April
 1992





 6. Security

 The NDMP client normally is authenticated by the NDMP server using a
 secure MD5 digest.  However, the NDMP server optionally can
 authenticate using a clear text password or even permit access without
 authentication. Once authenticated, privileges are not specified by
 the NDMP protocol, but it is expected that NDMP-server implementations
 will permit data to be transferred to and from tape using the
 protocol.


 The NDMP_SCSI_OPEN permits low level access to SCSI jukebox devices.
 The NDMP server should prevent access to other SCSI devices (such as
 disk drives) to prevent the NDMP client from bypassing filesystem
 security.


 File history information is transferred to the NDMP client through a
 TCP/IP connection.


 7. Authors
 D. Hitz                                 R. Stager
 Network Appliance                       PDC Software
 2770 San Tomas Expressway.              111C Lindbergh Ave
 Santa Clara, CA 95051                   Livermore, CA 94550
 USA                                     USA
 Tel: 408-367-3106                       Tel: 510-449-6881
 Fax: 408-367-3151                       Fax: 415-428-5151
 email: hitz@netapp.com                  email: rstager@pdc.com
 http://www.netapp.com                   http://www.pdc.com




 Expires:            March 1998

                                                                     119
 Stager,Hitz