[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04

            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            Network Working Group                                    Harald Skardal
            INTERNET DRAFT                                  Network Appliance, Inc.
            Category: Applications                                    James Bunnell
            Document: draft-skardal-ndmpv4-04.txt                     Spectra Logic
                                                                 Sudakar V. Chellam
                                                                                IBM
                                                                        Tim Gardner
                                                             Chewcoba Systems, Inc.
                                                                      Clive Hendrie
                                                                BlueArc Corporation
                                                                    Kiyoshi Komatsu
                                                            Network Appliance, Inc.
                                                                          Greg Linn
                                                            Network Appliance, Inc.
                                                                        Dave Manley
                                                                        Independent
                                                                   Gordon Waidhofer
                                                                            Traakan
                                                                           Jim Ward
                                                                       Reliaty, Inc.
            
            
            
            
            
            Network Data Management Protocol Version 4
            
            Status of this Memo
               This document is an Internet-Draft and is in full conformance with
               all provisions of Section 10 of RFC2026.
            
               Internet-Drafts are working documents of the Internet Engineering
               Task Force (IETF), its areas, and its working groups. Note that other
               groups may 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 become obsolete 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."
            
               The list of current Internet-Drafts can be accessed at
               http://www.ietf.org/ietf/1id-abstracts.txt
            
               The list of Internet-Draft Shadow Directories can be accessed at
               http://www.ietf.org/shadow.html.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                    [Page 1]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            Abstract
               The Network Data Management Protocol (NDMP) defines a mechanism and
               protocol for controlling backup, recovery, and other transfers of
               data between primary and secondary storage.
            
               The NDMP architecture separates the network attached Data Management
               Application (DMA), Data Servers and Tape Servers participating in
               archival or recovery operations. NDMP also provides low-level control
               of tape devices and SCSI media changers.
            
               The XDR and TCP/IP protocols are foundations for NDMP.
            
               The key goals of NDMP include interoperability, contemporary
               functionality, and extensibility.
            
            
            
            Copyright
               Copyright (C) The Internet Society (2001).  All Rights Reserved.
            
            
            
            Table of Contents
            1. Overview......................................................6
            1.1. Motivation..................................................6
            1.2. Audience....................................................6
            1.3. Terminology.................................................6
            1.4. Key Words...................................................9
            2. Architecture.................................................10
            2.1. Architectural Model........................................10
            2.2. NDMP Topologies............................................10
            2.2.1. Simple NDMP Configuration................................11
            2.2.2. NDMP Two Drive Configuration.............................12
            2.2.3. Tape Library Configuration...............................13
            2.2.4. Three-Way Configuration..................................14
            2.2.5. Data Replication Configurations..........................14
            2.3. Key NDMP Concepts..........................................17
            2.3.1. Session State............................................17
            2.3.2. Control Streams..........................................17
            2.3.3. Data Streams.............................................18
            2.3.4. NDMP Services............................................18
            2.3.4.1. Data Service...........................................19
            2.3.4.2. Tape Service...........................................19
            2.3.4.3. SCSI Pass Through Service..............................19
            2.3.5. Other Mechanisms.........................................19
            2.3.5.1. Tape Format and Mover Window...........................19
            2.3.5.1.1. Mover Records........................................20
            2.3.5.1.2. Tape Content Ownership...............................20
            2.3.5.1.3. Control of the Tape Drive............................20
            2.3.5.1.4. Mover Window.........................................20
            2.3.5.1.5. Mover Window Usage While Writing.....................21
            2.3.5.1.6. Mover Window Usage While Reading.....................22
            2.3.5.2. File History...........................................22
            2.3.5.3. Direct Access Recovery.................................23
            
            
            
            Expires October 2003                                    [Page 2]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.4. Character and Role.........................................23
            2.5. Protocol Interfaces........................................24
            2.5.1. Messages from DMA to NDMP Server.........................24
            2.5.2. Messages from the NDMP Server to the DMA.................25
            2.5.3. Optional Interfaces and Messages.........................26
            2.5.4. NDMP Server Extensions...................................27
            2.5.4.1. Proprietary vs. Standard Extensions:...................27
            2.5.4.2. The Class..............................................28
            2.5.4.2.1. Class Versions.......................................28
            2.5.4.2.2. Class Version vs. Core NDMP Version..................29
            2.5.4.3. Discovery and Negotiation..............................29
            2.5.4.4. Extension Management...................................30
            2.5.4.4.1. The NDMP Class Space Allocation......................30
            2.5.4.4.2. Extension Allocation and Management..................30
            2.6. Messaging Protocol.........................................31
            2.7. Message Header.............................................31
            2.8. Error Reporting............................................33
            2.8.1 Error Codes In Core NDMP..................................33
            2.8.2 Error Codes in NDMP Extensions............................37
            2.9. Message Numbers............................................37
            2.10. Message Definitions.......................................39
            2.11. Message Sequencing and State Tables.......................40
            2.11.1. General Rules...........................................40
            2.11.2. Connection..............................................40
            2.11.3. Authentication..........................................41
            2.11.4. SCSI and Tape Devices...................................42
            2.11.5. Data State Diagram......................................42
            2.11.5.1. Example Race Condition................................46
            2.11.6. Mover State Table.......................................47
            2.12. Supporting XDR Definitions for NDMP.......................51
            2.13. Protocol Version Compatibility............................59
            3. NDMP Server Interfaces.......................................60
            3.1. Connect Interface..........................................60
            3.1.1. NDMP_CONNECT_OPEN........................................61
            3.1.2. NDMP_CONNECT_CLIENT_AUTH.................................63
            3.1.3. NDMP_CONNECT_CLOSE.......................................66
            3.1.4. NDMP_CONNECT_SERVER_AUTH.................................67
            3.2. Config Interface...........................................69
            3.2.1. NDMP_CONFIG_GET_HOST_INFO................................70
            3.2.2. NDMP_CONFIG_GET_SERVER_INFO..............................71
            3.2.3. NDMP_CONFIG_GET_CONNECTION_TYPE..........................73
            3.2.4. NDMP_CONFIG_GET_AUTH_ATTR................................75
            3.2.5. NDMP_CONFIG_GET_BUTYPE_INFO..............................77
            3.2.6. NDMP_CONFIG_GET_FS_INFO..................................82
            3.2.7. NDMP_CONFIG_GET_TAPE_INFO................................85
            3.2.8. NDMP_CONFIG_GET_SCSI_INFO................................87
            3.2.9 NDMP_CONFIG_GET_EXT_LIST..................................89
            3.2.10 NDMP_CONFIG_SET_EXT_LIST.................................91
            3.3. SCSI Interface.............................................93
            3.3.1. NDMP_SCSI_OPEN...........................................94
            3.3.2. NDMP_SCSI_CLOSE..........................................96
            3.3.3. NDMP_SCSI_GET_STATE......................................97
            3.3.4. NDMP_SCSI_RESET_DEVICE...................................98
            3.3.5. NDMP_SCSI_EXECUTE_CDB....................................99
            3.4. Tape Interface............................................102
            
            
            
            Expires October 2003                                    [Page 3]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.1. Tape Model..............................................102
            3.4.2. NDMP_TAPE_OPEN..........................................104
            3.4.3. NDMP_TAPE_CLOSE.........................................106
            3.4.4. NDMP_TAPE_GET_STATE.....................................108
            3.4.5. NDMP_TAPE_MTIO..........................................111
            3.4.6. NDMP_TAPE_WRITE.........................................115
            3.4.7. NDMP_TAPE_READ..........................................118
            3.4.8. NDMP_TAPE_EXECUTE_CDB...................................121
            3.5. Data Interface............................................122
            3.5.1. Data Interface Overview.................................122
            3.5.1.1. Data Interface Variables & Constants..................123
            3.5.2. Data Message Definitions................................127
            3.5.2.1. NDMP_DATA_CONNECT.....................................128
            3.5.2.2. NDMP_DATA_LISTEN......................................130
            3.5.2.3. NDMP_DATA_START_BACKUP................................133
            3.5.2.4. NDMP_DATA_START_RECOVER...............................136
            3.5.2.5. NDMP_DATA_START_RECOVER_FILEHIST......................142
            3.5.2.6. NDMP_DATA_GET_STATE...................................146
            3.5.2.7. NDMP_DATA_GET_ENV.....................................147
            3.5.2.8. NDMP_DATA_STOP........................................149
            3.5.2.9. NDMP_DATA_ABORT.......................................150
            3.6. Mover Interface...........................................151
            3.6.1. Mover Interface Overview................................151
            3.6.1.1. Mover Interface Variables & Constants.................152
            3.6.2. Mover Message Definitions...............................158
            3.6.2.1. NDMP_MOVER_SET_RECORD_SIZE............................160
            3.6.2.2. NDMP_MOVER_SET_WINDOW.................................162
            3.6.2.3. NDMP_MOVER_CONNECT....................................165
            3.6.2.4. NDMP_MOVER_LISTEN.....................................168
            3.6.2.5. NDMP_MOVER_READ.......................................172
            3.6.2.6. NDMP_MOVER_GET_STATE..................................175
            3.6.2.7. NDMP_MOVER_CONTINUE...................................176
            3.6.2.8. NDMP_MOVER_CLOSE......................................178
            3.6.2.9. NDMP_MOVER_ABORT......................................179
            3.6.2.10. NDMP_MOVER_STOP......................................180
            4. DMA Interfaces..............................................181
            4.1. Notify Interface..........................................181
            4.1.1. NDMP_NOTIFY_DATA_HALTED.................................182
            4.1.2. NDMP_NOTIFY_CONNECTION_STATUS...........................183
            4.1.3. NDMP_NOTIFY_MOVER_HALTED................................185
            4.1.4. NDMP_NOTIFY_MOVER_PAUSED................................186
            4.1.5. NDMP_NOTIFY_DATA_READ...................................187
            4.2. Log Interface.............................................188
            4.2.1. NDMP_LOG_MESSAGE........................................189
            4.2.2. NDMP_LOG_FILE...........................................192
            4.3. File History Interface....................................194
            4.3.1. NDMP_FH_ADD_FILE........................................195
            4.3.2. NDMP_FH_ADD_DIR.........................................198
            4.3.3. NDMP_FH_ADD_NODE........................................200
            5. Security....................................................201
            7. Recognition of Prior Work...................................203
            8. Authors and Contributors....................................204
            8.1. Document Editor...........................................204
            8.2. Authors' Addresses........................................204
            8.3. Contributors..............................................205
            
            
            
            Expires October 2003                                    [Page 4]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            Appendixes:....................................................206
            Appendix A: NDMP Extension Management..........................206
            Appendix B: NDMP Extensions Test Message.......................209
            Appendix C: XDR for an NDMP Implementation.....................212
            Appendix D: Workflow...........................................232
            D.1. Backup....................................................232
            D.2. Data Recovery.............................................236
            D.2.1. Recovery Exceptions.....................................239
            D.2.1.1. End-of-file...........................................239
            D.2.1.2. Media error...........................................240
            D.2.1.3. User aborted..........................................241
            D.3 Direct Access Recovery.....................................242
            D.4 Loss of Data Connection....................................243
            D.5 Using a Jukebox............................................244
            D.5.1 Backing Up and Restoring Using a Jukebox.................244
            D.5.2 Initializing a Jukebox...................................245
            D.5.3 Jukebox Exception Handling...............................246
            D.6 Tape File Duplication......................................246
            D.7 Network Copy...............................................248
            D.8 NDMP Exceptions............................................250
            D.8.1 End-of-media.............................................250
            D.8.2 Media Errors.............................................252
            D.8.3 User Aborted.............................................253
            D.8.4 Loss of Data Connection..................................254
            D.8.5 Broken Connection........................................255
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                    [Page 5]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
            
            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/recovery 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
               recovery. 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 or Network Data Management Protocol
                  An open protocol for enterprise-wide, network-based data
                  management such as backup and recovery. NDMP is a control
                  protocol used to control the NDMP services participating in the
                  session. NDMP specifies the format and means of transmission of
                  messages and payload data between a DMA and an NDMP server, and
                  between two NDMP servers.
            
                  NDMP is increasingly being used for replication/copying of data
                  in primary or secondary storage systems.
            
               DMA or Data Management Application
                  The Data Management Application (DMA) that controls the NDMP
                  session. In NDMP there is a master-slave relationship. The DMA is
                  the session master; the NDMP services are the slaves.
            
                  In NDMP versions 1, 2, and 3 the term "NDMP client" was used
                  instead of ôDMA.ö
            
               NDMP Host
                  The host computer system 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.
            
            
            
            Expires October 2003                                    [Page 6]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               NDMP Service
                  The state machine on the NDMP host accessed with the Internet
                  protocol and controlled using the NDMP protocol. This term is
                  used independently of implementation.
            
                  There are three types of NDMP Services: Data Service, Tape
                  Service, and SCSI Service.
            
               NDMP Server
                  An instance of one or more distinct NDMP services controlled by a
                  single NDMP control connection. Thus a Data/Tape/SCSI Server is
                  an NDMP Server providing Data, Tape, and SCSI services.
            
               NDMP Session
                  The configuration of one DMA and two NDMP services to perform a
                  data management operation such as a backup or a recovery.
            
               Primary Storage System
                  A storage system that stores live or "in production" data on an
                  active file system. Examples are direct or SAN attached storage
                  in application servers, or dedicated storage appliances such as
                  filers.
            
                  A primary storage system hosts an NDMP data service.
            
               Secondary Storage System
                  A storage system used for archiving or data protection. Examples
                  are application servers with direct attached tape drives,
                  libraries or robots, or dedicated network attached archiving/data
                  protection appliances.
            
                  A secondary storage system hosts an NDMP tape service and often a
                  SCSI service.
            
               Backup or Backup Operation
                  Copying selected data from primary storage to secondary storage.
            
               Recovery or Recovery Operation
                  Copying selected data from secondary storage to primary storage.
            
               Backup Data
                  The resulting data from a Backup Operation.
            
               Recovery data
                  The resulting data from a recovery Operation.
            
               Replication
                  The copying of data between two services of the same type.
                  Examples are data to data service replication or tape to tape
                  service replication.
            
            
            
            
            
            Expires October 2003                                    [Page 7]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Control Connection
                  A bi-directional TCP/IP connection that carries XDR encoded NDMP
                  messages between the DMA and the NDMP Server.
            
               Data Connection
                  The connection between the two NDMP Servers that carry the data
                  stream. The data connection in NDMP is either an NDMP
                  interprocess communication mechanism (for local operations) or a
                  TCP/IP connection (for 3-way operations).
            
               Data stream
                  A unidirectional byte stream of data flowing over a data
                  connection between two peer NDMP Services in an NDMP session. For
                  example, in a backup, the data stream is generated by the data
                  service and consumed by the tape service.
            
                  The data stream can be backup data, recovered data, etc.
            
               Data Service
                  A NDMP Service that transfers data between primary storage and
                  the Data Connection.
            
               Tape Service
                  A NDMP Service that transfers data between secondary storage and
                  the Data Connection and allows the DMA to manipulate and access
                  secondary storage.
            
               Mover
                  An aspect of the Tape Service that transfers data between the
                  secondary storage and the Data Connection.
            
               SCSI Service
                  A NDMP Service that passes low-level SCSI commands to a SCSI
                  device, typically used by the DMA to manipulate a SCSI or fibre
                  channel attached media changer.
            
               DAR or Direct Access Recovery
                  An optional capability of NDMP Data and Tape Services whereby
                  only relevant portions of secondary media are accessed during
                  Recovery Operations.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                    [Page 8]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
            
            1.4. Key Words
               The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
               "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
               document are to be interpreted as described in RFC 2119.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                    [Page 9]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2. Architecture
            2.1. Architectural Model
               The NDMP architecture is based on a client-server model. NDMP
               compliant backup software, which is referred to as the Data
               Management Application or DMA, is considered to be the client. A DMA
               interacts with one or more NDMP Servers, managing the transfer of
               data between server resident NDMP data and tape services. Each
               instantiation of a NDMP data or tape service is represented as a
               virtual state machine on the NDMP Server.
            
               Data services provide an abstracted interface to the file system or
               primary storage of the NDMP Server. A data service is the source of
               data during backup operations and the destination of data during
               recovery operations. Examples of data services are file servers and
               general compute platforms with direct or SAN attached storage.
            
               Tape services provide an abstracted interface to tape devices or
               other types of secondary storage attached to the NDMP Server. A tape
               library can implement its own NDMP Server and associated tape service
               or it can be connected through an external NDMP Server. A tape
               service is the source of data during recovery operations and the
               destination of data during backup operations. The tape service also
               provides a mechanism for tape positioning and I/O on behalf of the
               DMA. Examples of tape services are individual tape drives, tape
               libraries, or servers with one or more writeable CD ROM drives.
            
               An NDMP session is an instantiation of a pair of NDMP services with
               data connections between the two services and control connections
               between the DMA and each service. The DMA creates and controls the
               NDMP session. It is responsible for managing all session state
               required to fully or partially recover a file system including server
               topology, tape sets, numbering and so on.
            
               There is exactly one bi-directional TCP/IP control connection between
               the DMA and each NDMP Server.
            
               If the DMA is distributed in such a way that two or more DMA
               processes need to communicate to one NDMP service, the DMA commands
               MUST be merged into a single control connection to the NDMP Server.
            
               The NDMP protocol is a set of XDR encoded messages. These messages
               control and monitor the state of each NDMP service. The messages also
               report detailed information about the NDMP session and the data that
               is manipulated.
            
            2.2. NDMP Topologies
               This section describes typical NDMP topologies and configurations in
               terms of the relationship between DMAs and NDMP Servers that provide
               Data and Tape services.
            
            
            
            
            
            
            Expires October 2003                                   [Page 10]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.2.1. Simple NDMP Configuration
               In the simplest configuration, a DMA backs up the data from the NDMP
               Server to a locally attached tape subsystem. The NDMP control
               connection exists across the network boundary. The NDMP data
               connection between the data and tape services exists within the NDMP
               Server implementation.
            
                  +------------------------------+--------------------------------+
                  |           DMA                *           NDMP Server          |
                  |                              *                                |
                  |                              *                                |
                  |      +-------------+         *                                |
                  |      | NDMP Data   |         *                                |
                  |      | Management  | <-----------------------+                |
                  |      | Application |         *               |                |
                  |      +-------------+         * Network       |                |
                  |                              * Boundary      |                |
                  |                              *               |                |
                  |*******************************               |                |
                  |                                              | NDMP Control   |
                  |                                              | Connection     |
                  |                                              V                |
                  |                                        +-------------+        |
                  |                                        |    NDMP     |        |
                  |                                        | Data & Tape |        |
                  |                                        |  Services   |        |
                  |                                        +-------------+        |
                  |                                          ^  NDMP   |          |
                  |                                          |  Data   V          |
                  |                                 +-----------+  +-----------+  |
                  |                                 |    File   |  |   Tape    |  |
                  |                                 |   System  |  | Subsystem |  |
                  |                                 +-----------+  +-----------+  |
                  |                                                               |
                  +---------------------------------------------------------------+
               Figure 1. Simple configuration
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 11]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.2.2. NDMP Two Drive Configuration
               NDMP can also simultaneously back up to multiple backup devices
               physically attached to the NDMP Server. In this configuration, there
               are two instances of the NDMP data and tape services on the NDMP
               Server. The NDMP control connection exists across the network
               boundary. The NDMP data connections between the data and tape
               services exist within the NDMP Server implementation.
            
                  +------------------------------+--------------------------------+
                  |           DMA                *           NDMP Server          |
                  |                              *                                |
                  |                              *                                |
                  |      +-------------+         *                                |
                  |      | NDMP Data   |         *                                |
                  |      | Management  | <-----------------------+                |
                  |      | Application |         *               |                |
                  |      +-------------+         * Network       |                |
                  |             ^                * Boundary      |                |
                  |             |                *               |                |
                  |*************|*****************               |                |
                  |             | NDMP Control                   | NDMP Control   |
                  |             | Connection                     | Connection     |
                  |             v                                V                |
                  |      +-------------+                   +-------------+        |
                  |      |    NDMP     |                   |    NDMP     |        |
                  |      | Data & Tape |                   | Data & Tape |        |
                  |      |  Services   |                   |  Services   |        |
                  |      +-------------+                   +-------------+        |
                  |        ^  NDMP   |                       ^  NDMP   |          |
                  |        |  Data   V                       |  Data   V          |
                  |+-----------+  +-----------+     +-----------+  +-----------+  |
                  ||   File    |  |   Tape    |     |   File    |  |   Tape    |  |
                  ||  System   |  | Subsystem |     |  System   |  | Subsystem |  |
                  |+-----------+  +-----------+     +-----------+  +-----------+  |
                  |                                                               |
                  +---------------------------------------------------------------+
               Figure 2. Two-drive configuration
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 12]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.2.3. Tape Library Configuration
               NDMP can back up data to a tape library that is physically attached
               to the NDMP Server. In this configuration a separate instance of the
               NDMP Server control the robotics within the tape library.
            
                  +------------------------------+--------------------------------+
                  |            DMA               *           NDMP Server          |
                  |                              *                                |
                  |                              *                                |
                  |     +-------------+     NDMP Control    +-------------+       |
                  |     | NDMP Data   |      Connection     |     NDMP    |       |
                  |     | Management  | <------------------>| Tape & Data |--+    |
                  |     | Application |          *          |  Service    |  |    |
                  |     +-------------+          *          +-------------+  |    |
                  |            ^                 * Network        ^          |    |
                  |            |                 * Boundary       |          |    |
                  |************|******************           +---------+     |    |
                  |            | NDMP Control                |  File   |     |    |
                  |            | Connection                  | System  |     |    |
                  |            v                             +---------+     |    |
                  |      +------------+                                      |    |
                  |      |  NDMP Tape |                                      |    |
                  |      |   Service  |                            NDMP Data |    |
                  |      |            |                           Connection |    |
                  |      +------------+                                      |    |
                  |            |                                             |    |
                  |            |   +---------------------------------+       |    |
                  |            |   |           Tape Library          |       |    |
                  |            |   |  +-----------+   +-----------+  |       |    |
                  |            +----->|  Robotic  |   |   Tape    |<---------+    |
                  |                |  |  Control  |   | Subsystem |  |            |
                  |                |  +-----------+   +-----------+  |            |
                  |                +---------------------------------+            |
                  |                                                               |
                  +---------------------------------------------------------------+
               Figure 3. Tape library configuration
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 13]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.2.4. Three-Way Configuration
               One may back up an NDMP Server that supports NDMP but does not have a
               locally attached backup device by sending the data through a TCP/IP
               connection to another NDMP Server. In this configuration, the NDMP
               data service exists on one NDMP Server and the NDMP tape service
               exists on a separate server. Both the NDMP control connections (to
               server 1 and server 2 and the NDMP data connection (between server 1
               and server 2 exist across the network boundary.
            
                  +-------------------+----------------------+--------------------+
                  |   NDMP Server 1   *          DMA         *   NDMP Server 2    |
                  |                   *                      *                    |
                  |                   *                      *                    |
                  |   NDMP Control    *   +--------------+   *   NDMP Control     |
                  |    Connection     *   |  NDMP Data   |   *    Connection      |
                  |         +------------>|  Management  |---*---------+          |
                  |         |         *   |  Application |   *         |          |
                  |         |         *   +--------------+   *         |          |
                  |         |         *                      *         |          |
                  |         |         *   Network Boundary   *         |          |
                  |         |         ************************         |          |
                  |         |                    *                     |          |
                  |         V                    *                     V          |
                  |+------------------+      NDMP Data       +------------------+ |
                  ||     NDMP Data    |      Connection      |     NDMP Tape    | |
                  ||      Service     | -------------------->|      Service     | |
                  |+------------------+          *           +------------------+ |
                  |        ^                     *                     |          |
                  |        |Backup               *                     | Backup   |
                  |        |Data                 *                     | Data     |
                  |        |                     * Network             V          |
                  |  +-----------+               * Boundary      +-----------+    |
                  |  |   File    |               *               |   Tape    |    |
                  |  |  System   |               *               | Subsystem |    |
                  |  +-----------+               *               +-----------+    |
                  |                              *                                |
                  +---------------------------------------------------------------+
               Figure 4. Three-way configuration
            
            2.2.5. Data Replication Configurations
               In addition to backup and recovery operations, NDMP supports
               replication of data between two services of the same type. The two
               cases in NDMP are:
            
                  - Tape to tape replication: replicating a set of backup tapes.
            
                  - Data to data replication: replicating data between two primary
                  storage systems.
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 14]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               In the tape replication configuration one tape service performs a
               read operation while the other performs a write operation. This
               allows tape data to be copied from one NDMP tape service to another.
               The tape to tape copy is useful when duplicating backup tapes for
               offsite storage.
            
                  +-------------------+----------------------+--------------------+
                  |   NDMP Server 1   *          DMA         *   NDMP Server 2    |
                  |                   *                      *                    |
                  |                   *                      *                    |
                  |   NDMP Control    *   +--------------+   *   NDMP Control     |
                  |    Connection     *   |  NDMP Data   |   *    Connection      |
                  |         +------------>|  Management  |---*---------+          |
                  |         |         *   |  Application |   *         |          |
                  |         |         *   +--------------+   *         |          |
                  |         |         *                      *         |          |
                  |         |         *   Network Boundary   *         |          |
                  |         |         ************************         |          |
                  |         |                    *                     |          |
                  |         V                    *                     V          |
                  |+------------------+      NDMP Data       +------------------+ |
                  ||     NDMP Tape    |      Connection      |     NDMP Tape    | |
                  ||      Service     | -------------------->|      Service     | |
                  |+------------------+          *           +------------------+ |
                  |        ^                     *                     |          |
                  |        |Recovery             *                     | Backup   |
                  |        |Data                 *                     | Data     |
                  |        |                     * Network             V          |
                  |  +-----------+               * Boundary      +-----------+    |
                  |  |   Tape    |               *               |   Tape    |    |
                  |  | Subsystem |               *               | Subsystem |    |
                  |  +-----------+               *               +-----------+    |
                  |                              *                                |
                  +---------------------------------------------------------------+
               Figure 5 Tape to tape configuration
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 15]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
               NDMP also supports replication between two primary storage systems.
               In this configuration, one data service performs a backup operation
               while the other performs a recovery operation on the same data
               stream. This capability is useful for performing a logical
               duplication of a portion of a file system (data migration).
            
                  +-------------------+----------------------+--------------------+
                  |   NDMP Server 1   *          DMA         *   NDMP Server 2    |
                  |                   *                      *                    |
                  |                   *                      *                    |
                  |   NDMP Control    *   +--------------+   *   NDMP Control     |
                  |    Connection     *   |  NDMP Data   |   *    Connection      |
                  |         +---------*-->|  Management  |---*---------+          |
                  |         |         *   |  Application |   *         |          |
                  |         |         *   +--------------+   *         |          |
                  |         |         *                      *         |          |
                  |         |         *   Network Boundary   *         |          |
                  |         |         ************************         |          |
                  |         |                    *                     |          |
                  |         V                    *                     V          |
                  |+------------------+      NDMP Data       +------------------+ |
                  ||     NDMP Data    |      Connection      |     NDMP Data    | |
                  ||      Service     | -------------------->|      Service     | |
                  |+------------------+          *           +------------------+ |
                  |        ^                     *                     |          |
                  |        |Backup               *                     | Recovery |
                  |        |Data                 *                     | Data     |
                  |        |                     * Network             V          |
                  |  +-----------+               * Boundary      +-----------+    |
                  |  |   File    |               *               |   File    |    |
                  |  |  System   |               *               |  System   |    |
                  |  +-----------+               *               +-----------+    |
                  |                              *                                |
                  +---------------------------------------------------------------+
               Figure 6 Data to data configuration
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 16]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.3. Key NDMP Concepts
               The NDMP architectural model is focused around the creation and
               management of control connections and data streams in an NDMP
               session. Data from a volume or file system is turned into a data
               stream by a data service, a tape service takes a stream, converts it
               into a tape format and writes it to tape, or vice versa.
            
               The role of the NDMP protocol is to allow the DMA to set up,
               configure, and control an NDMP session of NDMP Servers and services.
            
            2.3.1. Session State
               In NDMP, the DMA is responsible for capturing and managing all state
               needed to provide the desired capabilities such as enabling partial
               recoveries of data. In addition, the DMA is responsible for media
               management.
            
               The NDMP service only keeps local running state. The DMA will poll
               the state from the NDMP services in order to record sufficient
               information to enable optimized access to subsets of the backed up
               data on the tapes.
            
               There are several benefits to an architecture where state is
               centralized to one place, and the other components are ôstate lean:ö
            
                  - The architecture is simpler.
            
                  - The protocol commands and event notifications are clearer and
                  simpler.
            
                  - The state diagrams are simpler.
            
                  - The code becomes simpler and more supportable.
            
               The net result is more robust products, and therefore a more robust
               data management environment.
            
            2.3.2. Control Streams
               Between the DMA and every NDMP Server is one and only one control
               connection. The DMA uses this control connection to manage each NDMP
               service associated with the server. The control connection is
               implemented as a TCP/IP connection. Messages flow in both directions
               on a control connection. The DMA sends messages to the NDMP Server
               for the purpose of managing the operations of its NDMP services. The
               NDMP Server sends notifications to the DMA when a NDMP service
               requires the DMAÆs attention. The NDMP Server also uses the control
               connection to send file history information about the content of the
               data stream.
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 17]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.3.3. Data Streams
               NDMP data streams convey implementation specific backup or recovery
               data between NDMP services. In the native or general case the
               transport for NDMP data streams is TCP/IP over any IP supported
               network media. In NDMP each service may return multiple IP addresses
               to the DMA, addresses on which the service will be listening for a
               connection from the other service. This is done to accommodate the
               following:
            
                  - Many servers have multiple connections to an IP network. These
                  connections may offer different performance characteristics.
            
                  - Different network segments may be created for different
                  purposes: one for communication between users and servers, one
                  for communication between applications servers and dedicated
                  storage, one for specific data management such as backup,
                  recovery and replication, etc.
            
                  - Specific network segments may provide important service level
                  characteristics such as guaranteed minimum bandwidth etc. that
                  would guarantee a maximum time for an NDMP session.
            
                  - Fiber Channel SANs are established, and VI and Infiniband are
                  emerging as future high-speed technologies for data management.
                  IP is the global addressing mechanism; it is also being used to
                  address non-IP node connections such as for FC and VI.
            
               NDMP sessions must be able to take advantage of the ways the
               networking infrastructure is constructed. It is therefore the
               recommendation that the DMA, possibly with the assistance of a
               general directory service, understands the capabilities and purpose
               of the network topology, and thus makes the determination about which
               network connections to use. The NDMP services will make a simple
               recommendation for use of connections based on basic information such
               as the bandwidth of a NIC.
            
               Notice that each server still MUST be connected to the LAN for TCP/IP
               based NDMP control connections.
            
            2.3.4. NDMP Services
               The NDMP services are the NDMP interfaces to the storage devices.
               Data services interface to primary storage devices such as servers
               with storage subsystems or filers, tape services interface to
               secondary storage devices such as tape drives or writeable CDROMs.
            
               The NDMP services are controlled by the DMA through a set of service
               parameters. There are two types of service parameters, service
               parameters that impact the NDMP protocol or state, and ôNDMP opaqueö
               service parameters that only impact vendor specific state in a NDMP
               service.
            
            
            
            
            
            Expires October 2003                                   [Page 18]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.3.4.1. Data Service
               A data service provides the NDMP interface to a primary storage
               device such as a filer, a compute server with direct or SAN attached
               storage, or a read-only CDROM library. The data service allows a DMA
               to read or write all or a subset of a volume or a file system, for
               the purpose of a backup or a recovery.
            
               The data service reads or writes one single data stream for backup or
               recovery, respectively.
            
            2.3.4.2. Tape Service
               A tape service provides the NDMP interface to a secondary storage
               device, such as a tape drive or a writeable CDROM. The tape service
               reads or writes a single data stream, for backup or recovery
               respectively.
            
               Note that a tape service only handles the reading or writing of one
               ôcartridge,ö a single tape or CD. The tape service when notify the
               DMA when a cartridge is read or written, the DMA will provide the
               necessary media management.
            
            2.3.4.3. SCSI Pass Through Service
               The SCSI pass through service allows a DMA to issue SCSI commands to
               a device such as a tape robot. This service allows the DMA to control
               other devices such as a tape or CD media changer.
            
            2.3.5. Other Mechanisms
               Two additional important NDMP concepts are the mover window, the file
               history, and their use in direct access recovery.
            
            2.3.5.1. Tape Format and Mover Window
               Tapes recorded by NDMP-conformant software contain one of two types
               of data:
            
                  - backup image data, generated by the data service and recorded
                  by the mover, and
            
                  - metadata, generated by the DMA and recorded by the Tape service
            
               The portions of the tape to which backup image data are written, and
               from which those data are read, are specified by the DMA. Though this
               placement is under DMA control, content of backup image data is
               controlled by the data service.
            
               Placement and content of metadata are controlled exclusively by the
               DMA.
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 19]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.3.5.1.1. Mover Records
               Backup image data is recorded by the mover in units of mover records.
               The size of a mover record is equal to the size of a tape block if
               the tape drive is operating in variable block size mode. (That is,
               specifying mover record size using NDMP_MOVER_SET_RECORD_SIZE
               implicitly defines the tape block size.) For tape drives operating in
               fixed block size mode, the mover record size is an integer multiple
               of that fixed block size.
            
            2.3.5.1.2. Tape Content Ownership
               Each tape data block contains either backup image data or metadata,
               but never both. Backup image data consists solely of tape data
               blocks. Metadata may include tape data blocks, file marks, and other
               out-of-band information, the specifics of which are beyond the scope
               of this specification. Thus, each tape data block or instance of out-
               of-band information is "owned" by exactly one of the mover or the
               DMA. It is the DMA's responsibility to manage this distinction and
               ensure that the mover operates only on tape data blocks it owns.
            
            2.3.5.1.3. Control of the Tape Drive
               Operationally, when a tape drive is opened, it is controlled by the
               DMA and accessed via NDMP Tape interface requests. When the DMA is
               ready for backup image data to be transferred between a data service
               and a mover, presumably after transferring metadata and positioning
               the tape, it passes control of the tape drive to the mover. This
               occurs when the DMA issues a NDMP_MOVER_LISTEN or NDMP_MOVER_CONNECT
               request.
            
               Once the DMA hands control of the tape drive to the mover, the DMA is
               not permitted to perform NDMP Tape requests until the mover returns
               control to the DMA. This occurs when the mover pauses or halts.
            
            2.3.5.1.4. Mover Window
               A mover window is the means by which the DMA constrains the mover to
               use a certain, contiguous set of tape blocks.
            
               A mover window identifies a range of tape data blocks that a mover
               may operate on when it is given control of the tape drive. It is
               expressed in terms of an offset in bytes from the beginning of the
               backup image data, and a length in bytes. The offset corresponds to
               the first byte of the first mover record to be transferred when the
               DMA passes control of the tape drive to the mover.
            
               The length, when divided by the mover record size, identifies the
               total number of mover records represented by the window.
            
               Mover windows always begin and end on mover record boundaries; they
               do not span tapes. Exactly one mover window is in effect at all times
               a mover is operating. (Certain events, however, cause that window to
               be made invalid.) A mover suppresses any attempt to operate outside
               the bounds of the mover window. If such attempt is made, the mover
               transitions to the PAUSED state.
            
            
            
            Expires October 2003                                   [Page 20]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.3.5.1.5. Mover Window Usage While Writing
               A mover writing to a tape (e.g., performing a backup operation)
               considers only the mover window length. Although the offset is
               specified in requests and replies, its value is ignored except when
               checked by the mover to ensure it aligns with a mover record
               boundary.
            
               Should a mover writing to a tape encounter the end of the mover
               window, it pauses with the NDMP_MOVER_PAUSE_EOW reason code. Should
               such mover encounter logical end of medium before the end of the
               mover window, it pauses with the NDMP_MOVER_PAUSE_EOM reason code.
            
               Consider the following sample tape content. Each "d" indicates that a
               10 byte data block -- containing one mover record -- is recorded; "f"
               indicates a file mark. "m" or "i" identifies the tape content as
               metadata or backup image data.
            
                   file#  0   0   0   0   0   0   0   0   0   1   1   1
                  block#  0   1   2   3   4   5   6   7   8   0   1   2
                      BOT                                               EOD
                       |  d   d   d   d   d   d   d   d   f   d   d   f  |
                       |  m   m   m   i   i   i   i   m   m   i   m   m  |
            
               Assume for the sake of example that the DMA wishes to write metadata,
               consisting of one data block and a file mark, every 4 mover records.
               Assume, too, that the data service has 50 bytes to write. (The mover,
               though, has no a priori knowledge of this.)
            
               After opening the tape and writing 3 blocks of metadata, the DMA sets
               the mover record size to 10 bytes and the mover window to offset 0,
               length 40. It then requests the data service to begin the backup
               operation.
            
               The mover writes the 1st 40 bytes of the backup image data as 4
               consecutive 10 byte data blocks. Attempting to write the 5th data
               block causes the mover to pause with an end-of-window reason code.
               Note that the EOW condition is detected only when an attempt is made
               to write beyond the window limit.
            
               Following the EOW, the DMA regains control of the tape drive, writes
               a block of metadata and a file mark using the NDMP Tape interface. It
               establishes a new mover window by again setting the offset to 0 and
               length to 40, then requests the mover to continue. After writing one
               more record, the data service and mover complete, ultimately
               producing a NDMP_NOTIFY_MOVER_HALTED. The DMA regains control of the
               tape drive and writes a final data block and file mark.
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 21]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.3.5.1.6. Mover Window Usage While Reading
               A mover reading from a tape (e.g., performing a recovery operation)
               correlates the mover window offset to the first byte to be read at
               the tape position when the mover is passed control of the tape drive.
               Thus, it honors mover "read" and "seek" requests by reading and
               seeking among the tape data blocks within the mover window, pausing
               for assistance from the DMA only when it needs data outside of the
               window.
            
               Consider the example tape format above. To read the 50 bytes of
               backup image data, the DMA first reads the 3 blocks of metadata at
               BOT. It sets the mover record size to 10, window offset to 0 and
               length to 40, then begins the recovery. The mover reads the 1st 40
               bytes of the backup image data as 4 consecutive 10 byte data blocks.
               When attempting to read the 5th record, the mover pauses with a mover
               seek notification, indicating that the seek position is byte 40. As
               with a write operation, the EOW condition is detected only when an
               attempt is made to read beyond the window limit.
            
               Following the EOW, the DMA regains control of the tape drive,
               processes the metadata in tape block 7 and spaces over the file mark
               that follows. The DMA resets the mover window to offset 40, length
               10, and requests the mover to continue.
            
               Upon arrival at the end of this window -- and the end of the backup
               image -- the mover will pause (reason: seek), or remain in the active
               state but operationally idle.
            
            2.3.5.2. File History
               Backup data formats such as tar and cpio include metadata in the
               backup data stream. This includes file name, access control lists,
               etc. In addition NDMP enables the data service to send file history
               notifications to the DMA as the backup data is written to the data
               stream.
            
               The file history includes the following information: file name and
               path, file status information, and file positioning information (the
               address of the file in the backup data stream).
            
               The file locator data in the file history record is in a data service
               (OS) specific format. To the DMA this information is an opaque
               string. This means that the DMA will not attempt to interpret it. In
               order to determine the location of a file in the backup data stream,
               the DMA will send the complete file history record for the
               corresponding file history record to the data service, the data
               service will calculate the starting location and the length of the
               byte string to be read from the original backup data stream. The DMA
               will use this data to manipulate the tape service to retrieve the
               selected data.
            
            
            
            
            
            
            Expires October 2003                                   [Page 22]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               The two typical applications of the file history are: to provide a
               human readable user interface to the backup data and to provide a
               basis for direct access recovery.
            
               The file history enables the DMA to build a database over all the
               files in a backup database. This database enables users to locate
               which backup has the file, when (before the backup time) the file was
               modified, and other similar information. Notice that the file locator
               data is not in a DMA readable form.
            
               Direct access recovery depends upon accurate file positioning
               information in the backup data stream. For more on this see the
               section on direct access recovery.
            
            2.3.5.3. Direct Access Recovery
               Direct access recovery (DAR) is an optimized data recovery operation
               based on the use of the mover window function. DAR is used to allow
               the DMA to directly access backed up data in the middle of a tape set
               without having to parse the tape set sequentially. This is very
               useful when backup data tape sets can take many hours to read or
               write. Direct access recovery is typically achieved as follows.
            
               The DMA uses the mover window tool to partition the backup data into
               segments that are written to tape. The DMA records where these
               segment are located on the tapes, as well as their start and end
               address relative to the start of the backup data stream.
            
               The DMA receives file history notifications from the data service;
               these notifications include (in DMA opaque format) the address of the
               file relative to the start of the backup data image.
            
               By using the file addresses the data service can cause
               NDMP_NOTIFY_MOVER_PAUSED post (reason seek) from the mover service
               which the DMA can use to compute which segment contains the starting
               point of a requested file. It can therefore start the recovery
               process from the beginning of the tape that has the segment, use the
               mover to move across segments and start reading through the segment
               to locate the beginning of the file.
            
               Direct access recovery requires a tape drive that can generate
               accurate tape block numbers. Some tape devices do not support this.
            
            2.4. Character and Role
               An NDMP Server may provide a number of services, for example: a Data
               Service, a Tape service, and a SCSI Service. An NDMP Server may
               provide one or more of these services simultaneously. In the most
               common case of a transfer of data between a disk and a local tape
               library the NDMP Server might perform all three roles.
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 23]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               An NDMP Server providing a Data Service is called a Data Server.
               During the backup, the Data Server reads the data from disk,
               generates an NDMP data stream using a specified backup format, and
               returns the file history information, if requested, back to the DMA.
               During the retrieval, the Data Server reads the NDMP data stream and
               recovers it back to the disk. The Data Server SHOULD NOT be aware of
               any backup device or medium issues, e.g. tape size, block size, end
               of medium and so on.
            
               An NDMP Server providing a Tape service is called a Tape Server.
               During a backup the Tape Server reads data from an NDMP data stream
               and writes it to tape. During a recovery the Tape Server reads from
               tape and writes to the NDMP data stream. The Tape Server SHOULD NOT
               be aware of the backup format, for instance dump or tar. All tape
               handling functions, such as split image issues MUST be dealt with by
               this service.
            
               An NDMP Server providing a SCSI Service is called a SCSI Server. The
               SCSI Server is usually but not necessarily co-located with the Tape
               Server. It passes SCSI control commands from the DMA to a SCSI device
               that is usually a media auto-changer device.
            
            2.5. Protocol Interfaces
               NDMP messages are grouped by functionality into several interfaces.
               An NDMP Server implementation is NOT REQUIRED to implement all of the
               listed messages. See 2.5.3 for details about optional interfaces and
               messages.
            
            2.5.1. Messages from DMA to NDMP Server
               The NDMP Server MUST implement a consistent subset of the following
               interfaces:
            
               Connect Interface
                  This interface allows the NDMP Server to authenticate the client
                  and negotiate the version of protocol used. The Connect Interface
                  is used after a client first establishes a connection to an NDMP
                  Server.
            
               Config Interface
                  This interface allows a DMA to discover the configuration of the
                  NDMP Server. The Config Interface discovers NDMP Server
                  configuration and attributes.
            
                  The Config Interface includes commands for discovering extensions
                  in the server. Extensions are groups of requests used to control
                  server functionality that is not part of the core NDMP Server
                  specification. See section 2.5.4 for details on server
                  extensions.
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 24]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               SCSI Interface
                  This interface passes SCSI CDBs through to a SCSI device and
                  retrieve the resulting SCSI status. The DMA uses the SCSI
                  Interface to control locally attached tape library media changer.
                  Software on the DMA will construct SCSI CDBs and interprets the
                  returned status and data. The SCSI Interface MAY also exploit
                  special features of SCSI backup devices.
            
               Tape interface
                  This interface supports tape positioning and tape read/write
                  operations. The DMA typically uses the Tape interface to write
                  tape metadata. This includes tape labels and information
                  identifying and describing backup data included on the tape. The
                  DMA also uses the Tape interface to position the tape during
                  backups and recoveries.
            
               Data Interface
                  This interface initiates backup and recover operations. The DMA
                  provides all the parameters that affect the backup or recovery
                  using the Data Interface. The DMA 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 controls the reading and writing of backup data
                  from and 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 recover the Mover
                  Interface reads data from the tape device and writes the data to
                  the data connection. The MOVER handles tape exceptions and
                  notifies the DMA.
            
            2.5.2. Messages from the NDMP Server to the DMA
               The NDMP Server implementation MAY send the following messages to the
               DMA. All the messages that the DMA accepts are asynchronous. None of
               these messages generates a reply message.
            
                  Notify Interface
                     These messages enable the NDMP Server to notify the DMA that
                     the NDMP Server requires attention.
            
                  File History interface
                     These messages enable the NDMP Server to make entries in the
                     file history catalog for the current backup. The DMA uses
                     file history information to track the files contained in each
                     backup and to select and locate files for recovery.
            
                  Log Interface
                     These messages enable the NDMP Server to make entries in the
                     backup and recovery log. The operator uses the log to monitor
                     the progress and completion status of the backup and recovery
                     operations. The log MAY also be used to diagnose problems.
            
            
            
            Expires October 2003                                   [Page 25]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.5.3. Optional Interfaces and Messages
               An NDMP server MAY omit implementation of certain messages as
               described below. However, if the NDMP server receives a request that
               it does not implement, it MUST generate a reply containing the
               NDMP_NOT_SUPPORTED_ERR error code.
            
               This section describes optional large-scale features and lists the
               associated messages. Certain individual messages are also optional.
               Where this is the case it is noted in the detailed description of the
               message in section 3. If a request is not explicitly indicated as
               optional in its description in section 3 and it is part of the
               feature set supported by the NDMP Server, the NDMP Server MUST
               implement that request.
            
               If an NDMP Server does not implement one of the features described
               below then it MUST reject any of the associated requests with error
               code NDMP_NOT_SUPPORTED_ERR.
            
               The NDMP messages can be partitioned functionally into the following
               four subsets:
            
               Core messages
                  The core subset of NDMP requests applicable to all NDMP servers
                  include the following:
            
                     - All Connect Interface requests.
            
                     - General-purpose Config Interface requests including
                     NDMP_CONFIG_GET_HOST_INFO, NDMP_CONFIG_GET_SERVER_INFO,
                     NDMP_CONFIG_GET_CONNECTION_TYPE, NDMP_CONFIG_GET_AUTH_ATTRIB,
                     NDMP_CONFIG_GET_EXT_LIST and NDMP_CONFIG_SET_EXT_LIST.
            
                  All NDMP servers MUST be able to generate the initial
                  NDMP_NOTIFY_CONNECTION_STATUS message and MAY generate
                  NDMP_LOG_MESSAGE.
            
               Data service messages
                  The data service is responsible for the interfaces to the file
                  system that is being backed up or recovered. The Data Server
                  feature consists of the following messages:
            
                     - All Data Interface requests.
            
                     - Config Interface NDMP_CONFIG_GET_BUTYPE_INFO and
                     NDMP_CONFIG_GET_FS_INFO requests.
            
                  The Data Server MUST be able to generate an
                  NDMP_NOTIFY_DATA_HALTED message. It MUST be able to generate
                  NDMP_FH_ADD_FILE, and/or NDMP_FH_ADD_DIR/NDMP_FH_ADD_NODE
                  messages if the data it returns in an NDMP_CONFIG_GET_BUTYPE_INFO
                  reply indicates that it will. It MAY also generate NDMP_LOG_FILE
                  notification messages.
            
            
            
            Expires October 2003                                   [Page 26]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Tape service messages
                  The Tape service provides access to tape drives. It MAY also
                  provide access to media changer devices. The tape access feature
                  consists of the following messages:
            
                     - All Tape interface and Mover Interface requests.
            
                     - The Config Interface NDMP_CONFIG_GET_TAPE_INFO request.
            
                     - The server MUST be able to generate
                     NDMP_NOTIFY_MOVER_PAUSED and NDMP_NOTIFY_MOVER_HALTED
                     messages.
            
               SCSI Service messages
                  The SCSI Service provides access to media changer devices. The
                  SCSI Service consists of the following messages:
            
                     - All SCSI Interface requests.
            
                     - The Config Interface NDMP_CONFIG_GET_SCSI_INFO request.
            
            2.5.4. NDMP Server Extensions
               NDMP provides for a server extension mechanism that enables the
               following:
            
                  - The NDMP community can develop and standardize new
                  functionality in NDMP without requiring a revision of core NDMP
            
                  - Implementers can expose proprietary functionality in NDMP
                  Server implementations through NDMP Server extensions
            
                  - DMAs can discover and negotiate the use of these extensions
            
                  - Extensions are managed at two levels: standard extensions
                  developed or ratified by the NDMP community, and proprietary
                  extensions developed for the individual implementations
            
                  - Extensions are versioned, and can evolve over time
            
               The following sections describe the architecture of NDMP extensions.
            
            2.5.4.1. Proprietary vs. Standard Extensions:
               The architecture provides for two classes of extensions. These are
               proprietary NDMP extensions and standard NDMP extensions.
            
               Proprietary extensions are used for exposing proprietary
               functionality. These extensions are owned by the implementers of NDMP
               Servers. The functionality is specific to the implementation. There
               is no requirement to this functionality other than it MUST comply
               with the NDMP extension architecture.
            
            
            
            
            
            Expires October 2003                                   [Page 27]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Standard extensions are standardized by the NDMP community into
               separate NDMP standards specifications. The specifications of
               standard extensions are owned by the standards community.
            
            2.5.4.2. The Class
               The basic building block in NDMP extensions is the class. All NDMP
               extensions are implemented in classes and managed on a per class
               basis.
            
               The NDMP code space is 32 bit. The class is a set of 64k NDMP
               messages with the same value in the upper 16 bits, i.e. there are 64k
               NDMP classes. The complete message code is defined as
               "class.message," where "class" and "message" are 16 bit each.
            
               Notice that "core NDMP" is technically known as "class 0x0".
            
               For convenience the messages in a class is grouped into "interfaces."
               Interfaces are groups of messages that operate on the same functional
               module, for instance NDMP Server configuration. Observe that
               "interface" is only a conceptual and organizational tool, there is no
               architectural element called interface in NDMP. Therefore the
               implementer is free to organize the messages in a class as he/she
               prefers.
            
            2.5.4.2.1. Class Versions
               Classes are versioned. The version number is a 16 bit unsigned
               integer.
            
               A DMA MUST select only one version of each class it selects to use.
               The version is decided during the discovery and negotiation phase.
               (See 2.5.4.3.)
            
               The version mechanism is used for several purposes. First it gives
               implementers a tool to communicate a change in the feature set
               exposed to NDMP. Secondly it imposes some discipline in that
               extensions are built and advanced in a structured process.
            
               The implementer MAY use versioning at his/her desire. However, in
               order to get a consistent handling of versions in NDMP implementers
               SHOULD comply with the following guidelines:
            
               The version of a class SHOULD be revised ONLY when the semantics of
               the class changes. This includes the following cases:
            
                  - New functionality is added to the class. For instance, a tape
                  library implementer adds a set of tape library management
                  functions to an existing tape library extension.
            
                  - A bug has been found and it cannot be fixed without changing
                  the semantic definition of one or more messages or message
                  replies in the class.
            
            
            
            
            Expires October 2003                                   [Page 28]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  - When a function is changed in terms of the number or type of
                  parameters.
            
               The class version SHOULD NOT be changed if a bug is detected, and the
               fix does not change the semantics of any part of the class.
            
            2.5.4.2.2. Class Version vs. Core NDMP Version
               The versioning scheme for NDMP extensibility is orthogonal to the
               version of core NDMP. The only requirement is that core NDMP MUST be
               of version 4 or later.
            
               Future versions of core NDMP MUST NOT depend upon any particular
               extension, standard or proprietary. Core NDMP MUST be a complete
               functional implementation of a sufficient and necessary set of
               functionality to allow for the most common data management
               operations.
            
            2.5.4.3. Discovery and Negotiation
               Discovery and negotiation is used by the DMA to probe which
               extensions are supported in the NDMP Servers, and to select a subset
               of these extensions in the NDMP session.
            
               The Discovery and Negotiation (D+N) messages MUST be implemented in
               core NDMP starting in NDMP version 4. The server MUST be able to
               handle D+N requests according to the specification.
            
               If D+N calls are made, the D+N exchange MUST occur before ANY
               extension requests are issued by the DMA.
            
               The D+N exchange between the requesting DMA and the NDMP Server
               SHOULD proceed as follows:
            
                  1: The DMA requests the list of supported extensions in the NDMP
                  Server by issuing the message NDMP_CONFIG_GET_EXT_LIST.
            
                  2: The NDMP Server replies with a list of all extensions,
                  standard and proprietary, that are supported and should be
                  exposed. (*)
            
                  3: The DMA selects a subset of the extensions and sends the list
                  of selected extensions to the NDMP Server with the command
                  NDMP_CONFIG_SET_EXT_LIST.
            
                  4: The NDMP Server acknowledges the selected extensions.
            
               * - Implementers may decide to hide extensions, or to require a more
               sophisticated authentication or negotiation scheme before an
               extension can be accessed. This is specific to the implementations.
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 29]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               The requester (DMA) SHOULD discover and negotiate classes of
               extensions before attempting to use any extensions. This explicitly
               determines the set of extension that will be used by the two parties
               in this session.
            
               If a server allows a requester to use extensions without first going
               through the D+N steps, the server SHOULD assume a default version of
               a class. It is recommended that the default version is the most
               recent version of the class.
            
               It is highly recommended that the discovery and negotiation process
               is completed such that the classes and versions to be used are
               explicitly known by both parties.
            
            2.5.4.4. Extension Management
               Standard extensions are managed by the standards community. A group
               of NDMP implementers can propose an extension for standardization,
               the community will evaluate the proposal in the same way as this
               specification is evaluated for standardization.
            
               Proprietary extensions are owned by the NDMP implementer.
               Implementers will use multiple extensions, some for internal
               prototyping, and some for publicly exposing functionality. A small
               set of classes is therefore allocated to each implementer; this is
               considered an "extension sandbox". See Appendix A.
            
            2.5.4.4.1. The NDMP Class Space Allocation
               The class space is selected with the upper 16 bits of the 32-bit NDMP
               message code. In order to maintain core NDMP, and provide for
               standard and proprietary extensions, the class space is allocated
               into separate ranges as follows:
            
                 Class = 0x0000: Core NDMP.
            
                 Class = 0x0001 - 0x0007: Standard NDMP extensions.
            
                 Class = 0x0008 - 0x1fff: Reserved.
            
                 Class = 0x2000 - 0x7fef: Proprietary extensions.
            
                 Class = 0x7ff0 - 0x7ffe: Reserved for test use.
            
                 Class = 0x7fff - 0xffff: Reserved.
            
               Notice that a reserved area is allocated at the separation point
               between standard and proprietary extensions.
            
            2.5.4.4.2. Extension Allocation and Management
               The code space allocation and management for proprietary extensions
               is described in Appendix A.
            
            
            
            
            
            Expires October 2003                                   [Page 30]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.6. Messaging Protocol
               NDMP consists of NDMP request, reply and post messages sent over a
               TCP/IP connection. Request messages are sent from the DMA to the NDMP
               Server, and have corresponding reply messages. Post messages are used
               by the NDMP Server to pass information to the DMA, and hence have no
               associated reply messages.
            
               NDMP uses the RPC Record Marking (RM) Standard [4]. An NDMP message
               consists of a message header optionally followed by a message body. A
               message sequence number identifies each message. This message
               sequence number is sent as part of the header. Each message is XDR
               encoded and sent within a single RM record. (See [1] for details of
               XDR.)
            
               Implementation note:
                  The XDR libraries available on UNIX/LINUX platforms include a set
                  of xdrrec functions that provide RPC RM and XDR translation
                  functionality.
            
               All NDMP requests (except NDMP_CONNECT_CLOSE) from the DMA to the
               NDMP Server have associated NDMP reply messages that MUST be returned
               by the server to indicate success or failure. NDMP post messages from
               the NDMP server to the DMA do not have associated replies. When a DMA
               sends a request to the NDMP server it SHOULD wait to receive the
               reply before sending its next request. If the DMA sends multiple
               requests without waiting for the reply to a previous request, the
               NDMP server may either queue the requests and deal with them
               sequentially or handle them asynchronously.
            
               Because it is RECOMMENDED that the DMA wait for a reply before
               sending the next request, the NDMP server MUST make every effort to
               reply to requests. In particular, if it receives an unrecognized
               message or has problems decoding a request with a valid message
               header it MUST send an NDMP reply message reporting the error. If the
               NDMP server receives a message for which it cannot decode the message
               header it MUST discard the message. (This might happen if the RM
               record is too short to contain the full NDMP header.) If the NDMP
               Server determines that the session is in an unrecoverable error state
               then it SHOULD disconnect the TCP connection. This would be the case
               if the NDMP server received a sequence of malformed messages.
            
            2.7. Message Header
               A message header starts each message. The message header identifies
               the message and defines how to de-serialize the arguments and
               dispatch the message.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 31]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
                  ----------------------------------------------------------
                  |                           |                            |
                  |       ndmp_header         |       message_request      |
                  |                           |                            |
                  ----------------------------------------------------------
            
                  ----------------------------------------------------------
                  |                            |                           |
                  |       ndmp_header          |       message_reply       |
                  |                            |                           |
                  ----------------------------------------------------------
            
               The following XDR block defines the message header:
            
                  ndmp_header_message_type
                  {
                      NDMP_MESSAGE_REQUEST,
                      NDMP_MESSAGE_REPLY
                  };
            
                  const NDMP_MESSAGE_POST = NDMP_MESSAGE_REQUEST;
            
                  struct ndmp_header
                  {
                      u_long                    sequence;
                      u_long                    time_stamp;
                      ndmp_header_message_type  message_type;
                      ndmp_message              message_code;
                      u_long                    reply_sequence;
                      ndmp_error                error_code;
                  };
            
               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 either a
                     request/post or a reply message. Note that in order to
                     minimize changes from version 3, request and post messages
                     use the same message_type identifier.
            
            
            
            
            
            Expires October 2003                                   [Page 32]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  message_code
                     The message_code field identifies the message.
            
                  reply_sequence
                     The reply_sequence field MUST be 0 in a request message. In
                     reply messages, the reply_sequence MUST be the sequence
                     number from the request message with which the reply is
                     associated.
            
                  error_code
                     The error_code field MUST be 0 in request and post messages.
                     In reply messages, the error_code field identifies any
                     problem that occurred receiving or decoding the message. If
                     the error_code value is nonzero, no message body will follow
                     the message header. The complete list of error codes is in
                     the next section.
            
               When the NDMP Server receives and decodes a request that has a
               message field indicating a function that the NDMP Server supports, it
               MUST create a suitable message_reply. In this case, errors SHOULD be
               reported by setting the error field in the ndmp_header to NDMP_NO_ERR
               and setting the error field in the message_reply to the relevant
               error value. However, DMAs MUST handle any error codes appearing in
               the error code field in the ndmp_header.
            
            2.8. Error Reporting
               When the NDMP Server receives a request from the DMA it MUST generate
               a reply that indicates success or failure. If the NDMP Server does
               not recognize or support a request it MUST generate an error reply
               and ignore the request. The error reply in this case MUST either use
               the ndmp_header error_code field to report NDMP_NOT_SUPPORTED_ERR, or
               generate a valid message reply body with error set. (See section 2.6
               for ndmp_header details.)
            
               Core NDMP has a set of error codes that are specified in section
               2.8.1. These error codes are also used for errors that occur as a
               result of extension messages, but the error is best described in the
               context of core NDMP. In addition, there are error codes specific to
               each extension.
            
            2.8.1 Error Codes In Core NDMP
               All possible error codes for core NDMP are listed below. Some of
               these error codes cover a range of cases. It is strongly RECOMMENDED
               that the NDMP Server use the Log Interface Log Message request (see
               4.2.1) to provide further information. A log type of NDMP_LOG_ERROR
               SHOULD be used.
            
               The following error codes are defined:
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 33]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  enum ndmp_error
                  {
                      NDMP_NO_ERR                     =  0,
                      NDMP_NOT_SUPPORTED_ERR          =  1,
                      NDMP_DEVICE_BUSY_ERR            =  2,
                      NDMP_DEVICE_OPENED_ERR          =  3,
                      NDMP_NOT_AUTHORIZED_ERR         =  4,
                      NDMP_PERMISSION_ERR             =  5,
                      NDMP_DEV_NOT_OPEN_ERR           =  6,
                      NDMP_IO_ERR                     =  7,
                      NDMP_TIMEOUT_ERR                =  8,
                      NDMP_ILLEGAL_ARGS_ERR           =  9,
                      NDMP_NO_TAPE_LOADED_ERR         = 10,
                      NDMP_WRITE_PROTECT_ERR          = 11,
                      NDMP_EOF_ERR                    = 12,
                      NDMP_EOM_ERR                    = 13,
                      NDMP_FILE_NOT_FOUND_ERR         = 14,
                      NDMP_BAD_FILE_ERR               = 15,
                      NDMP_NO_DEVICE_ERR              = 16,
                      NDMP_NO_BUS_ERR                 = 17,
                      NDMP_XDR_DECODE_ERR             = 18,
                      NDMP_ILLEGAL_STATE_ERR          = 19,
                      NDMP_UNDEFINED_ERR              = 20,
                      NDMP_XDR_ENCODE_ERR             = 21,
                      NDMP_NO_MEM_ERR                 = 22,
                      NDMP_CONNECT_ERR                = 23,
                      NDMP_SEQUENCE_NUM_ERR           = 24,
                      NDMP_READ_IN_PROGRESS_ERR       = 25,
                      NDMP_PRECONDITION_ERR           = 26,
                      NDMP_CLASS_NOT_SUPPORTED_ERR    = 27,
                      NDMP_VERSION_NOT_SUPPORTED_ERR  = 28,
                      NDMP_EXT_DUPL_CLASSES_ERR       = 29,
                      NDMP_EXT_DANDN_ILLEGAL_ERR      = 30
                  };
            
            
               The following list describes each error code. The errors that are
               returned in reply to specific requests are described in detail under
               the relevant message descriptions in section 3. However, there might
               be cases where the NDMP Server uses other error replies and the DMA
               MUST be implemented to accept these. In particular there are a number
               of error codes describing unexpected conditions that can affect any
               request. These are marked in the following list as Generic Errors.
            
                  NDMP_NO_ERR
                     No error.
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 34]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NOT_SUPPORTED_ERR
                     Specified message not supported. This error code is used in
                     all of the following situations:
                     The request forms part of a service (see 2.5.3) that is not
                     implemented by the NDMP Server.
                     The request is an optional message not supported by the NDMP
                     Server.
                     The specific operation included in request is not supported
                     by the NDMP Server.
                     This error code is also used if the message code is
                     unrecognized by the NDMP Server.
            
                  NDMP_DEVICE_BUSY_ERR
                     Specified device is in use. This error is used in two
                     circumstances. It is used when an NDMP_SCSI_OPEN request
                     fails because the device is in use by an agent other than
                     this NDMP Server. It is also returned by NDMP_TAPE_OPEN if
                     the tape is currently in use by the MOVER. (The MOVER is in
                     Active or Listen state.)
            
                  NDMP_DEVICE_OPENED_ERR
                     A device is already open. NDMP connections are limited to a
                     single tape or SCSI device open at a time.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     NDMP connection not yet authenticated. Prior to issuing most
                     requests, the NDMP connection MUST first be authenticated
                     through the NDMP_CONNECT_AUTH_CLIENT 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 name used to authenticate the connection does not
                     have 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.
            
                  NDMP_IO_ERR
                     Device I/O error. This general error SHOULD only be used if
                     none of the more specific device failure error codes apply. A
                     Log Message SHOULD be sent to describe the error in more
                     detail.
            
                  NDMP_TIMEOUT_ERR
                     Command timeout error.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     Message received containing one or more invalid arguments. It
                     is RECOMMENDED that a Log Message be sent to describe the
                     unacceptable arguments.
            
            
            
            Expires October 2003                                   [Page 35]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NO_TAPE_LOADED_ERR
                     Tape device could not be opened because no tape was loaded.
                     Alternatively the tape has been unloaded since the open
                     command. (If the Server cannot detect this specific condition
                     an NDMP_IO_ERR SHOULD be reported.)
            
                  NDMP_WRITE_PROTECT_ERR
                     Tape device could not be opened in write mode because the
                     tape is write protected. Alternatively the tape write protect
                     state has changed since it was opened or the open was a raw
                     mode open.
            
                  NDMP_EOF_ERR
                     The Tape command failed because end-of-file was encountered.
                     See Tape/Mover Interface for details of usage.
            
                  NDMP_EOM_ERR
                     The tape command failed because the end of media mark was
                     encountered. See Tape/Mover Interface for details of usage.
            
                  NDMP_FILE_NOT_FOUND_ERR
                     During a recover operation, a specified file was not found.
                     This error code is used in a Log Interface File Recovered
                     message.
            
                  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 (Generic Error)
                     Error decoding message.
            
                  NDMP_ILLEGAL_STATE_ERR
                     Message cannot be processed in the current state.
            
                  NDMP_UNDEFINED_ERR (Generic Error)
                     This error code SHOULD only be used if no other error code
                     describes the condition. A Log Message SHOULD be sent to
                     describe the condition in detail.
            
                  NDMP_XDR_ENCODE_ERR (Generic Error)
                     Error encoding reply message.
            
                  NDMP_NO_MEM_ERR (Generic Error)
                     Memory allocation error. To avoid diagnostic errors, it might
                     be useful to send a Log Message giving more information about
                     the operation that failed.
            
            
            
            Expires October 2003                                   [Page 36]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_CONNECT_ERR
                     Data Server - Tape Server failed to establish a data
                     connection.
            
                  NDMP_SEQUENCE_NUM_ERR
                     Request header received contains an invalid sequence number.
            
                  NDMP_READ_IN_PROGRESS_ERR
                     The mover read request was received while a previous mover
                     read was in progress. Only one read request may be processed
                     at any one time.
            
                  NDMP_PRECONDITION_ERR
                     The request was rejected because a required preparatory
                     action has not been performed. For instance, an
                     NDMP_MOVER_LISTEN or NDMP_MOVER_CONNNECT command would be
                     rejected with this error code if the mover record size had
                     not been set.
            
                  NDMP_CLASS_NOT_SUPPORTED_ERR
                     The list of selected class-version pairs includes one or more
                     classes that the NDMP Server does not support.
            
                  NDMP_VERSION_NOT_SUPPORTED_ERR
                     The list of selected class-version pairs includes one or more
                     class with unsupported version.
            
                  NDMP_EXT_DUPL_CLASSES_ERR
                     The list of selected class-version pairs includes two or more
                     instances of one class with different versions.
            
                  NDMP_EXT_DANDN_ILLEGAL_ERR
                     The D+N requests are illegal at this point because extension
                     requests have already been issued.
            
            2.8.2 Error Codes in NDMP Extensions
               NDMP extensions need to provide error codes in the context of the
               extension. This is done by looking at the 32 bit error code as two 16
               bit numbers: "class"."class_specific_error_code". Implicitly the
               error codes for core NDMP is "class_0x0"."core_NDMP_error_code".
            
               The definition of error codes for extensions is extension specific,
               and is specified together with the extension. For proprietary
               extensions the implementer provides the specification. For standard
               extensions the error codes are specified in the standard extension
               specification.
            
            2.9. Message Numbers
               The following messages are defined:
            
            
            
            
            
            
            Expires October 2003                                   [Page 37]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                   enum ndmp_message
                  {
                      NDMP_CONNECT_OPEN               = 0x900,
                      NDMP_CONNECT_CLIENT_AUTH        = 0x901,
                      NDMP_CONNECT_CLOSE              = 0x902,
                      NDMP_CONNECT_SERVER_AUTH        = 0x903,
            
                      NDMP_CONFIG_GET_HOST_INFO       = 0x100,
                      NDMP_CONFIG_GET_CONNECTION_TYPE = 0x102,
                      NDMP_CONFIG_GET_AUTH_ATTR       = 0x103,
                      NDMP_CONFIG_GET_BUTYPE_INFO     = 0x104,
                      NDMP_CONFIG_GET_FS_INFO         = 0x105,
                      NDMP_CONFIG_GET_TAPE_INFO       = 0x106,
                      NDMP_CONFIG_GET_SCSI_INFO       = 0x107,
                      NDMP_CONFIG_GET_SERVER_INFO     = 0x108,
                      NDMP_CONFIG_SET_EXT_LIST        = 0x109,
                      NDMP_CONFIG_GET_EXT_LIST        = 0x10A,
            
                      NDMP_SCSI_OPEN                  = 0x200,
                      NDMP_SCSI_CLOSE                 = 0x201,
                      NDMP_SCSI_GET_STATE             = 0x202,
                      NDMP_SCSI_OBSOLETE1             = 0x203,
                      NDMP_SCSI_RESET_DEVICE          = 0x204,
                      NDMP_SCSI_OBSOLETE2             = 0x205,
                      NDMP_SCSI_EXECUTE_CDB           = 0x206,
            
                      NDMP_TAPE_OPEN                  = 0x300,
                      NDMP_TAPE_CLOSE                 = 0x301,
                      NDMP_TAPE_GET_STATE             = 0x302,
                      NDMP_TAPE_MTIO                  = 0x303,
                      NDMP_TAPE_WRITE                 = 0x304,
                      NDMP_TAPE_READ                  = 0x305,
                      NDMP_TAPE_EXECUTE_CDB           = 0x307,
            
                      NDMP_DATA_GET_STATE             = 0x400,
                      NDMP_DATA_START_BACKUP          = 0x401,
                      NDMP_DATA_START_RECOVER         = 0x402,
                      NDMP_DATA_ABORT                 = 0x403,
                      NDMP_DATA_GET_ENV               = 0x404,
                      NDMP_DATA_STOP                  = 0x407,
                      NDMP_DATA_LISTEN                = 0x409,
                      NDMP_DATA_CONNECT               = 0x40A,
                      NDMP_DATA_START_RECOVER_FILEHIST = 0x40B,
            
                      NDMP_NOTIFY_DATA_HALTED         = 0x501,
                      NDMP_NOTIFY_CONNECTION_STATUS   = 0x502,
                      NDMP_NOTIFY_MOVER_HALTED        = 0x503,
                      NDMP_NOTIFY_MOVER_PAUSED        = 0x504,
                      NDMP_NOTIFY_DATA_READ           = 0x505,
            
                      NDMP_LOG_FILE                   = 0x602,
                      NDMP_LOG_MESSAGE                = 0x603,
            
            
            
            Expires October 2003                                   [Page 38]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
                      NDMP_FH_ADD_FILE                = 0x703,
                      NDMP_FH_ADD_DIR                 = 0x704,
                      NDMP_FH_ADD_NODE                = 0x705,
            
                      NDMP_MOVER_GET_STATE            = 0xA00,
                      NDMP_MOVER_LISTEN               = 0xA01,
                      NDMP_MOVER_CONTINUE             = 0xA02,
                      NDMP_MOVER_ABORT                = 0xA03,
                      NDMP_MOVER_STOP                 = 0xA04,
                      NDMP_MOVER_SET_WINDOW           = 0xA05,
                      NDMP_MOVER_READ                 = 0xA06,
                      NDMP_MOVER_CLOSE                = 0xA07,
                      NDMP_MOVER_SET_RECORD_SIZE      = 0xA08,
                      NDMP_MOVER_CONNECT              = 0xA09,
            
                      NDMP_EXT_STANDARD_BASE          = 0x10000,
            
                      NDMP_EXT_PROPRIETARY_BASE       = 0x20000000
                  };
            
            
            2.10. Message Definitions
               Each message is described using XDR specifications. These form either
               a request/reply message pair as shown below or a single post message
               constructed in a similar fashion.
            
                  struct message_name_request
                  {
                      type request_argument1;
                      ...
                      type request_argumentN;
                  };
            
                  struct message_name_reply
                  {
                  ndmp_error error;
                      type reply_argument1;
                      ...
                      type reply_argumentN;
                  };
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 39]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Each XDR specification conforms to the format given in [1] and can be
               processed using a program such as rpcgen. 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 arguments or if no
               reply message is defined. Following the XDR specification is a
               description of each argument in the message or messages. 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 MAY be
               meaningless. A list of errors that MAY typically be returned in the
               reply is provided for each message. This is not an exhaustive list.
               Generic errors, such as NDMP_NO_MEM_ERR, are not listed.
            
            2.11. Message Sequencing and State Tables
            2.11.1. General Rules
               This section describes the timing of NDMP messages. It describes when
               messages MUST be sent and when they MUST NOT be sent. The timing of
               messages is closely related to a number of state variables that
               describes the state of the NDMP Server. Some state variables are
               simple booleans. Two examples of Boolean variables are: "Is the
               client authorized?" or "Is the tape device open?" However, the Data
               and Mover Interfaces are more complex and are described below in
               state diagrams.
            
               The state machines are conceptually located in the NDMP Server and
               states changes are made in response to events in the NDMP Server. The
               DMA is informed of state changes by the receipt of NDMP messages. The
               DMA SHOULD recognize a state change when it receives a state change
               notification message from the NDMP Server or when it receives a reply
               from the NDMP Server accepting a previously issued request. The Data
               and Mover states may also be monitored using NDMP_DATA_GET_STATE and
               NDMP_MOVER_GET_STATE requests.
            
               If the DMA issues a request that would normally cause the NDMP Server
               to change state and this request is rejected, no state change is
               made.
            
               In normal conditions it is clear whether it is the responsibility of
               the DMA or the NDMP Server to send the next operational message.
               However, in error situations, abort messages may be sent by the party
               that is not currently in control. These situations can result in
               messages crossing in transmission causing race conditions. The usual
               result of this situation is that the request sent by the DMA is
               rejected by the NDMP Server with an NDMP_ILLEGAL_STATE_ERR error
               code. The DMA MUST handle this situation in a reasonable fashion.
               (That is, it SHOULD continue to tidy up the session and it MUST NOT
               treat the NDMP Server as if it had caused the error.) An example race
               condition is shown in section 2.11.5.1.
            
            2.11.2. Connection
               When an NDMP session first starts the DMA and NDMP server MUST ensure
               that they can communicate successfully.
            
            
            
            Expires October 2003                                   [Page 40]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               The TCP/IP connection is initiated by the DMA, which must know the
               port on which the NDMP Server is listening. Port 10,000 is reserved
               for NDMP. NDMP Servers SHOULD typically listen on port 10,000.
               However, to accommodate conflicts caused by another service already
               using port 10,000, both DMAs and Servers SHOULD be implemented so
               that they may be configured to use a different port.
            
               The first message sent on the connection MUST be an
               NDMP_NOTIFY_CONNECTION_STATUS message from the NDMP Server. The
               server MAY either refuse the connection because of some local
               difficulty or it MAY suggest that the DMA use a particular version of
               NDMP. The DMA SHOULD then send an NDMP_CONNECT_OPEN request
               specifying an NDMP version it wishes to support. If the NDMP Server
               accepts the NDMP_CONNECT_OPEN request the specified protocol version
               is used thereafter by the client and server for all successive
               messages.
            
               If the DMA uses the same NDMP version as specified in the original
               NDMP_NOTIFY_CONNECTION_STATUS message it MAY omit sending the
               NDMP_CONNECT_OPEN request. Sending any other request implicitly
               indicates acceptance of the NDMP version specified in the
               NDMP_NOTIFY_CONNECTION_STATUS message.
            
               If the client does not support the protocol version specified in the
               NDMP_NOTIFY_CONNECTION_STATUS message, the client SHOULD continue to
               send NDMP_CONNECT_OPEN requests with successively lower version
               numbers until the server accepts a message. Consider a server that
               supports versions 2 and 4 and a client that supports versions 2 and
               3. The server SHOULD specify version 4 in the
               NDMP_NOTIFY_CONNECTION_STATUS message. Because the client does not
               support version 4, the client SHOULD send an NDMP_CONNECT_OPEN
               request containing a version of 3. Because the server does not
               support version 3, the server MUST reject the request by returning an
               NDMP_CONNECT_OPEN reply containing an NDMP_ILLEGAL_ARGS_ERROR error
               code. The client SHOULD then send an NDMP_CONNECT_OPEN request
               containing a version of 2. Because the server supports version 2, it
               SHOULD accept the request by returning an NDMP_CONNECT_OPEN reply
               containing an NDMP_NO_ERR error code.
            
               When the DMA finishes using the connection it SHOULD send an
               NDMP_CONNECT_CLOSE message prior to closing the TCP connection. The
               NDMP Server SHOULD not close the connection until requested to do so
               by the DMA. If forced to close the connection due to a local error or
               shutdown it SHOULD first send an NDMP_NOTIFY_CONNECTION_STATUS
               request containing an NDMP_SHUTDOWN reason code.
            
            2.11.3. Authentication
               The NDMP Server stores user data that MUST be protected from
               unauthorized access. The DMA MUST be authenticated by using the
               NDMP_CONNECT_CLIENT_AUTH request before it is allowed to use most of
               the NDMP requests. Following are the only requests that the DMA MAY
               use prior to authentication:
            
            
            
            Expires October 2003                                   [Page 41]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               NDMP_CONNECT_OPEN, NDMP_CONNECT_CLOSE, NDMP_CONNECT_CLIENT_AUTH,
               NDMP_CONFIG_GET_SERVER_INFO, NDMP_CONFIG_GET_AUTH_ATTR.
            
               Because the DMA is in control of establishing the TCP/IP connection
               and does not have any resources to protect there is less need to
               authenticate the server. There is an NDMP_CONNECT_SERVER_AUTH request
               that MAY be used. However, this is optional and the NDMP Server MAY
               choose not to implement it.
            
            2.11.4. SCSI and Tape Devices
               The SCSI Interface accesses media changer devices. A single media
               changer device can be associated with the NDMP connection using the
               NDMP_SCSI_OPEN request. After finishing with the device the
               association is removed by issuing an NDMP_SCSI_CLOSE request.
            
               Other SCSI Interface commands MAY only be issued when the SCSI device
               is open.
            
               The Tape interface is similar, using NDMP_TAPE_OPEN and
               NDMP_TAPE_CLOSE to associate and disassociate the device with the
               NDMP connection.
            
               An NDMP Server is restricted to having a single device (SCSI or tape)
               associated with a connection at a time. The NDMP Server MUST return
               an NDMP_BUSY_ERROR upon receiving an NDMP_TAPE_OPEN or NDMP_SCSI_OPEN
               request if a device is already open.
            
               The Tape interface prepares the tape for use by the MOVER which
               writes and reads the actual backup data. For the two to work
               together, a number rules must be followed about when requests can be
               issued:
            
                  - The TAPE device MUST be open when the MOVER is activated by one
                  of NDMP_DATA_CONNECT, NDMP_MOVER_CONNECT or NDMP_MOVER_CONTINUE
                  requests.
            
                  - When the MOVER state is NDMP_MOVER_STATE_ACTIVE, no Tape
                  interface requests can be issued except NDMP_TAPE_GET_STATE.
            
                  - When the MOVER state is NDMP_MOVER_STATE_PAUSED, the Tape
                  interface can be freely used. This might even involve closing the
                  current tape device and opening the same or another device before
                  issuing a NDMP_MOVER_CONTINUE request.
            
            
            
            2.11.5. Data State Diagram
               In the following diagram the states are shown in boxes of "*"-s.
               Requests received from the DMA are shown through their message
               identifier (for example, NDMP_DATA_CONNECT). The state transitions
               occur as the events take place at the NDMP Server. The DMA is
               informed of the transitions in the following ways:
            
            
            
            Expires October 2003                                   [Page 42]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  - The transition to NDMP_DATA_STATE_HALTED state is always
                  indicated by an NDMP_NOTIFY_DATA_HALTED message. This is true
                  even if the transition was instigated by an NDMP_DATA_ABORT
                  request.
            
                  - The transition from NDMP_DATA_STATE_LISTEN state to
                  NDMP_DATA_STATE_CONNECTED state is only indicated indirectly
                  through the NDMP_MOVER_CONNECT reply on the Mover Interface.
            
                  - All other state transitions are related to direct requests on
                  the Data Interface and are complete when the corresponding reply
                  message indicates success.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 43]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     +----------------->-----------------+
                     |                                   |
                     |                                   V
                     |                             *************
                     |                             **  Idle   **
                     |                             *************
                     |                              |         |
                     |               +--------------+         |
                     |               |                        |
                     |        NDMP_DATA_LISTEN                |
                     |               V                        |
                     |         ************                   |
                     |         ** Listen **           NDMP_DATA_CONNECT
                     |         ************                   |
                     |          |        |                    |
                     |          |      connected              |
                     |          |        +----->------+       |
                     |          |                     |       |
                     |   NDMP_DATA_ABORT              V       V
                     |         OR               **********************
                     |    Internal Error        **    Connected     **
                     |         OR               **********************
                     |   Connection Error        |                  |
                     |          |                |         NDMP_DATA_START_BACKUP
                     |          |                |                  OR
                     |          |                | NDMP_DATA_START_RECOVER_FILEHIST
                     |          |                |                  OR
                     |          V                |          NDMP_DATA_START_RECOVER
                     |          |         NDMP_DATA_ABORT           |
                     ^          |               OR                  V
                     |          |          Internal Error     ***************
                     |          |               OR            **  Active   **
                     |          |         Connection Error    ***************
                     |          |                |                  |
                     |          |                |         Successful Completion
                     |          +---->-----+     |                  OR
                     |                     |     |            NDMP_DATA_ABORT
                     |                     |     |                  OR
                  NDMP_DATA_STOP           |     |            Internal Error
                     |                     |     |                  OR
                     |                     |     |           Connection Error
                     |                     |     |                  |
                     |                     |     |     +------<-----+
                     |                     |     |     |
                     |                     V     V     V
                     |                    ***************
                     |                    **  Halted   **
                     |                    ***************
                     |                           |
                     +------------<--------------+
            
               Figure 7 - Data state diagram
            
            
            
            Expires October 2003                                   [Page 44]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Idle State (NDMP_DATA_STATE_IDLE)
                  Idle is the start state of the state machine.
            
                  - Transition to listen state upon receipt of an NDMP_DATA_LISTEN
                  request.
            
                  - Transition to Connected state upon establishing a connection
                  with a local or remote NDMP Server after receiving an
                  NDMP_DATA_CONNECT request.
            
               Listen State (NDMP_DATA_STATE_LISTEN)
                  The NDMP Server remains in Listen state while waiting for a
                  connection from either a local or remote NDMP Server.
            
                  - Transition to Connected state upon establishing a connection
                  with an NDMP Server.
            
                  - Transition to Halted state upon receipt of an NDMP_DATA_ABORT
                  message.
            
                  - Transition to Halted state upon detection of a connection
                  failure.
            
                  - Transition to Halted state upon detection of an internal error.
            
               Connected State (NDMP_DATA_STATE_CONNECTED)
                  After the data connection is established, the NDMP Server is in
                  the Connected state.
            
                  - Transition to Active state upon receipt of a successful
                  NDMP_DATA_START_BACKUP message.
            
                  - Transition to Active state upon receipt of a successful
                  NDMP_DATA_START_RECOVER message.
            
                  - Transition to Halted state upon receipt of an NDMP_DATA_ABORT
                  message.
            
                  - Transition to Halted state upon detection of connection
                  failure.
            
                  - Transition to Halted state upon detection of an internal error.
            
               Active State (NDMP_DATA_STATE_ACTIVE)
                  The NDMP Server remains in Active state while a backup or
                  recovery is active.
            
                  - Transition to Halted state upon detection of a backup/recover
                  error. (Note: Errors related to isolated files SHOULD be reported
                  through the Log Interface and the backup/recover MUST continue.)
            
            
            
            
            
            Expires October 2003                                   [Page 45]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  - Transition to Halted state upon detection of a connection
                  error.
            
                  - Transition to Halted state upon receipt of an NDMP_DATA_ABORT
                  message.
            
                  - Transition to Halted state upon completion of backup/recover.
            
               Halted State (NDMP_DATA_STATE_HALTED)
                  The NDMP Server enters Halted state after a backup/recover has
                  been completed or aborted.
            
                  - Transition to Idle state upon receipt of an NDMP_DATA_STOP
                  message.
            
            2.11.5.1. Example Race Condition
               The NDMP Server is in NDMP_DATA_STATE_CONNECTED state waiting to
               receive an NDMP_DATA_START_BACKUP request. If at this point the
               connection fails (alternatively a local error or shutdown situation
               arises), the NDMP Server will send an NDMP_NOTIFY_DATA_HALTED message
               and move into NDMP_DATA_STATE_HALTED state. The DMA can send an
               NDMP_DATA_START_BACKUP request that crosses the halted notification.
               In this case the NDMP_DATA_START_BACKUP request is rejected with an
               NDMP_ILLEGAL_STATE_ERR error code.
            
                  DMA                                        NDMP Server
                  -----------                               -----------
                  DMA tries to                              NDMP Server detects
                  start backup.                             connection error on
                                                            mover i/f
            
                  NDMP_DATA_START_BACKUP                    NDMP_NOTIFY_DATA_HALTED
                                      --->-----\    /-----<---
                                                \  /         NDMP Server moves to
                                                 \/          Halted state
                                                 /\
                                                /  \
                                      ----<----/    \---->---
                  DMA now thinks                            Since NDMP Server is
                  NDMP Server is halted                     in halted state the
                                                            Received
                                                            NDMP_DATA_START_BACKUP
                                                            is rejected
                                     ------------<------------
                  DMA MUST               NDMP_DATA_START_BACKUP reply
                  handle this error       (NDMP_ILLEGAL_STATE_ERR)
                  response.
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 46]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.11.6. Mover State Table
               In the following diagram the states are shown in boxes of "*"-s.
               Requests received from the DMA are shown through their message
               identifier (for example, NDMP_MOVER_LISTEN). The state transitions
               occur as the events take place at the NDMP Server. The DMA is
               informed of the transitions in the following ways:
            
                  - The transition to NDMP_MOVER_STATE_HALTED state is always
                  indicated by an NDMP_NOTIFY_MOVER_HALTED message. This is true
                  even if the transition was instigated by an NDMP_MOVER_ABORT
                  request.
            
                  - The transition from NDMP_MOVER_STATE_LISTEN state to
                  NDMP_MOVER_STATE_CONNECTED state is only indicated indirectly
                  through the NDMP_DATA_CONNECT reply on the Data Interface.
            
                  - All other state transitions are related to direct requests on
                  the Mover Interface and are complete when the corresponding reply
                  message indicates success.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 47]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     +--------------->----------------+
                     |                                |
                     |                                V
                     |                          *************
                     |                          **  Idle   **
                     |                          *************
                     |                             |     |
                     |               +------<------+     |
                     |               |                   |
                     |       NDMP_MOVER_LISTEN           |
                     |               V                   |
                     |         ************              |
                     |         ** Listen **       NDMP_MOVER_CONNECT
                     |         ************              |
                     |          |        |               |
                     |          |      connected         |
                     |          |        +----->-----+   |   +---------<--------+
                     |          |                    |   |   |                  |
                     |   NDMP_MOVER_ABORT            V   V   V                  |
                     |         OR               *******************             |
                     |   Internal Error         ***   Active    ***             |
                     |         OR               *******************             |
                     |  Connection Error         |               |              |
                     |          |        Connection Closed       |              ^
                     |          |               OR             EOW OR    NDMP_MOVER
                     |          |         NDMP_MOVER_ABORT     Seek OR    CONTINUE
                     |          V               OR            EOM OR EOF        |
                     ^          |         Internal Error         |              |
                     |          |               OR               |              |
                     |          |        Connection Error        V              |
                     |          |               OR            ***************   |
                     |          |           Media Error       **  Paused   **   |
                     |          |                |            ***************   |
                     |          +---->-----+     |              |          |    |
                     |                     |     |       NDMP_MOVER_ABORT  +->--+
                     |                     |     |             OR
                  NDMP_MOVER_STOP          |     |       Internal Error
                     |                     |     |             OR
                     |                     |     |      Connection Closed
                     |                     |     |             OR
                     |                     |     |       NDMP_MOVER_CLOSE
                     |                     |     |              |
                     |                     |     |     +---<----+
                     |                     |     |     |
                     |                     V     V     V
                     |                    ***************
                     |                    **  Halted   **
                     |                    ***************
                     |                           |
                     +------------<--------------+
            
               Figure 8 - Mover state diagram
            
            
            
            Expires October 2003                                   [Page 48]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Idle State (NDMP_MOVER_STATE_IDLE)
                  Idle is the start state of the state machine.
            
                  - Transition to Listen state upon receipt of an NDMP_MOVER_LISTEN
                  message.
            
                  - Transition to Active state upon establishing a connection with
                  another NDMP Server by an NDMP_MOVER_CONNECTED message.
            
               Listen State (NDMP_MOVER_STATE_LISTEN)
                  The NDMP Server remains in Listen state while waiting for a
                  connection from either a local or remote NDMP Data Server.
            
                  - Transition to Active state upon establishing a connection with
                  an NDMP Server.
            
                  - Transition to Halted state upon receipt of an NDMP_MOVER_ABORT
                  message.
            
                  - Transition to Halted state upon detection of an internal error.
            
                  - Transition to Halted state upon detection of a connection
                  error.
            
               Active State (NDMP_MOVER_STATE_ACTIVE)
            
                  The NDMP Server remains in Active state while the data connection
                  is active.
            
                  - Transition to Halted state upon detection of an internal error.
            
                  - Transition to Halted state upon receipt of an 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 Halted state upon detection of media error.
            
                  - Transition to Paused state upon detection of End of Media
                  (EOM).
            
                  - Transition to Paused state upon detection of End of File (EOF).
            
                  - Transition to Paused state upon reaching end of data window.
            
               Halted State (NDMP_MOVER_STATE_HALTED)
                  The NDMP Server enters Halted state after a backup/recover has
                  completed or aborted.
            
            
            
            
            Expires October 2003                                   [Page 49]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  - Transition to Idle state upon receipt of an NDMP_MOVER_STOP
                  message.
            
               Paused State (NDMP_MOVER_STATE_PAUSED)
                  The NDMP Server remains in Paused state while waiting for a tape
                  to be changed or a new MOVER window to be set.
            
                  - Transition to Active state upon receipt of an
                  NDMP_MOVER_CONTINUE message.
            
                  - Transition to Halted state upon receipt of an NDMP_MOVER_ABORT
                  message.
            
                  - Transition to Halted state upon receipt of an NDMP_MOVER_CLOSE
                  message.
            
                  - Transition to Halted state upon detection of an internal error.
            
                  - Transition to Halted state upon detection of connection close.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 50]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            2.12. Supporting XDR Definitions for NDMP
               This section defines the XDRs for the enums, constants and supporting
               structures that the messages in sections 3 and 4 use. They are
               presented as in a common place because many of these structures are
               used by more than one message.
            
               Note that this list of enums and constants does not include the ones
               already presented in section 2. As a result, there should be no
               duplication.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 51]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  enum ndmp_auth_type
                  {
                      NDMP_AUTH_NONE          = 0,
                      NDMP_AUTH_TEXT          = 1,
                      NDMP_AUTH_MD5           = 2
                  };
            
                  struct ndmp_auth_text
                  {
                      string auth_id<>;
                      string auth_password<>;
                  };
            
                  struct ndmp_auth_md5
                  {
                      string auth_id<>;
                      opaque auth_digest[16];
                  };
            
                  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_attr
                      switch (enum ndmp_auth_type auth_type)
                  {
                      case NDMP_AUTH_NONE:
                          void;
                      case NDMP_AUTH_TEXT:
                          void;
                      case NDMP_AUTH_MD5:
                          opaque challenge[64];
                  };
            
                  enum ndmp_addr_type
                  {
                      NDMP_ADDR_LOCAL          = 0,
                      NDMP_ADDR_TCP            = 1,
                      NDMP_ADDR_RESERVED       = 2,
                      NDMP_ADDR_IPC            = 3
                  };
            
                  const NDMP_BUTYPE_BACKUP_FILELIST =        0x0002;
                  const NDMP_BUTYPE_RECOVER_FILELIST =       0x0004;
                  const NDMP_BUTYPE_BACKUP_DIRECT =          0x0008;
                  const NDMP_BUTYPE_RECOVER_DIRECT =         0x0010;
            
            
            
            Expires October 2003                                   [Page 52]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  const NDMP_BUTYPE_BACKUP_INCREMENTAL =     0x0020;
                  const NDMP_BUTYPE_RECOVER_INCREMENTAL =    0x0040;
                  const NDMP_BUTYPE_BACKUP_UTF8 =            0x0080;
                  const NDMP_BUTYPE_RECOVER_UTF8 =           0x0100;
                  const NDMP_BUTYPE_BACKUP_FH_FILE =         0x0200;
                  const NDMP_BUTYPE_BACKUP_FH_DIR =          0x0400;
                  const NDMP_BUTYPE_RECOVER_FILEHIST =       0x0800;
                  const NDMP_BUTYPE_RECOVER_FH_FILE =        0x1000;
                  const NDMP_BUTYPE_RECOVER_FH_DIR =         0x2000;
            
                  struct ndmp_butype_info
                  {
                      string      butype_name<>;
                      ndmp_pval   default_env<>;
                      u_long      attrs;
                  };
            
                  const NDMP_FS_INFO_TOTAL_SIZE_UNS    = 0x00000001;
                  const NDMP_FS_INFO_USED_SIZE_UNS     = 0x00000002;
                  const NDMP_FS_INFO_AVAIL_SIZE_UNS    = 0x00000004;
                  const NDMP_FS_INFO_TOTAL_INODES_UNS  = 0x00000008;
                  const NDMP_FS_INFO_USED_INODES_UNS   = 0x00000010;
            
                  struct ndmp_fs_info
                  {
                      u_long            unsupported;
                      string            fs_type<>;
                      string            fs_logical_device<>;
                      string            fs_physical_device<>;
                      ndmp_u_quad       total_size;
                      ndmp_u_quad       used_size;
                      ndmp_u_quad       avail_size;
                      ndmp_u_quad       total_inodes;
                      ndmp_u_quad       used_inodes;
                      ndmp_pval         fs_env<>;
                      string            fs_status<>;
                  };
            
                  const NDMP_TAPE_ATTR_REWIND = 0x00000001;
                  const NDMP_TAPE_ATTR_UNLOAD = 0x00000002;
                  const NDMP_TAPE_ATTR_RAW    = 0x00000004;
            
                  struct ndmp_device_capability
                  {
                      string                  device<>;
                      u_long                  attr;
                      ndmp_pval               capability<>;
                  };
            
                  struct ndmp_device_info
                  {
                      string                  model<>;
            
            
            
            Expires October 2003                                   [Page 53]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      ndmp_device_capability  caplist<>;
                  };
            
                  struct ndmp_pval
                  {
                      string      name<>;
                      string      value<>;
                  };
            
                  struct ndmp_class_list
                  {
                      u_short ext_class_id;
                      u_short ext_version<>;
                  };
            
                  struct ndmp_class_version
                  {
                      u_short      ext_class_id;
                      u_short      ext_version;
                  };
            
                  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<>;
                  };
            
                  enum ndmp_tape_open_mode
                  {
                      NDMP_TAPE_READ_MODE          = 0,
                      NDMP_TAPE_RDWR_MODE          = 1,
                      NDMP_TAPE_RAW_MODE           = 2
                  };
            
                  struct ndmp_u_quad
                  {
                      u_long high;
            
            
            
            Expires October 2003                                   [Page 54]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      u_long low;
                  };
            
                  const NDMP_TAPE_STATE_NOREWIND         = 0x0008;
                  const NDMP_TAPE_STATE_WR_PROT          = 0x0010;
                  const NDMP_TAPE_STATE_ERROR            = 0x0020;
                  const NDMP_TAPE_STATE_UNLOAD           = 0x0040;
                  const NDMP_TAPE_STATE_FILE_NUM_UNS     = 0x00000001;
                  const NDMP_TAPE_STATE_SOFT_ERRORS_UNS  = 0x00000002;
                  const NDMP_TAPE_STATE_BLOCK_SIZE_UNS   = 0x00000004;
                  const NDMP_TAPE_STATE_BLOCKNO_UNS      = 0x00000008;
                  const NDMP_TAPE_STATE_TOTAL_SPACE_UNS  = 0x00000010;
                  const NDMP_TAPE_STATE_SPACE_REMAIN_UNS = 0x00000020;
                  const NDMP_TAPE_RESERVED1_UNS          = 0x00000040;
            
                  enum ndmp_tape_mtio_op
                  {
                      NDMP_MTIO_FSF          = 0,
                      NDMP_MTIO_BSF          = 1,
                      NDMP_MTIO_FSR          = 2,
                      NDMP_MTIO_BSR          = 3,
                      NDMP_MTIO_REW          = 4,
                      NDMP_MTIO_EOF          = 5,
                      NDMP_MTIO_OFF          = 6,
                      NDMP_MTIO_TUR          = 7
                  };
            
                  enum ndmp_data_operation
                  {
                      NDMP_DATA_OP_NOACTION           = 0,
                      NDMP_DATA_OP_BACKUP             = 1,
                      NDMP_DATA_OP_RECOVER            = 2,
                      NDMP_DATA_OP_RECOVER_FILEHIST   = 3
                  };
            
                  enum ndmp_data_state
                  {
                      NDMP_DATA_STATE_IDLE            = 0,
                      NDMP_DATA_STATE_ACTIVE          = 1,
                      NDMP_DATA_STATE_HALTED          = 2,
                      NDMP_DATA_STATE_LISTEN          = 3,
                      NDMP_DATA_STATE_CONNECTED       = 4
                  };
            
                  enum ndmp_data_halt_reason
                  {
                      NDMP_DATA_HALT_NA                      = 0,
                      NDMP_DATA_HALT_SUCCESSFUL              = 1,
                      NDMP_DATA_HALT_ABORTED                 = 2,
                      NDMP_DATA_HALT_INTERNAL_ERROR          = 3,
                      NDMP_DATA_HALT_CONNECT_ERROR           = 4
                  };
            
            
            
            Expires October 2003                                   [Page 55]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
                  struct ndmp_tcp_addr
                  {
                      u_long       ip_addr;
                      u_short      port;
                      ndmp_pval    addr_env<>;
                  };
            
                  struct ndmp_ipc_addr
                  {
                      opaque comm_data<>;
                  };
            
                  union ndmp_addr switch (ndmp_addr_type addr_type)
                  {
                      case NDMP_ADDR_LOCAL:
                          void;
                      case NDMP_ADDR_TCP:
                          ndmp_tcp_addr tcp_addr<>;
                      case NDMP_ADDR_IPC:
                          ndmp_ipc_addr ipc_addr;
                  };
            
                  const NDMP_DATA_STATE_EST_BYTES_REMAIN_UNS = 0x00000001;
                  const NDMP_DATA_STATE_EST_TIME_REMAIN_UNS  = 0x00000002;
            
                  struct ndmp_name
                  {
                      string           original_path<>;
                      string           destination_dir<>;
                      string           name<>;
                      string           other_name<>;
                      ndmp_u_quad      node;
                      ndmp_u_quad      fh_info;
                  };
            
                  enum ndmp_mover_state
                  {
                      NDMP_MOVER_STATE_IDLE            = 0,
                      NDMP_MOVER_STATE_LISTEN          = 1,
                      NDMP_MOVER_STATE_ACTIVE          = 2,
                      NDMP_MOVER_STATE_PAUSED          = 3,
                      NDMP_MOVER_STATE_HALTED          = 4
                  };
            
                  enum ndmp_mover_pause_reason
                  {
                      NDMP_MOVER_PAUSE_NA            = 0,
                      NDMP_MOVER_PAUSE_EOM           = 1,
                      NDMP_MOVER_PAUSE_EOF           = 2,
                      NDMP_MOVER_PAUSE_SEEK          = 3,
                      NDMP_MOVER_PAUSE_EOW          = 5
            
            
            
            Expires October 2003                                   [Page 56]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  };
            
                  enum ndmp_mover_halt_reason
                  {
                      NDMP_MOVER_HALT_NA                    = 0,
                      NDMP_MOVER_HALT_CONNECT_CLOSED        = 1,
                      NDMP_MOVER_HALT_ABORTED               = 2,
                      NDMP_MOVER_HALT_INTERNAL_ERROR        = 3,
                      NDMP_MOVER_HALT_CONNECT_ERROR         = 4,
                      NDMP_MOVER_HALT_MEDIA_ERROR           = 5
                  };
            
                  enum ndmp_mover_mode
                  {
                      NDMP_MOVER_MODE_READ            = 0,
                      NDMP_MOVER_MODE_WRITE           = 1,
                      NDMP_MOVER_MODE_NOACTION        = 2
                  };
            
                  enum ndmp_connection_status_reason
                  {
                      NDMP_CONNECTED          = 0,
                      NDMP_SHUTDOWN           = 1,
                      NDMP_REFUSED            = 2
                  };
            
                  enum ndmp_has_associated_message
                  {
                      NDMP_NO_ASSOCIATED_MESSAGE     = 0,
                      NDMP_HAS_ASSOCIATED_MESSAGE    = 1
                  };
            
                  enum ndmp_log_type
                  {
                      NDMP_LOG_NORMAL  = 0,
                      NDMP_LOG_DEBUG   = 1,
                      NDMP_LOG_ERROR   = 2,
                      NDMP_LOG_WARNING = 3
                  };
            
                  enum ndmp_recovery_status
                  {
                      NDMP_RECOVERY_SUCCESSFUL               = 0,
                      NDMP_RECOVERY_FAILED_PERMISSION        = 1,
                      NDMP_RECOVERY_FAILED_NOT_FOUND         = 2,
                      NDMP_RECOVERY_FAILED_NO_DIRECTORY      = 3,
                      NDMP_RECOVERY_FAILED_OUT_OF_MEMORY     = 4,
                      NDMP_RECOVERY_FAILED_IO_ERROR          = 5,
                      NDMP_RECOVERY_FAILED_UNDEFINED_ERROR   = 6,
                      NDMP_RECOVERY_FAILED_FILE_PATH_EXISTS  = 7
                  };
            
            
            
            
            Expires October 2003                                   [Page 57]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  enum ndmp_fs_type
                  {
                      NDMP_FS_UNIX          = 0,
                      NDMP_FS_NT            = 1,
                      NDMP_FS_OTHER         = 2
                  };
            
                  typedef string ndmp_path<>;
            
                  struct ndmp_nt_path
                  {
                      ndmp_path      nt_path;
                      ndmp_path      dos_path;
                  };
            
                  union ndmp_file_name switch (ndmp_fs_type fs_type)
                  {
                      case NDMP_FS_UNIX:
                           ndmp_path      unix_name;
                      case NDMP_FS_NT:
                           ndmp_nt_path   nt_name;
                      default:
                           ndmp_path      other_name;
                  };
            
                  enum ndmp_file_type
                  {
                      NDMP_FILE_DIR            =0,
                      NDMP_FILE_FIFO           =1,
                      NDMP_FILE_CSPEC          =2,
                      NDMP_FILE_BSPEC          =3,
                      NDMP_FILE_REG            =4,
                      NDMP_FILE_SLINK          =5,
                      NDMP_FILE_SOCK           =6,
                      NDMP_FILE_REGISTRY       =7,
                      NDMP_FILE_OTHER          =8
                  };
            
                  const NDMP_FILE_STAT_ATIME_UNS = 0x00000001;
                  const NDMP_FILE_STAT_CTIME_UNS = 0x00000002;
                  const NDMP_FILE_STAT_GROUP_UNS = 0x00000004;
            
                  struct ndmp_file_stat
                  {
                      u_long            unsupported;
                      ndmp_fs_type      fs_type;
                      ndmp_file_type    ftype;
                      u_long            mtime;
                      u_long            atime;
                      u_long            ctime;
                      u_long            owner;
                      u_long            group;
            
            
            
            Expires October 2003                                   [Page 58]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      u_long            fattr;
                      ndmp_u_quad       size;
                      u_long            links;
                  };
            
                  struct ndmp_file
                  {
                      ndmp_file_name      name<>;
                      ndmp_file_stat      stat<>;
                      ndmp_u_quad         node;
                      ndmp_u_quad         fh_info;
                  };
            
                  struct ndmp_dir
                  {
                      ndmp_file_name    name<>;
                      ndmp_u_quad       node;
                      ndmp_u_quad       parent;
                  };
            
                  struct ndmp_node
                  {
                      ndmp_file_stat    stats<>;
                      ndmp_u_quad       node;
                      ndmp_u_quad       fh_info;
                  };
            
            
            2.13. Protocol Version Compatibility
               For reasons of backward compatibility, some requests must not change
               between versions of NDMP. The messages that MUST remain unchanged
               between versions of NDMP are:
            
                  - NDMP_CONNECT_OPEN
            
                  - NDMP_CONNECT_CLOSE
            
                  - NDMP_NOTIFY_CONNECTION_STATUS
            
               These messages will not change in any future release. The parameters
               MUST not change since these messages may be sent before protocol
               version negotiation has completed.
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 59]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3. NDMP Server Interfaces
               This section defines the protocol interfaces implemented by the NDMP
               Server.
            
            3.1. Connect Interface
               This interface authenticates the client and negotiates the version of
               protocol to be used.
            
               The DMA first connects to a well-known port (10,000). The NDMP Server
               accepts the connection and sends an NDMP_NOTIFY_CONNECTION_STATUS
               message. The DMA then sends an NDMP_CONNECT_OPEN message. The DMA is
               authenticated by the NDMP Server using an NDMP_CONNECT_CLIENT_AUTH
               message. Optionally, the DMA MAY use an NDMP_CONNECT_SERVER_AUTH
               message to authenticate the NDMP Server as well.
            
               If any of the Connect Interface messages fail, the DMA SHOULD close
               the connection using NDMP_CONNECTION_CLOSE.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 60]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.1.1. NDMP_CONNECT_OPEN
               This message negotiates the protocol version to be used between the
               DMA and NDMP Server. This message is OPTIONAL if the DMA agrees to
               the protocol version specified in the NDMP_NOTIFY_CONNECTION_STATUS
               message. If sent, it MUST be the first message type sent by the DMA.
               If the suggested protocol version is not supported on the NDMP
               Server, an NDMP_ILLEGAL_ARGS_ERR MUST be returned.
            
               The DMA SHOULD continue to try this same request with a different
               protocol version until the negotiation succeeds or there are no more
               protocol versions to try. After the protocol version has been
               successfully negotiated, it remains until the end of the NDMP
               session. It is illegal to send this message after any other type of
               message has been sent.
            
               If no agreement on protocol version is reached the DMA SHOULD close
               the connection with an NDMP_CONNECT_CLOSE request.
            
               For reasons of backward compatibility, it is guaranteed that the
               parameters of this message will not change in any future release. The
               parameters MUST not change since this message is sent prior to
               protocol version negotiation.
            
               Message XDR definition
            
                  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 DMA. The valid
                     protocol_version is 1, 2, 3 or 4.
            
               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
                     different protocol version number.
            
            
            
            
            Expires October 2003                                   [Page 61]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The protocol has already been negotiated.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 62]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.1.2. NDMP_CONNECT_CLIENT_AUTH
               This request authenticates the DMA to a NDMP Server. Successful DMA
               authentication MUST occur prior to processing most NDMP requests.
               Requests that do not require DMA authentication are limited to
               NDMP_CONNECT_OPEN, NDMP_CONNECT_CLOSE, NDMP_CONFIG_GET_SERVER_INFO,
               NDMP_CONFIG_GET_AUTH_ATTR and NDMP_CONNECT_CLIENT_AUTH. Any other
               request received prior to successful DMA authentication will result
               in a NDMP_NOT_AUTHORIZED reply error.
            
               NDMP DMA and server implementations MUST support at least one of the
               three authentication methods described below.
            
               NONE
                  No authentication is required.
            
               TEXT
                  The DMA identity is authenticated using an auth id representing
                  the user account name and an unencrypted (clear text) password.
            
               MD5
                  The DMA identity is authenticated using an auth_id representing
                  the user account name and a MD5 generated auth_digest derived
                  from a random, unpredictable challenge string and a password
                  known to both the DMA and the server. The MD5 message digest
                  algorithm is defined in RFC 1321.
            
                  The key advantage of the MD5 authentication method is that the
                  password is not passed between the DMA and the server, therefore
                  not subject to network snooping. Instead the server generates a
                  random challenge string that is made available to the DMA. The
                  challenge string and the password are used by both the DMA and
                  the server to compute a unique 16 byte MD5 message digest
                  representing the challenge response (auth_digest) from the DMA
                  back to the server. The DMA is successfully authenticated if it
                  is able to generate and present a challenge response that matches
                  the auth_digest independently generated by the server.
            
                  The DMA auth_digest is generated as follows. First the DMA issues
                  a NDMP_CONFIG_GET_AUTH_ATTR request to obtain a 64 byte random
                  challenge string from the server. The DMA constructs an input
                  string for MD5 message digest processing by concatenating the 1
                  to 32 byte password, 0 to 62 bytes of null (0x00) padding, the 64
                  byte random challenge string obtained from the server, and the 1
                  to 32 byte password again. The following diagram graphically
                  represents the required format of the 128 byte MD5 message digest
                  input. Note: individual fields are not shown to scale.
            
                  0                                                   127
                  +------------+-----------+-------------+------------+
                  |  Password  |  Padding  |  Challenge  |  Password  |
                  +------------+-----------+-------------+------------+
                  .------------------- 128 bytes -------------------->
            
            
            
            Expires October 2003                                   [Page 63]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  Note: if the password length is greater than 32 bytes, it is
                  truncated and the padding field is zero length. If the password
                  is less than 32 bytes, the padding field length is computed as
                  64-2*(password length). If the password is zero length, the
                  server should terminate the authentication process and return a
                  NDMP_NOT_AUTHORIZED_ERR reply error.
            
                  The output of the MD5 message digest processing is a unique 16
                  byte auth_digest. The auth_id and the auth_digest are sent by the
                  DMA to the server in the NDMP_CONNECT_CLIENT_AUTH request. The
                  server uses the auth_id to access the appropriate password for
                  the specified user account and independently computes the
                  auth_digest using the same 64 byte challenge and the locally
                  accessed password. If the resultant server computed auth_digest
                  matches the DMA supplied auth_digest, the authentication is
                  successful.
            
               Message XDR definition
            
                  struct ndmp_connect_client_auth_request
                  {
                      ndmp_auth_data       auth_data;
                  };
            
                  struct ndmp_connect_client_auth_reply
                  {
                      ndmp_error           error;
                  };
            
               Request Arguments
            
                  auth_data
                     A structure specifying the type of authentication used and
                     authentication data (auth_data) appropriate for the specified
                     type. NDMP DMAs and servers MUST support at least one of the
                     following authentication types:
            
                     NONE
                        No authentication required.
            
                     TEXT
                        The DMA identity is authenticated using an auth id string
                        representing the user account name and an auth_password
                        string representing the unencrypted (clear text) user
                        account password.
            
                     MD5
                        The DMA identity is authenticated using an auth_id
                        representing the user account name and a 16 byte MD5
                        generated auth_digest derived from a random challenge
                        string generated by the server and a user account password
                        known to both the DMA and the server.
            
            
            
            Expires October 2003                                   [Page 64]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Connection successfully authenticated.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     Incorrect authentication data or a zero length password was
                     detected by the MD5 authentication processing.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     Specified authentication method not supported.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 65]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.1.3. NDMP_CONNECT_CLOSE
               This message is used when the client wants to close the NDMP
               connection. The DMA SHOULD send this message before shutting down the
               TCP/IP connection. For reasons of backward compatibility, it is
               guaranteed that the parameters of this message will not change in any
               future release. The parameters MUST not change since this message is
               sent prior to protocol version negotiation.
            
               The message XDR definition has no request arguments.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 66]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.1.4. NDMP_CONNECT_SERVER_AUTH
               This optional request is used by the DMA to force the NDMP Server to
               authenticate itself. The DMA may use this request when there is a
               security requirement to validate the sever identity. A DMA MUST
               authenticate itself to the server using the NDMP_CONNECT_CLIENT_AUTH
               prior to issuing this request.
            
               Server authentication uses the same three methods (NONE, TEXT, and
               MD5) defined in section 3.1.2 for client (DMA) authentication.
               However in the case of server authentication, the DMA specifies the
               authentication attributes in the request. The attributes include the
               auth_type and for MD5 the 64 byte challenge string.
            
               The DMA response to a server authentication failure is implementation
               specific, however the DMA SHOULD gracefully close the NDMP
               connection.
            
               Message XDR definition
            
                  struct ndmp_connect_server_auth_request
                  {
                      ndmp_auth_attr        client_attr;
                  };
            
                  struct ndmp_connect_server_auth_reply
                  {
                      ndmp_error            error;
                      ndmp_auth_data        server_result;
                  };
            
               Request Arguments
            
                  client_attr
                     A structure specifying the type of authentication requested
                     and the authentication attributes appropriate for the
                     specified type.
            
                     challenge
                        For NDMP_AUTH_MD5, the DMA supplies a 64 byte challenge
                        string. This string MUST be both unique per
                        NDMP_CONNECT_SERVER_AUTH request and random such that the
                        string can not be predicted.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  server_result
                     Authentication result. NDMP Servers may return information to
                     the DMA to authenticate the server to the client.
            
            
            
            
            Expires October 2003                                   [Page 67]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     NONE
                        No authentication returned.
            
                     TEXT
                        The server identity is authenticated using an auth id
                        string representing the server account name and an
                        auth_password string representing the unencrypted (clear
                        text) server account password.
            
                     MD5
                        The server identity is authenticated using an auth_id
                        representing the server account name and a 16 byte MD5
                        generated auth_digest derived from a random challenge
                        string supplied by the DMA and a server account password
                        known to both the DMA and the server.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Connection successfully authenticated.
            
                  NDMP_NOT_SUPPORTED_ERR
                     Request not supported.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     Specified authentication method not supported.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA, or a zero length password was detected by the MD5
                     authentication processing.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 68]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2. Config Interface
               This interface allows the DMA to discover the configuration of the
               NDMP Server.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 69]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.1. NDMP_CONFIG_GET_HOST_INFO
               This request is used to get information about the host on which the
               NDMP Server is running.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_host_info_reply
                  {
                      ndmp_error  error;
                      string      hostname<>;
                      string      os_type<>;
                      string      os_vers<>;
                      string      hostid<>;
                  };
            
               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. It SHOULD be a globally unique
                     and persistent value for the host computer such as the CPU
                     type:serial_number, the on board MAC address, etc. This value
                     MAY be used by the DMA for licensing purposes.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Request successfully processed.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            Expires October 2003                                   [Page 70]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.2. NDMP_CONFIG_GET_SERVER_INFO
               This request is used to get information about the NDMP Server
               implementation. Since this request is also used to obtain the
               connection authentication types supported by the server, it is valid
               prior to client authentication.
            
               In the interest of security it is recommended that the vendor_name,
               product_name, and revision_number reply fields contain a null strings
               when accessed prior to successful client authentication.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_server_info_reply
                  {
                      ndmp_error        error;
                      string            vendor_name<>;
                      string            product_name<>;
                      string            revision_number<>;
                      ndmp_auth_type    auth_type<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  vendor_name
                     The name of the vendor that implements the NDMP Server. This
                     field SHOULD contain a null string prior to successful client
                     authentication.
            
                  product_name
                     The product name of the NDMP Server provided by the vendor.
                     This field SHOULD contain a null string prior to successful
                     client authentication.
            
                  revision_number
                     The revision number of the NDMP Server. This field SHOULD
                     contain a null string prior to successful client
                     authentication.
            
                  auth_types
                     Connection authentication types supported by the NDMP Server.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Request successfully processed.
            
            
            
            Expires October 2003                                   [Page 71]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 72]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.3. NDMP_CONFIG_GET_CONNECTION_TYPE
               This request returns a list of the data connection types supported by
               the NDMP Server.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_connection_type_reply
                  {
                      ndmp_error          error;
                      ndmp_addr_type      addr_types<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  addr_types
                     Array of supported connection types.
            
                     NDMP_ADDR_LOCAL
                        The Data service and the Tape service are instantiated
                        within the same NDMP Server, which is controlled by one
                        control connection. The communication mechanism is
                        implementation dependent.
            
                     NDMP_ADDR_TCP
                        One NDMP Server listens for a TCP/IP connection from
                        another NDMP Server.
            
                     NDMP_ADDR_IPC
                        Two NDMP Servers are on the same host, but controlled by
                        separate DMA connections.
            
                     * Notice that the value NDMP_ADDR_FC has been removed from
                     version 3 to 4. Clients MUST still tolerate the value, but
                     treat it as RESERVED.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Returned the supported connection type successfully.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
            
            
            
            
            
            Expires October 2003                                   [Page 73]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 74]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.4. NDMP_CONFIG_GET_AUTH_ATTR
               This message is used by the DMA to obtain the attributes of the
               authentication methods supported by the server.
            
               If the connection will be authenticated using the MD5 method, the DMA
               MUST use this message to obtain the server challenge string before
               sending the NDMP_CONNECT_CLIENT_AUTH message. Therefore this request
               is valid prior to client authentication.
            
               Message XDR definition
            
                  struct ndmp_config_get_auth_attr_request
                  {
                      ndmp_auth_type      auth_type;
                  };
            
                  struct ndmp_config_get_auth_attr_reply
                  {
                      ndmp_error          error;
                      ndmp_auth_attr      server_attr;
                  };
            
               Request Arguments
            
                  auth_type
                     The specific authentication method to be used to authenticate
                     the DMA to the NDMP Server.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  server_attr
                     Returned attributes required for a specific authentication
                     scheme. The following attribute is defined:
            
                     challenge
                        For NDMP_AUTH_MD5, the NDMP Server will return 64 byte
                        challenge string. This string MUST be both unique per
                        NDMP_CONFIG_GET_AUTH_ATTR reply and random such that the
                        string can not be predicted. If more than one challenge
                        string is requested for a given NDMP session, the most
                        recently generated string MUST be used by the server when
                        validating a subsequent client authentication attempt.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Returned the specific authentication type attributes
                     successfully.
            
            
            
            
            Expires October 2003                                   [Page 75]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     Specified authentication method not supported.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 76]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.5. NDMP_CONFIG_GET_BUTYPE_INFO
               This message is used to query the backup types supported by the NDMP
               Server and the capability of each supported backup type.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_butype_attr_reply
                  {
                      ndmp_error            error;
                      ndmp_butype_info      butype_info<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  butype_info
                     Information about the backup types supported by the NDMP
                     Server. Backup types are NDMP Server implementation
                     dependent. The following information is provided:
            
                     butype_name
                        Name of the backup application (such as dump, tar, cpio).
            
                     default_env
                        The default value of the environment variables specific to
                        the backup type.
            
                        The following are examples of the environment variables
                        that can be defined by the NDMP Server and the
                        corresponding default values.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 77]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  Variable     Meaning                Value          Default Value
                  ----------------------------------------------------------------
                  FILESYSTEM   device or file         file system or (No default
                               system name to         device name,    value)
                               be backed up (*)       e.g.
                                                      /dev/rsd0a
            
                  DIRECT       Utilize direct access  y/n            n
                               retrieval.
            
                  RECURSIVE    Processing             y/n            y (**)
                               subdirectories
                               y = recovery operation
                               should recurse into
                               directories and
                               recursively recover
                               directory contents.
                               n = recovery operation
                               should not recurse
                               into directories.
                               For each nlist entry
                               specifying a directory,
                               the recovery operation
                               should recover just
                               the directory but not
                               its contents.
                               This variable only
                               effects recovery
                               operations.
                               It has no effect during
                               backup operations.
            
            
                  TYPE         Backup type.           dump, tar,     (No default
                                                                     value)
                                                      cpio,...
            
                  USER         User id to run         user name      (No default
                                                                     value)
                               Backup.
            
                  HIST         Specifies type of file    f/d/n       n
                               history to generate.
                               f = file format history
                               d = node/dir format history
                               y = generate history - type of history
                                   is decided by the server
                               n = no history
            
                  PATHNAME_SEPARATOR                     *           "/"
                               This pval defines the
                               pathname separator
            
            
            
            Expires October 2003                                   [Page 78]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                               character for the
                               file system being
                               backed up. (***)
            
            
            
               * - FILESYSTEM can refer to either the file system device name (e.g.
               /dev/rdsk/c0t0d0s0) or the pathname of a directory. It is invalid for
               FILESYSTEM to refer to a regular file.
            
               ** - Default operation if RECURSIVE is not supported is to process
               subdirectories recursively.
            
               *** - The Data Server SHOULD add this pval to the environment at the
               start of the backup. The DMA must not define this pval in the pval
               list sent as part of the NDMP_DATA_START_BACKUP request. Default
               value is the forward slash, i.e. Unix style separator.
            
               The following are examples of the environment variables that can be
               defined by dump type and the corresponding default values.
            
                  Variable     Meaning             Value          The Default Value
                  -----------------------------------------------------------------
                  LEVEL        dump level          0 - 9           0
            
                  EXTRACT      "y" specifies       y/n             y
                               the -x option
                               for the
                               extraction, otherwise
                               the -r option is used
                               for the extraction.
            
                  UPDATE       update the          y/n             y
                               dumpdates file
            
            
               The following are examples of environment variables that can be
               defined by tar type and the corresponding default values.
            
            
            
                  Variable       Meaning         Value            The Default Value
                  -----------------------------------------------------------------
                  FILES          list of files   e.g. ./* ./*.c   (No default
                                 to be backed            ./*.h     value)
                                 up
            
            
               The following are examples of environment variables that can be
               defined by cpio type and the corresponding default values.
            
            
            
            
            
            Expires October 2003                                   [Page 79]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  Variable      Meaning          Value            The Default Value
                  -----------------------------------------------------------------
                  CMD           command to       e.g. find .      (No default
                                generate the     -name -print      value)
                                file list for
                                cpio.
            
            
                  attrs
                     Backup attributes bit mask. The following attribute bits are
                     defined:
            
                     NDMP_BUTYPE_BACKUP_FILELIST
                        The backup type supports archiving of selective files as
                        specified by a file list.
            
                     NDMP_BUTYPE_RECOVER_FILELIST
                        The backup type supports the recovery of individual files.
            
                     NDMP_BUTYPE_BACKUP_DIRECT
                        The backup type generates valid fh_info data usable for
                        direct access recovery.
            
                     NDMP_BUTYPE_RECOVER_DIRECT
                        The backup type supports direct access recovery
                        (positioning to an offset within a backup image and
                        recovery of the specified file).
            
                     NDMP_BUTYPE_BACKUP_INCREMENTAL
                        The backup type supports incremental backup.
            
                     NDMP_BUTYPE_RECOVER_INCREMENTAL
                        The backup type supports incremental-only recovery.
            
                     NDMP_BUTYPE_BACKUP_UTF8
                        The backup type supports UTF8 format in the file history.
            
                     NDMP_BUTYPE_RECOVER_UTF8
                        The backup type supports UTF8 format in the recovered file
                        list.
            
                     NDMP_BUTYPE_BACKUP_FH_FILE
                        The backup type supports the generation of file history
                        using NDMP_FH_ADD_FILE requests.
            
                     NDMP_BUTYPE_BACKUP_FH_DIR
                        The backup type supports the generation of file history
                        using NDMP_FH_ADD_DIR and NDMP_FH_ADD_NODE requests.
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 80]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     NDMP_BUTYPE_RECOVER_FILEHIST
                        The backup type supports NDMP_DATA_START_RECOVER_FILEHIST
                        operations which recovers file history from the backup
                        data.
            
                     NDMP_BUTYPE_RECOVER_FH_FILE
                        The backup type supports the generation of file format
                        file history for recovery of file history.
            
                     NDMP_BUTYPE_RECOVER_FH_DIR
                        The backup type supports the generation of node/dir format
                        file history for recovery of file history.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The backup type information successfully returned.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 81]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.6. NDMP_CONFIG_GET_FS_INFO
               This message is used to query information about the file systems on
               the NDMP Server host.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_fs_info_reply
                  {
                      ndmp_error        error;
                      ndmp_fs_info      fs_info<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  fs_info
                     Information about the file system. The following attributes
                     are defined:
            
                     unsupported
                        The unsupported bit mask is used to identify unsupported
                        arguments in the message.
            
                     fs_type
                        The type of the file system.
            
                     fs_logical_device
                        The mount point or share name of the file system.
            
                     fs_physical_device
                        The physical device name of the file system, e.g.
                        /dev/rsd0c.
            
                     total_size
                        The total size of the file system in bytes.
                        NDMP_FS_INFO_TOTAL_SIZE_UNS is set if this argument is not
                        supported.
            
                     used_size
                        The used size of the file system in bytes.
                        NDMP_FS_INFO_USED_SIZE_UNS is set if this argument is not
                        supported.
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 82]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     avail_size
                        The available size of the file system in bytes.
                        NDMP_FS_INFO_AVAIL_SIZE_UNS is set if this argument is not
                        supported.
            
                     total_inodes
                        The total number of inodes within the file system.
                        NDMP_FS_INFO_TOTAL_INODES_UNS is set if this argument is
                        not supported.
            
                     used_inodes
                        The number of the inodes being used within the file
                        system. NDMP_FS_INFO_USED_INODES_UNS is set if this
                        argument is not supported.
            
                     fs_env
                        The environment variables defined for the file system. In
                        addition to whatever a vendor finds useful to add, the
                        following SHOULD (where possible) be defined:
            
            
                  Variable           Meaning                      Value
                  --------------------------------------------------------------
                  LOCAL              Whether file system is       y/n
                                     Local to the machine on
                                     which the data service
                                     is running
            
                  TYPE               Kind of file system          nfs/ufs/afs/FAT
                                                                  MSDOS/NTFS/hsfs
                                                                  riserfs/ext2fs
            
                  AVAILABLE_BACKUP   Mode permitted for backup    dump/tar/cpio/
                                                                  gtar/dd/dump,tar/
                                                                  tar,dd,gtar/...
            
                  AVAILABLE_RECOVERY Mode permitted for recovery  dump/tar/cpio/
                                                                  gtar/dd/dump,tar/
                                                                  tar,dd,gtar/...
            
                        (Note that listed values SHOULD be used where appropriate,
                        but (as is the case with TYPE) the value might be outside
                        one of the values enumerated in the chart. Not also that
                        for the AVAILABLE_BACKUP and AVAILABLE_RECOVERY fields,
                        the "dump,tar" notation, for example, is meant to express
                        that both dump and tar options are available. The entire
                        set of types supported by the file system should be
                        concatenated with commas.)
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 83]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     fs_status
                        The current status of the file system. The string values
                        returned here SHOULD be one of: "online," "offline," or
                        another implementation-specific string of the category
                        that displays the current state of the file system.
                        Whereas this string is not well enough defined take on a
                        closed set of values, this string is intended for human
                        consumption only.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     File system information successfully returned.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 84]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.7. NDMP_CONFIG_GET_TAPE_INFO
               This message is used to query information about the tape devices
               connected to the NDMP Server host.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_tape_info_reply
                  {
                      ndmp_error              error;
                      ndmp_device_info        tape_info<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  tape_info
                     Each entry in the tape_info array describes one tape drive.
            
                     model
                        The tape device model name. For example: EXB-8500.
            
                     caplist
                        The tape device capability list. One physical tape device
                        can have more than one device name, each with different
                        capabilities. Each entry in the list contains the
                        following:
            
                        device
                           The device name of the tape device. For example:
                           /dev/rmt/0mn.
            
                        attr
                           The bit mask of tape attributes.
            
                           NDMP_TAPE_ATTR_REWIND
                              The tape will be rewound when the device is closed.
            
                           NDMP_TAPE_ATTR_UNLOAD
                              The tape will be unloaded when the device is
                              closed.
            
                           NDMP_TAPE_ATTR_RAW
                              The device supports raw mode open.
            
                              Note that the device will be opened whether or not
                              there is a tape present.
            
            
            
            Expires October 2003                                   [Page 85]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                        capability
                           The capability environment variables for the tape
                           drive device.
            
               The following are examples of the environment variables that can be
               defined for a tape device.
            
                  Variable Name    Meaning            Value       The Default Value
                  --------------------------------------------------------------
                  EXECUTE_CDB      Command supported    t/s/b/n     t
                                   for t-tape/s-scsi/
                                   b-both/n-none. (*)
            
                  COMPRESSION      Compression ratio    integer     1 (no
                  compression)
            
            
               * - Note that in order for the NDMP_TAPE_EXECUTE_CDB command to
               succeed it is typically necessary for the tape device to be open for
               write.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Tape information successfully returned.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 86]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.8. NDMP_CONFIG_GET_SCSI_INFO
               This message is used to query information about the SCSI media
               changer devices connected to the NDMP Server host.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_scsi_info_reply
                  {
                      ndmp_error            error;
                      ndmp_device_info      scsi_info<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code. MUST be given only if operation fails.
            
                  scsi_info
                     Each entry in the scsi_info array describes one SCSI device:
            
                     model
                        The model name of the SCSI media changer device. For
                        example: Spectra 10000F.
            
                     caplist
                        The capability list for the SCSI media changer device.
                        Each entry in the list contains the following:
            
                        device
                           The device name of the SCSI media changer device. For
                           example: /dev/scsi0.
            
                           NOTE: This name is the one required for use with the
                           NDMP_SCSI_OPEN command.
            
                        attr
                           The bit mask of SCSI attributes.
            
                          SHARED_ROBOT      0x00000001
                              Indicates that additional time may be required for
                              robot movement commands because the robot is a
                              shared resource.
            
                        capability
                           The capability environment variables for the SCSI
                           media changer device.
            
            
            
            
            
            Expires October 2003                                   [Page 87]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                           NOTE: Capabilities strings are optional and MAY
                           include:
            
                          SELECT_TIMEOUT
                           Time in milliseconds to wait for robot commands to
                           complete because of SHARED ROBOT bit.
               Reply Errors
            
                  NDMP_NO_ERR
                     SCSI information successfully returned.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 88]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.9 NDMP_CONFIG_GET_EXT_LIST
               NDMP_CONFIG_GET_EXT_LIST is used to request which classes of
               extensions and versions are available.
            
               This request MUST be issued by the DMA prior to issuing a
               NDMP_CONFIG_SET_EXT_LIST to specify the extensions to be enabled.
               This implies that the D+N process ONLY can occur before extensions
               are used, and that new extensions can not be negotiated once use of
               any extensions have started.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_config_get_ext_list_reply
                  {
                      ndmp_error         error;
                      ndmp_class_list    class_list<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  class_list
                     The list of classes of extensions and versions of these that
                     the NDMP Server supports.
            
                     The structure is a sequence of 16 bit values where the first
                     number is the class ID, and the following values are the
                     version numbers available for the class.
            
                     In an ndmp_class_list struct, the first version in the
                     version list is the default version. If the D+N process is
                     omitted, or if the DMA elects to skip the negotiation step of
                     the D+N process, the NDMP Server assumes that the default
                     version is the one to be used by the DMA.
            
                  The requested party may respond with only a subset of the
                  available extensions, including none if all extensions are
                  "private." The decision of which extensions to expose is entirely
                  up to the implementer of the server.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The get extensions request was successfully processed. The
                     data get extensions list reply message body accurately
                     represents the NDMP Server's available extensions.
            
            
            
            Expires October 2003                                   [Page 89]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_EXT_DANDN_ILLEGAL_ERR
                     This request is illegal at this point. Extensions have
                     already been selected; by a previous NDMP_SET_EXT_LIST
                     request, or because requests have been issued, thus selecting
                     the default set.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 90]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.2.10 NDMP_CONFIG_SET_EXT_LIST
               After a successful reply to the NDMP_CONFIG_GET_EXT_LIST the DMA
               SHOULD issue a NDMP_CONFIG_SET_EXT_LIST request to select which
               extensions, and which version of each extension it will use. An
               extension is selected with the class-version pair combination. The
               DMA MUST select all desired extensions in a single request and MUST
               NOT select more than one version of each extension.
            
               Once a successful set extension list reply is received, the DMA MUST
               NOT issue a subsequent set extension list request. If any error is
               reported, no extensions will be selected and the DMA MAY issue a
               subsequent set request containing a modified extension list.
            
               Message XDR definition
            
                  struct ndmp_config_set_ext_list_request
                  {
                      ndmp_class_version    ndmp_selected_ext<>;
                  };
            
                  struct ndmp_config_set_ext_list_reply
                  {
                      ndmp_error            error;
                  };
            
               Request Arguments
            
                  ndmp_select_ext
                     The structure lists the classes that the DMA will use. The
                     list MUST include only one instance of each class. This
                     version MUST be one returned from the NDMP Server in
                     preceding NDMP_CONFIG_GET_EXT_LIST request.
            
               Reply Arguments
            
                  error
                     Error code. MUST be given only if the selected set of classes
                     is NOT a subset of the supported classes returned in
                     NDMP_CONFIG_GET_EXT_LIST and can not be supported by the NDMP
                     Server.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The set extensions request was successfully processed and the
                     specified extensions are enabled for subsequent DMA use.
            
                  NDMP_CLASS_NOT_SUPPORTED_ERR
                     One or more of the selected classes in the class-version list
                     are not supported and was not in the list of classes received
                     from the NDMP Server.
            
            
            
            
            Expires October 2003                                   [Page 91]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_VERSION_NOT_SUPPORTED_ERR
                     One or more of the selected versions in the class-version
                     list are not supported and was not in the list of versions
                     received from the NDMP Server.
            
                  NDMP_EXT_DUPL_CLASSES_ERR
                     Two or more of the selected classes in the class-version list
                     have the same class ID.
            
                  NDMP_EXT_DANDN_ILLEGAL_ERR
                     The D+N process is illegal at this point. Extensions have
                     already been selected, from a previous set extension request,
                     or because extension requests have been issued thus selecting
                     the default set.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_PRECONDITION_ERR
                     The set extensions list request was received from the DMA
                     prior to receiving a valid NDMP_CONFIG_GET_EXT_LIST request.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 92]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.3. SCSI Interface
               The SCSI Interface provides low-level control of SCSI devices. This
               interface is primarily intended to provide control of media changer
               devices, and to a lesser extent, tape devices.
            
               This interface is not limited to media changer or tape drive devices.
               The types of SCSI devices allowed to be controlled via this interface
               are implementation dependent. An NDMP connection may have open at
               most one device at any time.
            
               Implementation Guideline: an NDMP Server implementer SHOULD carefully
               consider the security implications of providing access via this
               interface to SCSI other device types such as random access devices.
            
               Low-level SCSI control of tape devices is also provided by the tape
               interface via the NDMP_TAPE_EXECUTE_CDB request. However,
               implementation of this request is OPTIONAL as it is impractical to
               implement on some NDMP Server platforms. The SCSI Interface provides
               DMAs an alternative interface for accessing tape devices on NDMP
               Server implementations that do not support NDMP_TAPE_EXECUTE_CDB.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 93]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.3.1. NDMP_SCSI_OPEN
               Opens the specified SCSI device. This operation is REQUIRED before
               any other SCSI requests may be executed.
            
               Although any SCSI based device can be opened with this command, a
               matching device name string MUST be supplied.
            
               The NDMP Server software SHALL NOT do any I/O to the requested device
               during the open sequence.
            
               It is the responsibility of the NDMP Server to offer best effort
               exclusive access to the device.
            
               Message XDR definition
            
                  struct ndmp_scsi_open_request
                  {
                      string          device<>;
                  };
            
                  struct ndmp_scsi_open_reply
                  {
                      ndmp_error      error;
                  };
            
               Request Arguments
            
                  device
                     Name of SCSI Interface device to open. This argument MUST
                     reference and open access to a single device. Ideally, the
                     name string provided here SHOULD match a device in either the
                     NDMP_CONFIG_GET_SCSI_INFO or NDMP_CONFIG_GET_TAPE_INFO device
                     list, provided they are SCSI devices in nature.
            
                     NOTE: This does not prohibit the opening of a device other
                     than in the above list, provided the string can be
                     interpreted by the server and access granted.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     SCSI Interface device successfully opened.
            
                  NDMP_DEVICE_OPENED_ERR
                     The connection already has a tape device or SCSI device open.
            
            
            
            
            
            Expires October 2003                                   [Page 94]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_DEVICE_BUSY_ERR
                     Another NDMP connection currently has the specified device
                     open.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     Connection not authorized or device is not a tape or media
                     changer.
            
                  NDMP_NO_DEVICE_ERR
                     Invalid device specified.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 95]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.3.2. NDMP_SCSI_CLOSE
               This request closes the currently open SCSI device. No further
               requests SHALL be made until another open request is successfully
               executed.
            
               Message XDR definition
            
                  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_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 96]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.3.3. NDMP_SCSI_GET_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.
            
               Implementation of this request is OPTIONAL.
            
               The message XDR definition has 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.
            
                  target_id
                     SCSI target identifier. Specifies the SCSI bus address of the
                     targeted device.
            
                  target_lun
                     Logic unit number of the targeted device.
            
               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_ERR
                     The request is not supported by the implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            Expires October 2003                                   [Page 97]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.3.4. NDMP_SCSI_RESET_DEVICE
               This request sends a SCSI device reset message to the currently
               opened SCSI device.
            
               This is an OPTIONAL request. If not implemented, the server MUST
               return an NDMP_NOT_SUPPORTED_ERR error code. Implementation of this
               request MUST guarantee that only the specific device is reset,
               without affecting any other devices on the SCSI bus.
            
               The message XDR definition has 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.
            
               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_ERR
                     The request is not supported by the implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                   [Page 98]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.3.5. NDMP_SCSI_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 SHALL NOT modify the CDB.
            
               It is the responsibility of the DMA to construct a valid CDB for the
               target device.
            
               The server selects the SCSI target, specified in the NDMP_SCSI_OPEN
               command. 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. If timeout is zero, the server MUST wait
               indefinitely for the command to complete. If timeout is not zero, the
               server MUST wait for the command to complete and return an
               NDMP_TIMEOUT_ERR if the command does not complete within timeout
               milliseconds. If the target reselects and the status is CHECK
               CONDITION, then the server MUST execute 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 MUST
               be returned.
            
               There are no limitations to commands given to a SCSI device in this
               interface. The OPEN command SHOULD limit the type of device that can
               be targeted by this command.
            
               Message XDR definition
            
                  typedef ndmp_execute_cdb_request ndmp_scsi_execute_cdb_request;
            
                  typedef ndmp_execute_cdb_reply ndmp_scsi_execute_cdb_reply;
            
            
               Request Arguments
            
                  flags
                     Specifies the data transfer (if any) direction. DATA_IN and
                     DATA_OUT reference the server. DATA_IN refers to data from
                     the SCSI device into the server. DATA_OUT refers to data from
                     the server to the SCSI device.
            
                  timeout
                     Number of milliseconds to wait for command completion to
                     occur. If timeout is zero, then the server MUST wait
                     indefinitely for the command to complete. This timeout is
                     command and implementation dependent. It is the
                     responsibility of the DMA to set the timeout appropriately.
            
            
            
            
            
            Expires October 2003                                   [Page 99]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  datain_len
                     If the data transfer direction is DATA_IN, the expected
                     number of data bytes to read. If the return contains more
                     than this value, the data is truncated to the requested
                     length. In such a case, the NDMP_NO_ERR return MUST be
                     returned.
            
                  cdb
                     The SCSI command data block.
            
                  dataout
                     If the data transfer direction is DATA_OUT, the data to be
                     transferred to the SCSI device.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  status
                     SCSI status byte.
            
                  dataout_len
                     If the data transfer direction is DATA_OUT, the number of
                     data bytes transferred to the device.
            
                  datain
                     If the data transfer direction is DATA_IN, the data
                     transferred from the SCSI device. This number MUST not exceed
                     the datain_len value.
            
                  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
                     This message is restricted to errors encountered with a local
                     driver in processing the request.
            
                  NDMP_ILLEGAL_ARGS
                     Invalid argument in request message.
            
            
            
            
            Expires October 2003                                  [Page 100]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_TIMEOUT_ERR
                     The SCSI command timed out. The SCSI device is in an unknown
                     state as the result of a timeout error
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 101]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4. Tape Interface
               The Tape interface provides complete and exclusive control of a tape
               drive. If the tape drive is a SCSI tape drive, then the Tape
               interface SHOULD also provide low-level CDB access to the tape drive.
            
            3.4.1. Tape Model
               Tape device names
                  Tape device names are server implementation dependent and not a
                  topic of this specification. At the implementer's option, an
                  implementation MAY use more than one device name to identify the
                  same physical tape device. Also, the implementer MAY choose to
                  imbue behavioral semantics onto the tape device based upon the
                  device name. (Such are also outside the purview of this
                  specification, but may include rewind or unload on close,
                  density, fixed block size, compression, or the like.)
            
               Exclusive device access
                  All devices accessed by implementations of this protocol are
                  subject to the following restrictions:
            
                     - An NDMP connection may have open at most one device at any
                     time.
            
                     - An NDMP Server SHALL, to the extent possible, exclude other
                     entities from accessing any device that is open by a DMA.
            
                  These requirements pertain to both SCSI and Tape interfaces.
            
               Implicit file mark generation
                  The Tape interface MUST automatically write a file mark to the
                  tape under the following circumstances:
            
                     - The tape drive is opened in either NDMP_TAPE_RDWR_MODE or
                     NDMP_TAPE_RAW_MODE; and,
            
                     - Data have been written to the tape using either
                     NDMP_TAPE_WRITE or a mover (*) that are not followed by a
                     file mark (**); and,
            
                     - The operation being performed is one of NDMP_TAPE_CLOSE or
                     any NDMP_TAPE_MTIO except NDMP_MTIO_EOF or NDMP_MTIO_TUR.
            
                  If any one or more of these conditions are not satisfied, no file
                  mark is generated.
            
                  Following the implicit generation of a file mark, the Tape server
                  shall position the tape on the EOT side of that mark.
            
                  * - Automatic file mark creation does not occur if all write
                  operations were performed via NDMP_TAPE_EXECUTE_CDB.
            
            
            
            
            
            Expires October 2003                                  [Page 102]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  ** - File marks generated by NDMP_TAPE_EXECUTE_CDB are not
                  recognized by this rule.
            
               NDMP connection closure
                  In the event the NDMP connection between the client and server is
                  closed while a tape device is open, the server performs an
                  implicit NDMP_TAPE_CLOSE.
            
               Using NDMP_TAPE_EXECUTE_CDB with other Tape operations
                  DMAs are permitted to use NDMP_TAPE_EXECUTE_CDB to control tape
                  drive state or tape position. Any such use of
                  NDMP_TAPE_EXECUTE_CDB may cause NDMP_TAPE_GET_STATE to return
                  imprecise data with respect to absolute tape position. Absent
                  intervening NDMP_TAPE_EXECUTE_CDB requests, NDMP_TAPE_GET_STATE
                  requests that are intermingled with tape operations performed by
                  the MOVER or by the client via the Tape interface MUST return
                  valid data relative to one another.
            
                  Using NDMP_TAPE_EXECUTE_CDB and NDMP_TAPE_MTIO operations in the
                  same session MAY result in undefined behavior.
            
               NDMP_TAPE_READ and NDMP_TAPE_WRITE ops for tape drives in fixed block
               size mode
                  The number of tape blocks affected by a NDMP_TAPE_READ or
                  NDMP_TAPE_WRITE operation performed on a tape drive in fixed
                  block size mode is a whole integer number computed as follows:
            
                     blocks = int ( (bytes-requested + block-size - 1) / block-
                     size )
            
               CDBs and data expressed in TAPE_EXECUTE_CDB requests
                  NDMP Servers MUST NOT modify any CDB contents or related data
                  communicated from or to the client in TAPE_EXECUTE_CDB requests
                  and replies.
            
               NDMP Server SHOULD NOT interpret any CDB contents or related data
               communicated from or to the client in TAPE_EXECUTE_CDB requests and
               replies.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 103]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.2. NDMP_TAPE_OPEN
               This request opens the tape device in the specified mode. This
               operation is required before any other tape requests can be executed.
            
               If the drive does not have a tape loaded, an error MUST be returned
               unless the mode is NDMP_TAPE_RAW_MODE.
            
               If the loaded media is write protected, then the device can be opened
               only in NDMP_TAPE_READ_MODE or NDMP_TAPE_RAW_MODE mode.
            
               Message XDR definition
            
                  struct ndmp_tape_open_request
                  {
                      string                device<>;
                      ndmp_tape_open_mode   mode;
                  };
            
                  struct ndmp_tape_open_reply
                  {
                      ndmp_error            error;
                  };
            
               Request Arguments
            
                  mode
                     One of the following modes MUST be specified when opening the
                     tape device:
            
                     NDMP_TAPE_READ_MODE
                        Open the tape device for read only.
            
                     NDMP_TAPE_RDWR_MODE
                        Open the tape device for read/write.
            
                     NDMP_TAPE_RAW_MODE
                        Open the tape device for read/write. Permit the open to
                        succeed if no tape is present.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Tape device successfully opened.
            
                  NDMP_DEVICE_OPENED_ERR
                     The NDMP Server already has a SCSI device or tape device
                     open.
            
            
            
            Expires October 2003                                  [Page 104]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  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. MAY also be returned if no drive is
                     present.
            
                  NDMP_WRITE_PROTECT_ERR
                     Device cannot be opened in write mode because the tape is
                     write protected.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_PERMISSION_ERR
                     The user who authenticated the connection does not have
                     permission to open the tape device.
            
                  NDMP_NO_TAPE_LOADED_ERR
                     There is no tape loaded and ready for operation in the tape
                     drive. This error MUST only be reported if the mode is
                     NDMP_TAPE_READ_MODE or NDMP_TAPE_RDWR_MODE.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 105]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.3. NDMP_TAPE_CLOSE
               This request closes the tape drive.
            
               For this request to succeed, any MOVER using this tape device MUST
               NOT be either in an active or a listen state.
            
               If the tape device is opened in NDMP_TAPE_RDWR_MODE or
               NDMP_TAPE_RAW_MODE, file mark generation occurs as specified earlier.
            
               Should a tape I/O operation (such as writing a file mark or rewinding
               the tape) be impossible because no tape is loaded, the server shall
               fail this request and report NDMP_NO_TAPE_LOADED_ERR.
            
               Should an I/O error occur while the server is performing a tape
               operation implied by this request, the resultant tape position is
               indeterminate.
            
               Should the server report any error that results from an I/O operation
               implied by tape close, it shall not close the tape drive. In this
               case, should the server receive a subsequent NDMP_TAPE_CLOSE request
               with no intervening NDMP_TAPE request, it shall not attempt to
               perform any further I/O operation, but instead close the tape drive
               and report NDMP_NO_ERR.
            
               Should a DMA that relies on implicit file mark generation or other
               tape I/O that resulting from an NDMP_TAPE_CLOSE request receive an
               error reply, the DMA should reissue the NDMP_TAPE_CLOSE request to
               close the tape drive.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_tape_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
                     Tape device successfully closed.
            
                  NDMP_DEV_NOT_OPEN_ERR
                     No tape device currently open by the connection.
            
            
            
            
            Expires October 2003                                  [Page 106]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_IO_ERR
                     Device I/O error.
            
                  NDMP_DEVICE_BUSY_ERR
                     A MOVER associated with this tape drive is either in an
                     active or listen state.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NO_TAPE_LOADED_ERR
                     An I/O operation to the tape is required, but there is no
                     tape loaded or ready in the drive.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 107]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.4. NDMP_TAPE_GET_STATE
               This request returns the state of the tape drive interface.
            
               If any Tape Interface operations are supported by a server, support
               of this message is required.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_tape_get_state_reply
                  {
                      u_long       unsupported;
                      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 request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  flags
                     A bit field of the following tape device modes:
            
                     NDMP_TAPE_STATE_NOREWIND
                        Upon device close, the tape will not be rewound.
            
                     NDMP_TAPE_STATE_WR_PROT
                        The tape currently loaded is write protected.
            
                     NDMP_TAPE_STATE_ERROR
                        A media error was detected during the previous tape
                        operation; this bit is cleared at the start of each tape
                        operation.
            
                     NDMP_TAPE_STATE_UNLOAD
                        The tape currently loaded will be unloaded when the device
                        is closed.
            
                  file_num
                     Current file number: the number of file marks between BOT and
                     the current tape position.
            
            
            
            
            Expires October 2003                                  [Page 108]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     At tape open time, a server shall set file_num to a specific
                     file number if it has maintained, or can determine, tape
                     position; otherwise, it must set this value to all ones
                     (binary). Once set to all ones (binary), file_num shall
                     remain all ones (binary) unless the tape reaches BOT; at such
                     time, the server shall set this value to zero.
            
                  soft_errors
                     Total number of soft media errors detected since the device
                     was opened.
            
                     This value SHALL be set to all ones (binary) if it is unknown
                     to or unsupported by the server. Further, if the server does
                     not support this value, it SHALL set the
                     NDMP_TAPE_STATE_SOFT_ERRORS_UNS bit in the "unsupported" bit
                     field to one.
            
                  block_size
                     If the tape drive is in fixed block size mode, this is the
                     fixed tape block size in bytes. If the tape is in variable
                     block size mode, this value is zero. If the server supports
                     this value, it SHALL always report it to the client. If the
                     server does not support this value, it SHALL set it to all
                     ones (binary) and set the NDMP_TAPE_STATE_BLOCK_SIZE_UNS bit
                     in the "unsupported" bit field to one.
            
                  blockno
                     The current block number: the number of tape blocks between
                     the current tape position and either the preceding file mark
                     or BOT, which ever occurs nearest.
            
                     At tape open time, a server shall set blockno to a specific
                     block number if it has maintained, or can determine, tape
                     position. Otherwise, it must set this value to all ones
                     (binary). Once set to all ones (binary), blockno shall remain
                     all ones (binary) unless one of the following conditions is
                     met, at which time the server shall set blockno to zero:
            
                        - tape position reaches BOT
            
                        - one or more file marks are written using NDMP_MTIO_EOF
            
                        - one or more file marks are crossed using NDMP_MTIO_FSF
            
                     Should a server space backward over one or more file marks it
                     shall set blockno to all ones (binary), unless it can
                     determine the number of blocks in the tape file made current
                     by the NDMP_MTIO_BSF operation. If blockno is set to all ones
                     (binary) by this rule, it shall remain all ones (binary)
                     until occurrence of any of the three conditions described
                     above.
            
            
            
            
            Expires October 2003                                  [Page 109]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  total_space
                     The total tape capacity in bytes. If the tape drive is
                     capable of data compression, this is the total capacity with
                     compression disabled (regardless of its actual state).
            
                     This value SHALL be set to all ones (binary) if it is unknown
                     to or unsupported by the server. Further, if the server does
                     not support this value, it SHALL set the
                     NDMP_TAPE_STATE_TOTAL_SPACE_UNS bit in the "unsupported" bit
                     field to one.
            
                  space_remain
                     The total remaining tape capacity in bytes. If the tape drive
                     is capable of data compression, this is the total remaining
                     tape capacity with compression disabled (regardless of its
                     actual state).
            
                     This value SHALL be set to all ones (binary) if it is unknown
                     to or unsupported by the server. Further, if the server does
                     not support this value, it SHALL set the
                     NDMP_TAPE_STATE_SPACE_REMAIN_UNS bit in the "unsupported" bit
                     field to one.
            
               Reply errors:
            
                  NDMP_NO_ERR
                     Tape state successfully returned.
            
                  NDMP_DEV_NOT_OPEN_ERR
                     No tape device is presently open by the connection.
            
                  NDMP_NOT_SUPPORTED_ERR
                     This request is not supported by this server.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_IO_ERR
                     A device I/O error occurred while processing this request.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 110]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.5. NDMP_TAPE_MTIO
               This request provides access to common magnetic tape I/O operations.
            
               Message XDR definition
            
            
                  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 count file marks. The tape is
                        positioned on the EOT side of the last file mark skipped.
            
                        Should this operation encounter blank tape, NDMP_NO_ERR
                        and a non-zero resid_count are reported and the tape is
                        positioned on the EOT side of the last recorded tape block
                        or file mark.
            
                     NDMP_MTIO_BSF
                        Backward space over count file marks. The tape is
                        positioned on the BOT side of the last file mark skipped,
                        such that the next read or NDMP_MTIO_FSR encounters EOF.
            
                        Should this operation encounter beginning of tape,
                        NDMP_NO_ERR and a non-zero resid_count are reported and
                        the tape is positioned at BOT.
            
                     NDMP_MTIO_FSR
                        Forward space over count tape blocks. The tape is
                        positioned on the EOT side of the last block skipped.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 111]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                        When a file mark is encountered as a result of an
                        NDMP_MTIO_FSR operation, the server reports a non-zero
                        resid_count and NDMP_NO_ERR. In such case, the server
                        leaves the tape positioned at the BOT side of the file
                        mark. Subsequent NDMP_MTIO_FSR operations return a
                        resid_count equal to count and leave the tape position
                        unchanged.
            
                        Blank tape encounters are handled identically as for
                        NDMP_MTIO_FSF.
            
                     NDMP_MTIO_BSR
                        Backward space over count tape blocks. The tape is
                        positioned on the BOT side of the last tape block skipped.
            
                        When a file mark is encountered as a result of an
                        NDMP_MTIO_BSR operation, the server returns a non-zero
                        resid_count and NDMP_NO_ERR. In such case, the server
                        leaves the tape positioned at the EOT side of the file
                        mark. Subsequent NDMP_MTIO_BSR operations return a
                        resid_count equal to count and leave the tape position
                        unchanged.
            
                        Beginning of tape encounters are handled identically as
                        for NDMP_MTIO_BSF.
            
                     NDMP_MTIO_REW
                        Rewind the tape to BOT. The value of count is ignored.
                        Implementers may choose whether NDMP_MTIO_REW is an
                        "immediate" operation or not. Regardless, any subsequent
                        Tape operation MUST NOT fail because an immediate
                        operation is incomplete. This requirement does not apply
                        to NDMP_TAPE_EXECUTE_CDB.
            
                     NDMP_MTIO_EOF
                        Write end of file marks. If this operation encounters
                        logical end of medium, it succeeds and reports NDMP_NO_ERR
                        and a zero resid_count. Implementers may choose whether
                        NDMP_MTIO_EOF is an "immediate" operation or not.
                        Regardless, any subsequent Tape operation MUST NOT fail
                        because an immediate operation is incomplete. This
                        requirement does not apply to NDMP_TAPE_EXECUTE_CDB.
            
                     NDMP_MTIO_OFF
                        Eject the tape from the device. The value of count is
                        ignored. Implementers may choose whether NDMP_MTIO_OFF is
                        an "immediate" operation or not. Regardless, any
                        subsequent Tape operation MUST NOT fail because an
                        immediate operation is incomplete. This requirement does
                        not apply to NDMP_TAPE_EXECUTE_CDB. Also, implementers MAY
                        choose whether to position the tape to BOT, EOT or some
                        intermediate point before ejecting it.
            
            
            
            Expires October 2003                                  [Page 112]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     NDMP_MTIO_TUR
                        Test the readiness of the tape drive to perform I/O. The
                        value of count is ignored. The server shall return
                        NDMP_NO_ERR if a tape is present in the drive and ready to
                        perform an I/O operation; it shall return
                        NDMP_NO_TAPE_LOADED_ERR if no tape is loaded or ready. A
                        server MAY provide this operation; if it does not, it
                        SHALL return an error of NDMP_NOT_SUPPORTED_ERR when a DMA
                        requests it.
            
                  count
                     Number of operations to perform. The count field is ignored
                     for NDMP_MTIO_REW, NDMP_MTIO_OFF and NDMP_MTIO_TUR
                     operations. For all other operations, a zero count causes the
                     tape position to be left unchanged, NDMP_NO_ERR and a
                     resid_count of zero are reported.
            
               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_ERR
                     The request is not supported by this implementation. This
                     error is returned only if the Tape interface is unsupported,
                     or if the NDMP_MTIO_TUR operation is unsupported.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            Expires October 2003                                  [Page 113]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_WRITE_PROTECT_ERR
                     Tape is write protected.
            
                  NDMP_NO_TAPE_LOADED_ERR
                     There is no tape loaded or ready in the drive
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 114]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.6. NDMP_TAPE_WRITE
               This request writes data to the tape device. The number of tape
               blocks written depends on the mode of the tape drive:
            
                     - In variable block size mode, the NDMP Server writes count
                     bytes of data to one tape block.
            
                     - In fixed block size mode, the NDMP Server writes the data
                     to the number of tape blocks computed as specified earlier.
                     It is the client's responsibility to ensure that count is a
                     multiple of that fixed block size.
            
               A client uses NDMP_TAPE_GET_STATE to sense whether a device is in
               fixed or variable block size mode. Setting fixed or variable block
               size mode -- for devices for which it is configurable -- is outside
               the scope of this specification.
            
               The NDMP Server does not buffer or pad the data.
            
               This request is typically used by the DMA to write tape header and
               trailer file data.
            
               When a write operation succeeds but encounters logical end of medium,
               it reports NDMP_NO_ERR and count bytes written. ("Logical end of
               medium is generated when crossing the SCSI "early warning
               indicator.") The next write operation fails, reporting zero bytes
               written and NDMP_EOM_ERR. Subsequent write operations succeed with
               NDMP_NO_ERR reported. If physical EOM is reached, the write operation
               fails with NDMP_IO_ERR.
            
               If a tape drive is open in NDMP_TAPE_RDWR_MODE or NDMP_TAPE_RAW_MODE
               and a client requests an NDMP_TAPE_WRITE with a data_out length equal
               to zero, no action occurs, NDMP_NO_ERR is generated, and count of
               zero is returned. Servers behave this way regardless of any other
               state of the tape drive.
            
               Message XDR definition
            
                  struct ndmp_tape_write_request
                  {
                      opaque              data_out<>;
                  };
            
                  struct ndmp_tape_write_reply
                  {
                      ndmp_error          error;
                      u_long              count;
                  };
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 115]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               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
            
                  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. This error MAY be returned if no tape is
                     loaded (see below). Also returned if the physical end of
                     medium was encountered.
            
                  NDMP_EOM_ERR
                     Logical end of medium (SCSI early warning indicator) was
                     encountered; no data was written.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The request is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_WRITE_PROTECT_ERR
                     Tape is write protected.
            
                  NDMP_PERMISSION_ERR
                     The device is open in NDMP_TAPE_READ_MODE.
            
                  NDMP_NO_TAPE_LOADED_ERR
                     An I/O operation to the tape is required, but there is no
                     tape loaded or ready in the drive. If the server is able to
                     distinguish this condition from a general NDMP_IO_ERR, it
                     reports this error when no tape is loaded.
            
            
            
            
            
            
            Expires October 2003                                  [Page 116]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_DEVICE_BUSY_ERR
                     A MOVER associated with this tape drive is either in an
                     active or listen state.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 117]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.7. NDMP_TAPE_READ
               This request reads data from the tape drive. The number of tape
               blocks read depends on the mode of the tape drive:
            
                     - In variable block size mode, the NDMP Server reads one tape
                     block and returns, at most, count bytes of data. If the tape
                     block contains more than count bytes, that data is discarded.
            
                     - In fixed block size mode, the NDMP Server reads data from
                     the number of tape blocks computed as described earlier. It
                     is the client's responsibility to ensure that count is a
                     multiple of the fixed block size.
            
               If the last or only tape block read contains excess data, that data
               is discarded.
            
               When a file mark is encountered in lieu of the first or only data
               block to read, the server returns zero data bytes and an NDMP_EOF_ERR
               error. In such case, the server leaves the tape positioned at the BOT
               side of the file mark. Subsequent reads encounter the same file mark
               and act identically.
            
               When blank tape (end of recorded data) is encountered in lieu of the
               first or only data block to read, the server returns zero data bytes
               and an NDMP_EOM_ERR error. The tape remains positioned on the EOT
               side of the last recorded tape block or file mark.
            
               Should an NDMP_TAPE_READ operation encounter a file mark or blank
               tape on the second or subsequent tape block read from a drive in
               fixed block size mode, all data from blocks read are returned, the
               value of data_in_len is set to the actual number of data bytes
               returned and NDMP_NO_ERR is reported. The server leaves the tape
               positioned on the EOT side of the last block read, such that the next
               NDMP_TAPE_READ will report the condition that caused the early
               termination of this operation.
            
               If a tape drive is open and a client requests a read with a count
               equal to zero, no action occurs, NDMP_NO_ERR is generated, and a
               data_in_len of zero is returned. Servers behave this way regardless
               of any other state of the tape drive.
            
               Upon successful completion of NDMP_TAPE_READ, the tape is positioned
               on the EOT side of the last tape block read.
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 118]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Message XDR definition
            
                  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
                     A read from the tape was successful.
            
                  NDMP_DEV_NOT_OPEN_ERR
                     No tape device currently open by the connection.
            
                  NDMP_IO_ERR
                     Device I/O error during read. The tape position following
                     this error is undetermined. Also, this error may be returned
                     if no tape is loaded.
            
                  NDMP_NO_TAPE_LOADED_ERR
                     An I/O operation to the tape is required, but there is no
                     tape loaded or ready in the drive. If the server is able to
                     distinguish this condition from a general NDMP_IO_ERR, it
                     reports this error when no tape is loaded.
            
                  NDMP_EOF_ERR
                     End of file was encountered while reading. A data_in_len of
                     zero is returned.
            
            
            
            
            
            
            Expires October 2003                                  [Page 119]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_EOM_ERR
                     A blank tape was encountered while reading. A data_in_len of
                     zero is returned.
            
                  NDMP_DEVICE_BUSY_ERR
                     A MOVER associated with this tape drive is either in an
                     active or listen state.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The Tape interface is not supported for this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 120]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.4.8. NDMP_TAPE_EXECUTE_CDB
               This message behaves in exactly the same way as the
               NDMP_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
            
                  typedef ndmp_execute_cdb_request ndmp_tape_execute_cdb_request;
            
                  typedef ndmp_execute_cdb_reply ndmp_tape_execute_cdb_reply;
            
            
               Reply Errors
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 121]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5. Data Interface
               The Data Interface manages the transfer of backup and recovery stream
               data between a Tape Server or peer Data Server and the file system
               represented by the local Data Server. The Data Server uses the
               services of one or more backup and recovery methods implemented by
               the NDMP host system.
            
            3.5.1. Data Interface Overview
               The Data Interface consists of nine unique request/reply message
               pairs. These message pairs can be loosely categorized as providing
               connection management, data transfer management, and status
               reporting. NDMP_DATA_LISTEN, NDMP_DATA_CONNECT, NDMP_DATA_ABORT and
               NDMP_DATA_STOP provide control over the Data Server data connection.
               NDMP_DATA_START_BACKUP and NDMP_DATA START_RECOVER control the
               transfer of data between peer tape or Data Servers and the local file
               system. The optional NDMP_DATA_START_RECOVER_FILEHIST reconstructs
               file history, normally generated during backup operations, without
               interacting with the local file system. NDMP_DATA_GET_STATE and
               NDMP_DATA_GET_ENV provide methods of querying the Data Server for
               status and environment information.
            
               During backup operations the Data Server accesses file data from the
               backup method and writes the backup data stream to the data
               connection. The Data Server also uses the File History Interface to
               provide the DMA a file by file record of all data contained in the
               backup operation.
            
               During recover and recover file history operations the Data Server
               accesses the backup stream from the data connection and passes it to
               the local backup method. The Data Server typically issues
               NDMP_NOTIFY_DATA_READ messages to request the peer tape or Data
               Server to send specific portions of the backup stream over the data
               connection. The exception to this is when both the data and Tape
               Server reside on the same NDMP host and communicate in an
               implementation specific manner.
            
               During both backup and recovery operations the Data Server issues
               NDMP_NOTIFY DATA_HALTED messages to indicate a data operation has
               ended, either successfully, or abnormally. This allows the DMA to
               issue a NDMP_DATA_GET_ENV request to access Data Server state and
               environment information before issuing a NDMP_DATA_STOP request
               causing the Data Server to transition back to the IDLE state.
            
               In addition to backup and recovery operations where backup stream
               data transfer occurs between Data Servers and Tape Servers (movers),
               copy operations are also supported. A data connection between two
               Data Servers provides the basis for NDMP data migration. This occurs
               when one Data Server performs a backup operation and the other a
               recovery operation on the same backup stream.
            
            
            
            
            
            
            Expires October 2003                                  [Page 122]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.1.1. Data Interface Variables & Constants
               There are a number of variables and constants that are key to the
               operation of the Data Server. These variables are exposed by the NDMP
               protocol definition and MUST be maintained in a consistent manner by
               all NDMP implementations. The definitions contained in this section
               will be referenced in subsequent Data Interface sections.
            
               unsupported
                  This unsigned long bit field value identifies the optional state
                  variables this Data Server implementation does not support.
                  Optional state variables are identified by the
                  NDMP_DATA_STATE_EST_BYTES_REMAIN_UNS and
                  NDMP_DATA_STATE_EST_TIME_REMAIN_UNS constants.
            
               operation
                  This integer value identifies the current Data Server operation.
                  Valid data operations are defined by the ndmp_data_operation
                  enumeration and consist of NDMP_DATA_OP_NOACTION,
                  NDMP_DATA_OP_BACKUP, NDMP_DATA_OP_RECOVER and
                  NDMP_DATA_OP_RECOVER_FILEHIST.
            
                  Operation MUST be set to NDMP_DATA_OP_NOACTION during Data Server
                  initialization and upon transition to the IDLE state. Operation
                  MUST be set to NDMP_DATA_OP_BACKUP following the generation of a
                  NDMP_DATA_START_BACKUP reply with a NDMP_NO_ERR indication.
                  Operation MUST be set to NDMP_DATA_OP_RECOVER following the
                  generation of a NDMP_DATA_START_RECOVER reply with a NDMP_NO_ERR
                  indication. Operation MUST be set to
                  NDMP_DATA_OP_RECOVER_FILEHIST following the generation of a
                  NDMP_DATA_START_RECOVER_FILEHIST reply with a NDMP_NO_ERR
                  indication.
            
               state
                  This integer value identifies the current state of the Data
                  Server's state machine. Valid data states are defined by the
                  ndmp_data_state enumeration and consist of IDLE, LISTEN,
                  CONNECTED, ACTIVE and HALTED. Refer to section 2 for a complete
                  definition of the data state machine.
            
               halt_reason
                  This integer value identifies the event that caused the Data
                  Server state machine to enter the HALTED state. Valid halt
                  reasons are defined by the ndmp_data_halt reason enumeration. The
                  halt reason MUST be set to NA when the Data Server state machine
                  is initialized and MUST be set to NDMP_DATA_HALT_SUCCESSFUL,
                  NDMP_DATA_HALT_ABORTED, NDMP_DATA_HALT_INTERNAL_ERROR, or
                  NDMP_DATA_HALT_CONNECT_ERROR as appropriate upon transition to
                  the HALTED state. The halt reason MUST be set to
                  NDMP_DATA_HALT_NA upon mover transition out of the HALTED state.
                  The halt reason is valid only when the Data Server is in the
                  HALTED state.
            
            
            
            
            Expires October 2003                                  [Page 123]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_DATA_HALT_NA
                     The Data Server is not in the halted state.
            
                  NDMP_DATA_HALT_SUCCESSFUL
                     The Data Server successfully completed the backup or recovery
                     data operation.
            
                  NDMP_DATA_HALT_ABORTED
                     The Data Server received an NDMP_DATA_ABORT request from the
                     DMA.
            
                  NDMP_DATA_HALT_INTERNAL_ERROR
                     The Data Server detected an unrecoverable error condition.
            
                  NDMP_DATA_HALT_CONNECT_ERROR
                     The Data Server detected a connection failure while in the
                     LISTEN, CONNECTED, or ACTIVE states.
            
               Following a transition to the HALTED state, the Data Server MUST
               issue an NDMP_NOTIFY_DATA_HALTED message to identify the halt reason
               and allow the DMA to cleanup. Transition to the HALTED state can
               result from expected or unexpected conditions. In progress Data
               Server operations MUST NOT continue, and any data connection, if
               present, MUST be closed upon transition to the HALTED state.
            
               bytes_processed
                  This double unsigned long value represents the cumulative number
                  of data stream bytes transferred between the backup or recovery
                  method and the data connection during the current data operation.
                  bytes_processed MUST be set to zero when the Data Server is
                  initialized and whenever the Data Server transitions to the IDLE
                  state.
            
               est_bytes_remain
                  This optional double unsigned long value represents the Data
                  Server's best estimate of the number of bytes remaining to be
                  transferred between the backup or recovery method and the data
                  connection to satisfy the current data operation.
                  est_bytes_remain MUST be set to zero when the Data Server is
                  initialized and whenever the Data Server transitions to the IDLE
                  state. The update frequency for this value is Data Server
                  implementation dependent. A update frequency of 60 seconds is
                  considered optimal.
            
                  Note: If the Data Server does not support the est_bytes_remain
                  variable, it MUST assert the NDMP_DATA_STATE_EST_BYTES_REMAIN_UNS
                  bit in the NDMP_DATA_GET_STATE reply unsupported field.
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 124]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               est_time_remain
                  This optional double unsigned long value represents the Data
                  Server's best estimate of the number of seconds remaining before
                  the current data operation completes. est_time_remain MUST be set
                  to zero when the Data Server is initialized and whenever the Data
                  Server transitions to the IDLE state. The update frequency for
                  this value is Data Server implementation dependent. A update
                  frequency of 60 seconds is considered optimal.
            
                  Note: If the Data Server does not support the est_time_remain
                  variable, it MUST assert the NDMP_DATA_STATE_EST_TIME_REMAIN_UNS
                  bit in the NDMP_DATA_GET_STATE reply unsupported field.
            
               data_connection_addr
                  This structure represents the connection endpoint information for
                  the Data Server's data connection. The data_connection_addr MUST
                  be set to NDMP_ADDR_LOCAL when the Data Server is initialized and
                  whenever the Data Server state machine transitions to the IDLE
                  state.
            
                  Upon transition to the CONNECTED state the data connection_addr
                  is set to the ndmp_addr value representing connection endpoint
                  address of the peer tape or Data Server. The type of data
                  connection is determined as follows:
            
                  If a single control connection exists between the DMA and co-
                  located Data/Tape Servers then NDMP_ADDR_LOCAL MUST be specified.
            
                  If two independent control connections exist between the DMA and
                  co-located Tape and Data Servers then NDMP_ADDR_IPC SHOULD be
                  specified if supported. Otherwise NDMP_ADDR_TCP MAY be specified.
            
                  If a remote three-way data operation is being performed between
                  Tape and Data Servers residing on two networked NDMP hosts then
                  NDMP_ADDR_TCP MUST be specified.
            
                  When NDMP_ADDR_TYPE_TCP is specified, the ndmp_addr structure
                  provides for an array of one or more IP address and TCP port
                  pairs, as well as a list of environment variables associated with
                  each address pair. However when the Data Server's
                  data_connection_addr structure specifies NDMP_ADDR_TYPE_TCP, it
                  MUST contain exactly one address pair, and MUST NOT contain any
                  environment variables.
            
                  The TCP address pair used to initialize the data_connection_addr
                  SHOULD be accessed from the Data Server's network subsystem after
                  a connection is established with the peer tape or Data Server. It
                  SHOULD NOT simply be copied from the NDMP_DATA_LISTEN reply or
                  NDMP_DATA_CONNECT request message.
            
            
            
            
            
            
            Expires October 2003                                  [Page 125]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               read_offset
                  This double unsigned long value represents the read offset
                  specified in the last NDMP_NOTIFY_DATA_READ post message.
                  read_offset MUST be set to zero when the Data Server is
                  initialized and whenever it transitions to the IDLE state. Upon
                  generation of NDMP_NOTIFY_DATA_READ post message, read_offset
                  MUST be set to the specified offset value of the post.
                  read_offset is not updated as a result of backup or recovery data
                  transfer operations. Its purpose is to allow the DMA to query the
                  Data Server for the read_offset of the current read operation.
            
            
               read_length
                  This double unsigned long value represents the read length
                  specified in the last NDMP_NOTIFY_DATA_READ post message.
                  read_length MUST be set to zero when the Data Server is
                  initialized and whenever it transitions to the IDLE state. Upon
                  generation of NDMP_NOTIFY_DATA_READ post message, read_length
                  MUST be set to the specified length value of the post.
                  read_length is not updated as a result of backup or recovery data
                  transfer operations. Its purpose is to allow the DMA to query the
                  Data Server for the read_length of the current read operation.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 126]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2. Data Message Definitions
               The following section defines each of the eight Data Interface
               request/reply message pairs. Message pair definitions are presented
               in typical usage order: connect, listen, start backup, start recover,
               get state, get env, close and abort.
            
               NDMP Server support of the Data Interface is OPTIONAL. It is possible
               for a server to implement the mover and tape interfaces without the
               Data Interface. However, if the Data Interface is implemented, all
               eight data request messages MUST be supported. If the Data Interface
               is not implemented, any data request message MUST result in a
               NDMP_NOT_SUPPORTED error reply.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 127]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.1. NDMP_DATA_CONNECT
               This request is used by the DMA to instruct the Data Server to
               establish a data connection to a Tape Server or peer Data Server. A
               connect request is only valid when the Data Server is in the IDLE
               state.
            
               A successful connect request causes the Data Server to transition to
               the CONNECTED state. The Data Server normally transitions from the
               CONNECTED state to the ACTIVE state upon receipt of a valid
               NDMP_DATA_START_BACKUP or NDMP_DATA_START_RECOVER request. The Data
               Server also transitions from the CONNECTED state to the HALTED state
               upon detection of an internal error, a connection error or receipt of
               a NDMP_DATA_ABORT request.
            
               A Data Server data connection is used to transfer backup stream data
               between the file system associated with the Data Server that
               initiated the connection and the Tape Server or peer Data Server
               specified in the connect request. The data connection can be
               established locally within a given system or between remote networked
               systems.
            
               The direction of the data transfer is not specified as a argument to
               the data connect request as in the mover connect case. Rather it is
               indicated by the subsequent DMA request of NDMP_DATA_START_BACKUP or
               NDMP_DATA_START_RECOVER.
            
               The type of connection is specified by the addr_type argument. A
               connection within a system can be either null (ADDR_LOCAL) or inter
               process (ADDR_IPC), while a connection between systems can be
               established via TCP/IP (ADDR_TCP).
            
               Note: It is permissible to establish a connection between two Data
               Servers for file system to file system transfers.
            
               Message XDR definition
            
                   struct ndmp_data_connect_request
                  {
                      ndmp_addr   addr;
                  };
            
                  struct ndmp_data_connect_reply
                  {
                      ndmp_error  error;
                  };
            
               Request Arguments
            
                  addr
            
            
            
            
            
            
            Expires October 2003                                  [Page 128]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     Specifies the endpoint address or addresses that the Data
                     Server will use when establishing a data connection. The
                     ndmp_addr structure conveys both the address type
                     (NDMP_ADDR_IPC, NDMP_ADDR_LOCAL, or NDMP_ADDR_TCP) as well as
                     the address information appropriate for the specified type.
            
                     If the address type is NDMP_ADDR_TCP, then the connect
                     address contains an array of one or more IP address and TCP
                     port pairs that the peer server is listening at for a data
                     connection. The array of addresses SHOULD be ordered from
                     highest to lowest preference based on peer server criteria.
            
                     The Data Server SHOULD examine the set of addresses and
                     select the one it considers best based on implementation
                     specific criteria. Alternately the Data Server MAY attempt to
                     connect to each address in sequence until it establishes a
                     connection or exhausts the addresses or MAY simply attempt to
                     connect to the first address.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The data connect request was successfully processed. The Data
                     Server has successfully connected to the specified address
                     and transitioned to the CONNECTED state.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The data connect request was received while the Data Server
                     state machine was in a state that prevented processing this
                     request. Connect requests are only valid in the IDLE state.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The data connect request specified an invalid or unsupported
                     address type.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_CONNECT_ERR
                     The Data Server was unable to establish a data connection to
                     the specified endpoint address.
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 129]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.2. NDMP_DATA_LISTEN
               This request is used by the DMA to instruct the Data Server create a
               connection end point and listen for a subsequent data connection from
               a Tape Server (mover) or peer Data Server. This request is also used
               by the DMA to obtain the address of connection end point the Data
               Server is listening at. A listen request is only valid when the Data
               Server is in the IDLE state.
            
               A successful listen request causes the Data Server to transition to
               the LISTEN state. The Data Server will remain in the LISTEN state
               until a data connection is established resulting in a transition to
               the CONNECTED state, or until the Data Server enters the HALTED state
               following the detection of an internal error, a connection error or
               receipt of an NDMP_DATA_ABORT request.
            
               A Data Server data connection is used to transfer backup stream data
               between the server initiating the connection and the file system
               associated with the Data Server. The data connection can be
               established locally within a given system or between remote networked
               systems.
            
               The type of connection is specified by the addr_type argument. A
               connection within a system can be either null (NDMP_ADDR_LOCAL) or
               interprocess (NDMP_ADDR_IPC), while a connection between systems can
               be established via TCP/IP (NDMP_ADDR_TCP).
            
               Note: It is permissible to establish a connection between two Data
               Servers for file system to file system transfers.
            
               Message XDR definition
            
                  struct ndmp_data_listen_request
                  {
                      ndmp_addr_type   addr_type;
                  };
            
                  struct ndmp_data_listen_reply
                  {
                      ndmp_error       error;
                      ndmp_addr        connect_addr;
                  };
            
               Request Arguments
            
                  addr_type
                     NDMP_ADDR_LOCAL
                        The Data Server listens for a data connection from a mover
                        that exists on the same NDMP host. The Data Server and the
                        mover are controlled by a single DMA connection. The
                        communication mechanism is implementation dependent.
            
            
            
            
            
            Expires October 2003                                  [Page 130]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     NDMP_ADDR_IPC
                        The Data Server listens for a connection from a mover that
                        exists on the same NDMP host. The mover and the Data
                        Server are controlled by separate DMA connections. The
                        communication mechanism is implementation dependent.
            
                     NDMP_ADDR_TCP
                        The Data Server listens for a TCP connection from a remote
                        mover (Tape Server) or peer Data Server on one or more
                        specific IP address and TCP port pairs.
            
                        This address type can also be used to listen for a
                        connection from a mover that exists on the same NDMP host.
                        In this case the mover and the Data Server MUST be
                        controlled by separate DMA connections.
            
            
            
               Reply Arguments
            
                  error
                     Error code.
            
                  connect_addr
                     Specifies the endpoint address or addresses that the Data
                     Server is listening at for a connection. The ndmp_addr
                     structure conveys both the address type (NDMP_ADDR_IPC,
                     NDMP_ADDR_LOCAL, or NDMP_ADDR_TCP) as well as the address
                     information appropriate for the specified type.
            
                     If the address type is NDMP_ADDR_TCP, then the listen reply
                     connect address contains an array of one or more IP address
                     and TCP port pairs that the Data Server is listening for a
                     data connection at. The array of addresses SHOULD be ordered
                     from highest to lowest preference based on Data Server
                     implementation specific criteria. Typical criteria can
                     include interface bandwidth, interface utilization, and
                     network reachability.
            
                     The NDMP_ADDR_TCP address type also allows specification of
                     implementation specific environment variables on a per
                     address basis. The use of these environment variables is
                     optional and intended to provide a mechanism for the
                     listening NDMP Server to pass additional network related
                     information to the peer server.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The data listen request was successfully processed. The Data
                     Server has transitioned to the LISTEN state and the connect
                     address information contained in this reply message is valid.
            
            
            
            Expires October 2003                                  [Page 131]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_ILLEGAL_STATE_ERR
                     The data listen request was received while the Data Server
                     state machine was in a state that prevented processing this
                     request. Listen requests are only valid in the IDLE state.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The data listen request specified an invalid or unsupported
                     address type.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 132]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.3. NDMP_DATA_START_BACKUP
               This request is used by the DMA to instruct the Data Server to
               initiate a backup operation and begin transferring backup data from
               the file system represented by this Data Server to a Tape Server or
               peer Data Server over the previously established data connection.
            
               Each NDMP data connection is limited to providing a single backup or
               recovery operation. Therefore the Data Server MUST be in the
               CONNECTED state to accept and process a start backup request. A
               successful start backup request causes the Data Server to transition
               to the ACTIVE state.
            
               The Data Server backup method is specified as a name string by the
               butype_name argument and MUST match one of the Data Server
               implementation specific butype_name strings accessible via the
               NDMP_CONFIG_GET_BUTYPE_INFO request.
            
               The backup method environment is specified as an array of environment
               variables by the start backup env argument. Each variable specified
               by the start backup env argument SHOULD match one of the backup
               method specific environment variables accessible via the
               NDMP_CONFIG_GET_BUTYPE_INFO request.
            
               Prior to starting the backup, the Data Server should add the
               PATHNAME_SEPARATOR pval to the environment. The value of this pval
               SHOULD be set to the pathname separator character appropriate for the
               file system (as specified by the FILESYSTEM pval) being backed up. If
               the Data Server neglects to add this pval to the environment, the DMA
               MUST assume the path separation character is '/'. Note: The Data
               Server MUST NOT fail a start backup request due to unrecognized DMA
               specified environment variables. Furthermore in response to a
               NDMP_DATA_GET_ENV request, all environment variables specified in the
               start backup request MUST be returned including those not recognized
               or processed by the Data Server.
            
               The Data Server invokes the specified backup method with the DMA
               supplied environment variables and transfers the resultant backup
               stream to the data connection. NDMP_ADDR_TCP type data connections
               require the backup method to support backup stream flow control.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 133]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Message XDR definition
            
                  struct ndmp_data_start_backup_request
                  {
                      string          butype_name<>;
                      ndmp_pval       env<>;
                  };
            
                  struct ndmp_data_start_backup_reply
                  {
                      ndmp_error      error;
                  };
            
               Request Arguments
            
                  butype_name
                     Specifies the name of the backup method to be used for the
                     transfer (dump, tar, cpio, etc). Backup types are NDMP Server
                     implementation dependent and MUST match one of the Data
                     Server implementation specific butype_name strings accessible
                     via the NDMP_CONFIG_GET_BUTYPE_INFO request.
            
                  env
                     Specifies an array of environment variables representing the
                     operational environment for the specified backup method. Each
                     environment variable is specified as a name string value
                     string pair. The Data Server will only process variables that
                     match one of the backup method specific environment variables
                     accessible via the NDMP_CONFIG_GET_BUTYPE_INFO request.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The start backup request was successfully processed. The Data
                     Server has transitioned to the ACTIVE state and the specified
                     backup method has been invoked.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The start backup request was received while the Data Server
                     state machine was in a state that prevented processing this
                     request. Start backup requests are only valid in the
                     CONNECTED state.
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 134]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The start backup request specified an invalid or backup type
                     or an invalid backup environment variable. Backup types and
                     backup environment variable are Data Server implementation
                     dependent.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 135]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.4. NDMP_DATA_START_RECOVER
               This request is used by the DMA to instruct the Data Server to
               initiate a recovery operation and transfer the recovery stream
               received from a Tape Server or peer Data Server over the previously
               established data connection to the specified local file system
               location.
            
               Each NDMP data connection is limited to providing a single backup or
               recovery operation. Therefore the Data Server MUST be in the
               CONNECTED state to accept and process a start recover request. A
               successful start recover request causes the Data Server to transition
               to the ACTIVE state.
            
               The Data Server backup method which originally generated the backup
               data is specified as a name string by the butype_name argument and
               MUST match one of the Data Server implementation specific butype_name
               strings accessible via the NDMP_CONFIG_GET_BUTYPE_INFO request. Note:
               butype_name does not specify the name of the Data Server recovery
               method if different from the backup method. The Data Server is
               responsible for making the proper association between backup and
               recovery methods if they are independently named (for example dump
               and restore).
            
               The data to be recovered is specified by the nlist argument as an
               array of structures containing one or more directory or file names as
               well as recovery method specific context and file history information
               that may be used during direct access recovery (DAR) operations.
            
               Note: If direct access recovery is supported by both the DMA and the
               Data Server, the DMA is responsible for storing file history
               information during backup operations so that it can be supplied as
               part of the recovery nlist. Refer to the File History Interface
               description for further details.
            
               The recovery method environment is specified as an array of
               environment variables by the env argument. During normal recovery
               operations this argument MUST include all environment variables
               associated with the original backup operation and MAY include
               additional environment variable specific to the recovery operation.
            
               Note that for a recovery operation, if "DIRECT = Y" AND "RECURSIVE =
               Y", AND the Data Server is not capable of direct access recursive
               directory recoveries, then the server SHOULD fail the recovery with
               an NDMP_ILLEGAL_ARGS error.
            
               Following a successful backup operation, when the Data Server is in
               the HALTED states, the DMA MUST access the backup method environment
               variables by issuing a NDMP_DATA_GET_ENV request and save this
               information for subsequent recoveries.
            
            
            
            
            
            
            Expires October 2003                                  [Page 136]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Note: During file system to file system copy operations the start
               NDMP_DATA_START_RECOVER request is issued to one Data Server before
               the NDMP_DATA_START_BACKUP request is issued to the peer Data Server.
            
               In this case the recovery operation is not dependent on a prior
               backup operation or associated backup environment variables. The
               expected recovery method environment represented by the env argument
               is implementation dependent and MAY be null. Upon receipt of a start
               recover request, the Data Server invokes the specified recovery
               method with the DMA supplied environment variables and file list and
               initiates the recovery operation. If the connection type is
               NDMP_ADDR_TCP or NDMP_ADDR_IPC, the Data Server MUST issue a
               NDMP_NOTIFY_DATA_READ message to the DMA specifying the offset and
               length of the recovery stream. In the case of NDMP_ADDR_LOCAL the
               Data Server initiates the recovery stream in an implementation
               specific manner that MAY generate NDMP_NOTIFY_DATA_READ messages.
            
               The Data Server then waits to receive the specified recovery stream
               from the data connection. Upon successful receipt and processing of
               the specified recovery stream, the Data Server either issues another
               NDMP_NOTIFY_DATA_READ message to initiate the next recovery stream or
               issues a NDMP_NOTIFY_DATA_HALTED message to indicate the recovery
               operation is complete and transitions to the HALTED state.
            
               Message XDR definition
            
                  struct ndmp_data_start_recover_request
                  {
                      ndmp_pval        env<>;
                      ndmp_name        nlist<>;
                      string           butype_name<>;
                  };
            
                  struct ndmp_data_start_recover_reply
                  {
                      ndmp_error       error;
                  };
            
               Request Arguments
            
                  env
                     Specifies an array of environment variables representing the
                     backup environment associated with the specified directories
                     or files. These parameters MUST include all environment
                     variables accessed by the DMA following the successful backup
                     operation and MAY include additional recovery specific
                     variables. The DMA accesses the backup environment by issuing
                     a NDMP_DATA_GET_ENV request while the Data Server is in the
                     HALTED state.
            
            
            
            
            
            
            Expires October 2003                                  [Page 137]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  nlist
                     An array of ndmp_name structures specifying the data to be
                     recovered. At least one member shall be supplied.
            
                     The ndmp_name structure contains the following fields:
            
                     original_path
                        The original path name of the data to be recovered,
                        relative to the backup root. If original_path is the null
                        string, the server shall recover all data contained in the
                        backup image.
            
                     destination_path
                     name
                     other_name
                        Together, these identify the absolute path name to which
                        data are to be recovered.
            
                        If name is the null string:
                           destination_path identifies the name to which the data
                           identified by original_path are to be recovered.
                           other_name must be the null string.
            
                        If name is not the null string:
                           destination_path, when concatenated with the server-
                           specific path name delimiter and name, identifies the
                           name to which the data identified by original_path are
                           to be recovered.
            
                        If other_name is not the null string:
                           destination_path, when concatenated with the server-
                           specific path name delimiter and other_name,
                           identifies the alternate name-space name of the data
                           to be recovered. The definition of such alternate
                           name-space is server-specific.
            
                        Neither name nor other_name may contain a path name
                        delimiter.
            
                        Under no circumstance may destination_path be the null
                        string.
            
                        If intermediate directories that lead to the path name to
                        recover do not exist, the server should create them.
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 138]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     node
                        Specifies node number for the file entry reported via the
                        File History Interface during the backup operation. The
                        Data Server recovery method MAY use node number during
                        selective file recovery operations to verify that the data
                        at the location specified by fh_info is the expected file.
                        Node can also be used by the recovery method to locate a
                        specific file in the case where fh_info allows only
                        approximate positioning. This field is set to all ones
                        (binary) if not supported or value unknown by the DMA, and
                        ignored by recovery methods that do not support selective
                        file recovery operations.
            
                     fh_info
                        Specifies file history specific context information
                        generated by the Data Server during the backup operation
                        and passed to the DMA via the File History Interface. The
                        Data Server recovery method MAY use this implementation
                        specific context information to determine tape position
                        for direct access recovery (DAR) operations. Typically
                        this information will represent the byte or record offset
                        of the specified file relative to the start of the backup
                        stream. This field is ignored by recovery methods that do
                        not support DAR. This field is set to all ones (binary) if
                        not supported or value unknown by the DMA, and ignored by
                        recovery methods that do not support selective file
                        recovery operations.
            
                  butype_name
                     Specifies the name of the backup method originally used to
                     generate the backup data which will be recovered. Recovery
                     types are NDMP Server implementation dependent and MUST match
                     one of the Data Server implementation specific butype_name
                     strings accessible via the NDMP_CONFIG_GET_BUTYPE_INFO
                     request.
            
            
                  ndmp_name examples:
            
                     1: To recover the whole backup image into its original pre-
                     backup location /vol/vol3:
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 139]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
                          FILE_SYSTEM = "/vol/vol3"
            
                              original_path    = ""
                              destination_path = "/vol/vol3"
                              name             = ""
                          or,
                              original_path    = ""
                              destination_path = "/vol"
                              name             = "vol3"
            
                     2: To perform a selective recovery of a directory whose
                     original name is "/vol/vol3/users/tyler" to
            
                         "/vol/vol1/users/tyler.from.vol3":
            
                          FILE_SYSTEM = "/vol/vol3"
            
                              original_path    = "/users/tyler"
                              destination_path = "/vol/vol1/users/tyler.from.vol3"
                              name             = ""
                          or,
                              original_path    = "/users/tyler"
                              destination_path = "/vol/vol1/users"
                              name             = "tyler.from.vol3"
            
                     3: To perform a selective recovery of one file whose original
                     name is "/vol/vol3/updatelog" and whose alternate name-space
                     name is "/vol/vol3/updatelog.txt" to the directory
                     "/vol/vol3/recovered":
            
            
                          FILE_SYSTEM = "/vol/vol3"
            
                              original_path    = "/updatelog"
                              destination_path = "/vol/vol3/recovered"
                              name             = "updatelog"
                              other_name       = "updatelog.txt"
            
                     4: To perform a selective recovery of "/viewstore/sally" from
                     the backup of "/viewstore", into its original location.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 140]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                          FILESYSTEM is "/viewstore" for both backup and recovery.
            
                              original_path    = "/sally"
                              destination_path = "/viewstore"
                              new_name         = "sally"
                              other_name       = ""
                          or,
                              original_path    = "/sally"
                              destination_path = "/viewstore/sally"
                              new_name         = ""
                              other_name       = ""
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The start recover request was successfully processed. The
                     Data Server has transitioned to the ACTIVE state and the
                     specified recover method has been invoked.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The start recover request was received while the Data Server
                     state machine was in a state that prevented processing this
                     request. Start recover requests are only valid in the
                     CONNECTED state.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The start recover request specified an invalid recovery
                     method (butype_name), an invalid backup environment (env) or
                     an invalid file recovery list (nlist). Recovery types and
                     backup environment variables are Data Server implementation
                     dependent.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 141]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.5. NDMP_DATA_START_RECOVER_FILEHIST
               This optional request is used by the DMA to instruct the Data Server
               to initiate a file history recovery operation and process the
               recovery stream received from a Tape Server or peer Data Server over
               the previously established data connection to generate file history
               as during backup operations. No changes are made to the local file
               system.
            
               The message format of this request is intentionally identical to
               NDMP_DATA_START_RECOVER. The fields referencing the local file system
               are ignored.
            
               Each NDMP data connection is limited to providing a single backup or
               recovery operation. Therefore the Data Server MUST be in the
               CONNECTED state to accept and process a start recover request. A
               successful start recover request causes the Data Server to transition
               to the ACTIVE state.
            
               The Data Server backup method which originally generated the backup
               data is specified as a name string by the butype_name argument and
               MUST match one of the Data Server implementation specific butype_name
               strings accessible via the NDMP_CONFIG_GET_BUTYPE_INFO request.
            
               Note: butype_name does not specify the name of the Data Server
               recovery method if different from the backup method. The Data Server
               is responsible for making the proper association between backup and
               recovery methods if they are independently named (for example dump
               and recovery).
            
               The file history to be recovered is specified by the nlist argument
               as an array of structures containing one or more directory or file
               names as well as recovery method specific context and file history
               information that may be used during direct access recovery (DAR)
               operations.
            
               The recovery method environment is specified as an array of
               environment variables by the env argument. This argument MUST include
               all environment variables associated with the original backup
               operation and MAY include additional environment variable specific to
               the recovery operation. Following a successful backup operation, when
               the Data Server is in the HALTED states, the DMA MUST access the
               backup method environment variables by issuing a NDMP_DATA_GET_ENV
               request and save this information for subsequent recoveries.
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 142]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Upon receipt of a start recover file history request, the Data Server
               invokes the specified recovery method with the DMA supplied
               environment variables and file list and initiates the recovery
               operation. If the connection type is NDMP_ADDR_TCP or NDMP_ADDR_IPC,
               the Data Server MUST issue a NDMP_NOTIFY_DATA_READ message to the DMA
               specifying the offset and length of the recovery stream. In the case
               of NDMP_ADDR_LOCAL, the Data Server initiates the recovery stream in
               an implementation specific manner that MAY generate
               NDMP_NOTIFY_DATA_READ messages.
            
               The Data Server then waits to receive the specified recovery stream
               from the data connection. Upon successful receipt and processing of
               the specified recovery stream, the Data Server either issues another
               NDMP_NOTIFY_DATA_READ message to initiate the next recovery stream or
               issues a NDMP_NOTIFY_DATA_HALTED message to indicate the recovery
               operation is complete and transitions to the HALTED state.
            
               Message XDR definition
            
                  struct ndmp_data_start_recover_request
                  {
                      ndmp_pval        env<>;
                      ndmp_name        nlist<>;
                      string           butype_name<>;
                  };
            
                  struct ndmp_data_start_recover_reply
                  {
                      ndmp_error       error;
                  };
            
               Request Arguments
            
                  env
                     Specifies an array of environment variables representing the
                     backup environment associated with the specified directories
                     or files. These parameters MUST include all environment
                     variables accessed by the DMA following the successful backup
                     operation and MAY include additional recovery specific
                     variables. The DMA accesses the backup environment by issuing
                     a NDMP_DATA_GET_ENV request while the Data Server is in the
                     HALTED state. The HIST variable is implied by this request.
                     If missing, the recovery method chooses a format (file or
                     node/dir).
            
                  nlist
                     An array of ndmp_name structures specifying the data for
                     which file history is to be recovered. At least one member
                     shall be supplied. The ndmp_name structure contains the
                     following fields:
            
            
            
            
            
            Expires October 2003                                  [Page 143]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
                     original_path
                        The original path name of the data to be recovered,
                        relative to the backup root. If original_path is the null
                        string, the server shall recover file history for all data
                        contained in the backup image. If original_path is not the
                        null string its first character must be the pathname
                        component separator character.
            
                     destination_dir
                        Ignored.
            
                     name
                        Ignored.
            
                     other_name
                        Ignored.
            
                     node
                        Specifies node number for the file entry reported via the
                        File History Interface during the backup operation. The
                        Data Server recovery method MAY use node number during
                        selective file recovery operations to verify that the data
                        at the location specified by fh_info is the expected file.
                        Node can also be used by the recovery method to locate a
                        specific file in the case where fh_info allows only
                        approximate positioning. This field is set to all ones
                        (binary) if not supported or value unknown by the DMA, and
                        ignored by recovery methods that do not support selective
                        file recovery operations.
            
                     fh_info
                        Specifies file history specific context information
                        generated by the Data Server during the backup operation
                        and passed to the DMA via the File History Interface. The
                        Data Server recovery method MAY use this implementation
                        specific context information to determine tape position
                        for direct access recovery (DAR) operations. Typically
                        this information will represent the byte or record offset
                        of the specified file relative to the start of the backup
                        stream. This field is ignored by recovery methods that do
                        not support DAR. This field is set to all ones (binary) if
                        not supported or value unknown by the DMA, and ignored by
                        recovery methods that do not support selective file
                        recovery operations.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 144]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  butype_name
                     Specifies the name of the backup method originally used to
                     generate the backup data which will be recovered. Recovery
                     types are NDMP Server implementation dependent and MUST match
                     one of the Data Server implementation specific butype_name
                     strings accessible via the NDMP_CONFIG_GET_BUTYPE_INFO
                     request.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The NDMP_DATA_START_RECOVER_FILEHIST request was successfully
                     processed. The Data Server has transitioned to the ACTIVE
                     state and the specified recover method has been invoked to
                     recover the specified file history.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The NDMP_DATA_START_RECOVER_FILEHIST request was received
                     while the Data Server state machine was in a state that
                     prevented processing this request. Start recover requests are
                     only valid in the CONNECTED state.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The NDMP_DATA_START_RECOVER_FILEHIST request specified an
                     invalid recovery method (butype_name), an invalid backup
                     environment (env) or an invalid file recovery list (nlist).
                     Recovery types and backup environment variables are Data
                     Server implementation dependent.
            
                  NDMP_NOT_SUPPORTED_ERR
                     The NDMP_DATA_START_RECOVER_FILEHIST request is not supported
                     by this implementation.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 145]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.6. NDMP_DATA_GET_STATE
               This request is used by the DMA to obtain information about the Data
               Server's operational state as represented by the Data Server variable
               set. Refer to section 3.5.1.1 for a complete definition of the
               standard Data Server variables and associated enumerations.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_data_get_state_reply
                  {
                      u_long                    unsupported;
                      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_addr                 data_connection_addr;
                      ndmp_u_quad               read_offset;
                      ndmp_u_quad               read_length;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The data get state request was successfully processed. The
                     data get state reply message body accurately represents the
                     Data Server's current operational state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 146]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.7. NDMP_DATA_GET_ENV
               This request is used by the DMA to obtain the backup environment
               variable set associated with the current data operation. The
               NDMP_DATA_GET_ENV request is typically issued following a successful
               backup operation but MAY be issued during or after a recovery
               operation as well. This request is only valid when the Data Server is
               in the ACTIVE or HALTED states.
            
               The NDMP_DATA_GET_ENV request returns the environment set specified
               in the NDMP_DATA_START_BACKUP or NDMP_DATA_START_RECOVER request
               along with any additional parameters added or modified by the backup
               or recovery method. Note: all environment variables specified in the
               start backup or recovery request MUST be returned including those not
               recognized or processed by the Data Server.
            
               The returned environment set MUST be saved by the DMA and passed back
               to the NDMP Server in the NDMP_DATA_START_RECOVER request whenever
               data from the backup is to be recovered.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_data_get_env_reply
                  {
                      ndmp_error  error;
                      ndmp_pval   env<>;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
                  env
                     Specifies an array of environment variables representing the
                     final backup environment for the completed backup operation.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The NDMP_DATA_GET_ENV request was successfully processed. The
                     data get env reply represents the final backup environment.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The NDMP_DATA_GET_ENV request was received while the Data
                     Server state machine was in a state that prevented processing
                     this request. NDMP_DATA_GET_ENV requests are only valid in
                     the ACTIVE or HALTED states.
            
            
            
            
            Expires October 2003                                  [Page 147]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 148]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.8. NDMP_DATA_STOP
               This request is used by the DMA to instruct the Data Server to
               release all resources, reset all Data Server state variables, reset
               all backup environment variables and transition the Data Server to
               the IDLE state.
            
               Note: Prior to issuing the data stop request after a successful
               backup operation, the DMA SHOULD issue a NDMP_DATA_GET_ENV request to
               access the final backup environment. This information SHOULD be
               stored by the DMA for subsequent recovery operations.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_data_stop_reply
                  {
                      ndmp_error    error;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The data stop request was successfully processed. All data
                     resources have been released, Data Server state variables
                     reset, and the Data Server has transitioned to the IDLE
                     state.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The data stop request was received while the Data Server
                     state machine was in a state that prevented processing this
                     request. Stop requests are only valid in the HALTED state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 149]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.5.2.9. NDMP_DATA_ABORT
               This request is used by the DMA to instruct the Data Server to
               terminate any in progress data operation, close the data connection
               if present, and transition the Data Server to the HALTED state. An
               abort request is valid when the Data Server is in any state except
               IDLE. If the data abort is received in the ACTIVE state the Data
               Server SHOULD terminate the backup or recovery operation as soon as
               practical.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_data_abort_reply
                  {
                      ndmp_error   error;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The data abort request was successfully processed. All data
                     operations have been terminated, the data connection closed,
                     and the Data Server has transitioned to the HALTED state.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The data abort request was received while the Data Server
                     state machine was in a state that prevented processing this
                     request. Abort requests are not valid in the IDLE state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 150]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6. Mover Interface
               The Mover Interface manages the transfer of backup stream data
               between a data or Tape Server and the local tape subsystem. The Mover
               Interface also provides control over the size and location of the
               mover window relative to the start of a backup stream.
            
               Mover windows represent logical boundaries of tape control and
               provide a mechanism for differentiating backup stream data from
               metadata on NDMP generated tapes. Data that resides outside of the
               mover window is controlled by the DMA and represents metadata such as
               header and trailer information. Data written within the mover window
               is controlled by the Data Server and represents the backup stream
               data. The DMA is responsible for establishing a mover window that
               differentiates metadata from backup stream data.
            
               Mover windows can also represent physical boundaries of the backup
               stream layout on tape. The window represents the portion or segment
               of the backup stream data that can be accessed by the tape subsystem
               without requesting DMA controlled tape change or tape positioning
               intervention.
            
            3.6.1. Mover Interface Overview
               The Mover Interface consists of ten unique request/reply message
               pairs. These message pairs can be loosely categorized as providing
               connection management, data transfer management, and status
               reporting. NDMP_MOVER_LISTEN, NDMP_NOVER_CONNECT, NDMP_MOVER_ABORT,
               NDMP_MOVER_STOP and NDMP_MOVER_CLOSE provide control over the mover
               data connection. NDMP_MOVER_SET_RECORD_SIZE, NDMP_MOVER_SET_WINDOW,
               NDMP_MOVER_READ and NDMP_MOVER_CONTINUE control the transfer of data
               between servers and the local tape subsystem. NDMP_MOVER_GET_STATE
               provides a method of querying the mover for status information.
            
               During a backup operation the mover reads the backup stream from the
               data connection, buffers the data into tape records, and writes data
               to the tape subsystem. During a recover operation the mover reads
               data from the tape subsystem and writes the backup stream to the data
               connection. The mover is also responsible for handling tape
               exceptions and notifying the DMA when tape related intervention is
               required.
            
               During a backup operation, window length can be used to partition the
               data stream into multiple stream segments by limiting the amount of
               data written to each segment. This provides the DMA an opportunity to
               interleave metadata between the backup stream segments.
            
               During a recover operation, the DMA is responsible for positioning
               the tape over any non-backup stream metadata (headers, etc). The DMA
               MUST also establish a mover window representing the size and location
               of the current backup stream segment within the entire backup stream
               image.
            
            
            
            
            
            Expires October 2003                                  [Page 151]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               During a recover operation, the DMA may receive several successive
               data read requests from the Data Server. The DMA MUST forward these
               requests to the mover as mover read requests without changing the
               offset or length arguments. If a mover read offset falls within the
               currently defined mover window, the mover is expected to position to
               that offset relative to the start of the window with some simple
               math.
            
               If a mover read specifies an offset that falls outside the current
               mover window, the mover MUST pause and notify the DMA that a new tape
               position is required. The DMA MUST examine the requested offset and
               with the aid of information in its catalog, determine how to get to
               the correct offset (skipping over metadata on the same tape or
               switching to the tape containing the desired offset). The DMA MUST
               then set a new mover window, position the tape to the start of the
               window, and instruct the mover to continue the read operation. Note:
               upon receipt of the NDMP_MOVER_CONTINUE request, the mover is
               responsible for positioning to the required offset within the new
               window.
            
               The mover window avoids the need for the DMA to control tape
               positioning for each data read it receives. In the case of a local
               recover operation where the Data Server and the mover are on the same
               system, the DMA does not receive data read messages. Therefore the
               mover MUST be capable of performing tape positioning within a window.
            
               In addition to backup and recover operations where backup stream data
               transfer occurs between Data Servers and mover/Tape Servers, copy
               operations are also supported. A data connection between two movers
               provides the basis for NDMP tape duplication. This occurs when one
               mover performs a backup operation and the other a recovery operation.
            
            3.6.1.1. Mover Interface Variables & Constants
               There are a number of variables and constants that are key to the
               operation of the Mover Interface. These variables are exposed by the
               NDMP protocol definition and MUST be maintained in a consistent
               manner by all NDMP implementations. The definitions contained in this
               section will be referenced in subsequent Mover Interface sections.
            
               mover_mode
                  This integer value identifies the direction of the mover data
                  transfer. Valid mover modes are defined by the ndmp_mover_mode
                  enumeration. The mode MUST be set to NDMP_MOVER_MODE_NOACTION
                  when the mover state machine is initialized and whenever it
                  transitions to the IDLE state. The move MUST be set to either
                  NDMP_MOVER_MODE_READ or NDMP_MOVER_MODE_WRITE as appropriate
                  whenever a NDMP_MOVER_LISTEN or NDMP_MOVER_CONNECT request is
                  successfully processed.
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 152]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               mover_state
                  This integer value identifies the current state of the NDMP Tape
                  Server's mover state machine. Valid mover states are defined by
                  the ndmp_mover_state enumeration and consist of IDLE, LISTEN,
                  ACTIVE, PAUSED, and HALTED. Refer to section 2 for a complete
                  definition of the mover state machine.
            
               pause_reason
                  This integer value identifies the event that caused the mover
                  state machine to enter the PAUSED state. Pause reason events are
                  defined by the ndmp_mover_pause_reason enumeration. The pause
                  reason MUST be set to NDMP_MOVER_PAUSE_NA whenever the mover
                  state machine is initialized and MUST be set to
                  NDMP_MOVER_PAUSE_EOM (end of media), NDMP_MOVER_PAUSE_EOF (end of
                  file), NDMP_MOVER_PAUSE_SEEK (seek required), or
                  NDMP_MOVER_PAUSE_EOW (end of window) as appropriate upon
                  transition to the PAUSED state. The pause reason MUST be set to
                  NDMP_MOVER_PAUSE_NA upon mover transition out of the PAUSED
                  state. The pause reason is valid only when the mover is in the
                  PAUSED state.
            
                  NDMP_MOVER_PAUSE_NA
                     The mover is not in the paused state.
            
                  NDMP_MOVER_PAUSE_EOM
                     The last mover read operation encountered an End of Media
                     condition. This is also the preferred pause reason when a
                     mover read operation detects a blank tape condition. DMA
                     intervention is required.
            
                  NDMP_MOVER_PAUSE_EOF
                     The last mover operation (read or write) encountered an End
                     of File condition. This pause reason MAY also be used when a
                     mover read can not distinguish between a zero length file and
                     a blank tape condition. DMA intervention is required.
            
                  NDMP_MOVER_PAUSE_SEEK
                     The last mover operation (read) exceeded the bounds of the
                     current mover window. DMA intervention is required.
            
                  NDMP_MOVER_PAUSE_EOW
                     The last mover operation (write) exceeded the bounds of the
                     current mover window. DMA intervention is required.
            
                  Following a transition to the PAUSED state, the mover MUST issue
                  a NDMP_NOTIFY_MOVER_PAUSED message to identify the pause reason
                  and request corrective action by the DMA. Transition to the
                  PAUSED state can result from expected or unexpected conditions.
                  After the appropriate corrective action is taken, paused mover
                  operations are resumed when the DMA issues a NDMP_MOVER_CONTINUE
                  request causing the mover to transition back to the ACTIVE state.
            
            
            
            
            Expires October 2003                                  [Page 153]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               halt_reason
                  This integer value identifies the event that caused the mover
                  state machine to enter the HALTED state. Valid halt reasons are
                  defined by the ndmp_mover_halt reason enumeration. The halt
                  reason MUST be set to NA when the mover state machine is
                  initialized and MUST be set to NDMP_MOVER_HALT_CONNECTION_CLOSED,
                  NDMP_MOVER_HALT_ABORTED, NDMP_MOVER_HALT_INTERNAL_ERROR, or
                  NDMP_MOVER_HALT_CONNECT_ERROR as appropriate upon transition to
                  the HALTED state. The halt reason MUST be set to
                  NDMP_MOVER_HALT_NA upon mover transition out of the HALTED state.
                  The halt reason is valid only when the mover is in the HALTED
                  state.
            
                  NDMP_MOVER_HALT_NA
                     The mover is not in the halted state.
            
                  NDMP_MOVER_HALT_CONNECT_CLOSED
                     The mover's connection to the Data Server was closed.
            
                  NDMP_MOVER_HALT_ABORTED
                     The mover received an NDMP_MOVER_ABORT request from the DMA.
            
                  NDMP_MOVER_HALT_INTERNAL_ERROR
                     The mover detected an unrecoverable error condition.
            
                  NDMP_MOVER_HALT_CONNECT_ERROR
                     The mover detected a connection failure while in the LISTEN
                     state.
            
                  NDMP_MOVER_HALT_MEDIA_ERROR
                     The mover encountered a non-recoverable error while reading
                     from or writing to tape.
            
                  Following a transition to the HALTED state, the mover MUST issue
                  an NDMP_NOTIFY_MOVER_HALTED message to identify the halt reason
                  and allow the DMA to cleanup. Transition to the HALTED state can
                  result from expected or unexpected conditions. In progress mover
                  operations MUST NOT continue after a transition to the HALTED
                  state.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 154]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               record_size
                  This unsigned long value represents the current mover record size
                  in bytes. The Tape Server MUST set the record size to zero when
                  the mover state machine is initialized for the first time. Since
                  zero is not a valid operational value for mover record size, the
                  mover record size MUST be explicitly set by the DMA before the
                  mover transitions out of the IDLE state. Record size is
                  persistent between mover connections and state transitions and
                  remains in effect until reestablished by the DMA. A DMA defined
                  mover record size is not reset by subsequent mover transitions to
                  the IDLE state.  Note: Plans call for the next version of NDMP to
                  eliminate the persistent record_size requirement to make record
                  size handling consistent with other mover state variables.
            
                  The DMA establishes a mover record size by sending an
                  NDMP_MOVER_SET_RECORD_SIZE_request. The mover record size MUST be
                  set to a multiple of the tape block size when the tape subsystem
                  is operating in fixed block mode. When in variable block mode, as
                  indicated by a tape block_size value of zero, the mover record
                  size defines the actual block size used by the tape subsystem.
            
               record_number
                  This unsigned long value represents the last tape record
                  processed by the mover. Record number MUST be set to zero
                  whenever the mover transitions to the IDLE state. Record number
                  is updated upon receipt of a NDMP_MOVER_SET_WINDOW_request, as a
                  result of mover tape positioning operations, and whenever the
                  mover transfers backup data to or from the tape subsystem.
            
                  A DMA MAY change the record number by sending a
                  NDMP_MOVER_SET_WINDOW request. However, this can only be done
                  when the mover is in the IDLE state. Upon receipt of an
                  NDMP_MOVER_SET_WINDOW request, the mover record number MUST be
                  set to the window offset divided by the mover record size. Since
                  the record number is calculated based on mover window_offset and
                  mover record_size the mover record_size MUST be explicitly set by
                  the DMA prior to issuing the first MOVER_SET_WINDOW request.
            
                  Record number MUST be incremented each time the mover reads or
                  writes a mover record from the tape subsystem regardless of
                  whether any data was transferred to the data connection. As the
                  mover initiates forward or backward tape positioning operations
                  it MUST update the record_number appropriately to reflect the new
                  position. Record number reflects only data records processed by
                  the mover. It does not include file marks or metadata processed
                  via the tape interface.
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 155]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               bytes_moved
                  This double unsigned long value represents the cumulative number
                  of data stream bytes written to the data connection or the number
                  of data stream bytes read from the data connection and written to
                  the tape subsystem, depending on the mode of mover operation.
                  Bytes moved MUST be set to zero whenever the mover transitions to
                  the IDLE state.
            
                  When the mover is in write mode (transferring data to the data
                  connection), bytes moved MUST be incremented with the actual data
                  byte count each time the mover writes data to the data
                  connection. Bytes moved does not represent the number of data
                  bytes transferred from the tape subsystem. For example the mover
                  record size can be greater than the mover read request length,
                  resulting in data read from tape that is not transferred to the
                  data connection.
            
                  When the mover is in read mode (transferring data to the tape
                  subsystem) bytes moved MUST be incremented with the actual count
                  of data stream bytes following each successful transfer of data
                  from the data connection to the tape subsystem. The bytes moved
                  value does not include any trailing pad data used to align the
                  data stream segment to a full tape record. When the mover is in
                  read mode and in either the PAUSED or HALTED state, the DMA MAY
                  reference bytes_moved to determine the data stream segment size
                  actually written to the tape subsystem.
            
               seek_position
                  This double unsigned long value represents the data stream offset
                  of the first byte the DMA requested the mover to transfer to the
                  data connection during a mover read operation. Seek position MUST
                  be set to zero whenever the mover transitions to the IDLE state.
                  Upon receipt of a NDMP_MOVER_READ request, seek position MUST be
                  set to the specified read offset value of the request. Seek
                  position is not updated as a result of read operations from the
                  tape subsystem. Its purpose is to allow the DMA to query the
                  mover to determine the start of the last tape read operation.
            
               bytes_left_to_read
                  This double unsigned long value represents the number of data
                  bytes remaining to be transferred to the data connection to
                  satisfy the current NDMP_MOVER_READ request. Bytes left to read
                  MUST be set to zero whenever the mover transitions to the IDLE
                  state. Upon receipt of a mover read request, the
                  bytes_left_to_read value MUST be set to the specified read length
                  value. During a mover read operation, the bytes left to read
                  value MUST be decremented by the number of bytes successfully
                  written to the data connection. A bytes left to read value of
                  zero indicates that the last mover read operation completed and
                  that the mover is waiting for the next read request.
            
            
            
            
            
            Expires October 2003                                  [Page 156]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  Data is not always transferred from the tape subsystem to the
                  data connection in mover record size units. Since the data
                  connection is a flow-controlled stream, it is possible that the
                  transfer of a single mover record will require multiple writes to
                  the data connection. The bytes left to read value MUST accurately
                  represent the actual amount of data remaining to be transferred
                  to the data connection. The data represented by
                  bytes_left_to_read can reside either on tape or buffered within
                  the mover.
            
               window_offset
                  This double unsigned value represents the absolute offset of the
                  first byte of the mover window within the overall data stream.
                  The window offset and window length (described below) together
                  define the portion of the overall data stream that is accessible
                  to the mover without intervening DMA tape manipulation. Window
                  offset is only applicable to recover operations and has no
                  meaning for backup operations. Window offset MUST be set to zero
                  whenever the mover transitions to the IDLE state and whenever a
                  valid NDMP_MOVER_SET_RECORD_SIZE is received.
            
                  Upon receipt of an NDMP_MOVER_SET_WINDOW request, while in either
                  the mover IDLE or PAUSED state, the mover window offset MUST be
                  set to the data stream offset value specified in the request.
                  Prior to issuing an NDMP_MOVER_SET_WINDOW request, the DMA is
                  expected to position the tape so that the next byte read will be
                  from the specified data stream offset. Window offset is not
                  updated as result of mover data transfer or tape positioning
                  operations. The only events that cause window offset updates are
                  the NDMP_MOVER_SET_WINDOW requests and transitions to the IDLE
                  state.
            
               window_length
                  This double unsigned long value represents the length of the
                  current mover window in bytes. The window length and window
                  offset (described above) together define the portion of the
                  overall data stream that is accessible to the mover without
                  intervening DMA tape manipulation. Window length is applicable to
                  both backup and recover operations. For backup operations, window
                  length MAY be used to partition the backup stream into multiple
                  stream segments by limiting the amount of data written to each
                  segment. This provides the DMA an opportunity interleave metadata
                  between the data stream segments.
            
                  Window length MUST be set to zero whenever the mover transitions
                  to the IDLE state and whenever a valid NDMP_MOVER_SET_RECORD_SIZE
                  is received in order to indicate an invalid window definition.
                  The DMA MUST establish a valid window size and endpoint by
                  issuing a NDMP_MOVER_SET_WINDOW request. Upon receipt of an
                  NDMP_MOVER_SET_WINDOW request, while in either the IDLE or PAUSED
                  state, the window length MUST be set to the length value
                  specified in the request.
            
            
            
            Expires October 2003                                  [Page 157]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  Window length MUST be set to a multiple of the mover record_size
                  except when specifying a mover window prior to a recover
                  operation that will include the last mover record of the backup
                  stream. In this case the window length MUST NOT be greater than
                  the end of the backup stream and MUST NOT include any pad bytes
                  written to tape.
            
                  Window length is not updated as result of mover data transfer or
                  tape positioning operations. The only events that cause window
                  length updates are NDMP_MOVER_SET_WINDOW requests and transitions
                  to the IDLE state.
            
               data_connection_addr
                  This structure represents the connection endpoint information for
                  the mover's data connection. The data_connection_addr MUST be set
                  to NDMP_ADDR_LOCAL when the mover is initialized and whenever the
                  mover state machine transitions to the IDLE state.
            
                  Upon transition to the ACTIVE state the data_connection_addr is
                  set to the ndmp_addr value representing connection endpoint
                  address of the peer data or Tape Server. The type of data
                  connection is determined as follows:
            
                  If a single control connection exists between the DMA and co-
                  located data/Tape Servers then NDMP_ADDR_LOCAL MUST be specified.
            
                  If two independent control connections exist between the DMA and
                  co-located tape and Data Servers then NDMP_ADDR_IPC SHOULD be
                  specified if supported. Otherwise NDMP_ADDR_TCP MAY be specified.
            
                  If a remote three-way data operation is being performed between
                  tape and Data Servers residing on two networked NDMP hosts then
                  NDMP_ADDR_TCP MUST be specified.
            
                  When NDMP_ADDR_TYPE_TCP is specified, the ndmp_addr structure
                  provides for an array of one or more IP address and TCP port
                  pairs, as well as a list of environment variables associated with
                  each address pair. However when the mover's data_connection_addr
                  structure specifies NDMP_ADDR_TYPE_TCP, it MUST contain exactly
                  one address pair, and MUST NOT contain any environment variables.
            
                  The TCP address pair used to initialize the data_connection_addr
                  SHOULD be accessed from the mover's network subsystem after a
                  connection is established with the peer tape or Data Server. It
                  SHOULD NOT simply be copied from the NDMP_MOVER_LISTEN reply or
                  NDMP_MOVER_CONNECT request message.
            
            3.6.2. Mover Message Definitions
               The following section defines each of the ten Mover Interface
               request/reply message pairs. Message pair definitions are presented
               in typical usage order: set record size, set window, connect, listen,
               read, get state, continue, close, abort, and stop.
            
            
            
            Expires October 2003                                  [Page 158]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               NDMP Server support of the Mover Interface is OPTIONAL. It is
               possible for a server to implement the Data Interface without the
               Mover Interface. However, if the Mover Interface is implemented, all
               ten mover request messages MUST be supported. If the Mover Interface
               is not implemented, any mover request message MUST result in a
               NDMP_NOT_SUPPORTED error reply.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 159]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.1. NDMP_MOVER_SET_RECORD_SIZE
               This request is used by the DMA to establish the record size used for
               mover-initiated tape read and write operations. The mover record size
               MUST be set to a multiple of the tape block size when the tape
               subsystem is operating in fixed block mode. When in variable block
               mode, as indicated by a tape block_size value of zero, the mover
               record size defines the actual block size used by the tape subsystem.
            
               The mover record size MUST be set to zero when the mover state
               machine is initialized for the first time. The mover record size MUST
               be explicitly set to a valid operational value by the DMA prior to
               issuing a NDMP_MOVER_SET_WINDOW_request and before the mover
               transitions out of the IDLE state. The NDMP_MOVER_SET_WINDOW,
               NDMP_MOVER_CONNECT and NDMP_MOVER_LISTEN requests MUST fail if the
               DMA has not previously established a valid mover record size.
               Therefore a successful NDMP_MOVER_SET_RECORD_SIZE request MUST set
               the mover window_offset and window_length variables to zero.
            
               Record size is persistent between mover connections and state
               transitions and remains in effect until reestablished by the DMA. A
               DMA defined mover record size is not reset by subsequent mover
               transitions to the IDLE state. Note: Plans call for the next version
               of NDMP to eliminate the persistent record_size requirement.  In
               anticipation of this change DMA implementations SHOULD always issue a
               NDMP_MOVER_SET_RECORD prior to issuing a NDMP_MOVER_SET_WINDOW when
               in the IDLE state.
            
               During backup operations, the mover buffers the backup stream read
               from the data connection until a full mover record is received, then
               writes the mover record to the tape subsystem. During recover
               operations, the mover requests full mover records from the tape
               subsystem, then writes some or all of the mover record to the data
               connection as required to satisfy the current mover read request.
               Depending on the mover record size, one or more tape blocks may be
               required to complete the read.
            
               Message XDR definition
            
                  struct ndmp_mover_set_record_size_request
                  {
                      u_long         len;
                  };
            
                  struct ndmp_mover_set_record_size_reply
                  {
                      ndmp_error     error;
                  };
            
               Request Arguments
            
                  len
                     The length of the mover record specified in bytes.
            
            
            
            Expires October 2003                                  [Page 160]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The mover set record size request was successfully processed.
                     The specified mover record size is now in effect.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The mover set record size request specified an invalid record
                     size. Maximum mover record size is implementation dependent
                     but MUST be set to a multiple of the tape block size when the
                     tape subsystem is operating in fixed block mode.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The mover set record size request was received while the
                     mover state machine was in a state that prevented processing
                     this request. Set record requests are only valid in the IDLE
                     state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 161]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.2. NDMP_MOVER_SET_WINDOW
               This request establishes a mover window in terms of offset and
               length. A mover window represents the portion of the overall backup
               stream that is accessible to the mover without intervening DMA tape
               manipulation.
            
               The location and size of the mover window is specified by the request
               offset and length arguments where the offset is an absolute byte
               offset from the start of the data stream and the length is the byte
               length of the window. The window offset plus the window length MUST
               not result in an overflow condition. There is no default mover
               window. Whenever the mover transitions to the IDLE state, the mover
               window is marked invalid by setting both the offset and length to
               zero.
            
               The DMA MUST issue an NDMP_MOVER_SET_WINDOW request to establish a
               valid mover window before causing the mover to transition out of the
               IDLE state via a mover connect or mover listen operation. During both
               backup and recovery operations the DMA MUST also issue this request
               before causing the mover to transition out of the PAUSED state via a
               mover continue request.
            
               Prior to issuing the request, the DMA MUST position the tape so that
               the next byte read from tape will be from the data stream offset
               specified as the start of the window. The set window mover request
               may only be issued when the mover is in the IDLE or PAUSED states.
            
               An NDMP_MOVER_SET_WINDOW request causes the mover record_number to be
               updated to the specified window offset divided by the mover record
               size. Therefore the mover record_size MUST be explicitly set by the
               DMA prior to issuing the first NDMP_MOVER_SET_WINDOW request.
            
               For backup operations (NDMP_MOVER_MODE_READ), the window length MUST
               be set to a multiple of the mover record_size or be set to a maximum
               length window. The offset SHOULD be set to zero. If the window length
               plus the offset is not equal to all ones, then the window length must
               be a multiple of the mover record size. For recovery operations
               (NDMP_MOVER_MODE_WRITE), the window offset MUST be set either to zero
               or a multiple of the mover record_size. These requirements MUST be
               enforced in the set window processing when the mover is in the PAUSED
               state. Note: this restriction MUST also be enforced by the processing
               of the NDMP_MOVER_CONNECT or NDMP_MOVER_LISTEN when the mover is in
               the IDLE state.
            
               A mover window length of all ones (binary) defines a maximum length
               window allowing recovery operations to extend to tape file limits.
               This will result in an NDMP_NOTIFY_MOVER_PAUSED notification with a
               NDMP_MOVER_PAUSE_EOF reason rather than an NDMP_MOVER_PAUSE_SEEK
               reason if an EOW was detected.
            
            
            
            
            
            
            Expires October 2003                                  [Page 162]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               A window length of all ones (binary) MUST only be specified with a
               zero offset since the offset plus the length MUST not result in an
               overflow condition. If a maximum length window is required following
               a mover transition to the PAUSED state, a window length of all ones
               (binary) minus the current window offset MUST be specified. Other
               than allowing recovery operations to extend to backup tape file
               limits, a maximum length window requires no special recovery
               processing.
            
               During backup operations, window length MAY be used to partition the
               data stream into multiple stream segments by limiting the amount of
               data written to each segment. Detection of an EOW condition causes
               the mover to transition to the PAUSED state and issue a
               NDMP_NOTIFY_MOVER_PAUSED message to the DMA. This provides the DMA an
               opportunity to interleave metadata between the data stream segments.
               Window offset is not applicable to backup operations.
            
               During recover operations, the DMA MAY define a mover window to
               optimize selective file recovery by performing a direct access
               recovery (DAR). The DMA SHOULD command the media changer (via the
               SCSI Interface) to load the required tape, then position the tape
               (via the tape interface) to the data record corresponding to the
               desired mover window location. Note: the start of a mover window need
               not be aligned with the start of a tape file but MUST be aligned with
               a mover record. Once the tape is properly positioned, a mover window
               MUST be established to specify the data stream range the mover is
               allowed to access via one or more subsequent mover read requests.
            
               Message XDR definition
            
                  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 start of the mover window specified as an absolute byte
                     offset from the start of the backup stream. This field is
                     ignored if the mover is writing the backup stream to the tape
                     subsystem.
            
                  length
                     The size of the mover window specified in bytes.
            
            
            
            
            Expires October 2003                                  [Page 163]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The request was successfully processed. The specified mover
                     window is now in effect.
            
                  NDMP_PRECONDITION_ERR
                     The request was received prior to establishing a valid mover
                     record_size.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The request specified an invalid window. The mover window
                     length was specified as zero, or the specified window offset
                     plus the window length resulted in an overflow condition.
            
                     For backup operations (NDMP_MOVER_MODE_READ) the window
                     length was not set to a multiple of the mover record_size or
                     all ones (binary) when not in the IDLE state. For recovery
                     operations (NDMP_MOVER_MODE_WRITE) the window offset was not
                     set to a multiple of the mover record_size or zero when not
                     in the IDLE state.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The request was received while the mover state machine was in
                     a state that prevented processing this request. The request
                     is only valid in the IDLE or PAUSED states.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 164]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.3. NDMP_MOVER_CONNECT
               This request is used by the DMA to instruct the mover to establish a
               data connection to a Data Server or peer mover. A connect request is
               only valid when the mover is in the IDLE state and requires the tape
               drive to be opened. A successful connect request causes the mover to
               transition to the ACTIVE state.
            
               A mover data connection is used to transfer backup stream data
               between the tape subsystem associated with the mover that initiated
               the connection and the data or tape subsystem specified in the
               connect request. The data connection can be established locally
               within a given system or between remote networked systems.
            
               The direction of the data transfer is specified by the connect mode
               argument as either reading from or writing to the data connection. If
               the "mode" value is NDMP_MOVER_READ_MODE, implying a write to tape,
               the tape must be open in NDMP_TAPE_RDWR_MODE or NDMP_TAPE_RAW_MODE
               mode.
            
               The type of connection is specified by the addr_type argument. A
               connection within a system can be either null (ADDR_LOCAL) or inter
               process (ADDR_IPC), while a connection between systems can be
               established via TCP/IP (ADDR_TCP).
            
               Note: It is permissible to establish a connection between two movers
               for tape to tape transfers.
            
               NDMP_MOVER_CONNECT processing MUST enforce the mover window offset
               and length requirements because they are mode dependent and the mover
               mode will not be established when the first NDMP_MOVER_SET_WINDOW
               request is received. For backup operations (NDMP_MOVER_READ_MODE) the
               window length MUST be set to a multiple of the mover record_size or
               be set to a maximum length window. For recovery operations
               (NDMP_MOVER_MODE_WRITE) the window offset MUST be set to zero or a
               multiple of the mover record_size. Note: These requirements MUST also
               be enforced in the NDMP_MOVER_SET_WINDOW processing when the mover is
               in the PAUSED state.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 165]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Message XDR definition
            
                  struct ndmp_mover_connect_request
                  {
                      ndmp_mover_mode       mode;
                      ndmp_addr             addr;
                  };
            
                  struct ndmp_mover_connect_reply
                  {
                      ndmp_error            error;
                  };
            
               Request Arguments
            
                  mode
                     Specifies the direction of the data transfer as follows:
            
                     NDMP_MOVER_MODE_READ
                        The mover reads the backup stream from the data connection
                        and writes the data to tape. This mode is used for backup
                        operations.
            
                     NDMP_MOVER_MODE_WRITE
                        The mover reads the backup stream from tape and writes the
                        data to the data connection. This mode is used for recover
                        operations.
            
                     NDMP_MOVER_MODE_NOACTION
                        This mode value is not valid in a mover connect request.
            
                  addr
                     Specifies the endpoint address or addresses that the mover
                     will use when establishing a data connection. The ndmp_addr
                     structure conveys both the address type (NDMP_ADDR_IPC,
                     NDMP_ADDR_LOCAL, or NDMP_ADDR_TCP) as well as the address
                     information appropriate for the specified type.
            
                     If the address type is NDMP_ADDR_TCP, then the connect
                     address contains an array of one or more IP address and TCP
                     port pairs that the peer server is listening at for a data
                     connection. The array of addresses SHOULD be ordered from
                     highest to lowest preference based on peer server criteria.
            
                     The mover SHOULD examine the set of addresses and select the
                     one it considers best based on implementation specific
                     criteria. Alternately the mover MAY attempt to connect to
                     each address in sequence until it establishes a connection or
                     exhausts the addresses or MAY simply attempt to connect to
                     the first address.
            
            
            
            
            
            Expires October 2003                                  [Page 166]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The mover connect request was successfully processed. The
                     mover has successfully connected to the specified address and
                     transitioned to the ACTIVE state.
            
                  NDMP_PRECONDITION_ERR
                     The mover connect request was received prior to establishing
                     a valid mover record_size or mover window.
            
                     For backup operations (NDMP_MOVER_MODE_READ) the window
                     length was not set to a multiple of the mover record_size or
                     all ones (binary). For recovery operations
                     (NDMP_MOVER_MODE_WRITE) the window offset was not set to a
                     multiple of the mover record_size or zero.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The mover connect request was received while the mover state
                     machine was in a state that prevented processing this
                     request. Connect requests are only valid in the IDLE state.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The mover connect request specified an invalid mode or
                     invalid or unsupported address type.
            
                  NDMP_DEVICE_NOT_OPEN_ERR
                     The mover connect request was received when the associated
                     tape drive was not open.
            
                  NDMP_PERMISSION_ERR
                     The NDMP_MOVER_CONNECT request specified NDMP_MOVER_MODE_READ
                     indicating a write to tape, but the tape device was opened
                     with NDMP_TAPE_MODE_READ (read only access).
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_CONNECT_ERR
                     Failed to establish the data connection.
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 167]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.4. NDMP_MOVER_LISTEN
               This request is used by the DMA to instruct the mover create a
               connection end point and listen for a subsequent data connection from
               a Data Server or peer Tape Server (mover). This request is also used
               by the DMA to obtain the address of connection end point the mover is
               listening at. A listen request is only valid when the mover is in the
               IDLE state.
            
               A successful listen request causes the mover to transition to the
               LISTEN state. The mover will remain in the LISTEN state until a data
               connection is established resulting in a transition to the ACTIVE
               state, or until the mover enters the HALTED state following the
               detection of an internal error or receipt of an NDMP_MOVER_ABORT
               request.
            
               A mover data connection is used to transfer backup stream data
               between the server initiating the connection and the tape subsystem
               associated with the mover. The data connection can be established
               locally within a given system or between remote networked systems.
            
               The direction of the data transfer is specified by the listen mode
               argument as either reading from or writing to the data connection.
               The type of connection is specified by the addr_type argument. A
               connection within a system can be either null (NDMP_ADDR_LOCAL) or
               inter process (NDMP_ADDR_IPC), while a connection between systems can
               be established via TCP/IP (NDMP_ADDR_TCP).
            
               Note: It is permissible to establish a connection between two movers
               for tape-to-tape transfers.
            
               The listen processing MUST enforce the mover window offset and length
               requirements because they are mode dependent and the mover mode will
               not be established when the first NDMP_MOVER_SET_WINDOW request is
               received. For backup operations (NDMP_MOVER_MODE_READ) the window
               length MUST be set to a multiple of the mover record_size or be set
               to a maximum length window. For recovery operations
               (NDMP_MOVER_MODE_WRITE) the window offset MUST be set to zero or a
               multiple of the mover record_size. Note: These requirements MUST also
               be enforced in the NDMP_MOVER_SET_WINDOW processing when the mover is
               in the PAUSED state.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 168]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Message XDR definition
            
                  struct ndmp_mover_listen_request
                  {
                      ndmp_mover_mode      mode;
                      ndmp_addr_type       addr_type;
                  };
            
                  struct ndmp_mover_listen_reply
                  {
                      ndmp_error           error;
                      ndmp_addr            connect_addr;
                  };
            
               Request Arguments
            
                  mode
                     Specifies the direction of the data transfer as follows:
            
                     NDMP_MOVER_MODE_READ
                        The mover reads the backup stream from the data connection
                        and writes the data to tape. This mode is used for backup
                        operations.
            
                     NDMP_MOVER_MODE_WRITE
                        The mover reads the backup stream from tape and writes the
                        data to the data connection. This mode is used for recover
                        operations.
            
                     NDMP_MOVER_MODE_NOACTION
                        This mode value is not valid in a mover listen request.
            
                  addr_type
                     NDMP_ADDR_LOCAL
                        The mover listens for a data connection from a Data Server
                        that exists on the same NDMP host. The Data Server and the
                        mover are controlled by a single DMA connection. The
                        communication mechanism is implementation dependent.
            
                     NDMP_ADDR_IPC
                        The mover listens for a connection from a Data Server that
                        exists on the same NDMP host. The mover and the Data
                        Server are controlled by separate DMA connections. The
                        communication mechanism is implementation dependent.
            
                     NDMP_ADDR_TCP
                        The mover listens for a TCP connection from a remote Data
                        Server or peer mover (Tape Server) on one or more specific
                        IP address and TCP port pairs.
            
            
            
            
            
            
            Expires October 2003                                  [Page 169]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                        This address type can also be used to listen for a
                        connection from a Data Server that exists on the same NDMP
                        host. In this case the mover and the Data Server MUST be
                        controlled by separate DMA connections.
            
               Reply Arguments
            
                  connect_addr
                     Specifies the endpoint address or addresses that the mover is
                     listening at for a connection. The ndmp_addr structure
                     conveys both the address type (NDMP_ADDR_IPC,
                     NDMP_ADDR_LOCAL, or NDMP_ADDR_TCP) as well as the address
                     information appropriate for the specified type.
            
                     If the address type is NDMP_ADDR_TCP, then the reply connect
                     address contains an array of one or more IP address and TCP
                     port pairs that the mover is listening for a data connection
                     at. The array of addresses SHOULD be ordered from highest to
                     lowest preference based on mover implementation specific
                     criteria. Typical criteria can include interface bandwidth,
                     interface utilization, and network reachability.
            
                     The NDMP_ADDR_TCP address type also allows specification of
                     implementation specific environment variables on a per
                     address basis. The use of these environment variables is
                     optional and intended to provide a mechanism for the
                     listening NDMP Server to pass additional network related
                     information to the peer server.
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The mover listen request was successfully processed. The
                     mover has transitioned to the LISTEN state and the connect
                     address information contained in this reply message is valid.
            
                  NDMP_PRECONDITION_ERR
                     The mover connect request was received prior to establishing
                     a valid mover record_size or mover window.
            
                     For backup operations (NDMP_MOVER_MODE_READ) the window
                     length was not set to a multiple of the mover record_size or
                     all ones (binary). For recovery operations
                     (NDMP_MOVER_MODE_WRITE) the window offset was not set to a
                     multiple of the mover record_size or zero.
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 170]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_ILLEGAL_STATE_ERR
                     The mover listen request was received while the mover state
                     machine was in a state that prevented processing this
                     request. Listen requests are only valid in the IDLE state.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The mover listen request specified an invalid mode or invalid
                     or unsupported address type.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_PERMISSION_ERR
                     The mover listen request specified NDMP_MOVER_MODE_READ
                     indicating a write to tape, but the tape device was opened
                     with NDMP_TAPE_MODE_READ (read only access).
            
                  NDMP_DEV_NOT_OPEN_ERR
                     No tape device currently open.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 171]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.5. NDMP_MOVER_READ
               This request is used by the DMA to instruct the mover to begin
               transferring the specified backup stream segment from the tape
               subsystem to the data connection. The mover MUST be in the ACTIVE
               state to accept and process a mover read request. Multiple
               outstanding read requests are not allowed.
            
               The location and size of the stream segment to be transferred is
               specified by the read request offset and length arguments where the
               offset is an absolute byte offset from the start of the backup stream
               and the length is the length in bytes of the stream segment.
            
               The mover read offset plus read length MUST not result in an overflow
               condition. A mover read length of all ones (binary) is valid in
               conjunction with a mover read offset of zero. This form of the
               request allows the read to proceed until interrupted by detection of
               an EOM, EOF or EOW condition resulting in a transition to the PAUSED
               state.
            
               The mover is responsible for positioning to the specified read offset
               within the current mover window. If the read offset is not accessible
               within the current mover window, the mover notifies the DMA that a
               tape change or seek is required by issuing a NDMP_NOTIFY_MOVER_PAUSED
               message then enters the PAUSED state.
            
               The mover reads the data stream from the tape subsystem and transfers
               the stream to the data connection. The mover read operation continues
               until the specified stream segment length has been completely
               transferred. If an EOM, EOF or EOW condition is encountered, the
               mover notifies the DMA that a tape change or seek is required via the
               NDMP_NOTIFY_MOVER_PAUSED message and then enters the PAUSED state.
            
               When the mover enters the PAUSED state with an NDMP_MOVER_PAUSE_EOF
               pause_reason, the tape is left positioned on the BOT side of the file
               mark that caused the pause.
            
               If a mover detects a blank tape during a read operation it SHOULD
               enter the PAUSED state with the NDMP_MOVER_PAUSE_EOM pause_reason.
            
               If a mover implementation can not differentiate between a blank tape
               condition and a file mark it MAY enter the PAUSED state with the
               NDMP_MOVER_PAUSE_EOF pause_reason.
            
               While processing a mover read request, the Tape Server MUST continue
               to accept additional messages from the DMA.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 172]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Message XDR definition
            
                  struct ndmp_mover_read_request
                  {
                      ndmp_u_quad            offset;
                      ndmp_u_quad            length;
                  };
            
                  struct ndmp_mover_read_reply
                  {
                      ndmp_error             error;
                  };
            
               Request Arguments
            
                  offset
                     The location of the first byte of data to be sent to the data
                     connection specified as an absolute byte offset from the
                     start of the backup stream.
            
                  length
                     Number of data bytes to be read and sent to the data
                     connection.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The mover read request was successfully processed. The
                     specified mover read is in progress.
            
                  NDMP_ILLEGAL_ARGS_ERR
                     The mover read request specified an invalid data segment. A
                     mover read length of zero is invalid. Additionally, the read
                     offset plus the read length MUST NOT result in an overflow
                     condition.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The mover read request was received while the mover state
                     machine was in a state that prevented processing this
                     request. Read requests are only valid in the ACTIVE state.
            
                  NDMP_READ_IN_PROGRESS_ERR
                     The mover read request was received while a previous mover
                     read operation was in progress. Only one read request may be
                     processed at any time.
            
            
            
            
            
            Expires October 2003                                  [Page 173]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 174]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.6. NDMP_MOVER_GET_STATE
               This request is used by the DMA to obtain information about the
               Mover's operational state as represented by the standard mover
               variable set. Refer to section 3.6.1.1 for a complete definition of
               the standard mover variables and associated enumerations.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_mover_get_state_reply
                  {
                          ndmp_error                   error;
                      ndmp_mover_mode              mode;
                      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                  bytes_moved;
                      ndmp_u_quad                  seek_position;
                      ndmp_u_quad                  bytes_left_to_read;
                      ndmp_u_quad                  window_offset;
                      ndmp_u_quad                  window_length;
                      ndmp_addr                    data_connection_addr;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The mover get state request was successfully processed. The
                     mover get state reply message body accurately represents the
                     mover's current operational state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 175]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.7. NDMP_MOVER_CONTINUE
               This request is used by the DMA to instruct the mover to transition
               from the PAUSED state to the ACTIVE state and to resume the transfer
               of data stream between the data connection and the tape subsystem.
            
               This request is typically issued after the DMA has completed a tape
               change or tape positioning operation in response to a
               NDMP_NOTIFY_MOVER_PAUSED message. An NDMP_MOVER_CONTINUE request can
               only be issued when the mover is in the PAUSED state. The DMA MUST
               issue a new NDMP_MOVER_SET_WINDOW request to establish the new
               absolute offset within the data stream prior to issuing the mover
               continue request.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_mover_continue_reply
                  {
                      ndmp_error            error;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The NDMP_MOVER_CONTINUE request was successfully processed.
                     The mover has transitioned to the ACTIVE state and resumed
                     the transfer of backup stream data.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The NDMP_MOVER_CONTINUE request was received while the mover
                     was in a state that prevented processing this request.
                     Continue requests are only valid when the mover is in the
                     PAUSED state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
                  NDMP_PRECONDITION_ERR
                     The NDMP_MOVER_CONTINUE request was received prior to
                     establishing a valid mover window.
            
            
            
            
            
            Expires October 2003                                  [Page 176]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 177]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.8. NDMP_MOVER_CLOSE
               This request is used by the DMA to instruct the mover to gracefully
               close the current data connection and transition to the HALTED state.
            
               This request is typically issued after all specified recovery data
               has been received by a remote data or Tape Server. A mover close
               request can only be issued when the mover is in the PAUSED state.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_mover_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
                     The mover close request was successfully processed. The mover
                     data connection has been closed and the mover has
                     transitioned to the HALTED state.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The mover close request was received while the mover state
                     machine was in a state that prevented processing this
                     request. Close requests are only valid in the PAUSED state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 178]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.9. NDMP_MOVER_ABORT
               This request is used by the DMA to instruct the mover to terminate
               any in progress mover operation, close the data connection if
               present, and transition the mover to the to the HALTED state. An
               abort request can be issued from any mover state except IDLE.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_mover_abort_reply
                  {
                      ndmp_error            error;
                  };
            
               Request Arguments
            
                   This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The mover abort request was successfully processed. All mover
                     operations have been terminated, the data connection closed,
                     and the mover has transitioned to the HALTED state.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The mover abort request was received while the mover state
                     machine was in a state that prevented processing this
                     request. Abort requests are not valid in the IDLE state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 179]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            3.6.2.10. NDMP_MOVER_STOP
               This request is used by the DMA to instruct the mover to release all
               resources, reset all mover state variables (except record_size), and
               transition the mover to the IDLE state. Note: NDMP_MOVER_STOP
               processing MUST NOT reset the record_size variable because the latter
               is defined to be persistent across mover connections. Although
               considered inconsistent with standard mover state variable handling,
               this special case is maintained in order to avoid impacting existing
               implementations.
            
               Plans call for the next version of NDMP to eliminate the persistent
               record_size requirement.  In anticipation of this change DMA
               implementations SHOULD always issue a NDMP_MOVER_SET_RECORD prior to
               issuing a NDMP_MOVER_SET_WINDOW when in the IDLE state.
            
               The message XDR definition has no request arguments.
            
                  struct ndmp_mover_stop_reply
                  {
                      ndmp_error            error;
                  };
            
               Request Arguments
            
                  This request does not have a message body.
            
               Reply Arguments
            
                  error
                     Error code.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     The mover stop request was successfully processed. All mover
                     resources have been released, mover state variables reset,
                     and the mover has transitioned to the IDLE state.
            
                  NDMP_ILLEGAL_STATE_ERR
                     The mover stop request was received while the mover state
                     machine was in a state that prevented processing this
                     request. Stop requests are only valid in the HALTED state.
            
                  NDMP_NOT_AUTHORIZED_ERR
                     The NDMP Server requires DMA authentication, but has not
                     received a valid NDMP_CONNECT_CLIENT_AUTH request from the
                     DMA.
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 180]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4. DMA Interfaces
               This section defines the protocol interfaces implemented by the DMA.
               Note that none of the messages in this section (LOG, NOTIFY, or
               FILE_HISTORY) have responses associated with them. As a result, the
               initial calls are suffixed with ôpostö instead of ôrequest.ö
            
            4.1. Notify Interface
               This interface is used by the NDMP Server to indicate to the DMA that
               a new state has been entered and/or some direct action is required.
               Upon receiving the message the DMA MUST move to the next phase in the
               backup/recovery procedure, carry out the requested action, or take
               appropriate error reporting/recovery action.
            
               Implementation guideline: It is the recommended client behavior that
               all of this information SHOULD be placed in a file for purposes of
               logging. If there is textual information to be communicated to the
               user, an NDMP_LOG_MESSAGE MAY be sent following the NOTIFY message.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 181]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.1.1. NDMP_NOTIFY_DATA_HALTED
               This message is used to notify the DMA that the NDMP Data Server has
               halted.
            
               Post Message
            
                  struct ndmp_notify_data_halted_post
                  {
                      ndmp_data_halt_reason    reason;
                  };
            
               Post Message Arguments
            
                  reason
                     Reason the data operation halted.
            
                     NDMP_DATA_HALT_SUCCESSFUL
                        Data operation completed successfully.
            
                     NDMP_DATA_HALT_CONNECT_ERROR
                        Connection error reported.
            
                     NDMP_DATA_HALT_ABORTED
                        Data operation aborted by the DMA.
            
                     NDMP_DATA_HALT_INTERNAL_ERROR
                        Data operation halted due to unrecoverable error incurred
                        by the NDMP Server or the data backup/recover method.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 182]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.1.2. NDMP_NOTIFY_CONNECTION_STATUS
               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. For reasons of backward
               compatibility, it is guaranteed that the parameters of this message
               will not change in any future release. The parameters MUST not change
               since this message is sent prior to protocol version negotiation.
            
               Post Message
            
                  struct ndmp_notify_connection_status_post
                  {
                      ndmp_connection_status_reason       reason;
                      u_short                             protocol_version;
                      string                              text_reason<>;
                  };
            
               Post Message Arguments
            
                  reason
                     Reason code describing the current connection state.
            
                     NDMP_CONNECTED
                        NDMP connection successfully established. This code will
                        only be returned in a message sent immediately after
                        successful connection establishment.
            
                     NDMP_SHUTDOWN
                        This reason will only be used after an NDMP connection has
                        been established and a NOTIFY has previously been sent
                        with an NDMP_CONNECTED reason. It is sent 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
                        only be returned in a message sent immediately after a
                        connection establishment attempt to notify the DMA 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.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 183]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  protocol_version
                     Highest version of protocol supported by the NDMP Server
                     implementation. This argument is only valid when the reason
                     argument is NDMP_CONNECTED. If the DMA does not support the
                     protocol version specified by protocol_version then the DMA
                     MUST negotiate an acceptable version using the
                     NDMP_CONNECT_OPEN message.
            
                  text_reason
                     If this message has a reason of NDMP_REFUSED, this NDMP
                     Server implementation dependent message SHOULD be a string
                     indicating why the connection was refused. In all other
                     cases, the text_reason MUST be a zero length string.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 184]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.1.3. NDMP_NOTIFY_MOVER_HALTED
               This message is used to notify the DMA that the NDMP Tape Server has
               entered the halted state.
            
               Post Message
            
                  struct ndmp_notify_mover_halted_post
                  {
                      ndmp_mover_halt_reason      reason;
                  };
            
               Post Message Arguments
            
                  reason
                     Reason the Tape Server halted.
            
                     NDMP_MOVER_HALT_CONNECTION_CLOSED
                        Close of the data detected.
            
                     NDMP_MOVER_HALT_ABORTED
                        Operation aborted by the DMA.
            
                     NDMP_MOVER_HALT_MEDIA_ERROR
                        Operation halted due to a reading or writing to tape.
            
                     NDMP_MOVER_HALT_INTERNAL_ERROR
                        Operation halted due to unrecoverable error incurred by
                        the Tape Server.
            
                     NDMP_MOVER_HALT_CONNECT_ERROR
                        Error establishing data connection.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 185]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.1.4. NDMP_NOTIFY_MOVER_PAUSED
               This message is used to notify the DMA that the NDMP Tape Server has
               paused.
            
               Post Message
            
                  struct ndmp_notify_mover_paused_post
                  {
                      ndmp_mover_pause_reason   reason;
                      ndmp_u_quad               seek_position;
                  };
            
               Post Message Arguments
            
                  reason
                     Reason the Tape Server paused.
            
                     NDMP_MOVER_PAUSE_NA
                        Operation not in progress or not in the pause state.
            
                     NDMP_MOVER_PAUSE_EOM
                        Operation encountered end of media. DMA attention
                        required.
            
                     NDMP_MOVER_PAUSE_EOF
                        Operation encountered end of file. DMA attention required.
            
                     NDMP_MOVER_PAUSE_SEEK
                        Data operation requested data stream offset that is
                        outside of the current mover window. DMA attention
                        required.
            
                     NDMP_MOVER_PAUSE_EOW
                        Operation encountered end of mover window. DMA attention
                        required.
            
                  seek_position
                     If reason is NDMP_MOVER_PAUSE_SEEK, indicates the desired
                     data stream seek position. The DMA MUST load the tape
                     containing the requested seek_position, position the tape
                     appropriately, set a new mover window, and then continue the
                     Tape Server.
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 186]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.1.5. NDMP_NOTIFY_DATA_READ
               This message is used to notify the DMA that the NDMP Server wants to
               read data from a remote Tape Server. The NDMP Server MUST send at
               least one NDMP_NOTIFY_DATA_READ message to the DMA if the Tape Server
               is remote.
            
               Upon receipt of this notification message when performing a normal
               recovery operation, the DMA MUST send an NDMP_MOVER_READ request to
               the remote Tape Server. When performing a file system to file system
               copy operation, the DMA MUST send an NDMP_DATA_START_BACKUP request
               to the peer Data Server.
            
               Post Message
            
                  struct ndmp_notify_data_read_post
                  {
                      ndmp_u_quad  offset;
                      ndmp_u_quad  length;
                  };
            
               Post Message Arguments
            
                  offset
                     Data stream offset of first byte that should be sent to the
                     data connection.
            
                  length
                     Number of data bytes the Tape Server should read from tape
                     and send to the data connection.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 187]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.2. Log Interface
               This interface is used by the NDMP Server to send informational and
               diagnostic data to the DMA. This data is used by the client to
               monitor the progress of the currently running data operation and to
               diagnose problems.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 188]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.2.1. NDMP_LOG_MESSAGE
               This post sends an informational message to the DMA. It MAY be used
               to send log and diagnostic messages generated by the backup or
               recovery method or give updates on any incremental update. It MAY
               also be used to send expanded textual diagnostics about any error
               condition or NOTIFY message.
            
               Each NDMP LOG message SHOULD represent a whole log message;
               fragmented log messages SHOULD be avoided.
            
               Non printing characters present in a message SHOULD be considered
               literal components of that message (such as characters in a file
               name), not an attempt by the server to control output format.
               Accordingly, new-line characters no longer terminate messages.
            
               The DMA may safely reformat each LOG message for presentation to the
               user or output to a file as it sees fit; such might include
               introducing line breaks or replacing non printing characters with
               printing equivalents (turning a new-line into "\n", for example).
            
               Post Message
            
                  struct ndmp_log_message_post
                  {
                      ndmp_log_type     log_type;
                      u_long            message_id;
                      string            entry<>;
                      ndmp_has_associated_message  \
                                        associated_message_valid;
                      u_long            associated_message_sequence;
                  };
            
               Post Message Arguments
            
                  log_type
                     One of the following:
            
                     NDMP_LOG_NORMAL:
                        The message doesnÆt require immediate attention. This kind
                        of message SHOULD be used to report the status of the
                        backup/retrieval process. Some examples of NDMP_LOG_NORMAL
                        log messages follow as an implementation guideline:
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 189]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                        Msg: Date of this level 0 dump: Fri Aug 11 20:24:13 2000.
                        Msg: creating "/vol/vol0/../snapshot_for_backup.0"
                        snapshot.
                        Msg: Using subtree dump
            
                     NDMP_LOG_DEBUG:
                        This kind of message SHOULD be used for diagnostic
                        purposes. This feature is primarily intended to be used
                        during software development and when troubleshooting. Some
                        examples of NDMP_LOG_DEBUG log messages follow as an
                        implementation guideline:
            
                        Msg: "Unrecognized environment variable foo ignored."
                        Msg: "Executing Line 77 of File Ndmpmonkey.java."
                        Msg: "Trace entered NdmpGetDonut function in
                        NdmpHsimpson.c."
            
                     NDMP_LOG_ERROR:
                        This message reports an error condition on the NDMP
                        Server. Users SHOULD pay immediate attention to this
                        message. Some examples of NDMP_LOG_ERROR log messages
                        follow as an implementation guideline:
            
                        Msg: Tape write failed.
                        Msg: Error dumping file.
                        Msg: Cannot dump inode 2848
            
                     NDMP_LOG_WARNING:
                        This message reports a warning condition on the NDMP
                        Server. Users SHOULD pay attention to this message. Some
                        examples of NDMP_LOG_WARNING log messages follow as an
                        implementation guideline:
            
                        Msg: Tape rst0a needs to be cleaned.
                        Msg: Raid disk is down.
            
            
                  message_id
                     The message_id is NDMP Server dependent. NDMP Servers MAY use
                     this field to assign a unique identifier to each message that
                     associates the message with information contained in a
                     reference document.
            
                  entry
                     Text message.
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 190]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  associated_message_valid
                     associated_message_valid indicates whether this LOG message
                     is associated with a previous NDMP message. If TRUE, the log
                     message is associated with the NDMP message identified by the
                     server sequence number contained in the
                     associated_message_sequence field. If FALSE, no message
                     association exists and the associated_message_sequence field
                     MUST be disregarded.
            
                  associated_message_sequence
                     associated_message_sequence identifies the sequence number of
                     a previous NDMP message sent by the NDMP Server associated
                     with this LOG message. Assignment of a non-zero value to this
                     field is optional and only valid if the
                     associated_message_valid field is TRUE. The association is
                     intended to allow servers to provide additional information
                     for any message based event. When set, the
                     associated_message_sequence field MUST always refer to a
                     server sequence number. Furthermore, of all associated
                     messages, this message needs to be sent last, which is only
                     logical since the association cannot refer to a message that
                     does not yet exist.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 191]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.2.2. NDMP_LOG_FILE
               This post sends a file recovered message to the DMA. It is used
               during recovery to notify the DMA that a file/directory specified in
               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.
               (Note: if the name in the recovery list is a directory, when even one
               file within that directory experiences a failure, the recovery for
               that directory SHOULD be considered to have been failed.)
            
               Post Message
            
                  struct ndmp_log_file_post
                  {
                      string                   name<>;
                      ndmp_recovery_status     recovery_status;
                  };
            
               Post Message Arguments
            
                  name
                     File name. This file name string MUST match an original_path
                     name from the nlist passed to NDMP_DATA_START_RECOVER.
            
                  recovery_status
                     One of the following:
            
                     NDMP_RECOVERY_SUCCESSFUL
                        File successfully recovered.
            
                     NDMP_RECOVERY_FAILED_PERMISSION
                        File recovery failed due to a permission problem.
            
                     NDMP_RECOVERY_FAILED_NOT_FOUND
                        File not found during recovery.
            
                     NDMP_RECOVERY_FAILED_NO_DIRECTORY
                        Directory not found.
            
                     NDMP_RECOVERY_FAILED_OUT_OF_MEMORY
                        Memory allocation failed during recovery.
            
                     NDMP_RECOVERY_FAILED_IO_ERROR
                        IO error encountered during recovery.
            
                     NDMP_RECOVERY_FAILED_UNDEFINED_ERROR
                        Error encountered during recovery other than one of those
                        listed above.
            
            
            
            
            
            Expires October 2003                                  [Page 192]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     NDMP_RECOVERY_FAILED_FILE_PATH_EXISTS
                        Recovery failed due to the requested path already
                        existing.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 193]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.3. File History Interface
               The NDMP Server uses this interface to send file history entries to
               the DMA. 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 file system or an NT file system compatible
               format. The backup method can generate UNIX, NT, or both UNIX and NT
               file system compatible format file history for each file.
            
               There are two sets of messages for sending file history data. The
               first set consists of the NDMP_FH_ADD_FILE message. This set is for
               use by filename based backup methods (such as tar and cpio) for which
               the full pathname and file attributes are available at the time each
               file is backed up. The second set consists of the NDMP_FH_ADD_DIR and
               NDMP_FH_ADD_NODE messages. This set is for use by inode based backup
               methods (such as UNIX dump) for which the full pathname is not
               necessarily available at the time the file data is backed up.
            
               It is NOT REQUIRED that the backup method support the sending of file
               history data. However, the NDMP Server MUST accurately report the
               type of file history supported (if any) for each backup type in the
               NDMP_CONFIG_GET_BUTYPE_INFO.
            
               Implementation Guideline: It is advised NOT to send the file history
               in one long sequence at the end at the end of a backup operation. As
               the total file history set can amount to a large amount of data, some
               DMAs are not prepared to receive this. The recommended approach is to
               send file history messages as the data is read from the file system.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 194]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.3.1. NDMP_FH_ADD_FILE
               This request adds a list of file paths with the corresponding
               attribute entries to the file history. The file path MUST be relative
               to the backup root directory (specified by the FILESYSTEM pval). The
               pathname separator character (specified by the PATHNAME_SEPARATOR
               pval) MUST be the first character of each file path.
            
               During an incremental backup or a selective file backup a backup
               method is NOT REQUIRED to send add file entries for intermediate
               directories leading to files being backed up. A DMA SHOULD only
               expect to receive add file entries for those files actually backed up
               to the backup data stream. Example: for an incremental backup of /a
               where only the file /a/b/c/d was modified, the backup method need
               only send one add file entry for the /a/b/c/d file. Entries for /a,
               /a/b, and /a/b/c need not be sent.
            
               Post Message
            
                  struct ndmp_fh_add_file_post
                  {
                      ndmp_file            files<>;
                  };
            
               Post Message Arguments
            
                  files
                     Array of file history entries. Each entry contains:
            
                     name
                        Array of the file names for a single file. Each file can
                        have one or more file names. Multiple names are typically
                        used by multi-protocol file servers to provide both the
                        UNIX and NT file name for a file being backed up. The name
                        union contains the following:
            
                        unix_name
                           UNIX path name of backed up file. MUST be the path
                           name relative to the backup root directory. The first
                           character of path name MUST be the path separation
                           character.
            
                        nt_name
                           UNIX path name of backed up file. MUST be the path
                           name relative to the backup root directory. The first
                           character of path name MUST be the path separation
                           character.
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 195]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                        other_name
                           Path name of backed up file. MUST be the path name
                           relative to the backup root directory. The first
                           character of path name MUST be the path separation
                           character. This field SHOULD be used when the file
                           system is of a type other than UNIX or NT.
            
                  stat
                     Array of the file attributes for a single file. The following
                     attributes are defined in the ndmp_file_stat structure:
            
                     unsupported
                        Identifies unsupported message arguments.
            
                     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). The NDMP_FILE_STAT_ATIME_UNS bit MUST
                        be set in the unsupported bitmask field if this feature is
                        not supported.
            
                     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.
                        The NDMP_FILE_STAT_CTIME_UNS bit MUST be set in the
                        unsupported bitmask field if this feature is not
                        supported.
            
                     owner
                        File owner identifier. uid SHOULD be used for UNIX file
                        system type. This field is undefined for NT file system
                        type.
            
                     group
                        File group identifier. gid SHOULD be used for UNIX file
                        system type. This field is undefined for NT file system
                        type.
            
                     fattr
                        System file attribute. UNIX file mode SHOULD be used for
                        UNIX file system type. On UNIX the file mode and type are
                        typically encoded together. fattr MUST be set to just the
                        mode bits, excluding the type bits. NT fattr SHOULD be
                        used for NT file system type.
            
            
            
            
            Expires October 2003                                  [Page 196]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     size
                        File size in bytes.
            
                     links
                        File link count.
            
                     node
                        inode number. This field is only used for UNIX file system
                        only. A value of 0 MUST be used if this field is not
                        supported. The value all ones (binary) is reserved and can
                        not be used.
            
                     fh_info
                        File history positioning data representing the data stream
                        position of the file. This data MAY be used by the
                        recovery method to perform direct access file retrieval.
                        The positioning data is NDMP Server dependent. Typically
                        it is the byte offset within the data stream of the start
                        of the file data. This field MUST be set to all ones
                        (binary) if the server implementation does not support
                        direct access file retrieval.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 197]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.3.2. NDMP_FH_ADD_DIR
               This message is used to report name and inode information for backed
               up files. The following rules apply to the generation of add
               directory entries:
            
                  1. The very first NDMP_FH_ADD_DIR entry sent MUST be the "."
                  entry for the backup root directory. The second ADD_DIR
                  entry sent MUST be the ".." entry for the backup root directory.
                  A DMA MUST NOT make any assumptions with regard to the value of
                  the node for the backup root directory. Although the value of the
                  node for a file system root directory for many file system types
                  is 2, a DMA MUST NOT expect the value to be 2. A Data Server is
                  NOT REQUIRED to use a value of 2 for the backup root directory
                  node.
            
                  2. In the event that the backup root directory, as specified by
                  the FILESYSTEM environment variable, is not the mount point for
                  the file system, NDMP_FH_ADD_DIR entries MUST NOT be reported for
                  directories, or files contained in directories, leading up to the
                  backup root directory.
            
                  Implementation Guideline: Rule 2 was added because some backup
                  applications, even though they support performing a backup of a
                  directory below the mount point, still backup all directories
                  (just the directories; not directory contents) starting from the
                  mount point. Upon reaching the backup root directory, the
                  application begins backing up directory contents. The implication
                  of rule 1 is that the Data Server must not generate add directory
                  entries for these directories from the mount point down to the
                  backup root directory.
            
                  3. For each directory, a "." NDMP_FH_ADD_DIR entry and a ".."
                  NDMP_FH_ADD_DIR entry MUST immediately precede all
                  NDMP_FH_ADD_DIR entries for files contained in the directory. A
                  "." NDMP_FH_ADD_DIR entry MUST contain "." as one of the names in
                  the name array. The node and parent values MUST be equivalent. A
                  ".." NDMP_FH_ADD_DIR entry MUST contain ".." as one of the names
                  in the name array. The parent value MUST match the node value
                  from the "." entry and the node value MUST match the node value
                  of the directory's parent directory. The only exception to this
                  rule is for the backup root directory in which case the node
                  value MUST be equivalent to the parent value.
            
                  4. All add entries for files/directories contained in a directory
                  MUST immediately follow the ".." NDMP_FH_ADD_DIR entry for that
                  directory. All NDMP_FH_ADD_DIR entries for a directory must be
                  sent prior to any NDMP_FH_ADD_DIR entry for another directory.
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 198]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  5. For any given node, an NDMP_FH_ADD_DIR entry for the node MUST
                  be sent prior to the NDMP_FH_ADD_NODE entry for the node. In the
                  event that multiple hard links exist for a node, one
                  NDMP_FH_ADD_DIR entry MUST be sent for each link but only one
                  NDMP_FH_ADD_NODE entry SHOULD be sent for the node. The first add
                  directory entry for a node with multiple hard links MUST be sent
                  prior to the add node entry. However, the Data Server is NOT
                  REQUIRED to send the remaining NDMP_FH_ADD_DIR entries before
                  sending the NDMP_FH_ADD_NODE entry.
            
                  6. For an incremental backup, NDMP_FH_ADD_DIR entries MAY be sent
                  for which no associated NDMP_FH_ADD_NODE entry is sent. The
                  server MUST send add directory entries for the entire contents of
                  every directory leading to each backed up file. NDMP_FH_ADD_NODE
                  entries MUST only be sent for each backed up file and the
                  directories leading to each backed up file.
            
                  7. The node number in each added directory entry MUST be unique
                  amongst all entries sent during the course of a backup. The only
                  exception to this rule is for entries for files having multiple
                  hard links. All entries for links to the same file MUST have the
                  same node number.
            
               Post Message
            
                  struct ndmp_fh_add_dir_post
                  {
                      ndmp_dir    dirs<>;
                  };
            
               Post Message Arguments
            
                  dirs
                     Array of directory entries. Each entry contains:
            
                  name
                     Array of file names for a single node. The name is not the
                     full pathname; just the base name relative to the node's
                     parent directory.
            
                  node
                     Node identifier that matches the node in a corresponding add
                     node message. NDMP Server implementation dependent but will
                     typically be the inode number of the file. The value all ones
                     (binary) is reserved and can not be used.
            
                  parent
                     Node identifier of the node's parent directory. NDMP Server
                     implementation dependent but will typically be the inode
                     number of the file's parent directory.
            
            
            
            
            
            Expires October 2003                                  [Page 199]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            4.3.3. NDMP_FH_ADD_NODE
               This request adds a list of file attribute entries to the file
               history. Each entry MUST match a corresponding node number from a
               previously sent add directory entry.
            
               Post Message
            
                  struct ndmp_fh_add_node_post
                  {
                      ndmp_node         nodes<>;
                  };
            
               Post Message Arguments
            
                  nodes
                     Array of file history node entries. Each entry contains:
            
                     stats
                        Array of file attribute data for a single file.
            
                     node
                        Node identifier that matches a node in a corresponding add
                        directory entry. NDMP Server implementation dependent but
                        typically is the inode number of the file. The value all
                        ones (binary) is reserved and can not be used.
            
                     fh_info
                        File history positioning data representing the data stream
                        position of the file. This data MAY be used by the
                        recovery method to perform direct access file retrieval.
                        The positioning data is NDMP Server dependent. Typically
                        it is the byte offset within the data stream of the start
                        of the file data. This field MUST be set to all ones
                        (binary) if the server implementation does not support
                        direct access file retrieval.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 200]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            5. Security
               NDMP through firewalls is problematic if the data and tape services
               reside in the interior of separate firewalls such that an NDMP data
               connection must originate from the exterior of one firewall. If only
               a single firewall exists, the NDMP Server inside the firewall SHOULD
               originate the connection as firewalls generally allow any outbound
               connection.
            
               NDMP Server implementations SHOULD resolve the two firewall problem
               by providing configurable control over the port number range that
               will be used for NDMP data connection listens. This control SHOULD be
               used by system administrators to constrain NDMP Servers to a limited
               range of TCP ports that correspond to ports the firewall will allow
               inbound connections on.
            
               NDMP is incompatible with Network Address Translation (NAT) firewalls
               because IP address and TCP port information is conveyed as payload
               data between NDMP peers (connect_addr in NDMP_MOVER_LISTEN &
               NDMP_DATA_LISTEN replies).
            
               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.
            
               Identification of server supported authentication types is provided
               via the NDMP_CONFIG_GET_SERVER_INFO request. This request also
               provides access to the NDMP Server's vendor/product name and revision
               information. It is recommended that the name and revision strings be
               suppressed prior to successful NDMP client authentication.
            
               The NDMP SCSI Interface provides low-level access to SCSI media
               changer devices. The NDMP Server SHOULD prevent access to other SCSI
               devices (such as disk drives) to prevent the NDMP client from
               bypassing file system security.
            
               File history information is transferred to the NDMP client through a
               TCP/IP connection.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 201]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               6. 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
            
                  [3] RFC 2044, "UTF-8 a transformation format of Unicode and ISO
                  10646", F. Yergeau, Alis Technologies, October 1996
            
                  [4] RFC 1831, "Remote Procedure Call Protocol Version 2",
                  Srinivasan, R., Sun Microsystems, Inc., August 1995.
            
                  [5] "NDMP Version 2", Dave Hitz, Network Appliance, Inc., and
                  Roger Stager, Legato Software, Inc., September 1997.
            
                  [6] "NDMP Version 3", Dave Hitz, Network Appliance, Inc., and
                  Roger Stager, Legato Software, Inc., April, 1998.
            
                  [7] "NDMP workflow document", www.ndmp.org
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 202]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            7. Recognition of Prior Work
               This work is based on NDMP version 1, 2 [5] and 3 [6], as developed
               by Dave Hitz, Network Appliance Inc., and Roger Stager, Legato
               Software Inc. These documents can be retrieved from www.ndmp.org.
            
               Version 4 of the NDMP specification is largely a cleanup effort from
               version 2 and version 3 of the NDMP specification. The only
               functional addition is NDMP extensibility.
            
               Very few aspects have changed from versions 2 and 3, to version 4 of
               the protocol, and the architecture of NDMP from versions 2 and 3 of
               the protocol is preserved.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 203]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            8. Authors and Contributors
            8.1. Document Editor
            
            
                  Harald Skardal
                  Network Appliance, Inc.
                  Tel: 603.882.3881
                  Email: Harald.Skardal@netapp.com
            
            
            8.2. Authors' Addresses
            
            
                  James Bunnell
                  Spectra Logic, Inc.
                  Email: jamesb@spectralogic.com
            
                  Sudakar V. Chellam,
                  IBM
                  Email: svelkant@us.ibm.com
            
                  Tim Gardner
                  Chewcoba Systems, Inc.
                  Email: tim@chewcoba.com
            
                  Clive Hendrie
                  BlueArc Corporation
                  Email: chendrie@bluearc.com
            
                  Kiyoshi Komatsu
                  Network Appliance, Inc.
                  Email: Kiyoshi.Komatsu@netapp.com
            
                  Greg Linn
                  Network Appliance, Inc.
                  Email: Greg.Linn@netapp.com
            
                  Dave Manley
                  Independent
                  Email: manley@cs.stanford.edu
            
                  Harald Skardal
                  Network Appliance, Inc.
                  Tel: 603.882.3881
                  Email: Harald.Skardal@netapp.com
            
                  Jim Ward
                  Reliaty, Inc.
                  Email: jimw@worksta.com
            
                  Gordon Waidhofer
                  Traakan Inc.
                  Email: gww@traakan.com
            
            
            Expires October 2003                                  [Page 204]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            8.3. Contributors
               In addition to the authors, the following people have contributed
               significantly in the reviews of this document:
            
                  Lawrence F Barnes
                  BakBone Software Ltd.
                  Email: lawrence@bakbone.co.uk
            
                  Steve Kappel
                  Veritas Software
                  Email: steve.kappel@veritas.com
            
                  Paul Lockwood
                  Legato Software
                  Email: plock@legato.com
            
                  Rudy Nedved
                  Spinnaker Networks, Inc.
                  Email: ern@spinnakernet.com
            
                  Sean O'Connor
                  Spectra Logic, Inc.
                  Email: seano@spectralogic.com
            
                  Arvind Pruthi
                  Network Appliance, Inc.
                  Email: pruthi@netapp.com
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 205]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            Appendixes:
            
            Appendix A: NDMP Extension Management.
               This appendix is a collection document for processes, rules and
               recommendations that support the NDMP extension system. As NDMP
               evolves, some or all of this may be taken over by existing or
               emerging IETF rules and processes, or become standardized as separate
               specification in the NDMP standards suite.
            
               Standard Extensions:
                  The layout and management of the standard extensions space is
                  deferred to a separate specification effort. This work will be
                  started when the community starts work on multi-vendor extensions
                  intended for standardization. This work will be based on existing
                  IETF standards and guidelines.
            
               Proprietary Extensions:
                  The following describes the preliminary layout and allocation
                  rules for proprietary extensions.
            
                  In the interest of frugality and sharing, sandboxes of four
                  classes each are created. One sandbox is allocated to each
                  implementer that can document a need. Implementers may apply for
                  additional sandboxes when the need can be documented.
            
                  The sandboxes are allocated from the proprietary standards code
                  space, starting at class 0x2000. To give each implementer some
                  growth space such that additional sandboxes can form a contiguous
                  code space, each sandbox is placed at every 0x10 class value.
            
                  The following sandboxes are allocated for implementers: (Hex
                  notation.)
            
                        Auspex:                     2000.0000 - 2003.FFFF
            
                        Compaq:                     2010.0000 - 2013.FFFF
            
                        Crosstor:                   2020.0000 - 2023.FFFF
            
                        IBM/Tivoli:                 2030.0000 - 2033.FFFF
            
                        Legato:                     2040.0000 - 2043.FFFF
            
                        NetApp:                     2050.0000 - 2053.FFFF
            
                        Procom:                     2060.0000 - 2063.FFFF
            
                        Spectralogic:               2070.0000 - 2073.FFFF
            
                        Bluearc:                    2080.0000 - 2083.FFFF
            
                        Syncsort:                   2090.0000 - 2093.FFFF
            
            
            
            Expires October 2003                                  [Page 206]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                        Traakan:                    20A0.0000 - 20A3.FFFF
            
                        Veritas:                    20B0.0000 - 20B3.FFFF
            
                        Reliaty:                    20C0.0000 - 20C3.FFFF
            
                        EMC:                        20D0.0000 - 20D3.FFFF
            
                        Atempo:                     20E0.0000 - 20E3.FFFF
            
                        VA Linux:                   20F0.0000 - 20F3.FFFF
            
                        Backbone:                   2100.0000 - 2103.FFFF
            
                        Commvault:                  2110.0000 - 2113.FFFF
            
                        Mirapoint:                  2120.0000 - 2123.FFFF
            
                        Network Engines:            2130.0000 - 2133.FFFF
            
                        Quantum/ATL:                2140.0000 - 2143.FFFF
            
                        HP:                         2150.0000 - 2153.FFFF
            
                        Broadband Storage:          2160.0000 - 2163.FFFF
            
                        Microtal:                   2170.0000 - 2173.FFFF
            
                        Land-5:                     2180.0000 - 2183.FFFF
            
                        Hitachi:                    2190.0000 û 2193.FFFF
            
                        Agile Storage:              21A0.0000 û 21A3.FFFF
            
                        Spinnaker Networks:         21B0.0000 û 21B3.FFFF
            
                        Overland Storage:           21C0.0000 û 21C3.FFFF
            
                        Dinostor:                   21D0.0000 û 21D3.FFFF
            
                        Reserved:   Everything not explicitly allocated from the
                        proprietary extension code range.
            
               A suggestion for class use:
                  Classes should follow products and their releases. For instance,
                  all the extensions supporting implementer specific functionality
                  in a implementer's data service ought to be grouped together in
                  one class, and follow the release schedule of the product of
                  which the data service is a component.
            
            
            
            
            
            
            Expires October 2003                                  [Page 207]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Extension Standardization Process
                  The process for how to conduct this standardization of extensions
                  should be discussed with the IETF area director, and it also
                  should be reviewed whether similar extensibility has been
                  developed in the IETF before.
            
                  The layout and management of the standard extensions code space
                  is to be determined.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 208]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            Appendix B: NDMP Extensions Test Message
               The extension class 0x7ff0, interface 00, message 00 will be used as
               a extension test message. All NDMP servers that implement extensions
               SHOULD also implement the test message. The DMA and server
               implementer can use this message as a vehicle for testing their
               implementation of extensions discovery and negotiation, as well as
               error handling. In order to test the discovery and negotiation
               process, two versions of the 0x7ff0 class with different message
               definitions will be defined.
            
            
               NDMP Extension Test Message Numbers:
            
               The following message is defined:
            
                  enum ndmp_test_ext_message
                  {
                      NDMP_TEST_ECHO = 0x7ff00000;
                  };
            
               Class 0x7ff0 V1 Echo Interface
            
               NDMP_TEST_ECHO
                  This message is used to test the basic implementations of
                  extensions D+N and error handling. If the server supports this
                  message, the DMA will receive an echo of the string that was sent
                  by the request message.
            
               Message XDR definitions
            
                  struct ndmp_test_echo_request
                  {
                       string       echo_msg<>;
                  };
            
                  struct ndmp_test_echo_reply
                  {
                      ndmp_error   error;
                      string       echo_msg<>;
                  };
            
               Request Arguments
            
                  echo_msg
                     This is any string that is expected to be echoed back from
                     the server.
            
               Reply Arguments
            
                  error
                     Error code.
            
            
            
            
            Expires October 2003                                  [Page 209]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  echo_msg
                     This should be the same string as that sent by the DMA in the
                     request message.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Echo message has been successfully returned.
            
                  NDMP_NOT_SUPPORTED_ERR
                    The request is not supported for this implementation.
            
               Class 0x7ff0 V2 Echo Interface
            
               NDMP_TEST_ECHO
                  Version 2 of this message is modified by adding a u_short to the
                  message. This allows the DMA to distinguish the message from the
                  V1 message. The server SHOULD implement this message so that the
                  D+N implementation can be tested with two versions of a
                  particular class. If the server supports this message, the DMA
                  will receive an echo of the string and u_short that was sent by
                  the request message.
            
               Message XDR definitions
            
                  struct ndmp_test_echo_request
                  {
                      string       echo_msg<>;
                      u_short      echo_short;
                  };
            
                  struct ndmp_test_echo_reply
                  {
                      ndmp_error   error;
                      string       echo_msg<>;
                      u_short      echo_short;
                  };
            
            
               Request Arguments
            
                  echo_msg
                     This is any string that is expected to be echoed back from
                     the server.
            
                  echo_short
                     This is any u_short that is expected to be echoed back from
                     the server.
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 210]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
               Reply Arguments
            
                  error
                     Error code.
            
                  message
                     This should be the same string as that sent from the DMA in
                     the request message.
            
               Reply Errors
            
                  NDMP_NO_ERR
                     Echo message has been successfully returned.
            
                  NDMP_NOT_SUPPORTED_ERR
                    The request is not supported for this implementation.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 211]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            Appendix C: XDR for an NDMP Implementation
               Although there are certainly many very different XDR files that could
               define an NDMP specification, one is included below for purposes of
               reference.
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 212]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  enum ndmp_header_message_type
                  {
                      NDMP_MESSAGE_REQUEST          = 0,
                      NDMP_MESSAGE_REPLY            = 1
                  };
            
                  const NDMP_MESSAGE_POST = NDMP_MESSAGE_REQUEST;
            
                  struct ndmp_pval
                  {
                      string      name<>;
                      string      value<>;
                  };
            
                  struct ndmp_u_quad
                  {
                      u_long high;
                      u_long low;
                  };
            
                   /* Note: because of extensibility, this is */
                   /* not a complete list of errors. */
                  enum ndmp_error
                  {
                      NDMP_NO_ERR                     =  0,
                      NDMP_NOT_SUPPORTED_ERR          =  1,
                      NDMP_DEVICE_BUSY_ERR            =  2,
                      NDMP_DEVICE_OPENED_ERR          =  3,
                      NDMP_NOT_AUTHORIZED_ERR         =  4,
                      NDMP_PERMISSION_ERR             =  5,
                      NDMP_DEV_NOT_OPEN_ERR           =  6,
                      NDMP_IO_ERR                     =  7,
                      NDMP_TIMEOUT_ERR                =  8,
                      NDMP_ILLEGAL_ARGS_ERR           =  9,
                      NDMP_NO_TAPE_LOADED_ERR         = 10,
                      NDMP_WRITE_PROTECT_ERR          = 11,
                      NDMP_EOF_ERR                    = 12,
                      NDMP_EOM_ERR                    = 13,
                      NDMP_FILE_NOT_FOUND_ERR         = 14,
                      NDMP_BAD_FILE_ERR               = 15,
                      NDMP_NO_DEVICE_ERR              = 16,
                      NDMP_NO_BUS_ERR                 = 17,
                      NDMP_XDR_DECODE_ERR             = 18,
                      NDMP_ILLEGAL_STATE_ERR          = 19,
                      NDMP_UNDEFINED_ERR              = 20,
                      NDMP_XDR_ENCODE_ERR             = 21,
                      NDMP_NO_MEM_ERR                 = 22,
                      NDMP_CONNECT_ERR                = 23,
                      NDMP_SEQUENCE_NUM_ERR           = 24,
                      NDMP_READ_IN_PROGRESS_ERR       = 25,
                      NDMP_PRECONDITION_ERR           = 26,
                      NDMP_CLASS_NOT_SUPPORTED_ERR    = 27,
            
            
            
            Expires October 2003                                  [Page 213]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      NDMP_VERSION_NOT_SUPPORTED_ERR  = 28,
                      NDMP_EXT_DUPL_CLASSES_ERR       = 29,
                      NDMP_EXT_DANDN_ILLEGAL_ERR       = 30
                  };
            
                  /* Note: Because of extensibility, this */
                  /* is not a complete list of messages */
                  enum ndmp_message
                  {
            
                      NDMP_CONNECT_OPEN               = 0x900,
                      NDMP_CONNECT_CLIENT_AUTH        = 0x901,
                      NDMP_CONNECT_CLOSE              = 0x902,
                      NDMP_CONNECT_SERVER_AUTH        = 0x903,
            
                      NDMP_CONFIG_GET_HOST_INFO       = 0x100,
                      NDMP_CONFIG_GET_CONNECTION_TYPE = 0x102,
                      NDMP_CONFIG_GET_AUTH_ATTR       = 0x103,
                      NDMP_CONFIG_GET_BUTYPE_INFO     = 0x104,
                      NDMP_CONFIG_GET_FS_INFO         = 0x105,
                      NDMP_CONFIG_GET_TAPE_INFO       = 0x106,
                      NDMP_CONFIG_GET_SCSI_INFO       = 0x107,
                      NDMP_CONFIG_GET_SERVER_INFO     = 0x108,
                      NDMP_CONFIG_SET_EXT_LIST        = 0x109,
                      NDMP_CONFIG_GET_EXT_LIST        = 0x10A,
            
                      NDMP_SCSI_OPEN                  = 0x200,
                      NDMP_SCSI_CLOSE                 = 0x201,
                      NDMP_SCSI_GET_STATE             = 0x202,
                      NDMP_SCSI_RESET_DEVICE          = 0x204,
                      NDMP_SCSI_EXECUTE_CDB           = 0x206,
            
                      NDMP_TAPE_OPEN                  = 0x300,
                      NDMP_TAPE_CLOSE                 = 0x301,
                      NDMP_TAPE_GET_STATE             = 0x302,
                      NDMP_TAPE_MTIO                  = 0x303,
                      NDMP_TAPE_WRITE                 = 0x304,
                      NDMP_TAPE_READ                  = 0x305,
                      NDMP_TAPE_EXECUTE_CDB           = 0x307,
            
                      NDMP_DATA_GET_STATE             = 0x400,
                      NDMP_DATA_START_BACKUP          = 0x401,
                      NDMP_DATA_START_RECOVER         = 0x402,
                      NDMP_DATA_ABORT                 = 0x403,
                      NDMP_DATA_GET_ENV               = 0x404,
                      NDMP_DATA_STOP                  = 0x407,
                      NDMP_DATA_LISTEN                = 0x409,
                      NDMP_DATA_CONNECT               = 0x40A,
                      NDMP_DATA_START_RECOVER_FILEHIST = 0x40B,
            
                      NDMP_NOTIFY_DATA_HALTED         = 0x501,
                      NDMP_NOTIFY_CONNECTION_STATUS   = 0x502,
            
            
            
            Expires October 2003                                  [Page 214]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      NDMP_NOTIFY_MOVER_HALTED        = 0x503,
                      NDMP_NOTIFY_MOVER_PAUSED        = 0x504,
                      NDMP_NOTIFY_DATA_READ           = 0x505,
            
                      NDMP_LOG_FILE                   = 0x602,
                      NDMP_LOG_MESSAGE                = 0x603,
            
                      NDMP_FH_ADD_FILE                = 0x703,
                      NDMP_FH_ADD_DIR                 = 0x704,
                      NDMP_FH_ADD_NODE                = 0x705,
            
                      NDMP_MOVER_GET_STATE            = 0xA00,
                      NDMP_MOVER_LISTEN               = 0xA01,
                      NDMP_MOVER_CONTINUE             = 0xA02,
                      NDMP_MOVER_ABORT                = 0xA03,
                      NDMP_MOVER_STOP                 = 0xA04,
                      NDMP_MOVER_SET_WINDOW           = 0xA05,
                      NDMP_MOVER_READ                 = 0xA06,
                      NDMP_MOVER_CLOSE                = 0xA07,
                      NDMP_MOVER_SET_RECORD_SIZE      = 0xA08,
                      NDMP_MOVER_CONNECT              = 0xA09,
            
                      NDMP_EXT_STANDARD_BASE          = 0x10000,
            
                      NDMP_EXT_PROPRIETARY_BASE       = 0x20000000
                  };
            
                  struct ndmp_header
                  {
                      u_long                    sequence;
                      u_long                    time_stamp;
                      ndmp_header_message_type  message_type;
                      ndmp_message              message_code;
                      u_long                    reply_sequence;
                      ndmp_error                error_code;
                  };
            
                  struct ndmp_connect_open_request
                  {
                      u_short     protocol_version;
                  };
            
                  struct ndmp_connect_open_reply
                  {
                      ndmp_error  error;
                  };
            
                  enum ndmp_auth_type
                  {
                      NDMP_AUTH_NONE  = 0,
                      NDMP_AUTH_TEXT  = 1,
                      NDMP_AUTH_MD5   = 2
            
            
            
            Expires October 2003                                  [Page 215]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  };
            
                  struct ndmp_auth_text
                  {
                      string auth_id<>;
                      string auth_password<>;
                  };
            
                  struct ndmp_auth_md5
                  {
                      string   auth_id<>;
                      opaque   auth_digest[16];
                  };
            
                  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_attr
                      switch (enum ndmp_auth_type auth_type)
                  {
                      case NDMP_AUTH_NONE:
                          void;
                      case NDMP_AUTH_TEXT:
                          void;
                      case NDMP_AUTH_MD5:
                          opaque challenge[64];
                  };
            
                  struct ndmp_connect_client_auth_request
                  {
                      ndmp_auth_data   auth_data;
                  };
            
                  struct ndmp_connect_client_auth_reply
                  {
                      ndmp_error       error;
                  };
            
                  struct ndmp_connect_server_auth_request
                  {
                      ndmp_auth_attr   client_attr;
                  };
            
                  struct ndmp_connect_server_auth_reply
            
            
            
            Expires October 2003                                  [Page 216]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  {
                      ndmp_error            error;
                      ndmp_auth_data        server_result;
                  };
            
                  struct ndmp_config_get_host_info_reply
                  {
                      ndmp_error  error;
                      string      hostname<>;
                      string      os_type<>;
                      string      os_vers<>;
                      string      hostid<>;
                  };
            
                  struct ndmp_config_get_server_info_reply
                  {
                      ndmp_error        error;
                      string            vendor_name<>;
                      string            product_name<>;
                      string            revision_number<>;
                      ndmp_auth_type    auth_type<>;
                  };
            
                  enum ndmp_addr_type
                  {
                      NDMP_ADDR_LOCAL    = 0,
                      NDMP_ADDR_TCP      = 1,
                      NDMP_ADDR_RESERVED = 2,
                      NDMP_ADDR_IPC      = 3
                  };
            
                  struct ndmp_config_get_connection_type_reply
                  {
                      ndmp_error          error;
                      ndmp_addr_type      addr_types<>;
                  };
            
                  struct ndmp_config_get_auth_attr_request
                  {
                      ndmp_auth_type      auth_type;
                  };
            
                  struct ndmp_config_get_auth_attr_reply
                  {
                      ndmp_error          error;
                      ndmp_auth_attr      server_attr;
                  };
            
                  const NDMP_BUTYPE_BACKUP_FILELIST        = 0x0002;
                  const NDMP_BUTYPE_RECOVER_FILELIST       = 0x0004;
                  const NDMP_BUTYPE_BACKUP_DIRECT          = 0x0008;
                  const NDMP_BUTYPE_RECOVER_DIRECT         = 0x0010;
            
            
            
            Expires October 2003                                  [Page 217]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  const NDMP_BUTYPE_BACKUP_INCREMENTAL     = 0x0020;
                  const NDMP_BUTYPE_RECOVER_INCREMENTAL    = 0x0040;
                  const NDMP_BUTYPE_BACKUP_UTF8            = 0x0080;
                  const NDMP_BUTYPE_RECOVER_UTF8           = 0x0100;
                  const NDMP_BUTYPE_BACKUP_FH_FILE         = 0x0200;
                  const NDMP_BUTYPE_BACKUP_FH_DIR          = 0x0400;
                  const NDMP_BUTYPE_RECOVER_FILEHIST       = 0x0800;
                  const NDMP_BUTYPE_RECOVER_FH_FILE        = 0x1000;
                  const NDMP_BUTYPE_RECOVER_FH_DIR         = 0x2000;
            
                  struct ndmp_butype_info
                  {
                      string      butype_name<>;
                      ndmp_pval   default_env<>;
                      u_long      attrs;
                  };
            
                  struct ndmp_config_get_butype_attr_reply
                  {
                      ndmp_error            error;
                      ndmp_butype_info      butype_info<>;
                  };
            
                  const NDMP_FS_INFO_TOTAL_SIZE_UNS    = 0x00000001;
                  const NDMP_FS_INFO_USED_SIZE_UNS     = 0x00000002;
                  const NDMP_FS_INFO_AVAIL_SIZE_UNS    = 0x00000004;
                  const NDMP_FS_INFO_TOTAL_INODES_UNS  = 0x00000008;
                  const NDMP_FS_INFO_USED_INODES_UNS   = 0x00000010;
            
                  struct ndmp_fs_info
                  {
                      u_long            unsupported;
                      string            fs_type<>;
                      string            fs_logical_device<>;
                      string            fs_physical_device<>;
                      ndmp_u_quad       total_size;
                      ndmp_u_quad       used_size;
                      ndmp_u_quad       avail_size;
                      ndmp_u_quad       total_inodes;
                      ndmp_u_quad       used_inodes;
                      ndmp_pval         fs_env<>;
                      string            fs_status<>;
                  };
            
                  struct ndmp_config_get_fs_info_reply
                  {
                      ndmp_error        error;
                      ndmp_fs_info      fs_info<>;
                  };
            
                  const NDMP_TAPE_ATTR_REWIND = 0x00000001;
                  const NDMP_TAPE_ATTR_UNLOAD = 0x00000002;
            
            
            
            Expires October 2003                                  [Page 218]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  const NDMP_TAPE_ATTR_RAW    = 0x00000004;
            
                  struct ndmp_device_capability
                  {
                      string                  device<>;
                      u_long                  attr;
                      ndmp_pval               capability<>;
                  };
            
                  struct ndmp_device_info
                  {
                      string                  model<>;
                      ndmp_device_capability  caplist<>;
                  };
            
                  struct ndmp_config_get_tape_info_reply
                  {
                      ndmp_error              error;
                      ndmp_device_info        tape_info<>;
                  };
            
                  struct ndmp_config_get_scsi_info_reply
                  {
                      ndmp_error            error;
                      ndmp_device_info      scsi_info<>;
                  };
            
                  struct ndmp_class_list
                  {
                      u_short      ext_class_id;
                      u_short      ext_version<>;
                  };
            
                  struct ndmp_class_version
                  {
                      u_short      ext_class_id;
                      u_short      ext_version;
                  };
            
                  struct ndmp_config_get_ext_list_reply
                  {
                      ndmp_error         error;
                      ndmp_class_list    class_list<>;
                  };
            
                  struct ndmp_config_set_ext_list_request
                  {
                      ndmp_class_version    ndmp_selected_ext<>;
                  };
            
                  struct ndmp_config_set_ext_list_reply
                  {
            
            
            
            Expires October 2003                                  [Page 219]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      ndmp_error      error;
                  };
            
                  struct ndmp_scsi_open_request
                  {
                       string      device<>;
                  };
            
                  struct ndmp_scsi_open_reply
                  {
                      ndmp_error      error;
                  };
            
                  struct ndmp_scsi_close_reply
                  {
                      ndmp_error      error;
                  };
            
                  struct ndmp_scsi_get_state_reply
                  {
                      ndmp_error       error;
                      short            target_controller;
                      short            target_id;
                      short            target_lun;
                  };
            
                  struct ndmp_scsi_reset_device_reply
                  {
                      ndmp_error      error;
                  };
            
                  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<>;
                  };
            
            
            
            
            Expires October 2003                                  [Page 220]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  enum ndmp_tape_open_mode
                  {
                      NDMP_TAPE_READ_MODE = 0,
                      NDMP_TAPE_RDWR_MODE = 1,
                      NDMP_TAPE_RAW_MODE  = 2
                  };
            
                  struct ndmp_tape_open_request
                  {
                      string                   device<>;
                      ndmp_tape_open_mode      mode;
                  };
            
                  struct ndmp_tape_open_reply
                  {
                      ndmp_error      error;
                  };
            
                  struct ndmp_tape_close_reply
                  {
                      ndmp_error      error;
                  };
            
                  const NDMP_TAPE_STATE_NOREWIND         = 0x0008;
                  const NDMP_TAPE_STATE_WR_PROT          = 0x0010;
                  const NDMP_TAPE_STATE_ERROR            = 0x0020;
                  const NDMP_TAPE_STATE_UNLOAD           = 0x0040;
                  const NDMP_TAPE_STATE_FILE_NUM_UNS     = 0x00000001;
                  const NDMP_TAPE_STATE_SOFT_ERRORS_UNS  = 0x00000002;
                  const NDMP_TAPE_STATE_BLOCK_SIZE_UNS   = 0x00000004;
                  const NDMP_TAPE_STATE_BLOCKNO_UNS      = 0x00000008;
                  const NDMP_TAPE_STATE_TOTAL_SPACE_UNS  = 0x00000010;
                  const NDMP_TAPE_STATE_SPACE_REMAIN_UNS = 0x00000020;
                  const NDMP_TAPE_STATE_RESERVED1_UNS    = 0x00000040;
            
                  struct ndmp_tape_get_state_reply
                  {
                      u_long       unsupported;
                      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;
                  };
            
                  enum ndmp_tape_mtio_op
                  {
                      NDMP_MTIO_FSF  = 0,
                      NDMP_MTIO_BSF  = 1,
            
            
            
            Expires October 2003                                  [Page 221]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      NDMP_MTIO_FSR  = 2,
                      NDMP_MTIO_BSR  = 3,
                      NDMP_MTIO_REW  = 4,
                      NDMP_MTIO_EOF  = 5,
                      NDMP_MTIO_OFF  = 6,
                      NDMP_MTIO_TUR  = 7
                  };
            
                  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;
                  };
            
                  struct ndmp_tape_write_request
                  {
                      opaque              data_out<>;
                  };
            
                  struct ndmp_tape_write_reply
                  {
                      ndmp_error          error;
                      u_long              count;
                  };
            
            
                  struct ndmp_tape_read_request
                  {
                      u_long              count;
                  };
            
                  struct ndmp_tape_read_reply
                  {
                      ndmp_error          error;
                      opaque              data_in<>;
                  };
            
                  typedef ndmp_execute_cdb_request ndmp_tape_execute_cdb_request;
                  typedef ndmp_execute_cdb_reply ndmp_tape_execute_cdb_reply;
            
            
                  enum ndmp_data_operation
                  {
                      NDMP_DATA_OP_NOACTION           = 0,
                      NDMP_DATA_OP_BACKUP             = 1,
                      NDMP_DATA_OP_RECOVER            = 2,
            
            
            
            Expires October 2003                                  [Page 222]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      NDMP_DATA_OP_RECOVER_FILEHIST   = 3
            
                  };
            
                  enum ndmp_data_state
                  {
                      NDMP_DATA_STATE_IDLE      = 0,
                      NDMP_DATA_STATE_ACTIVE    = 1,
                      NDMP_DATA_STATE_HALTED    = 2,
                      NDMP_DATA_STATE_LISTEN    = 3,
                      NDMP_DATA_STATE_CONNECTED = 4
                  };
            
                  enum ndmp_data_halt_reason
                  {
                      NDMP_DATA_HALT_NA             = 0,
                      NDMP_DATA_HALT_SUCCESSFUL     = 1,
                      NDMP_DATA_HALT_ABORTED        = 2,
                      NDMP_DATA_HALT_INTERNAL_ERROR = 3,
                      NDMP_DATA_HALT_CONNECT_ERROR  = 4
                  };
            
                   struct ndmp_tcp_addr
                  {
                      u_long       ip_addr;
                      u_short      port;
                      ndmp_pval    addr_env<>;
                  };
            
                  struct ndmp_ipc_addr
                  {
                      opaque comm_data<>;
                  };
            
                  union ndmp_addr
                  switch (ndmp_addr_type addr_type)
                  {
                      case NDMP_ADDR_LOCAL:
                          void;
                      case NDMP_ADDR_TCP:
                          ndmp_tcp_addr  tcp_addr<>;
                      case NDMP_ADDR_IPC:
                          ndmp_ipc_addr  ipc_addr;
                  };
            
                  const NDMP_DATA_STATE_EST_BYTES_REMAIN_UNS = 0x00000001;
                  const NDMP_DATA_STATE_EST_TIME_REMAIN_UNS  = 0x00000002;
            
                  struct ndmp_data_get_state_reply
                  {
                      u_long                    unsupported;
                      ndmp_error                error;
            
            
            
            Expires October 2003                                  [Page 223]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      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_addr                 data_connection_addr;
                      ndmp_u_quad               read_offset;
                      ndmp_u_quad               read_length;
                  };
            
                  struct ndmp_data_listen_request
                  {
                      ndmp_addr_type   addr_type;
                  };
            
                  struct ndmp_data_listen_reply
                  {
                      ndmp_error   error;
                      ndmp_addr    connect_addr;
                  };
            
                  struct ndmp_data_connect_request
                  {
                      ndmp_addr   addr;
                  };
            
                  struct ndmp_data_connect_reply
                  {
                      ndmp_error   error;
                  };
            
                  struct ndmp_data_start_backup_request
                  {
                      string          butype_name<>;
                      ndmp_pval       env<>;
                  };
            
                  struct ndmp_data_start_backup_reply
                  {
                      ndmp_error     error;
                  };
            
                  struct ndmp_name
                  {
                      string       original_path<>;
                      string       destination_dir<>;
                      string       name<>;
                      string       other_name<>;
                      ndmp_u_quad  node;
                      ndmp_u_quad  fh_info;
                  };
            
            
            
            Expires October 2003                                  [Page 224]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            
                  struct ndmp_data_start_recover_request
                  {
                      ndmp_pval       env<>;
                      ndmp_name       nlist<>;
                      string          butype_name<>;
                  };
            
                  struct ndmp_data_start_recover_reply
                  {
                      ndmp_error      error;
                  };
            
                  struct ndmp_data_abort_reply
                  {
                      ndmp_error error;
                  };
            
                  struct ndmp_data_stop_reply
                  {
                      ndmp_error error;
                  };
            
                  struct ndmp_data_get_env_reply
                  {
                      ndmp_error  error;
                      ndmp_pval   env<>;
                  };
            
                  enum ndmp_mover_mode
                  {
                      NDMP_MOVER_MODE_READ            = 0,
                      NDMP_MOVER_MODE_WRITE           = 1,
                      NDMP_MOVER_MODE_NOACTION        = 2
                  };
            
                  enum ndmp_mover_state
                  {
                      NDMP_MOVER_STATE_IDLE    = 0,
                      NDMP_MOVER_STATE_LISTEN  = 1,
                      NDMP_MOVER_STATE_ACTIVE  = 2,
                      NDMP_MOVER_STATE_PAUSED  = 3,
                      NDMP_MOVER_STATE_HALTED  = 4
                  };
            
                  enum ndmp_mover_pause_reason
                  {
                      NDMP_MOVER_PAUSE_NA    = 0,
                      NDMP_MOVER_PAUSE_EOM   = 1,
                      NDMP_MOVER_PAUSE_EOF   = 2,
                      NDMP_MOVER_PAUSE_SEEK  = 3,
                      NDMP_MOVER_PAUSE_EOW  = 5
            
            
            
            Expires October 2003                                  [Page 225]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  };
            
                  enum ndmp_mover_halt_reason
                  {
                      NDMP_MOVER_HALT_NA             = 0,
                      NDMP_MOVER_HALT_CONNECT_CLOSED = 1,
                      NDMP_MOVER_HALT_ABORTED        = 2,
                      NDMP_MOVER_HALT_INTERNAL_ERROR = 3,
                      NDMP_MOVER_HALT_CONNECT_ERROR  = 4,
                      NDMP_MOVER_HALT_MEDIA_ERROR    = 5
                  };
            
                  struct ndmp_mover_set_record_size_request
                  {
                      u_long         len;
                  };
            
                  struct ndmp_mover_set_record_size_reply
                  {
                      ndmp_error     error;
                  };
            
                  struct ndmp_mover_set_window_request
                  {
                      ndmp_u_quad            offset;
                      ndmp_u_quad            length;
                  };
            
                  struct ndmp_mover_set_window_reply
                  {
                      ndmp_error             error;
                  };
            
                  struct ndmp_mover_connect_request
                  {
                      ndmp_mover_mode       mode;
                      ndmp_addr             addr;
                  };
            
                  struct ndmp_mover_connect_reply
                  {
                      ndmp_error            error;
                  };
            
                  struct ndmp_mover_listen_request
                  {
                      ndmp_mover_mode         mode;
                      ndmp_addr_type          addr_type;
                  };
            
                  struct ndmp_mover_listen_reply
                  {
            
            
            
            Expires October 2003                                  [Page 226]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      ndmp_error           error;
                      ndmp_addr            connect_addr;
                  };
            
                  struct ndmp_mover_read_request
                  {
                      ndmp_u_quad            offset;
                      ndmp_u_quad            length;
                  };
            
                  struct ndmp_mover_read_reply
                  {
                      ndmp_error            error;
                  };
            
                  struct ndmp_mover_get_state_reply
                  {
                      ndmp_error               error;
                      ndmp_mover_mode          mode;
                      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              bytes_moved;
                      ndmp_u_quad              seek_position;
                      ndmp_u_quad              bytes_left_to_read;
                      ndmp_u_quad              window_offset;
                      ndmp_u_quad              window_length;
                      ndmp_addr                data_connection_addr;
                  };
            
                  struct ndmp_mover_continue_reply
                  {
                  ndmp_error            error;
                  };
            
                  struct ndmp_mover_close_reply
                  {
                      ndmp_error            error;
                  };
            
                  struct ndmp_mover_abort_reply
                  {
                      ndmp_error            error;
                  };
            
                  struct ndmp_mover_stop_reply
                  {
                      ndmp_error            error;
                  };
            
            
            
            
            Expires October 2003                                  [Page 227]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  struct ndmp_notify_data_halted_post
                  {
                      ndmp_data_halt_reason   reason;
                  };
            
                  enum ndmp_connection_status_reason
                  {
                      NDMP_CONNECTED  = 0,
                      NDMP_SHUTDOWN   = 1,
                      NDMP_REFUSED    = 2
                  };
            
                  struct ndmp_notify_connection_status_post
                  {
                      ndmp_connection_status_reason       reason;
                      u_short                             protocol_version;
                      string                              text_reason<>;
                  };
            
                  struct ndmp_notify_mover_halted_post
                  {
                      ndmp_mover_halt_reason      reason;
                  };
            
                  struct ndmp_notify_mover_paused_post
                  {
                      ndmp_mover_pause_reason reason;
                      ndmp_u_quad             seek_position;
                  };
            
                  struct ndmp_notify_data_read_post
                  {
                      ndmp_u_quad  offset;
                      ndmp_u_quad  length;
                  };
            
                  enum ndmp_has_associated_message
                  {
                      NDMP_NO_ASSOCIATED_MESSAGE     = 0,
                      NDMP_HAS_ASSOCIATED_MESSAGE    = 1
                  };
            
                  enum ndmp_log_type
                  {
                      NDMP_LOG_NORMAL  = 0,
                      NDMP_LOG_DEBUG   = 1,
                      NDMP_LOG_ERROR   = 2,
                      NDMP_LOG_WARNING = 3
                  };
            
                  struct ndmp_log_message_post
                  {
            
            
            
            Expires October 2003                                  [Page 228]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      ndmp_log_type      log_type;
                      u_long             message_id;
                      string             entry<>;
                      ndmp_has_associated_message associated_message_valid;
                      u_long             associated_message_sequence;
                  };
            
                  enum ndmp_recovery_status
                  {
                      NDMP_RECOVERY_SUCCESSFUL                 = 0,
                      NDMP_RECOVERY_FAILED_PERMISSION          = 1,
                      NDMP_RECOVERY_FAILED_NOT_FOUND           = 2,
                      NDMP_RECOVERY_FAILED_NO_DIRECTORY        = 3,
                      NDMP_RECOVERY_FAILED_OUT_OF_MEMORY       = 4,
                      NDMP_RECOVERY_FAILED_IO_ERROR            = 5,
                      NDMP_RECOVERY_FAILED_UNDEFINED_ERROR     = 6,
                      NDMP_RECOVERY_FAILED_FILE_PATH_EXISTS    = 7
                  };
            
                  struct ndmp_log_file_post
                  {
                      string                   name<>;
                      ndmp_recovery_status     recovery_status;
                  };
            
                  enum ndmp_fs_type
                  {
                      NDMP_FS_UNIX   = 0,
                      NDMP_FS_NT     = 1,
                      NDMP_FS_OTHER  = 2
                  };
            
                  typedef string ndmp_path<>;
            
                  struct ndmp_nt_path
                  {
                      ndmp_path      nt_path;
                      ndmp_path      dos_path;
                  };
            
                  union ndmp_file_name
                  switch (ndmp_fs_type fs_type)
                  {
                      case NDMP_FS_UNIX:
                          ndmp_path      unix_name;
                      case NDMP_FS_NT:
                          ndmp_nt_path   nt_name;
                      default:
                          ndmp_path      other_name;
                  };
            
                  enum ndmp_file_type
            
            
            
            Expires October 2003                                  [Page 229]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  {
                      NDMP_FILE_DIR      = 0,
                      NDMP_FILE_FIFO     = 1,
                      NDMP_FILE_CSPEC    = 2,
                      NDMP_FILE_BSPEC    = 3,
                      NDMP_FILE_REG      = 4,
                      NDMP_FILE_SLINK    = 5,
                      NDMP_FILE_SOCK     = 6,
                      NDMP_FILE_REGISTRY = 7,
                      NDMP_FILE_OTHER    = 8
                  };
            
                  const NDMP_FILE_STAT_ATIME_UNS = 0x00000001;
                  const NDMP_FILE_STAT_CTIME_UNS = 0x00000002;
                  const NDMP_FILE_STAT_GROUP_UNS = 0x00000004;
            
                  struct ndmp_file_stat
                  {
                      u_long            unsupported;
                      ndmp_fs_type      fs_type;
                      ndmp_file_type    ftype;
                      u_long            mtime;
                      u_long            atime;
                      u_long            ctime;
                      u_long            owner;
                      u_long            group;
                      u_long            fattr;
                      ndmp_u_quad       size;
                      u_long            links;
                  };
            
                  struct ndmp_file
                  {
                      ndmp_file_name      name<>;
                      ndmp_file_stat      stat<>;
                      ndmp_u_quad         node;
                      ndmp_u_quad         fh_info;
                  };
            
                  struct ndmp_fh_add_file_post
                  {
                      ndmp_file            files<>;
                  };
            
                  struct ndmp_dir
                  {
                      ndmp_file_name    name<>;
                      ndmp_u_quad       node;
                      ndmp_u_quad       parent;
                  };
            
                  struct ndmp_fh_add_dir_post
            
            
            
            Expires October 2003                                  [Page 230]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  {
                      ndmp_dir dirs<>;
                  };
            
                  struct ndmp_node
                  {
                      ndmp_file_stat    stats<>;
                      ndmp_u_quad       node;
                      ndmp_u_quad       fh_info;
                  };
            
                  struct ndmp_fh_add_node_post
                  {
                      ndmp_node         nodes<>;
                  };
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 231]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            Appendix D: Workflow
               This appendix provides example procedures for backup, recovery, tape
               duplication and file system copy operations as well as error
               condition processing. These examples are not to be considered
               definitive or restrictive. Individual implementations may deviate
               from these examples as long as they remain in conformance with the
               core protocol specification.
            
               Message Sequence Numbers
            
               Each NDMP message includes a sequence number, this sequence number is
               verified for each message. If the sequence number is invalid, the
               server will return NDMP_SEQUENCE_NUM_ERR.
            
            D.1. Backup
               This section describes the control sequence and the data flow of a
               backup. It assumes that the tape drive to be used is attached to the
               host running the NDMP Tape Server and that the data to be backed up
               is on the host running NDMP Data Server.
            
                  (1) DMA will open a communication channel to the NDMP Tape
                     Server, negotiate the protocol version to be used, and
                     authenticate the session.
            
                  (2) Prepare the tape drive for backup
            
                     (a) The DMA will use the TAPE interface messages to instruct
                        the NDMP Tape Server to open, read and position the tape
                        drive in preparation for backup.
            
                      (i)  The DMA will send an NDMP_TAPE_OPEN message to the
                           NDMP Tape Server to instruct it to open a tape drive
                           for writing. The NDMP Tape Server SHALL, to extent
                           possible exclude other entities from accessing any
                           device opened by the DMA.
            
                      (ii) The DMA can optionally send an NDMP_TAPE_READ message
                           to validate any volume labels from the tape. If the
                           volume label is invalid or the tape cannot be used for
                           backup. Then the DMA can send an NDMP_TAPE_MTIO
                           message to rewind and eject the tape. The DMA can then
                           load a new tape (manually via an operator or by using
                           a tape library).
            
                      (iii) The DMA will instruct the NDMP Tape Server to properly
                           position the tape for writing the backup data. This
                           may include:
            
                              Rewinding and optionally writing a new tape label
                              and header files.
            
            
            
            
            
            Expires October 2003                                  [Page 232]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                              Forward spacing the tape and optionally reading the
                              last trailer file.
            
                      (iv) The DMA will send an NDMP_MOVER_SET_RECORD_SIZE
                           message to tell the NDMP Server with a tape drive what
                           record size to use when writing to the tape.
            
                  (3) Connection to the NDMP Data Server
            
                     (a) If the data is on the same host as the tape drive, then
                        the DMA is not required to open a second connection. In
                        this case, the following references to NDMP Data Server
                        can be replaced by NDMP Tape Server and the remainder of
                        this step (3) should be skipped.
            
                     (b) If the data to be backed up is on a different host than
                        the tape drive, then the DMA will open an NDMP connection
                        to the new host. The DMA will negotiate the version and
                        authenticate the session. This new host will be referred
                        to as the NDMP Data Server.
            
                  (4) The DMA will send NDMP_CONFIG_GET_BUTYPE_INFO message to
                     query the capability of NDMP Data Server. For example, is
                     file history is supported or not
            
                  (5) Get a mover address from the NDMP Tape Server
            
                     (a) The DMA will send an NDMP_CONFIG_GET_CONNECTION_TYPE
                        message to the NDMP Data Server and the NDMP Tape Server
                        to query the type of connections supported.
            
                     (b) The DMA can optionally use the NDMP Tape interface of the
                        NDMP Server to write header data followed by a file mark.
            
                     (c) The DMA will send an MOVER_SET_WINDOW to the NDMP Tape
                        Server.
            
                     (d) The DMA will choose the type of connection to be used
                        between the NDMP Data Server and the NDMP Tape Server and
                        include it in the NDMP_MOVER_LISTEN message.
            
                     (e) The DMA will send NDMP_MOVER_LISTEN message to the NDMP
                        Tape Server.
            
                     (f) The mover running on the NDMP Tape Server will create one
                        or more connection points and begin listening for a
                        connection. The NDMP Tape Server will return the
                        corresponding list of IP addresses to the DMA.
            
                     (g) THE DMA will send NDMP_DATA_CONNECT message to the NDMP
                        Data Server, with the list of IP addresses of the NDMP
                        Tape Server.
            
            
            
            Expires October 2003                                  [Page 233]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (h) The NDMP Data Server will attempt to open a data
                        connection to the mover on the NDMP Tape Server. If the
                        NDMP Data Server cannot connect to the mover, then it will
                        return an error and the DMA will send NDMP_MOVER_ABORT
                        message to the mover on the NDMP Server to tell it to stop
                        listening for a connection.
            
                  (6) The DMA will initiate a backup.
            
                     (a) The DMA will send an NDMP_DATA_START_BACKUP message to the
                        NDMP Data Server to begin the backup. This message will
                        include what should be backed up and what type of backup
                        to perform. The DMA may include parameters what will
                        modify the behavior of the backup. Parameters could be
                        dumplevel, compression etc.
            
                     (b) The NDMP Data Server will begin to generate data and send
                        it to the mover via the data connection
            
                     (c) The mover will buffer the data into tape records and write
                        the data to tape.
            
                  (7) As the backup is running, the DMA will be prepared to accept
                     various messages from the NDMP Data Server and the NDMP Tape
                     Server.
            
                     (a) As individual files are backed up, the NDMP Data Server
                        may send NDMP_FH_ADD_FILE or NDMP_FH_ADD_DIR and
                        NDMP_FH_ADD_NODE messages to the DMA. The NDMP_FH_ADD_FILE
                        for a file based backup and NDMP_FH_ADD_NODE and
                        NDMP_FH_ADD_DIR for a inode based backup.
            
                     (b) Both the NDMP Tape Server and the NDMP Data Server may
                        send NDMP_LOG_messages to the DMA to indicate progress.
            
                     (c) If an event occurs that requires attention, the NDMP Data
                        Server or NDMP Tape Server will use the NDMP Notify
                        Interface to let the DMA know that attention is required.
            
                  (8) Successful backup completion.
            
                     (a) After writing end-of-volume or end-of-backup information,
                        a DMA should take an affirmative step to ensure that such
                        data are flushed from the drive's internal buffer to tape.
                        Possible actions include writing a file mark or issuing a
                        rewind or unload command. The DMA should sense the
                        resultant error code or SCSI status and consider the tape
                        contents valid only if this operation succeeds.
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 234]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (b) On completion of successful backup the NDMP Data Server
                        will close the connection to the mover and then send an
                        NDMP_NOTIFY_DATA_HALTED message with
                        NDMP_DATA_HALT_SUCCESSFUL reason to the DMA.
            
                     (c) The DMA will issue an NDMP_DATA_GET_STATE and
                        NDMP_DATA_GET_ENV to the NDMP Data Server and save the
                        information returned for use during the recovery process.
                        Note, that the backup method initiated by the NDMP Data
                        Server is free to modify and/or add NDMP environment
                        variables
            
                     (d) The DMA will send an NDMP_DATA_STOP message to the NDMP
                        Data Server.
            
                     (e) Once the NDMP Data Server has released the resources, it
                        will return the status to the DMA.
            
                     (f) Since the mover on the NDMP Tape Server detects the
                        disconnection from the NDMP Data Server, it will null pad
                        the last tape record and then send an
                        NDMP_NOTIFY_MOVER_HALTED message with
                        NDMP_MOVER_CONNECTION_CLOSED reason to the DMA.
            
                     (g) The DMA will issue an NDMP_MOVER_GET_STATE message to the
                        NDMP Tape Server and note the total number of bytes moved.
            
                     (h) The DMA will send an NDMP_MOVER_STOP message to the NDMP
                        Tape Server.
            
                     (i) The DMA should use the NDMP Server with Tape Interface to
                        write a file mark to tape.
            
                     (j) The DMA can optionally use the NDMP Tape Server to write
                        trailer data and another file mark.
            
                  (9) If the DMA has more backup requests to process.
            
                     (a) If the data to be backed up is on another host, then the
                        DMA will send an NDMP_CONNECT_CLOSE message to close the
                        connection to the NDMP Data Server and then open a new
                        connection with the new NDMP Data Server.
            
                     (b) The DMA can optionally use the NDMP Tape Server to write
                        more header data and file marks.
            
                     (c) The DMA will get another mover address as in step 5.
            
                     (d) The DMA will initiate another backup as in step 6.
            
                  (10) If the DMA has no more backups to process
            
            
            
            
            Expires October 2003                                  [Page 235]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (a) The DMA will send an NDMP_CONNECT_CLOSE message to close
                        the connection to the NDMP Data Server, unless the NDMP
                        Data Server and NDMP Tape Server are running on the same
                        host.
            
                     (b) The DMA optionally use the NDMP Tape Server to rewind the
                        tape.
            
                     (c) The DMA may choose to use the NDMP Tape Sever to eject the
                        tape.
            
                     (d) The DMA will send an NDMP_TAPE_CLOSE message to close the
                        tape driver.
            
                     (e) The DMA will send NDMP_CONNECT_CLOSE message to close the
                        connection to the NDMP Tape Server.
            
            D.2. Data Recovery
               This section describes the data recovery process. It assumes that the
               data to be recovered is already in a tape drive.
            
                  (1) DMA will open a communication channel to the NDMP Tape
                     Server, negotiate the protocol version to be used and
                     authenticate the connection.
            
            
                  (2) Prepare the tape in the drive for recover.
            
                     (a) The DMA will use the Tape interface messages to instruct
                        the NDMP Tape Server to open, read and position the tape
                        drive in preparation for recover.
            
                      (i)  The DMA will send an NDMP_TAPE_OPEN message to the
                           NDMP Tape Server to instruct it to open a tape drive
                           for reading. The NDMP Tape Server SHALL, to extent
                           possible exclude other entities from accessing any
                           device opened by the DMA.
            
                      (ii) The DMA can optionally send an NDMP_TAPE_READ message
                           to validate any volume labels from the tape. If the
                           volume label is invalid then the DMA can send an
                           NDMP_TAPE_MTIO message to rewind and eject the tape.
                           The DMA can then load a new tape (manually via an
                           operator or by using a tape library).
            
                      (iii) The DMA can optionally position and validate any
                           header files surrounding the data that is to be
                           recovered. If the header is incorrect or cannot be
                           read, the DMA can rewind and eject the tape.
            
            
            
            
            
            
            Expires October 2003                                  [Page 236]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                      (iv) The DMA will use the NDMP Tape interface to position
                           past the file mark to the beginning of the backed up
                           data.
            
                  (3) Connection to the NDMP Data Server
            
                     (a) If the data is on the same host as the tape drive, then
                        the DMA is not required to open a second connection. In
                        this case, the following references to NDMP Data Server
                        can be replaced by NDMP Tape Server and the remainder of
                        this step (3) should be skipped.
            
                     (b) If the data to be recovered is on a different host than
                        the tape drive, then the DMA will open a second NDMP
                        connection to the new host. This new host will be referred
                        to as the NDMP Data Server.
            
                  (4) The DMA will send an NDMP_CONFIG_GET_BUTYPE_INFO message to
                     query the capability of the NDMP recover utility on the host
                     running the NDMP Data Server. For example, is individual file
                     recover supported or not?
            
                  (5) Begin recover process on the NDMP Data Server.
            
                     (a) The DMA will send an NDMP_CONFIG_GET_CONNECTION_TYPE
                        message to the NDMP Data Server and the NDMP Tape Server
                        to query the type of connections supported.
            
                     (b) The DMA will choose the type of connection to be used
                        between the NDMP Data Server and the NDMP Tape Server and
                        include it in the NDMP_DATA_LISTEN message.
            
                     (c) The DMA will send an NDMP_DATA_LISTEN message to the NDMP
                        Data Server. The NDMP Data Server will return the address
                        on which it will begin to listen.
            
                     (d) The DMA will send NDMP_MOVER_SET_RECORD_SIZE and
                        NDMP_MOVER_SET_WINDOW to the NDMP Tape Server.
            
                     (e) THE DMA will send NDMP_MOVER_CONNECT message to the NDMP
                        Tape Server, with the address of the NDMP Data Server
            
                     (f) The DMA will send an NDMP_DATA_START_RECOVER message to
                        the NDMP Data Server. The message will include a list of
                        NDMP environment variables, the list of files to be
                        recovered and the destination. If the recover involves a
                        remote NDMP Server, i.e. not a local retrieval. The NDMP
                        Data Server will send an NDMP_NOTIFY_DATA_READ message to
                        the DMA to initiate the recover. The DMA should send an
                        NDMP_MOVER_READ message to the NDMP Tape Server to inform
                        the mover to start sending the requested data.
            
            
            
            
            Expires October 2003                                  [Page 237]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (g) The DMA MUST be prepared to accept NDMP LOG messages.
            
                  (6) Reading the last tape record
            
                     (a) The mover will read the data until it reaches the end of
                        the mover window as specified in the previous
                        NDMP_MOVER_SET_WINDOW command. If there are extra pad
                        bytes contained in the last tape record that has been read
                        that are outside of the window then those bytes are
                        discarded. The mover will send a NDMP_NOTIFY_MOVER_PAUSED
                        post with the reason NDMP_MOVER_PAUSE_SEEK.
            
                        Notice that whenever the Mover transitions to the paused
                        state, the Mover must re-establish the mover window, do
                        any other operations (e.g. a tape positioning operation,
                        or loading a new tape in the driver, etc.) and issue a
                        NDMP_MOVER_CONTINUE to the NDMP Tape Server.
            
                  (7) Successful recover
            
                     (a) The NDMP Data Server will send an NDMP_LOG_FILE message to
                        report if the files are recovered.
            
                     (b) Once all of the files have been recovered, the NDMP Data
                        Server will change its status to NDMP_DATA_STATE_HALTED
                        and the reason to NDMP_DATA_HALT_SUCCESSFUL. It will close
                        the connection to the mover on the NDMP Tape Server and
                        send an NDMP_NOTIFY_DATA_HALTED message to the DMA.
            
                     (c) The DMA will send an NDMP_DATA_STOP message to the NDMP
                        Data Server.
            
                     (d) Once the resources have been released the NDMP Data Server
                        will return the status to the DMA.
            
                     (e) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
                        with an NDMP_MOVER_CONNECT_CLOSED reason from the NDMP
                        Tape Server
            
                     (f) The DMA will send an NDMP_MOVER_STOP message to the NDMP
                        Tape Server.
            
                     (g) If there are more recovers to be processed from the tape,
                        the DMA will position the tape as above.
            
                     (h) The DMA may close the tape device.
            
                     (i) The DMA will close the connection.
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 238]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
            D.2.1. Recovery Exceptions
            D.2.1.1. End-of-file
               If the DMA can support backups that span multiple tape files, then
               during a recover, it is possible to reach an end-of-file mark before
               all of the data to be recovered has been read. This section describes
               how that condition should be handled.
            
                  (1) Detect end-of-file
            
                     (a) The mover on the NDMP Tape Server detects an end-of-file
                        condition. This is normally detected by the tape drive and
                        returned as a partial read by the device driver.
            
                     (b) The mover processes the data that was actually read.
            
                     (c) The NDMP Tape Server changes the mover status to
                        NDMP_MOVER_STATE_PAUSED and the reason to
                        NDMP_MOVER_PAUSE_EOF and sends an NDMP_NOTIFY_MOVER_PAUSED
                        message with an NDMP_MOVER_PAUSE_EOF reason to the DMA.
            
                  (2) More tape files associated with the backup image:
            
                     (a) If the DMA needs to select another tape.
            
                      (i)  The DMA will use the NDMP Tape interface to rewind and
                           eject the tape.
            
                      (ii) The DMA will use the NDMP Tape interface to close the
                           tape drive and open another.
            
                      (iii) The DMA will use the NDMP Tape interface to verify the
                           volume label.
            
                     (b) The DMA will use the NDMP Tape interface to position to
                        the correct tape file.
            
                     (c) The DMA will use the NDMP Mover Interface to set the new
                        mover_window.
            
                     (d) The DMA will send an NDMP_MOVER_CONTINUE message to the
                        NDMP.
            
                     (e) The mover will continue reading data and sending it to the
                        NDMP Data Server.
            
                     (f) If a continuation tape cannot be located, then the DMA
                        will send an NDMP_DATA_ABORT message to the NDMP Data
                        Server and the recover will be aborted. The NDMP Data
                        Server will change state to halted and will send an
                        NDMP_NOTIFY_DATA_HALTED message to the DMA with an
                        NDMP_DATA_HALT_ABORTED reason. The NDMP Data Server will
                        close the data connection to the NDMP Tape Server.
            
            
            
            Expires October 2003                                  [Page 239]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (g) The DMA will send an NDMP_DATA_STOP message to return the
                        NDMP Data Server to an idle state.
            
                     (h) Once the resources have been released the NDMP Data Server
                        will return the status to the DMA.
            
                     (i) The NDMP Tape Server will detect the closed data
                        connection and change its mover state to
                        NDMP_MOVER_STATE_HALTED. The NDMP Tape Server will send an
                        NDMP_NOTIFY_MOVER_HALTED with an NDMP_MOVER_CONNECT_CLOSED
                        reason message to the DMA.
            
                     (j) The DMA will send an NDMP_MOVER_STOP message to the NDMP
                        Tape Server.
            
                  (3) No more tape file:
            
                     (a) The DMA will send an NDMP_MOVER_CLOSE message to the NDMP
                        Tape Server.
            
                     (b) The mover will close the connection to the NDMP Data
                        Server.
            
                     (c) The mover will change its mover state to
                        NDMP_MOVER_STATE_HALTED. The NDMP Tape Server will send an
                        NDMP_NOTIFY_MOVER_HALTED message with an
                        NDMP_MOVER_CONNECT_CLOSED reason message to the DMA.
            
                     (d) The NDMP Data Server will detect the end of data
                        connection and change state to halted and will send an
                        NDMP_NOTIFY_DATA_HALTED message to the DMA with an
                        NDMP_HALT_SUCCESSFUL reason if receive the expected data,
                        or an NDMP_HALT_CONNECT_ERROR reason if not receiving the
                        expected end of data.
            
                     (e) The NDMP Data Server will send NDMP_LOG_FILE message to
                        report if the files are recovered.
            
                     (f) The DMA will send an NDMP_DATA_STOP message to return the
                        NDMP Data Server to an idle state.
            
                     (g) Once the resources have been released the NDMP Data Server
                        will return the status to the DMA.
            
                     (h) The DMA will send an NDMP_MOVER_STOP message to the NDMP
                        Tape Server.
            
            D.2.1.2. Media error
               It is possible for the tape drive to detect a media error while
               reading.
            
                  (1) Detecting a media error
            
            
            
            Expires October 2003                                  [Page 240]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (a) The NDMP Tape Server somehow detects a media error. This
                        is usually detected by the tape drive and returned by the
                        device driver.
            
                     (b) The NDMP Tape Server will change its mover status to
                        NDMP_MOVER_STATE_HALTED and the halt_reason to
                        NDMP_MOVER_HALTED_MEDIA_ERROR. No further processing of
                        data will occur.
            
                     (c) The NDMP Tape Server will send an NDMP_NOTIFY_MOVER_HALTED
                        message with an NDMP_MOVER_HALTED_MEDIA_ERROR reason to
                        the DMA.
            
                     (d) The DMA will send an NDMP_DATA_ABORT message to the NDMP
                        Data Server. The NDMP Data Server will close the
                        connection to the mover on the NDMP Tape Server and will
                        change its state to NDMP_DATA_STATE_HALTED and the reason
                        to NDMP_DATA_HALT_ABORTED.
            
                     (e) The DMA will send an NDMP_DATA_STOP message to the NDMP
                        Data Server.
            
                     (f) Once the resources have been released the NDMP Data Server
                        will return the status to the DMA.
            
                     (g) The DMA will send an NDMP_MOVER_STOP message to the mover
                        on the NMDP sever.
            
                  (2) Handling the Media error
            
                     (a) The DMA host will use the NDMP Tape interface to rewind
                        and eject the tape.
            
                     (b) The DMA will close the tape device.
            
            D.2.1.3. User aborted
               It is possible for the user to abort a recovery operation that is in
               progress. This section describes how that is handled.
            
                  (1) Sending an abort.
            
                     (a) The DMA uses the NDMP Data Interface to send an
                        NDMP_DATA_ABORT message to the NDMP Data Server.
            
                     (b) The NDMP Data Server will change the data state to
                        NDMP_DATA_STATE_HALTED and the reason to
                        NDMP_DATA_HALT_ABORTED. No further data will be processed.
                        The connection to the mover on the NDMP Tape Server will
                        be closed.
            
            
            
            
            
            
            Expires October 2003                                  [Page 241]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (c) The NDMP Tape Server will send an NDMP_NOTIFY_MOVER_HALTED
                        message with an NDMP_MOVER_HALT_SUCCESSFUL reason to the
                        DMA.
            
                  (2) Handling the abort
            
                     (a) The DMA host will send an NDMP_DATA_STOP message to the
                        NDMP Data Server.
            
                     (b) When the NDMP Data Server has released all resources it
                        changes its state to NDMP_DATA_STATE_IDLE and returns the
                        status to the DMA.
            
                     (c) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
                        from the NDMP Tape Server with the reason set to
                        NDMP_MOVER_CONNECT_CLOSED.
            
                     (d) The DMA will send an NDMP_MOVER_STOP message to the NDMP
                        Tape Server.
            
                  (3) Continuing
            
                     (a) The DMA may or may not continue with the next recover
                        request.
            
               If there are no more requests, then the DMA will use the NDMP Tape
               interface to rewind and eject the tape. The DMA will then close the
               connection to the NDMP Tape Server.
            
            D.3 Direct Access Recovery
               The DMA may support a mechanism that allows the recover process to
               position directly to the correct tape record to perform a file
               recover more quickly. If the NDMP Tape Server detects that tape
               positioning is required within the mover window, then it can perform
               the tape positioning without using the DMA, but if the tape record is
               outside the mover window, then the DMA must be used to position the
               tape.
            
                  (1) If the data required for the recover is outside the current
                     tape file as defined by the mover window, then the NDMP Tape
                     Server changes the mover status to NDMP_MOVER_STATE_PAUSED
                     and the reason to NDMP_MOVER_PAUSE_SEEK and the seek offset
                     in the status is set to the desired offset. The NDMP Tape
                     Server sends an NDMP_NOTIFY_MOVER_PAUSED message with reason
                     to NDMP_MOVER_PAUSE_SEEK to the DMA.
            
                  (2) If required the DMA may rewind and eject the tape drive or it
                     may close the tape device and open another device.
            
                  (3) The DMA will position the tape to the correct tape file.
            
                  (4) The DMA will send an NDMP_MOVER_SET_WINDOW message.
            
            
            
            Expires October 2003                                  [Page 242]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  (5) The DMA will use the NDMP Tape interface to position to the
                     tape record that contains the desired offset.
            
                  (6) The DMA will then send an NDMP_MOVER_CONTINUE message to the
                     NDMP Tape Server.
            
                  (7) The NDMP Tape Server will use the current record number, the
                     record size and the mover window_offset to calculate how much
                     of the tape record should be skipped.
            
               The NDMP Tape Server will read the next tape record, skip the correct
               number of bytes and continue reading the data and passing it to the
               NDMP Data Server.
            
            D.4 Loss of Data Connection
               The loss of data connection can be detected from the NDMP Data Server
               or from the NDMP Tape Server.
            
                  (1) Detected from the NDMP Data Server:
            
                     (a) The NDMP Data Server gets an error while reading from the
                        data connection.
            
                     (b) The NDMP Data Server will change the data state to
                        NDMP_DATA_STATE_HALTED and the reason to
                        NDMP_DATA_HALT_CONNECT_ERROR. Unwritten data is discarded.
                        No further backup data or file history will be generated.
            
                     (c) The NDMP Data Server will close the connection to the
                        mover on NDMP Tape Server.
            
                     (d) The NDMP Data Server sends an NDMP_NOTIFY_DATA_HALTED
                        message to the DMA with a reason of
                        NDMP_DATA_HALT_CONNECT_ERROR.
            
                     (e) The DMA will send an NDMP_DATA_STOP message to the NDMP
                        Data Server.
            
                     (f) The DMA will send an NDMP_MOVER_ABORT message to the NDMP
                        Tape Server.
            
                     (g) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
                        from the NDMP Tape Server with the reason set to
                        NDMP_MOVER_CONNECTION_CLOSED or NDMP_MOVER_HALT_ABORTED
                        depending on the sequence to detect the disconnection from
                        the NDMP Data Server first or receive an NDMP_MOVER_ABORT
                        message.
            
                     (h) DMA will issue a NDMP_MOVER_STOP to the NDMP Tape Server.
            
                  (2) Detected from the NDMP Tape Server:
            
            
            
            
            Expires October 2003                                  [Page 243]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (a) The NDMP Tape Server gets an error while writing to the
                        data connection.
            
                     (b) The NDMP Tape Server sends an NDMP_NOTIFY_MOVER_HALTED
                        message with the reason set to
                        NDMP_MOVER_HALT_CONNECT_ERROR.
            
                     (c) The DMA will use the NDMP Data Interface to send an
                        NDMP_DATA_ABORT message to the NDMP Data Server.
            
                     (d) The NDMP Data Server will change the data state to
                        NDMP_DATA_STATE_HALTED and the reason to
                        NDMP_DATA_HALT_ABORTED. Unwritten data is discarded. No
                        further backup data or file history will be generated.
            
                     (e) The NDMP Data Server will close the connection to the
                        mover on NDMP Tape Server.
            
                     (f) The NDMP Data Server will send an NDMP_NOTIFY_DATA_HALTED
                        message with an NDMP_DATA_HALT_ABORTED reason to the DMA.
            
                     (g) The DMA will send an NDMP_DATA_STOP message to the NDMP
                        Data Server.
            
                     (h) Once the resources have been released the NDMP Data Server
                        will return the status to the DMA.
            
                     (i) The DMA will send an NDMP_MOVER_STOP message to the NDMP
                        Tape Server.
            
            D.5 Using a Jukebox
               A jukebox manager application could make a connection to the NDMP
               Server when it starts and close the connection when exiting. After
               the connection is established it could use the NDMP SCSI Interface to
               open the jukebox device. This device name refers to the device that
               controls the mechanics of the jukebox.
            
            D.5.1 Backing Up and Restoring Using a Jukebox
               In most ways the workflow described here is identical to the previous
               workflow with the exception of how tapes are loaded into the drive
               and unloaded from the drive.
            
                  (1) Loading a tape.
            
                     (a) The jukebox manager forms and sends SCSI cdbs to determine
                        if the jukebox inventory has changed.
            
                     (b) The jukebox manager will determine which tape to load into
                        what drive and form and send a SCSI MOVE MEDIUM cdb to
                        move the tape into the drive.
            
            
            
            
            
            Expires October 2003                                  [Page 244]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (c) The jukebox manager will open a connection to the NDMP
                        Server to which the tape drive is attached.
            
                     (d) The jukebox manager will repeatedly attempt to open the
                        NDMP Tape interface to verify that the tape actually
                        loaded and became ready.
            
                     (e) The jukebox manager will close the connection to the NDMP
                        Server to which the tape drive is connected.
            
                  (2) Unloading a Tape.
            
                     (a) The jukebox manager will form and send SCSI cdbs to
                        determine if the jukebox inventory has changed.
            
                     (b) The jukebox manager will cause the tape drive to unload.
            
                      (i)  The jukebox manager will open a connection to the NDMP
                           Server to which the tape drive is attached.
            
                      (ii) The jukebox manager will use the NDMP Tape interface
                           to open the tape drive.
            
                      (iii) The jukebox manager will use the NDMP Tape interface
                           to eject the tape drive.
            
                      (iv) The jukebox manager will use the NDMP Tape interface
                           to close the tape drive.
            
                      (v)  The jukebox manager will close the connection to the
                           NDMP Server to which the tape drive is attached.
            
                     (c) The jukebox manager will form and send a SCSI MOVE MEDIUM
                        cdb to move the tape from the tape drive to its original
                        location.
            
            D.5.2 Initializing a Jukebox
               When the jukebox manager first contacts the jukebox it will form and
               send SCSI cdbs to determine the type and geometry of the jukebox.
            
                  (1) The jukebox manager will form and send a SCSI INQUIRY cdb to
                     obtain the product id of the jukebox.
            
                  (2) The jukebox manager will form and send a SCSI MODE SENSE cdb
                     to determine the number and physical addresses of the slots,
                     drive and other elements of the jukebox.
            
                  (3) The jukebox manager will form and send a SCSI READ ELEMENT
                     STATUS cdb for each slot or drive to determine if the slot or
                     tape drive is empty, full or missing.
            
            
            
            
            
            Expires October 2003                                  [Page 245]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                  (4) The jukebox manager may form and send other SCSI cdbs
                     depending on the product id returned by the SCSI INQUIRY.
            
            D.5.3 Jukebox Exception Handling
                  If the jukebox manager detects that the jukebox inventory may
                  have changed it will form and send a SCSI READ ELEMENT STATUS cdb
                  for each slot or drive to determine if the slot or tape drive is
                  empty, full or missing.
            
                     If the data returned by the SCSI READ ELEMENT STATUS cdb
                     indicates that the jukebox is unsure of its physical
                     inventory, The jukebox manager will form and send a SCSI
                     INITIALIZE ELEMENT STATUS cdb to cause the jukebox to scan
                     its physical inventory.
            
                     If any SCSI cdb fails the jukebox manager may form and send
                     additional SCSI cdbs to correct the problem.
            
            D.6 Tape File Duplication
               Two Tape Servers can be connected together to copy the contents of a
               tape file.
            
               Note that NDMP does not guarantee tape file duplication to succeed.
               Nevertheless, NDMP provides a viable mechanism to do tape file
               duplication. The caveat here is the various exceptions that the DMAs
               need to take care of.
            
                  (1) DMA will open a communication channel to both NDMP Tape
                     Servers, negotiate the protocol version to be used and
                     authenticate the connections.
            
                  (2) Prepare the tapes in each drive for duplication.
            
                     (a) The DMA will send an NDMP_TAPE_OPEN message to each NDMP
                        Tape Server to instruct it to open a tape drive for
                        reading or writing depending upon which is the source and
                        destination. It may be prudent to write protect the source
                        tape to prevent accidental overwriting.
            
                     (b) The DMA will use the Tape interface messages to instruct
                        the NDMP Tape Servers to properly position the tapes for
                        reading/writing.
            
                     (c) The DMA will send an NDMP_MOVER_SET_RECORD_SIZE message to
                        each NDMP Tape Server to select the record size(s) to use
                        when reading/writing tape.
            
                  (3) Connect NDMP Tape Servers.
            
                     (a) The DMA will send an NDMP_CONFIG_GET_CONNECTION_TYPE
                        message to both of the NDMP Tape Servers to query the type
                        of connections supported.
            
            
            
            Expires October 2003                                  [Page 246]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (b) The DMA will issue an NDMP_SET_WINDOW_SIZE message to the
                        destination NDMP Tape Server.
            
                     (c) The DMA will choose the type of connection to be used
                        between the two NDMP Tape Servers and include it in the
                        NDMP_MOVER_LISTEN message.
            
                     (d) The DMA will send an NDMP_MOVER_LISTEN message to the
                        destination NDMP Tape Server.
            
                     (e) The DMA will send an NDMP_MOVER_CONNECT message to source
                        NDMP Tape Server.
            
                  (4) The DMA will initiate a tape file copy.
            
                     (a) The DMA will send an NDMP_MOVER_READ message to the source
                        NDMP Tape Server with the desired offset and maximum
                        length.
            
                     (b) The source NDMP Tape Server will begin to read data from
                        the tape drive and write it to the data connection.
            
                     (c) The destination NDMP Tape Server will buffer the data into
                        tape records and write the data to its tape drive.
            
                  (5) As the copy is proceeding, the DMA will be prepared to accept
                     various messages from either of the NDMP Tape Servers.
            
                     (a) Both NDMP Tape Servers may send NDMP LOG messages to the
                        DMA to indicate progress.
            
                     (b) If an event occurs that requires attention, either of the
                        NDMP Tape Servers will use an NDMP_NOTIFY_MOVER_PAUSED
                        message to let the DMA know that attention is required.
            
                  (6) Successful tape file duplication completion.
            
                     (a) On completion of a successful tape file copy the source
                        NDMP Tape Server will send a NDMP_NOTIFY_MOVER_PAUSED
                        message with NDMP_MOVER_PAUSE_EOM reason to the DMA.
            
                     (b) The DMA will issue a NDMP_MOVER_CLOSE message to the
                        source NDMP Server. Upon this, the NDMP Tape Server will
                        transition to the HALTED state and send a
                        NDMP_NOTIFY_MOVER_HALTED message to the DMA with the
                        halt_reason as: NDMP_MOVER_HALT_CONNECT_CLOSE.
            
                     (c) The DMA will send an NDMP_MOVER_STOP message to the source
                        NDMP Tape Server.
            
            
            
            
            
            
            Expires October 2003                                  [Page 247]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (d) Since the mover on the destination NDMP Tape Server
                        detects the disconnection from the source NDMP Tape
                        Server, destination NDMP Tape Server sends an
                        NDMP_NOTIFY_MOVER_HALTED message with
                        NDMP_MOVER_CONNECTION_CLOSED reason to the DMA.
            
                     (e) The DMA will issue an NDMP_MOVER_GET_STATE message to the
                        destination NDMP Tape Server and note the total number of
                        bytes generated.
            
                     (f) The DMA will send an NDMP_MOVER_STOP message to the
                        destination NDMP Tape Server.
            
                     (g) The DMA will send a NDMP_TAPE_MTIO message to write a file
                        mark to the destination NDMP Tape Server.
            
                     (h) The DMA will send a NMDP_TAPE_CLOSE message to both NDMP
                        Tape Servers.
            
               The DMA will send NDMP_CONNECT_CLOSE message to close the connection
               to both the NDMP Tape Servers.
            
            D.7 Network Copy
               Two Data Servers can be connected together to copy the contents of a
               file system.
            
                  (1) DMA will open a communication channel to both NDMP Data
                     Servers, negotiate the protocol version to be used, and
                     authenticate the connections.
            
                  (2) Connect NDMP Data Servers.
            
                     (a) The DMA will send an NDMP_CONFIG_GET_CONNECTION_TYPE
                        message to both of the NDMP Data Servers to query the type
                        of connections supported.
            
                     (b) The DMA will choose the type of connection to be used
                        between the two NDMP Data Servers and include it in the
                        NDMP_DATA_LISTEN message.
            
                     (c) The DMA will send an NDMP_DATA_LISTEN message to the
                        destination NDMP Data Server.
            
                     (d) The destination NDMP Data Server will create a connection
                        point and begin listening for a connection. If the
                        connection type specified by the DMA is TCP, the NDMP
                        Server will report all the interfaces that the source NDMP
                        Server can connect to, to the DMA.
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 248]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (e) The DMA will send an NDMP_DATA_CONNECT message to the
                        source NDMP Data Server. If the connection type is TCP,
                        the DMA will include all the interfaces, which the source
                        NDMP Server can use to create a data connection with the
                        destination NDMP Server.
            
                  (3) The DMA will initiate a Data copy.
            
                     (a) The DMA will send an NDMP_DATA_START_RECOVER message to
                        the destination NDMP Data Server with the desired list of
                        environment variables and destination path for the data to
                        be recovered into.
            
                     (b) The destination NDMP Server will send an
                        NDMP_NOTIFY_DATA_READ message to the DMA indicating that
                        it wants to read an unlimited data length starting at
                        offset 0.
            
                     (c) The DMA will send an NDMP_DATA_START_BACKUP message to the
                        source NDMP Data Server with the desired list of
                        environment variables and the path of the data source (in
                        this case, the path to the file system of the source that
                        intends to be copied).
            
                     (d) The source NDMP Data Server will begin to read data from
                        the disk and write it to the data connection.
            
                     (e) The destination NDMP Data Server will write the data to
                        the specified path.
            
                  (4) As the copy is proceeding, the DMA will be prepared to accept
                     various messages from either of the NDMP Data Servers.
            
                     (a) Both NDMP Data Servers may send NDMP LOG messages to the
                        DMA to indicate progress.
            
                  (5) Successful Data duplication completion.
            
                     (a) On completion of a successful Data copy the source NDMP
                        Data Server will close the data connection and then send
                        an NDMP_NOTIFY_DATA_HALTED message with the halt reason
                        indicating either success or failure to the DMA.
            
                     (b) The DMA will send an NDMP_DATA_STOP message to the source
                        NDMP Data Server.
            
                     (c) Since the destination NDMP Data Server detects the
                        disconnection from the source NDMP Data Server, the
                        destination NDMP Data Server sends an
                        NDMP_NOTIFY_DATA_HALTED message with
                        NDMP_DATA_CONNECTION_CLOSED reason to the DMA.
            
            
            
            
            Expires October 2003                                  [Page 249]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (d) The DMA will issue an NDMP_DATA_GET_STATE message to the
                        destination NDMP Data Server and note the total number of
                        bytes generated.
            
                     (e) The DMA will send an NDMP_DATA_STOP message to the
                        destination NDMP Data Server.
            
               If the DMA has no more data copy to process the DMA will send
               NDMP_CONNECT_CLOSE message to close the connection to both the NDMP
               Data Server.
            
            D.8 NDMP Exceptions
               The previous workflow assumes that there were no problems writing to
               tape and that everything fits on a single tape. In this section, some
               exceptions that can occur and how they are handled are examined.
            
            D.8.1 End-of-media
               If the amount of data to be backed up is greater that the space
               available on tape, then the mover on the NDMP Tape Server will detect
               an end-of-media (EOM) condition before the backup is completed. This
               section describes how the EOM should be handled.
            
                  (1) Detecting an end-of-media condition
            
                     (a) The mover on destination NDMP Tape Server detects that not
                        all of the data was successfully written to tape. This is
                        usually indicated as a partial write by the device driver
                        to the tape.
            
                     (b) The destination mover will update the amount of data
                        successfully written and will change its mover state to
                        NDMP_MOVER_STATE_PAUSED and the mover_pause_reason to
                        NDMP_MOVER_PAUSE_EOM. The unwritten data will be saved for
                        writing at a later time.
            
                     (c) The destination NDMP Tape Server will send an
                        NDMP_NOTIFY_MOVER_PAUSED message with an
                        NDMP_MOVER_PAUSE_EOM reason to the DMA.
            
                     (d) The DMA will query the NDMP Mover_state and will remember
                        the amount of data written to tape.
            
                  (2) If the user has specified that backups may not span multiple
                     tapes
            
                     (a) An NDMP_MOVER_ABORT message is sent to the source NDMP
                        Tape Server.
            
                     (b) The source NDMP Tape Server will discard any unwritten
                        data and close the connection to the mover on the
                        destination NDMP Tape Server.
            
            
            
            
            Expires October 2003                                  [Page 250]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (c) The source NDMP Tape Server will change the data status to
                        NDMP_MOVER_STATE_HALTED and the reason to
                        NDMP_MOVER_HALT_ABORTED and then send an
                        NDMP_NOTIFY_MOVER_HALTED message with an
                        NDMP_MOVER_HALT_ABORTED reason to the DMA.
            
                     (d) The DMA will send an NDMP_MOVER_STOP message to the source
                        NDMP Tape Server.
            
                     (e) Once the resources have been released the source NDMP Tape
                        Server will return the status to the DMA.
            
                     (f) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
                        with NDMP_MOVER_CONNECTION_CLOSED reason from the Mover on
                        the destination NDMP Tape Server.
            
                     (g) The DMA will send an NDMP_MOVER_STOP message to the
                        destination NDMP Tape Server.
            
                  (3) Unloading the tape
            
                     (a) The DMA will use the NDMP TAPE interface to attempt to
                        write a file mark on the tape.
            
                     (b) The DMA will use the NDMP TAPE interface to rewind and
                        eject the tape.
            
                     (c) The DMA will use the NDMP TAPE interface to close the tape
                        device.
            
                  (4) Loading a new volume
            
                     (a) The DMA will load another tape into a drive (manually or
                        using the jukebox)
            
                     (b) The DMA will use the NDMP TAPE interface to open the new
                        tape device.
            
                     (c) The DMA will use the NDMP TAPE interface to prepare the
                        tape for the backup data in the same fashion as in the
                        local backup.
            
                  (5) Continuing the backup
            
                     (a) If the backup is not allowed to span multiple tapes, then
                        the backup is restarted as in step 5 and 6 of the tape
                        duplication workflow.
            
                     (b) If the backup is not restarted, then the DMA will send an
                        NDMP_MOVER_CONTINUE message to the destination NDMP Tape
                        Server.
            
            
            
            
            Expires October 2003                                  [Page 251]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (c) The mover on the destination NDMP Tape Server will combine
                        the data that was not written to tape with new backup data
                        to create a full sized tape record.
            
                     (d) The full size record is written to tape.
            
                     (e) The backup continues.
            
            D.8.2 Media Errors
               Many tape drives have read-after-write capability and can detect
               write errors. This section describes how the media error should be
               handled.
            
                  (1) Detecting a media error
            
                     (a) The mover on the destination NDMP Tape Server somehow
                        detects a media error. This is usually detected by the
                        tape drive and returned by the device driver.
            
                     (b) The destination NDMP Tape Server will change its mover
                        state to NDMP_MOVER_STATE_HALTED and the reason to
                        NDMP_MOVER_HALTED_MEDIA_ERROR.
            
                     (c) The destination NDMP Tape Server will send an
                        NDMP_NOTIFY_MOVER_HALTED message to the DMA with an
                        NDMP_MOVER_HALTED_MEDIA_ERROR reason.
            
                     (d) The DMA will send an NDMP_MOVER_STOP message to the source
                        NDMP Tape Server.
            
                     (e) Once the resources have been released the source NDMP Tape
                        Server will return the status to the DMA.
            
                     (f) The DMA will send an NDMP_MOVER_ABORT message to the
                        destination NDMP Tape Server.
            
                     (g) The destination NDMP Tape Server will change its mover
                        state to NDMP_MOVER_STATE_HALTED and the reason to
                        NDMP_MOVER_HALT_ABORTED.
            
                     (h) The destination NDMP Tape Server will send an
                        NDMP_NOTIFY_MOVER_HALTED message to the DMA with an
                        NDMP_MOVER_HALT_ABORTED reason.
            
                     (i) The DMA will send an NDMP_MOVER_STOP message to the mover
                        on the destination NMDP Tape Server.
            
                  (2) Handling the Media error
            
                     (a) The DMA host will use the NDMP TAPE interface to rewind
                        and eject the tape without writing a file mark.
            
            
            
            
            Expires October 2003                                  [Page 252]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (b) The DMA will close the tape device.
            
                  (3) The DMA will load another volume as in the EOM workflow.
            
                  (4) Restarting the backup
            
                     (a) The DMA will use the NDMP_DATA_START_BACKUP to start the
                        backup over.
            
            D.8.3 User Aborted
               It is possible for the user to abort a backup in progress. This
               section describes how that is handled.
            
                  (1) Sending an abort.
            
                     (a) The DMA uses the NDMP Mover Interface to send an
                        NDMP_MOVER_ABORT message to the source NDMP Tape Server.
            
                     (b) The source NDMP Tape Server will change the mover state to
                        NDMP_MOVER_STATE_HALTED and the reason to
                        NDMP_MVOER_HALT_ABORTED. Unwritten data is discarded. No
                        further backup data or file history will be generated.
            
                     (c) The source NDMP Tape Server will close the connection to
                        the mover on the destination NDMP Tape Server.
            
                     (d) The source NDMP Tape Server will send an
                        NDMP_NOTIFY_MOVER_HALTED message with an
                        NDMP_MOVER_HALT_ABORTED reason to the DMA host.
            
                     (e) The DMA will send an NDMP_MOVER_STOP message to the source
                        NDMP Data Server.
            
                     (f) Once the resources have been released the source NDMP Tape
                        Server will return the status to the DMA.
            
                     (g) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
                        from the destination NDMP Tape Server with the reason set
                        to NDMP_MOVER_CONNECT_CLOSED.
            
                     (h) The DMA will send an NDMP_MOVER_STOP message to the
                        destination NDMP Tape Server.
            
                  (2) Handling the abort
            
                     (a) The DMA host will use the NDMP TAPE interface on the NDMP
                        Tape Server to write a file mark to tape.
            
                     (b) The DMA host will use the NDMP TAPE interface to write a
                        trailer record that indicates that the backup was not
                        complete, followed by a file mark.
            
            
            
            
            Expires October 2003                                  [Page 253]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (c) The file history collected by the DMA will be discarded.
            
                  (3) Continuing
            
                     (a) The DMA may or may not continue with the next backup
                        request.
            
                     (b) If there are no more requests, then the DMA will use the
                        NDMP TAPE interface to rewind and eject the tape. The DMA
                        will then send an NDMP_CONNECT_CLOSE message to the NDMP
                        Tape Server to close the connection.
            
            D.8.4 Loss of Data Connection
               The loss of data connection can be detected from the source NDMP Tape
               Server or from the destination NDMP Tape Server.
            
                  (1) Detected from the source NDMP Tape Server:
            
                     (a) The source NDMP Tape Server gets an error while writing to
                        the data connection.
            
                     (b) The source NDMP Tape Server will change the mover state to
                        NDMP_MOVER_STATE_HALTED and the reason to
                        NDMP_MOVER_HALT_CONNECT_ERROR. Unwritten data is
                        discarded. No further backup data or file history will be
                        generated.
            
                     (c) The source NDMP Tape Server will close the connection to
                        the mover on destination NDMP Tape Server.
            
                     (d) The source NDMP Tape Server sends an
                        NDMP_NOTIFY_MOVER_HALTED message to the DMA with a reason
                        of NDMP_MOVER_HALT_CONNECT_ERROR.
            
                     (e) The DMA will send an NDMP_MOVER_STOP message to the source
                        NDMP Tape Server.
            
                     (f) The DMA will send an NDMP_MOVER_ABORT message to the
                        destination NDMP Tape Server.
            
                     (g) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
                        from the destination NDMP Tape Server with the reason set
                        to NDMP_MOVER_CONNECT_CLOSED or NDMP_MOVER_HALT_ABORTED
                        depending on the sequence to detect the disconnection from
                        the source NDMP Tape Server first or receive an
                        NDMP_MOVER_ABORT message.
            
                     (h) The DMA will issue a NDMP_MOVER_STOP to the destination
                        NDMP Tape Server.
            
                  (2) Detected from the destination NDMP Tape Server:
            
            
            
            
            Expires October 2003                                  [Page 254]


            Draft Specification           NDMP Version 4 Protocol        April 2003
            
            
                     (a) The destination NDMP Tape Server gets an error while
                        reading from the data connection.
            
                     (b) The destination NDMP Tape Server sends an
                        NDMP_NOTIFY_MOVER_HALTED message with the reason set to
                        NDMP_MOVER_HALT_CONNECT_ERROR.
            
                     (c) The DMA will use the NDMP Mover Interface to send an
                        NDMP_MOVER_ABORT message to the source NDMP Tape Server.
            
                     (d) The source NDMP Tape Server will change the mover state to
                        NDMP_MOVER_STATE_HALTED and the reason to
                        NDMP_MOVER_HALT_ABORTED. Unwritten data is discarded. No
                        further backup data or file history will be generated.
            
                     (e) The source NDMP Tape Server will close the connection to
                        the mover on destination NDMP Tape Server.
            
                     (f) The source NDMP Tape Server will send an
                        NDMP_NOTIFY_MOVER_HALTED message with an
                        NDMP_MOVER_HALT_ABORTED reason to the DMA.
            
                     (g) The DMA will send an NDMP_MOVER_STOP message to the source
                        NDMP Tape Server.
            
                     (h) Once the resources have been released the source NDMP Tape
                        Server will return the status to the DMA.
            
                     (i) The DMA will send an NDMP_MOVER_STOP message to the
                        destination NDMP Tape Server.
            
            D.8.5 Broken Connection
               If the TCP/IP connection between the DMA and the NDMP Server is
               broken, the DMA will be responsible for recovery. However, the NDMP
               Server is expected to shutdown in a manner that allows the DMA to
               reconnect.
            
                  (1) NDMP Server detects a broken connection
            
                     (a) NDMP Server discards any unwritten data.
            
                     (b) NDMP Server closes the tape device.
            
                     (c) NDMP Server terminates.
            
            
            
            
            
            
            
            
            
            
            
            Expires October 2003                                  [Page 255]
            

Html markup produced by rfcmarkup 1.128b, available from https://tools.ietf.org/tools/rfcmarkup/