Draft Specification NDMP Version 4 Protocol February 2001
Network Working Group Harald Skardal,
INTERNET DRAFT Network Appliance,
Category: Applications James Bunnell,
Document: draft-skardal-ndmpv4-01.txt Spectra Logic,
Sudakar V. Chellam,
IBM,
Tim Gardner,
Chewcoba Systems,
Clive Hendrie,
Synaxia,
Kiyoshi Komatsu,
Network Appliance,
Greg Linn,
Network Appliance,
Dave Manley,
Network Appliance,
Gordon Waidhofer,
Traakan,
Jim Ward,
Workstation Solutions,
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 obsoleted by other documents at any
time. It is inappropriate to use Internet- Drafts as reference
material or to cite them other than as "work in progress."
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.
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.
Expires August 2001 [Page 1]
Draft Specification NDMP Version 4 Protocol February 2001
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.......................................................9
1.1. Motivation...................................................9
1.2. Scope........................................................9
1.3. Audience.....................................................9
1.4. Terminology..................................................9
1.5. Key Words...................................................12
2. Architecture..................................................13
2.1. Architectural Model.........................................13
2.2. NDMP Topologies.............................................13
2.2.1. Simple NDMP Configuration.................................14
2.2.2. NDMP Two Drive Configuration..............................15
2.2.3. Tape Library Configuration................................16
2.2.4. NDMP 3 Way Configuration..................................17
2.2.5. NDMP Data Replication Configurations......................17
2.3. Key NDMP Concepts...........................................20
2.3.1. Session State.............................................20
2.3.2. Control Streams...........................................21
2.3.3. Data Streams..............................................21
2.3.4. NDMP services:............................................22
2.3.4.1. Data Service............................................22
2.3.4.2. Tape Service............................................22
2.3.4.3. SCSI Pass Through Service...............................22
2.3.5. Other Mechanisms..........................................22
2.3.5.1. Mover Window............................................23
2.3.5.2. File History............................................24
2.3.5.3. Direct Access Recovery..................................24
2.4. Character and Role..........................................25
2.5. Protocol Interfaces.........................................26
2.5.1. Messages from DMA to NDMP Server..........................26
2.5.2. Messages from NDMP Server to DMA..........................27
2.5.3. Optional Interfaces and Messages..........................27
2.5.4 NDMP Server Extensions.....................................29
2.5.4.1 Proprietary vs. Official Extensions:.....................29
2.5.4.2 The Class................................................29
2.5.4.2.1 Class Versions:........................................30
2.5.4.2.2 Class Version vs. Core NDMP Version:...................30
Expires August 2001 [Page 2]
Draft Specification NDMP Version 4 Protocol February 2001
2.5.4.3 Discovery and Negotiation:...............................31
2.5.4.4 Extension Management.....................................31
2.5.4.4.1 The NDMP Class Space Allocation........................32
2.5.4.4.3 Extension Allocation and Management....................32
2.6. Messaging Protocol..........................................32
2.7. Message Header..............................................33
2.8. Error Reporting.............................................34
2.8.1 Error Codes In Core NDMP...................................35
2.8.2 Error Codes in NDMP Extensions.............................39
2.9. Message Numbers.............................................40
2.10. Message Definitions........................................42
2.11. Message Sequencing and State Tables........................43
2.11.1. General Rules............................................43
2.11.2. Connection...............................................44
2.11.3. Authentication...........................................45
2.11.4. SCSI and Tape Devices....................................45
2.11.5. Data State Diagram.......................................46
2.11.5.1. Example Race Condition.................................49
2.11.6. Mover State Table........................................50
2.12. Supporting XDR Definitions for NDMP........................54
3. NDMP Server Interfaces........................................63
3.1. Connect Interface...........................................63
3.1.1. NDMP_CONNECT_OPEN.........................................64
3.1.2. NDMP_CONNECT_CLIENT_AUTH..................................65
3.1.3. NDMP_CONNECT_CLOSE........................................67
3.1.4. NDMP_CONNECT_SERVER_AUTH..................................68
3.2. Config Interface............................................70
3.2.1. NDMP_CONFIG_GET_HOST_INFO.................................71
3.2.2. NDMP_CONFIG_GET_SERVER_INFO...............................72
3.2.4. NDMP_CONFIG_GET_AUTH_ATTR.................................74
3.2.5. NDMP_CONFIG_GET_BUTYPE_INFO...............................75
3.2.6. NDMP_CONFIG_GET_FS_INFO...................................79
3.2.7. NDMP_CONFIG_GET_TAPE_INFO.................................82
3.2.8. NDMP_CONFIG_GET_SCSI_INFO.................................84
3.2.9 NDMP_CONFIG_GET_EXT_LIST...................................85
3.2.10 NDMP_CONFIG_SET_EXT_LIST..................................86
3.3. SCSI Interface..............................................89
3.3.1. NDMP_SCSI_OPEN............................................90
3.3.2. NDMP_SCSI_CLOSE...........................................92
3.3.3. NDMP_SCSI_GET_STATE.......................................93
3.3.4. NDMP_SCSI_RESET_DEVICE....................................94
3.3.5. NDMP_SCSI_EXECUTE_CDB.....................................95
3.4. Tape Interface..............................................98
3.4.1. Tape Model................................................98
3.4.2. NDMP_TAPE_OPEN...........................................100
3.4.3. NDMP_TAPE_CLOSE..........................................102
3.4.4. NDMP_TAPE_GET_STATE......................................104
3.4.5. NDMP_TAPE_MTIO...........................................107
3.4.6. NDMP_TAPE_WRITE..........................................111
3.4.7. NDMP_TAPE_READ...........................................113
3.4.8. NDMP_TAPE_EXECUTE_CDB....................................116
3.5. Data Interface.............................................117
3.5.1. Data Interface Overview..................................117
3.5.3. Data Message Definitions.................................121
3.5.1. NDMP_DATA_CONNECT........................................122
Expires August 2001 [Page 3]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.2. NDMP_DATA_LISTEN.........................................124
3.5.3. NDMP_DATA_START_BACKUP...................................127
3.5.4. NDMP_DATA_START_RECOVER..................................130
3.5.5. NDMP_DATA_START_RECOVER_FILEHIST.........................136
3.5.5. NDMP_DATA_GET_STATE......................................140
3.5.6. NDMP_DATA_GET_ENV........................................141
3.5.7. NDMP_DATA_STOP...........................................143
3.5.8. NDMP_DATA_ABORT..........................................144
3.6. Mover Interface............................................145
3.6.1. Mover Interface Overview.................................145
3.6.3. Mover Message Definitions................................152
3.6.3.1. NDMP_MOVER_SET_RECORD_SIZE.............................153
3.6.3.2. NDMP_MOVER_SET_WINDOW..................................155
3.6.3.3. NDMP_MOVER_CONNECT.....................................158
3.6.3.4. NDMP_MOVER_LISTEN......................................161
3.6.3.5. NDMP_MOVER_READ........................................165
3.6.3.6. NDMP_MOVER_GET_STATE...................................168
3.6.3.7. NDMP_MOVER_CONTINUE....................................169
3.6.3.8. NDMP_MOVER_CLOSE.......................................171
3.6.3.9. NDMP_MOVER_ABORT.......................................172
3.6.3.10. NDMP_MOVER_STOP.......................................173
4. DMA Interfaces...............................................174
4.1. Notify Interface...........................................174
4.1.1. NDMP_NOTIFY_DATA_HALTED..................................175
4.1.2. NDMP_NOTIFY_CONNECTION_STATUS............................176
4.1.3. NDMP_NOTIFY_MOVER_HALTED.................................178
4.1.4. NDMP_NOTIFY_MOVER_PAUSED.................................179
4.1.5. NDMP_NOTIFY_DATA_READ....................................180
4.2. Log Interface..............................................181
4.2.1. NDMP_LOG_MESSAGE.........................................182
4.2.2. NDMP_LOG_FILE............................................184
4.3. File History Interface.....................................185
4.3.1. NDMP_FH_ADD_FILE.........................................186
4.3.2. NDMP_FH_ADD_DIR..........................................189
4.3.3. NDMP_FH_ADD_NODE.........................................191
5. References...................................................191
6. Security.....................................................192
7. Recognition of Prior Work....................................192
8. Authors and Contributors.....................................193
8.1. Document Editor............................................193
8.2. Authors' Addresses.........................................193
8.3. Contributors...............................................194
Appendixes:.....................................................196
Appendix A: MD5 Based Authentication:...........................196
Appendix B: NDMP Extension Management...........................197
Appendix C: NDMP Extensions Test Message........................199
Appendix D: XDR for an NDMP implementation......................202
D.Recover.......................................................228
D.End-of-file...................................................231
D.Media error...................................................233
D.User aborted..................................................234
D.Direct access recovers........................................235
D.Loss of data connection.......................................235
D.Backing up and restoring using a jukebox......................237
D.Initializing a jukebox........................................238
Expires August 2001 [Page 4]
Draft Specification NDMP Version 4 Protocol February 2001
D.Exception handling............................................238
D.Tape Duplication..............................................239
D.End-of-media..................................................241
D.Media errors..................................................243
D.User aborted..................................................244
D.Loss of data connection.......................................245
D.Network Copy..................................................246
D.Broken connection.............................................247
Expires August 2001 [Page 5]
Draft Specification NDMP Version 4 Protocol February 2001
Revision Log
[This revision log will be removed from the final draft. For now it
is used to keep track of what has been added.]
Doc Version Update Date and Change Log
---------------------------------------------------------------------
4.0.0 This document is based on NDMP version 2 and 3. See
www.ndmp.org for these documents.
4.0.1 00/11/05: Incorporated the following revisions of
sections:
1: SCSI Interface - James Bunnell
2: Mover Interface: Greg Linn
3: Tape Interface: Tim Gardner and Jim
Ward
4: Config Interface: Harald Skardal
5: Notify Interface, Dave Manley
6: File History Interface: Tim Gardner
7: General Issues: Clive Hendrie
4.0.2 11/12/00: Tim Gardner
Revised entire document to conform to RFC
2119 guidelines.
Fixed formatting of sections that was
inconsistent with the rest of the
document.
Fixed grammar and spelling errors.
Added missing content (primarily in the
tape interface section).
Modified content where inconsistent
terminology was used.
Removed or replaced embedded editorial
notes with appropriate text.
Changed message sections to start at the
top of a page.
4.0.3 00/11/15: Corrected many small formatting
nit's. Included Greg Linn's Status,
Abstract (with one small addition), and
Security section. Filled in company name
and email for authors and contributors.
4.0.4 01/01/21: Added terminology and
extensibility from December emails. Merged
the tape and fata copy into a replication
section with two cases: primary and
secondary storage replication.
Expires August 2001 [Page 6]
Draft Specification NDMP Version 4 Protocol February 2001
4.0.5 01/02/07: Merged in updates from SC, TG,
CH, GL, DM, HS, JW. Added "key concepts"
sections.
4.0.6 01/02/12: Added key concepts: mover
window, file history and direct access
restore. Included updates to SCSI config,
updates to mover and data (GL), new
version of workflow from SC, and new
appendix for extensibility test messages.
DM reorganized all structs, including the
XDR appendix. Modified document name,
authors, and updated header and footer.
Expires August 2001 [Page 7]
Draft Specification NDMP Version 4 Protocol February 2001
List of Future Work:
[This section will be removed in the final version of this draft.]
The following tasks are planned in the following version of this
draft:
Inter-dispersed C-code sections:
As has been done for the Mover Interface section, the C-code
structs in other sections will be interleaved with the text
explaining it's function.
Data interface:
The data interface has not yet been reviewed. The current
text is from NDMP version 3.
Workflow Document:
The NDMP workflow document [7] will be reworked into
describing a few common NDMP session creation scenarios, and
added to this document as an appendix.
NDMP Header file:
The C-code in this document, together with other key NDMP
data structures, will be collected into a "header file" which
will become an appendix to this document.
Key Concepts:
We will add a section for "key concepts" which explains
important NDMP architectural or functional elements including
"mover window", "direct access recovery", "file history" and
more.
Formatting issues:
This document is maintained and edited as a Microsoft Word
document, and then printed to a file using "generic text
printer". In this version of the draft there are still some
outstanding formatting issues such as un-aligned TOC,
incorrect printing of TAB characters, etc. These will be
resolved in follow on versions of the draft.
Introduction:
Add introductory section which gives and overview of the
structure and content of the main sections.
Expires August 2001 [Page 8]
Draft Specification NDMP Version 4 Protocol February 2001
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. Scope
This document is the specification for Network Data Management
Protocol version 4.
The primary focus of the protocol was to improve interoperability
between NDMP products by clarifying and removing ambiguity from
previous versions. In addition this version has support for server
extensions.
1.3. 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.4. 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 does not carry the payload data, the data is
transmitted over a separate connection using any protocol.
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.
Expires August 2001 [Page 9]
Draft Specification NDMP Version 4 Protocol February 2001
In NDMP versions 1, 2 and 3 the term "NDMP client" was used
instead of the 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.
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 a data/tape/SCSI service.
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 which stores live or "in production" data.
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 attaced 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.
Expires August 2001 [Page 10]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Replication data
The resulting data from a replication operation.
Control Connection
A bi-directional TCP/IP connection which 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 native network data connection in NDMP is a raw
TCP/IP socket connection.
Data stream
A unidirectional byte stream of data flowing over a data
connection between two peer NDMP Services in an NDMP session. 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, data to be
replicated, etc.
Data Service
A NDMP Service which transfers data between primary storage and
the Data Connection.
Tape Service
A NDMP Service which 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 which transfers data between the
secondary storage and the Data Connection.
SCSI Service
A NDMP Service which passes low level SCSI commands to a SCSI
device typically used by the DMA to manipulate a SCSI 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 August 2001 [Page 11]
Draft Specification NDMP Version 4 Protocol February 2001
1.5. 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 August 2001 [Page 12]
Draft Specification NDMP Version 4 Protocol February 2001
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 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 may implement it's own NDMP server and associated tape
service or may be connected through an external NDMP server. A tape
service is the source of data during recover operations and the data
destination 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 and is responsible for managing all session state
required to fully or partially recover a file system including server
topology, tape sets and numbering etc.
There is exactly one control connection between the DMA and each NDMP
server. The control connection is a bi-directional TCP/IP connection.
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
are used to control and monitor the state of each NDMP service and to
collect detailed information about the NDMP session, and the data
that is backed up.
2.2. NDMP Topologies
This section describes typical NDMP topologies and configurations in
terms of the relationship between Data Management Applications (DMAs)
and NDMP server which provide Data and Tape services.
Expires August 2001 [Page 13]
Draft Specification NDMP Version 4 Protocol February 2001
2.2.1. Simple NDMP Configuration
In the simplest configuration, a DMA will backup the data from the
NDMP server to a locally attached tape subsystem. The NDMP control
connection exists across the network boundary while 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 August 2001 [Page 14]
Draft Specification NDMP Version 4 Protocol February 2001
2.2.2. NDMP Two Drive Configuration
It is also possible to use NDMP to 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 while 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 August 2001 [Page 15]
Draft Specification NDMP Version 4 Protocol February 2001
2.2.3. Tape Library Configuration
NDMP can be used to backup data to a tape library that is physically
attached to the NDMP server. In this configuration, there is a
separate instance of the NDMP server to control the robotics within
the tape library.
+------------------------------+--------------------------------+
| DMA * NDMP Server |
| * |
| * |
| +-------------+ NDMP Control +------------+ |
| | NDMP Data | Connection | NDMP Data | |
| | Management | <------------------>| Service |---+ |
| | Application | * | | | |
| +-------------+ * +------------+ | |
| ^ * 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 August 2001 [Page 16]
Draft Specification NDMP Version 4 Protocol February 2001
2.2.4. NDMP 3 Way Configuration
It is possible to backup an NDMP server that supports NDMP but does
not have a locally attached backup device by sending the data through
a raw TCP/IP connection to another NDMP server. In this case the
NDMP data service exists on one server and the NDMP tape service on a
separate server. Both the NDMP control connections (to server 1 &
server 2) and the NDMP data connection (between server 1 & 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. Backing up NDMP host through the network to another NDMP
host
2.2.5. NDMP 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 August 2001 [Page 17]
Draft Specification NDMP Version 4 Protocol February 2001
In the tape replication case one tape service performs a recovery
operation while the other performs a backup operation allowing tape
data to be copied from one NDMP server to another NDMP server. Tape
to tape copy function could be used to duplicate 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 copy
Expires August 2001 [Page 18]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP also supports replication between two primary storage systems.
In this case one data service performs a backup operation while the
other performs a recovery operation on the same data stream. This
capability can be used to perform 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 copy
Expires August 2001 [Page 19]
Draft Specification NDMP Version 4 Protocol February 2001
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.
This leads to a three component architecture: We call the module that
interfaces to the volume or file system to be operated on as the
ååData ServiceÝÝ. We call the module that interfaces to a tape drive
the ååTape ServiceÝÝ. We call the application that uses NDMP to set up
and control the entire NDMP event the åådata management applicationÝÝ,
or DMA. Notice that the tape service is complemented with a separate
SCSI service in order to control a media changer.
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 responsible for capturing and managing all state
needed to provide the desired capabilities such as recover/restart-
ability of a halted session, or for 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 serviceÝs in order to define potential
restart points if a session fails, or 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.
Expires August 2001 [Page 20]
Draft Specification NDMP Version 4 Protocol February 2001
2.3.2. Control Streams
Between the DMA and every NDMP service is one and only one control
connection. The DMA uses control connections to manage each NDMP
service. These control connections are implemented as TCP/IP sockets.
Messages flow in both directions on a control connection. The DMA
sends messages to the NDMP service for the purpose of managing the
operations of the NDMP service. The NDMP service sends notifications
to the DMA, when the NDMP service requires the DMAÝs attention, or
file history information about the content of the data stream.
Note that this requirement: one and only one connection between the
DMA and each NDMP service is a change from previous versions of NDMP.
2.3.3. Data Streams
In the native or general case the transport for NDMP data streams is
TCP/IP over any IP supported network media. In NDMP we allow each
service to return multiple IP addresses to the DMA, addresses on
which where 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. which
would guarantee a maximum time for an NDMP session.
Fiber Channel SAN's 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.
Expires August 2001 [Page 21]
Draft Specification NDMP Version 4 Protocol February 2001
2.3.4. NDMP services:
The NDMP serviceÝs 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 CDROMÝs.
The NDMP serviceÝs are controlled by the DMA through a set of service
parameters. There are two types of service parameters, service
parameters which impact the NDMP protocol or state, and ååNDMP opaqueÝÝ
service parameters that only impact vendor specific state in a NDMP
service.
A new NDMP service is created by the DMA making a connection request
to port 10000. This creates a new NDMP service which connects back to
the DMA over a new port number. The NDMP service is transformed into
a data, tape or SCSI service by the following commands that the DMA
sends it.
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.
With the addition of extensibility a data service can interface to
implementation specific functionality such as the management of
snapshots.
The data service reads or writes one single data stream, for backup
or replication, 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, tape library or jukebox, 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.
Expires August 2001 [Page 22]
Draft Specification NDMP Version 4 Protocol February 2001
2.3.5.1. Mover Window
The Mover Window has different application during backup and
recovery. During backup, when writing data to tape, the DMA uses the
mover window mechanism to partition the single backup data set into
"mover window segments". During recovery, i.e. the reading of the
tape, the mover window is a navigational tool.
At backup time the mover window is used by the DMA to partition the
backup data into segments of known size. The data written inside the
mover window is backup data. For each segment the DMA will configure
a mover window of the size it wants to write to tape as one segment,
and then issue a "continue" message to the tape service. When the
configured amount of data has been written to tape, the mover will
stop and signal "end of mover window" to the DMA.
All mover windows segments will be appended an <eof> character.
Mover windows MUST NOT span tapes.
In addition to the backup data the DMA can add metadata to the data
stream written to tape. This metadata is application specific, it may
be used for navigation aid, or for adding session state information
to the tape.
Example 1:
Input data from data service:
01234567890123456789012345678901234567890123456789
dddddddddddddddddddddddddddddddddddddddddddddddddd
Output data with successive 10 byte mover windows, no metadata,
but with "end-of-file" marks:
012345678901234567890123456789012345678901234567890123
ddddddddddeddddddddddeddddddddddeddddddddddedddddddddd
Output data with successive 10 byte mover windows, including
<eof> and 3 bytes of metadata per mover window segment:
01234567890123456789012345678901234567890123456789012345....
ddddddddddemmmddddddddddemmmddddddddddemmmddddddddddemmm....
The DMA will typically record the start and end point of each segment
relative to the backup data stream, and also the location of the
segments on the tapes to be written. This information must be used
later when processing the data stream read from tape, for instance
for Direct Access Recovery. See a separate section.
Expires August 2001 [Page 23]
Draft Specification NDMP Version 4 Protocol February 2001
When reading the tape data, the mover window is used to navigate
across the tape data stream. The DMA will use the mover window,
together with the data set recorded during backup, to extract the
backup data from the tape stream, and to filter out and possibly
process the metadata that was added.
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 among others 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.
The two typical applications of the file history are a) to provide a
human readable user i/f to the backup data, and b) 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 data base, this enables users to locate which
backup has the file, when (before the backup time) was the file
modified, etc. 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.
Expires August 2001 [Page 24]
Draft Specification NDMP Version 4 Protocol February 2001
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 combining the segment and file addresses relative to the backup
data stream, the file address being computed by the data service, the
DMA can 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.
Notice that the mover window is essential in creating the tape data
format that can be accessed directly, and a powerful tool for
navigation in the recovery process.
2.4. Character and Role
An NDMP server provides three services: 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.
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
sends the file history information, if requested, back to the DMA.
For 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. The Data Server will work the same way when
writing the backup data to an unlimited size backup tape or reading
the backup data from that.
An NDMP Server providing a Tape Service is called a Tape Server. The
Tape Server either reads an NDMP data stream and writes it to tape or
reads from tape and writes to the NDMP data stream, depending upon
whether a backup or recovery is taking place. The Tape Server SHOULD
NOT be aware of the backup format, e.g. dump, tar and so on. 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 colocated with the Tape
Server. It passes SCSI control commands from the DMA to a SCSI device
that is usually a media autochanger device.
Expires August 2001 [Page 25]
Draft Specification NDMP Version 4 Protocol February 2001
2.5. Protocol Interfaces
NDMP messages are grouped together by functionality into several
interfaces. An NDMP server implementation is NOT REQUIRED to
implement all of the listed messages. See 2.4.3 for details of
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 is used after a client first establishes a
connection to an NDMP server. The CONNECT interface allows the
NDMP server to authenticate the client and negotiate the version
of protocol used.
CONFIG interface
This interface allows a DMA to discover the configuration of the
NDMP server. The CONFIG interface can be used to discover 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.4.4 for details on server
extensions.
SCSI interface
This interface is used to pass 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 will interpret
the returned status and data. The SCSI interface MAY also be
used to exploit special features of SCSI backup devices.
TAPE interface
This interface supports both 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 is used to initiate backup and recover operations.
The DMA provides all of 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.
Expires August 2001 [Page 26]
Draft Specification NDMP Version 4 Protocol February 2001
MOVER interface
This interface is used to control the reading/writing of backup
data from/to a tape device. During a backup the MOVER reads data
from the data connection, buffers the data into tape records, and
writes the data to the tape device. During a recover the MOVER
reads data from the tape device and writes the data to the data
connection. The MOVER is responsible for handling tape exceptions
and notifying the DMA.
2.5.2. Messages from NDMP Server to DMA
The NDMP server's implementation MAY send the following messages to
the DMA. All the messages that the DMA accepts are asynchronous.
None of these messages will generate a reply message.
NOTIFY interface
The NDMP server uses these messages to notify the DMA that
the NDMP server requires attention.
FILE HISTORY interface
These messages allow the NDMP server to make entries in the
file history catalog for the current backup. File history
information is used by the DMA track the files contained in
each backup and to select and locate files for recovery.
LOG interface
These messages allow 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.
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 will be 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, then 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.
As described in section 2.3 an NDMP server can provide three separate
services: the Data Service, the Tape Service and the SCSI Service.
The NDMP messages can be partitioned functionally into the following
four subsets:
Expires August 2001 [Page 27]
Draft Specification NDMP Version 4 Protocol February 2001
Core Messages
The core subset of NDMP requests applicable to all NDMP Servers
includes:
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, and
NDMP_CONFIG_GET_AUTH_ATTRIB.
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 a
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.
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.
Expires August 2001 [Page 28]
Draft Specification NDMP Version 4 Protocol February 2001
The CONFIG interface NDMP_CONFIG_GET_SCSI_INFO request.
2.5.4 NDMP Server Extensions
NDMP provides for a server extension mechanism; a standard
architecture that allows for 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,
DMA's 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. Official Extensions:
The architecture provides for two classes of extensions. These are
proprietary NDMP extensions and standardized NDMP extensions.
Proprietary extensions are used for exposing proprietary
functionality, they 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.
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".
Expires August 2001 [Page 29]
Draft Specification NDMP Version 4 Protocol February 2001
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 a conceptual 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.4.4.4)
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, it cannot be fixed without changing the
semantic definition of one or more messages or message replies in
the class.
- 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. No further requirements to core NDMP or the
extensions exist.
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.
Expires August 2001 [Page 30]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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:
i: The DMA requests the list of supported extensions in the
NDMP server by issuing the message NDMP_CONFIG_GET_EXT_LIST.
ii: The NDMP server replies with a list of all extensions,
standard and proprietary, that is supported and should be
exposed. (a)
iii: 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.
iv: The NDMP server acknowledges the selected extensions.
a - 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.
The requester (DMA) SHOULD discover and negotiate 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. Among others, this will ease
debugging.
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.
Expires August 2001 [Page 31]
Draft Specification NDMP Version 4 Protocol February 2001
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 X.
2.5.4.4.1 The NDMP Class Space Allocation
The class space is 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 three
separate ranges as follows:
Class = 0x0000: Core NDMP.
Class = 0x0001 - 0x0007: Standard NDMP extensions.
Class = 0x0008 - 0x1fff: Reserved.
Class = 0x2000 - 0xffef: Proprietary extensions.
Class = 0xfff0 - 0xfffe: Reserved for test use.
Class = 0xffff - 0xffff: Reserved.
Notice that a reserved area is allocated at the separation point
between official and proprietary extensions.
2.5.4.4.3 Extension Allocation and Management
The code space allocation and management for proprietary extensions
is described in Appendix X.
2.6. Messaging Protocol
The NDMP protocol 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.
The protocol 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 (message
header plus optional message body) 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 Record Marking and XDR
translation functionality.
Expires August 2001 [Page 32]
Draft Specification NDMP Version 4 Protocol February 2001
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 queue the requests and deal with them sequentially or
it may handle them asynchronously.
Since 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 may 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 messages all of which were malformed.
2.7. Message Header
A message header starts each message. The header is used to identify
the message and defines how to de-serialize the arguments and
dispatch the message. 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:
Expires August 2001 [Page 33]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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 to 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 has received and decoded 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 be prepared to handle any error codes
appearing in the error 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 SHOULD use the
ndmp_header error_code field to report NDMP_NOT_SUPPORTED_ERR. (See
section 2.6 for ndmp_header details.)
Expires August 2001 [Page 34]
Draft Specification NDMP Version 4 Protocol February 2001
Core NDMP has a set of error codes which is specified in section
2.7.1. These error messages 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 server. 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 and 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 August 2001 [Page 35]
Draft Specification NDMP Version 4 Protocol February 2001
enum ndmp_error {
NDMP_NO_ERR = 0, /* No error */
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 may 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 August 2001 [Page 36]
Draft Specification NDMP Version 4 Protocol February 2001
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.4.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. Firstly, it is used when an open/set target
request fails because the device is in use by an agent other
than this NDMP Server. Secondly, it is returned by TAPE
Interface commands 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
having a single tape or SCSI device opened at a time.
NDMP_NOT_AUTHORIZED_ERR
NDMP connection not yet authenticated. Prior to issuing most
requests, the NDMP connection MUST first be authenticated via
the 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 that was used to authenticate the connection does
not have the access permissions to execute this message.
NDMP_DEV_NOT_OPEN_ERR
Device not open. An attempt was made to access a device that
was not open.
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 August 2001 [Page 37]
Draft Specification NDMP Version 4 Protocol February 2001
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 open 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. It may be useful for diagnostic
error avoidance purposes to send a Log Message giving more
information about the operation that failed.
Expires August 2001 [Page 38]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_CONNECT_ERR
Data Server - Tape Server data connection establishment
failed.
NDMP_SEQUENCE_NUM_ERR
The 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 has been 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 specification is provided by the implementer. For
standard extensions the error codes are specified in the standard
extension specification.
Expires August 2001 [Page 39]
Draft Specification NDMP Version 4 Protocol February 2001
2.9. Message Numbers
The following messages are defined:
Expires August 2001 [Page 40]
Draft Specification NDMP Version 4 Protocol February 2001
enum ndmp_message {
/* CONNECT INTERFACE */
NDMP_CONNECT_OPEN = 0x900,
NDMP_CONNECT_CLIENT_AUTH = 0x901,
NDMP_CONNECT_CLOSE = 0x902,
NDMP_CONNECT_SERVER_AUTH = 0x903,
/* CONFIG INTERFACE */
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,
/* SCSI INTERFACE */
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,
/* TAPE INTERFACE */
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,
/* DATA INTERFACE */
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,
/* NOTIFY INTERFACE */
NDMP_NOTIFY_DATA_HALTED = 0x501,
NDMP_NOTIFY_CONNECTION_STATUS = 0x502,
Expires August 2001 [Page 41]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_NOTIFY_MOVER_HALTED = 0x503,
NDMP_NOTIFY_MOVER_PAUSED = 0x504,
NDMP_NOTIFY_DATA_READ = 0x505,
/* LOGGING INTERFACE */
NDMP_LOG_FILE = 0x602,
NDMP_LOG_MESSAGE = 0x603,
/* FILE HISTORY INTERFACE */
NDMP_FH_ADD_FILE = 0x703,
NDMP_FH_ADD_DIR = 0x704,
NDMP_FH_ADD_NODE = 0x705,
/* MOVER INTERFACE */
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,
/* EXTENSIBILITY */
/* Reserved for Standard extensions */
NDMP_EXT_STANDARD_BASE = 0x10000,
/* Reserved for Proprietary extensions */
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.
Expires August 2001 [Page 42]
Draft Specification NDMP Version 4 Protocol February 2001
struct message_name_request
{
type request_argument1;
...
type request_argumentN;
};
struct message_name_reply
{
enum ndmp_error error;
type reply_argument1;
...
type reply_argumentN;
};
Each XDR specification conforms to 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. Note that 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
describe the state of the NDMP Server. Some of these are simple
booleans. (For instance "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 then no state change is
made.
Expires August 2001 [Page 43]
Draft Specification NDMP Version 4 Protocol February 2001
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 be able to 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.10.5.1.
2.11.2. Connection
When an NDMP session first starts the DMA and Server MUST ensure that
they can communicate successfully.
The TCP/IP connection is initiated by the DMA which must know the
port on which the NDMP Server is listening. Port 10000 is reserved
for NDMP. NDMP servers SHOULD typically listen on port 10000.
However, to accommodate conflicts caused by another service already
using port 10000, 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. This 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 that MUST be the same as or lower than that specified by the
server in the NDMP_NOTIFY_CONNECTION_STATUS message. If the NDMP
Server accepts the NDMP_CONNECT_OPEN request then the specified
protocol version is used thenceforth by both the client and server
for all successive messages.
If the DMA wishes to use the same NDMP version as specified in the
original NDMP_NOTIFY_CONNECTION_STATUS message then 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.
Expires August 2001 [Page 44]
Draft Specification NDMP Version 4 Protocol February 2001
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. Since the client does not
support version 4, the client SHOULD send an NDMP_CONNECT_OPEN
request containing a version of 3. Since 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. Since 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 has finished 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 then 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. The following are the only requests that the DMA
MAY use prior to authentication:
NDMP_CONNECT_OPEN, NDMP_CONNECT_CLOSE, NDMP_CONNECT_SERVER_AUTH,
NDMP_CONFIG_GET_SERVER_INFO, NDMP_CONFIG_GET_AUTH_ATTR.
Since 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 is used to access 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.
Expires August 2001 [Page 45]
Draft Specification NDMP Version 4 Protocol February 2001
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 is used to prepare the tape for use by the MOVER
which writes/reads the actual backup data. In order that the two work
together there are a number rules about when requests may 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 may be issued except NDMP_TAPE_GET_STATE.
When the MOVER state is NDMP_MOVER_STATE_PAUSED, the TAPE
interface may be freely used. This may 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 (e.g. 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:
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 via
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 August 2001 [Page 46]
Draft Specification NDMP Version 4 Protocol February 2001
+----------------->-----------------+
| |
| 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
| V | |
| | 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 **
| ***************
| |
+------------<--------------+
Expires August 2001 [Page 47]
Draft Specification NDMP Version 4 Protocol February 2001
Figure 7 - Data state diagram
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 Active state upon establishment of connection
with the local or a 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 establishment of 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)
Once the data connection is established, the NDMP server is in
the Connected state.
- Transition to Active state upon receipt of an
NDMP_DATA_START_BACKUP message.
- Transition to Active state upon receipt of an
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
via the LOG interface and the backup/recover MUST continue.)
Expires August 2001 [Page 48]
Draft Specification NDMP Version 4 Protocol February 2001
- 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
either completed or been 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), then the NDMP Server will send an NDMP_NOTIFY_DATA_HALTED
and move into NDMP_DATA_STATE_HALTED state. The DMA may send an
NDMP_DATA_START_BACKUP request that crosses the halted notification.
In this case the NDMP_DATA_START_BACKUP request will be 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 August 2001 [Page 49]
Draft Specification NDMP Version 4 Protocol February 2001
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 (e.g. 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 via
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 August 2001 [Page 50]
Draft Specification NDMP Version 4 Protocol February 2001
+--------------->----------------+
| |
| 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 **
| ***************
| |
+------------<--------------+
NDMP_MOVER_CONTINUE
Expires August 2001 [Page 51]
Draft Specification NDMP Version 4 Protocol February 2001
Figure 8 - Mover state diagram
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 establishment of 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 establishment of 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.
Expires August 2001 [Page 52]
Draft Specification NDMP Version 4 Protocol February 2001
Halted State (NDMP_MOVER_STATE_HALTED)
The NDMP server enters Halted state after a backup/recover has
either completed or been aborted.
- 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 August 2001 [Page 53]
Draft Specification NDMP Version 4 Protocol February 2001
2.12. Supporting XDR Definitions for NDMP
This section defines the XDRs for the enums, constants and supporting
structures that messages in both 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 is list of enums and constants does not include the
ones already presented in section 2 so that there should be no
duplication.
Expires August 2001 [Page 54]
Draft Specification NDMP Version 4 Protocol February 2001
/* NDMP_CONNECT_CLIENT_AUTH */
enum ndmp_auth_type
{
NDMP_AUTH_NONE,
NDMP_AUTH_TEXT,
NDMP_AUTH_MD5
};
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,
NDMP_ADDR_TCP,
NDMP_ADDR_RESERVED,
NDMP_ADDR_IPC
};
/* backup type attributes */
const NDMP_BUTYPE_BACKUP_FILELIST = 0x0002;
const NDMP_BUTYPE_RECOVER_FILELIST = 0x0004;
Expires August 2001 [Page 55]
Draft Specification NDMP Version 4 Protocol February 2001
const NDMP_BUTYPE_BACKUP_DIRECT = 0x0008;
const NDMP_BUTYPE_RECOVER_DIRECT = 0x0010;
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;
};
/* unsupported bits for ndmp_fs_info struct*/
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<>;
};
/* tape attributes */
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<>;
};
Expires August 2001 [Page 56]
Draft Specification NDMP Version 4 Protocol February 2001
struct ndmp_device_info
{
string model<>;
ndmp_device_capability caplist<>;
};
struct ndmp_pval
{
string name<>;
string value<>;
};
struct ndmp_device_capability
{
string device <>;
u_long attr;
ndmp_pval capability <>;
};
struct ndmp_device_info
{
string model <>;
ndmp_device_capability caplist <>;
};
struct ndmp_class_list
{
u_short class_id;
u_short version<>;
};
struct ndmp_class_version
{
u_short class_id;
u_short version;
};
const NDMP_SCSI_DATA_IN = 0x00000001;
const NDMP_SCSI_DATA_OUT = 0x00000002;
enum ndmp_tape_open_mode
{
NDMP_TAPE_READ_MODE,
NDMP_TAPE_RDWR_MODE,
NDMP_TAPE_RAW_MODE
};
/* generic unsigned 64-bit value */
struct ndmp_u_quad
{
u_long high;
Expires August 2001 [Page 57]
Draft Specification NDMP Version 4 Protocol February 2001
u_long low;
};
/* flags */
const NDMP_TAPE_STATE_NOREWIND = 0x0008; /* non-rewind device */
const NDMP_TAPE_STATE_WR_PROT = 0x0010; /* write-protected */
const NDMP_TAPE_STATE_ERROR = 0x0020; /* media error */
const NDMP_TAPE_STATE_UNLOAD = 0x0040; /* tape unloaded upon
close */
/* unsupported bits */
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;
enum ndmp_tape_mtio_op
{
NDMP_MTIO_FSF,
NDMP_MTIO_BSF,
NDMP_MTIO_FSR,
NDMP_MTIO_BSR,
NDMP_MTIO_REW,
NDMP_MTIO_EOF,
NDMP_MTIO_OFF,
NDMP_MTIO_TUR
};
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,
Expires August 2001 [Page 58]
Draft Specification NDMP Version 4 Protocol February 2001
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;
};
/* unsupported bitmask bits */
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_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
Expires August 2001 [Page 59]
Draft Specification NDMP Version 4 Protocol February 2001
};
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
};
enum ndmp_fs_type
{
NDMP_FS_UNIX,
NDMP_FS_NT,
NDMP_FS_OTHER
};
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;
};
Expires August 2001 [Page 60]
Draft Specification NDMP Version 4 Protocol February 2001
/* file type */
enum ndmp_file_type
{
NDMP_FILE_DIR,
NDMP_FILE_FIFO,
NDMP_FILE_CSPEC,
NDMP_FILE_BSPEC,
NDMP_FILE_REG,
NDMP_FILE_SLINK,
NDMP_FILE_SOCK,
NDMP_FILE_REGISTRY,
NDMP_FILE_OTHER
};
/* file stat */
/* unsupported bitmask */
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_dir
{
ndmp_file_name name<>;
ndmp_u_quad node;
ndmp_u_quad parent;
};
struct ndmp_node
{
Expires August 2001 [Page 61]
Draft Specification NDMP Version 4 Protocol February 2001
ndmp_file_stat stats<>;
ndmp_u_quad node;
ndmp_u_quad fh_info;
};
Expires August 2001 [Page 62]
Draft Specification NDMP Version 4 Protocol February 2001
3. NDMP Server Interfaces
This section defines the protocol interfaces implemented by the NDMP
server.
3.1. Connect Interface
This interface is used to authenticate the client and negotiate the
version of protocol that will 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.
Expires August 2001 [Page 63]
Draft Specification NDMP Version 4 Protocol February 2001
3.1.1. NDMP_CONNECT_OPEN
This message is used to negotiate the protocol version to be used
between the DMA and 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. Once the protocol version has
been successfully negotiated, it remains until the end of the NDMP
session. It is illegal to send this message once any other type of
message has been sent.
Message XDR definition
/* NDMP_CONNECT_OPEN */
struct ndmp_connect_open_request
{
u_short protocol_version;
};
struct ndmp_connect_open_reply
{
ndmp_error error;
};
Request Arguments
protocol_version
Protocol version suggested by the 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 lower
protocol version number.
NDMP_NOT_SUPPORTED_ERR
The request is not supported for this implementation.
NDMP_ILLEGAL_STATE_ERR
The protocol has already been negotiated.
Expires August 2001 [Page 64]
Draft Specification NDMP Version 4 Protocol February 2001
3.1.2. NDMP_CONNECT_CLIENT_AUTH
This message is used to authenticate the DMA to the NDMP server. Only
some of the request messages within the CONFIG and CON- NECT
interfaces may be processed on a connection that has not yet been
authenticated. A reply message containing an NDMP_NOT_AUTHORIZED_ERR
error will be returned in response to any other request messages
received when the connection has not yet been authenticated.
NDMP servers MUST support at least one of the following
authentication methods.
NONE
No authentication required.
TEXT
Connection is authenticated using an auth id and clear text
password.
MD5
Connection is authenticated using an MD5 algorithm.
The MD5 method uses the MD5 message digest algorithm described in
RFC1321 to authenticate the client and/or the server using a
shared secret (password). The message used to compute the MD5
digest is a concatenation of the password, null padding, the 64
byte fixed length challenge and a repeat of the password. The
length of the null padding is chosen to result in a 128 byte
fixed length message. The length of the padding can be computed
as 64 - 2*(length of the password). The client digest is computed
using the server challenge from the NDMP_CONFIG_GET_AUTH_ATTR
reply.
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
Authentication data. NDMP servers MUST support at least one
of the following authentication methods:
Expires August 2001 [Page 65]
Draft Specification NDMP Version 4 Protocol February 2001
NONE
No authentication required.
TEXT
Connection is authenticated using an auth id and
nonencrypted password.
MD5
Connection is authenticated using auth id and MD5 digest
of the server challenge and the client password.
Reply Arguments
error
Error code.
Reply Errors
NDMP_NO_ERR
Connection successfully authenticated.
NDMP_NOT_AUTHORIZED_ERR
Incorrect authentication data.
NDMP_NOT_SUPPORTED_ERR
The request sequence is not supported for this
implementation.
NDMP_ILLEGAL_ARGS_ERR
Specified authentication method not supported.
Expires August 2001 [Page 66]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_CONNECT_CLOSE */
/* no request arguments */
/* no reply message */
Expires August 2001 [Page 67]
Draft Specification NDMP Version 4 Protocol February 2001
3.1.4. NDMP_CONNECT_SERVER_AUTH
This message is used to authenticate the NDMP server to the DMA. This
request message is OPTIONAL and MUST only be processed after the
server has authenticated the DMA.
The same client authentication methods are supported for the server
authentication. Please refer to section 3.1.2 for usage of the
authentication methods. If the NDMP_AUTH_MD5 authentication method is
applied, the server digest is computed using the client challenge
from the request.
Message XDR definition
/* NDMP_CONNECT_SERVER_AUTH */
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
The following attribute is defined:
challenge
For NDMP_AUTH_MD5 the DMA will include a per session
challenge.
Reply Arguments
error
Error code.
server_result
Authentication result. NDMP servers may return information to
the DMA to authenticate the server to the client.
NONE
No authentication returned.
TEXT
Connection is authenticated using an auth id and clear
text password. The auth id and password authenticate the
auth id on DMA host.
Expires August 2001 [Page 68]
Draft Specification NDMP Version 4 Protocol February 2001
MD5
Connection is authenticated using user name and MD5 digest
of the challenge and the user password.
Reply Errors
NDMP_NO_ERR
Connection successfully authenticated.
NDMP_NOT_SUPPORTED_ERR
Request not supported.
NDMP_ILLEGAL_ARGS_ERR
Specified authentication method not supported.
Expires August 2001 [Page 69]
Draft Specification NDMP Version 4 Protocol February 2001
3.2. Config Interface
This interface allows the DMA to discover the configuration of the
NDMP server.
Expires August 2001 [Page 70]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_CONFIG_GET_HOST_INFO */
/* no request arguments */
struct ndmp_config_get_host_info_reply
{
ndmp_error error;
string hostname<>;
string os_type<>;
string os_vers<>;
string hostid<>;
};
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.
Expires August 2001 [Page 71]
Draft Specification NDMP Version 4 Protocol February 2001
3.2.2. NDMP_CONFIG_GET_SERVER_INFO
This request is used to get information about the NDMP server
implementation.
Message XDR definition
/* NDMP_CONFIG_GET_SERVER_INFO */
/* 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.
product_name
The product name of the NDMP server provided by the vendor.
revision_number
The revision number of the NDMP server.
auth_types
Connection authentication types supported by the NDMP server.
Reply Errors
NDMP_NO_ERR
Request successfully processed.
NDMP_NOT_SUPPORTED_ERR
The request is not supported for this implementation.
3.2.3. NDMP_CONFIG_GET_CONNECTION_TYPE
This request returns a list of the data connection types supported by
the NDMP server.
Expires August 2001 [Page 72]
Draft Specification NDMP Version 4 Protocol February 2001
Message XDR definition
/* NDMP_CONFIG_GET_CONNECTION_TYPE */
/* 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 August 2001 [Page 73]
Draft Specification NDMP Version 4 Protocol February 2001
3.2.4. NDMP_CONFIG_GET_AUTH_ATTR
This message is used to query the attributes of the supported
authentication methods. If the connection will be authenticated using
the MD5 method, the client MUST use this message to get the server
challenge before sending the NDMP_CONNECT_CLIENT_AUTH message.
Message XDR definition
/* NDMP_CONFIG_GET_AUTH_ATTR */
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 a per
session challenge. See appendix A for an outline of the
client authentication process.
Reply Errors
NDMP_NO_ERR
Returned the specific authentication type attributes
successfully.
NDMP_NOT_SUPPORTED_ERR
The request is not supported for this implementation.
NDMP_ILLEGAL_ARGS_ERR
Specified authentication method not supported.
Expires August 2001 [Page 74]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_CONFIG_GET_BUTYPE_INFO */
/* 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 August 2001 [Page 75]
Draft Specification NDMP Version 4 Protocol February 2001
Variable Meaning Value Default Value
---------------------------------------------------------------
DIRECT Utilize direct access y/n n
retrieval.
PREFIX Prefix path for path name (No default value)
the request.
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
n = no history
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
-----------------------------------------------------------------
FILESYSTEM device or file file system or (No default
system name to device name, value)
be backed up (*) e.g.
/dev/rsd0a
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
* - 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.
The following are examples of environment variables that can be
defined by tar type and the corresponding default values.
Expires August 2001 [Page 76]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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 (a full
recovery MUST be done before an incremental recovery).
NDMP_BUTYPE_BACKUP_UTF8
The backup type supports UTF8 format in the file history.
Expires August 2001 [Page 77]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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.
Expires August 2001 [Page 78]
Draft Specification NDMP Version 4 Protocol February 2001
3.2.6. NDMP_CONFIG_GET_FS_INFO
This message is used to query information about the file systems on
the NDMP server host.
Message XDR definition
/* NDMP_CONFIG_GET_FS_INFO */
/* 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 bitmask 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_INVALID is set if this argument is
not supported.
used_size
The used size of the file system in bytes.
NDMP_FS_INFO_USED_SIZE_INVALID is set if this argument is
not supported.
Expires August 2001 [Page 79]
Draft Specification NDMP Version 4 Protocol February 2001
avail_size
The available size of the file system in bytes.
NDMP_FS_INFO_AVAIL_SIZE_INVALID is set if this argument is
not supported.
total_inodes
The total number of inodes within the file system.
NDMP_FS_INFO_TOTAL_INODES_INVALID 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_INVALID 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 August 2001 [Page 80]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Expires August 2001 [Page 81]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_CONFIG_GET_TAPE_INFO */
/* 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.
Expires August 2001 [Page 82]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_TAPE_ATTR_RAW
The device supports raw mode open.
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
----------------------------------------------------------------
COMPRESSION Compression ratio integer 1 (no compression)
Reply Errors
NDMP_NO_ERR
Tape information successfully returned.
NDMP_NOT_SUPPORTED_ERR
The request is not supported for this implementation.
Expires August 2001 [Page 83]
Draft Specification NDMP Version 4 Protocol February 2001
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 RECOMMENDED naming convention for these devices which will allow
visual identification of the location in the scsi system of the
device is such:
LibraryX_Y_Z for media changer devices
TapeX_Y_X for tape devices
where X=the ASCII representation of the controller value with
leading zeros eliminated,
Y=the ASCII representation of the SCSI id value with leading
zeros eliminated,
Z=the ASCII representation of the LUN value with leading zeros
eliminated.
Message XDR definition
/* NDMP_CONFIG_GET_SCSI_INFO */
/* 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. 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 jukebox device. Each
entry in the list contains the following:
Expires August 2001 [Page 84]
Draft Specification NDMP Version 4 Protocol February 2001
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
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.
NOTE: Capabilities strings are optional and MAY
include:
SELECT_TIMEOUT
Time in milliseconds to wait for robot commands to
compelete 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
Connection not authorized.
3.2.9 NDMP_CONFIG_GET_EXT_LIST
NDMP_CONFIG_GET_EXT_LIST is used by the requester (DMA) to request
which extensions, i.e. which classes and versions are available in
the service.
This request MUST be issued before any requests to extensions are
issued. 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:
Message XDR definitions
/* NDMP_CONFIG_GET_EXT_LIST */
Expires August 2001 [Page 85]
Draft Specification NDMP Version 4 Protocol February 2001
/* no request arguments */
struct ndmp_config_get_ext_list_reply
{
ndmp_error error;
ndmp_class_listclass_list<>;
};
Request Arguments
This request does not have a message body.
Reply Arguments
error
Error code.
class_list
The list of classes 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". Which extensions to expose is entirely up to the
implementer of the server.
Reply Errors
NDMP_EXT_DANDN_ILLEGAL
The D+N process is illegal at this point. Extension requests
have been issued thus selecting the default set.
3.2.10 NDMP_CONFIG_SET_EXT_LIST
After a successful reply to the NDMP_CONFIG_GET_EXT_LIST the DMA
SHOULD select which extensions, and which version of each extension
it will use. An extension is selected with the class-version
combination.
Notice that only one version of each class MUST be selected.
Expires August 2001 [Page 86]
Draft Specification NDMP Version 4 Protocol February 2001
If an error is reported, is assumed that the D+N process is
restarted.
The DMA selects the extensions by issuing the
NDMP_CONFIG_SET_EXT_LIST message to the service:
/* NDMP_CONFIG_SET_EXT_LIST */
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. 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_CLASS_NOT_SUPPORTED
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.
NDMP_VERSION_NOT_SUPPORTED
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.
Two or more of the selected classes in the class-version list
have the same class ID.
Expires August 2001 [Page 87]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_EXT_DANDN_ILLEGAL
The D+N process is illegal at this point. Extensions have
already been selected, because extension requests have been
issued thus selecting the default set.
Expires August 2001 [Page 88]
Draft Specification NDMP Version 4 Protocol February 2001
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. 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 August 2001 [Page 89]
Draft Specification NDMP Version 4 Protocol February 2001
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
/* NDMP_SCSI_OPEN */
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 August 2001 [Page 90]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 91]
Draft Specification NDMP Version 4 Protocol February 2001
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
/* NDMP_SCSI_CLOSE */
/* no request arguments */
struct ndmp_scsi_close_reply
{
ndmp_error error;
};
Request Arguments
This request does not have a message body.
Reply Arguments
error
Error code.
Reply Errors
NDMP_NO_ERR
Device successfully closed.
NDMP_DEV_NOT_OPEN_ERR
No device currently open by the connection.
NDMP_NOT_AUTHORIZED_ERR
Connection not authorized.
Expires August 2001 [Page 92]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_SCSI_GET_STATE */
/* no request arguments */
struct ndmp_scsi_get_state_reply
{
ndmp_error error;
short target_controller;
short target_id;
short target_lun;
};
Request Arguments
This request does not have a message body.
Reply Arguments
error
Error code.
target_controller
Identifier of the SCSI controller to which the currently
targeted SCSI device is attached.
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
Connection not authorized.
Expires August 2001 [Page 93]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_SCSI_RESET_DEVICE */
/* no request arguments */
struct ndmp_scsi_reset_device_reply
{
ndmp_error error;
};
Request Arguments
This request does not have a message body.
Reply Arguments
error
Error code.
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
Connection not authorized.
Expires August 2001 [Page 94]
Draft Specification NDMP Version 4 Protocol February 2001
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
miliseconds. 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.
Expires August 2001 [Page 95]
Draft Specification NDMP Version 4 Protocol February 2001
Message XDR definition
/* NDMP_SCSI_EXECUTE_CDB */
struct ndmp_execute_cdb_request
{
u_long flags;
u_long timeout;
u_long datain_len;
opaque cdb<>;
opaque dataout<>;
};
struct ndmp_execute_cdb_reply
{
ndmp_error error;
u_char status;
u_long dataout_len;
opaque datain<>;
opaque ext_sense<>;
};
Request Arguments
flags
Specifies the data transfer (if any) direction. DATA_IN and
DATA_OUT reference the 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.
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.
Expires August 2001 [Page 96]
Draft Specification NDMP Version 4 Protocol February 2001
Reply Arguments
error
Error code.
status
SCSI status byte.
dataout
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.
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
Connection not authorized.
Expires August 2001 [Page 97]
Draft Specification NDMP Version 4 Protocol February 2001
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 also provides 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:
1. An NDMP connection may have open at most one device at any
time.
2. An NDMP server SHALL, to the extent possible, exclude
other entities from accessing any device that is open by an
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:
1. The tape drive is opened in either NDMP_TAPE_WRITE_MODE or
NDMP_TAPE_RAW_MODE; and,
2. Data have been written to the tape using either
NDMP_TAPE_WRITE or a mover (*1) that are not followed by a
file mark (*2); and,
3. The operation being performed is one of NDMP_TAPE_CLOSE or
any NDMP_TAPE_MTIO except NDMP_MTIO_EOF.
If any one or more of these conditions are not satisfied, no file
mark is generated.
(*1) Automatic file mark creation does not occur if all write
operations were performed via NDMP_TAPE_EXECUTE_CDB.
(*2) File marks generated by NDMP_TAPE_EXECUTE_CDB aren't
recognized by this rule.
Expires August 2001 [Page 98]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 99]
Draft Specification NDMP Version 4 Protocol February 2001
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
/* NDMP_TAPE_OPEN */
struct ndmp_tape_open_request
{
string device<>;
ndmp_tape_open_mode mode;
};
struct ndmp_tape_open_reply
{
ndmp_errorerror;
};
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.
Expires August 2001 [Page 100]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_DEVICE_OPENED_ERR
The NDMP server already has a SCSI device or tape device
open.
NDMP_NO_DEVICE_ERR
The specified device does not exist.
NDMP_DEVICE_BUSY_ERR
The device is already open by another NDMP server or system
process.
NDMP_IO_ERR
Device I/O error. 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_NO_TAPE_LOADED_ERR
No tape loaded in the tape device.
NDMP_NOT_SUPPORTED_ERR
The request is not supported for this implementation.
NDMP_NOT_AUTHORIZED_ERR
Connection not authorized.
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_WRITE_MODE.
Expires August 2001 [Page 101]
Draft Specification NDMP Version 4 Protocol February 2001
3.4.3. NDMP_TAPE_CLOSE
This request closes the tape drive.
For this request to succeed, any MOVER using this tape device MUST be
not either in an active or a listen state.
If the tape device is opened in NDMP_TAPE_WRITE_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, it shall not close the tape
drive. In such 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.
Message XDR definition
/* NDMP_TAPE_CLOSE */
/* no request arguments */
struct ndmp_tape_close_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error
Error code.
Reply Errors
NDMP_NO_ERR
Tape device successfully closed.
Expires August 2001 [Page 102]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_DEV_NOT_OPEN_ERR
No tape device currently open by the connection.
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
Connection not authorized.
Expires August 2001 [Page 103]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_TAPE_GET_STATE */
/* 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 message does not have a message body.
Reply Arguments
unsupported
This bit field identifies the arguments in the reply message
whose values are not set by the server.
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.
Expires August 2001 [Page 104]
Draft Specification NDMP Version 4 Protocol February 2001
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.
This value shall be set to all ones if it is unknown to or
unsupported by the server, or if there is no tape currently
loaded in the tape drive. Further, if the server does not
support this value, it SHALL set the
NDMP_TAPE_STATE_FILE_NUM_UNS bit in the "unsupported" bit
field to one.
soft_errors
Total number of soft media errors detected since the device
was opened.
This value SHALL be set to all ones 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 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. This value SHALL be set to
all ones 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_BLOCKNO_UNS bit in the "unsupported"
bit field to one.
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).
Expires August 2001 [Page 105]
Draft Specification NDMP Version 4 Protocol February 2001
This value SHALL be set to all ones 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 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 connection is not authorized.
NDMP_IO_ERR
A device I/O error occurred while processing this request.
Expires August 2001 [Page 106]
Draft Specification NDMP Version 4 Protocol February 2001
3.4.5. NDMP_TAPE_MTIO
This request provides access to common magnetic tape I/O operations.
Message XDR definition
/* NDMP_TAPE_MTIO */
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 August 2001 [Page 107]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 108]
Draft Specification NDMP Version 4 Protocol February 2001
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 and NDMP_MTIO_OFF 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.
NDMP_NOT_AUTHORIZED_ERR
Connection not authorized.
NDMP_WRITE_PROTECT_ERR
Tape is write protected.
Expires August 2001 [Page 109]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Expires August 2001 [Page 110]
Draft Specification NDMP Version 4 Protocol February 2001
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 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.
Message XDR definition
/* NDMP_TAPE_WRITE */
struct ndmp_tape_write_request
{
opaque data_out<>;
};
struct ndmp_tape_write_reply
{
ndmp_error error;
u_long count;
};
Request Arguments
data_out
The data to be written to the tape device.
Expires August 2001 [Page 111]
Draft Specification NDMP Version 4 Protocol February 2001
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 above). 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
Connection not authorized.
NDMP_WRITE_PROTECT_ERR
Tape is write protected.
o 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 above). 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
Connection not authorized.
Expires August 2001 [Page 112]
Draft Specification NDMP Version 4 Protocol February 2001
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
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_DEVICE_BUSY_ERR
A MOVER associated with this tape drive is either in an
active or listen state.
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.
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 tape block read contains excess data, that data is
discarded.
When a file mark is encountered in lieu of the first 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 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.
Expires August 2001 [Page 113]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Message XDR definition
/* NDMP_TAPE_READ */
struct ndmp_tape_read_request
{
u_long count;
};
struct ndmp_tape_read_reply
{
ndmp_error error;
opaque data_in<>;
};
Request Arguments
count
Number of bytes to read.
Reply Arguments
error
Error code.
data_in
The data read from the tape drive.
Reply Errors
NDMP_NO_ERR
A read from the tape was successful.
NDMP_DEV_NOT_OPEN_ERR
No tape device currently open by the connection.
Expires August 2001 [Page 114]
Draft Specification NDMP Version 4 Protocol February 2001
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
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.
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 request is not supported for this implementation.
NDMP_NOT_AUTHORIZED_ERR
Connection not authorized.
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.
Expires August 2001 [Page 115]
Draft Specification NDMP Version 4 Protocol February 2001
3.4.8. NDMP_TAPE_EXECUTE_CDB
This message behaves in exactly the same way as the SCSI_EXECUTE_CDB
request except that it sends the CDB to the tape device. This request
SHOULD not be used to change the state of the tape device (such as
tape positioning).
Message XDR definition
/* NDMP_TAPE_EXECUTE_CDB */
typedef ndmp_scsi_execute_cdb_request
ndmp_tape_execute_cdb_request;
typedef ndmp_scsi_execute_cdb_reply ndmp_tape_execute_cdb_reply;
Expires August 2001 [Page 116]
Draft Specification NDMP Version 4 Protocol February 2001
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.
3.5.2. Data Interface Variables & Constants
Expires August 2001 [Page 117]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 118]
Draft Specification NDMP Version 4 Protocol February 2001
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 after a 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 August 2001 [Page 119]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 120]
Draft Specification NDMP Version 4 Protocol February 2001
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.
3.5.3. 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 August 2001 [Page 121]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.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_DATE_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
/* NDMP_DATA_CONNECT */
struct ndmp_data_connect_request
{
ndmp_addr addr;
};
struct ndmp_data_connect_reply
{
ndmp_error error;
};
Request Arguments
addr
Expires August 2001 [Page 122]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 123]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.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
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 data
servers for file system to file system transfers.
Message XDR definition
/* NDMP_DATA_LISTEN */
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 August 2001 [Page 124]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 125]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 126]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.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.
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 August 2001 [Page 127]
Draft Specification NDMP Version 4 Protocol February 2001
Message XDR definition
/* NDMP_DATA_START_BACKUP */
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 August 2001 [Page 128]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 129]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.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 recovery).
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. 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.
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.
Expires August 2001 [Page 130]
Draft Specification NDMP Version 4 Protocol February 2001
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
/* NDMP_DATA_START_RECOVER */
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.
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.
Expires August 2001 [Page 131]
Draft Specification NDMP Version 4 Protocol February 2001
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 catenated 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 catenated 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.
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 if
not supported or value unknown by the DMA, and ignored by
recovery methods that do not support selective file
recovery operations.
Expires August 2001 [Page 132]
Draft Specification NDMP Version 4 Protocol February 2001
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 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:
a. To recover the whole backup image to /vol/vol3:
original_path = ""
destination_path = "/vol/vol3"
name = ""
or,
original_path = ""
destination_path = "/vol"
name = "vol3"
b. To recover a directory whose original name is
"/vol/vol3/users/tyler" to
"/vol/vol1/users/tyler.from.vol3":
Expires August 2001 [Page 133]
Draft Specification NDMP Version 4 Protocol February 2001
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"
c. To recovery a 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":
original_path = "/updatelog"
destination_path = "/vol/vol3/recovered"
name = "updatelog"
other_name = "updatelog.txt"
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 August 2001 [Page 134]
Draft Specification NDMP Version 4 Protocol February 2001
Expires August 2001 [Page 135]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.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.
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.
Expires August 2001 [Page 136]
Draft Specification NDMP Version 4 Protocol February 2001
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
/* NDMP_DATA_START_RECOVER */
struct ndmp_data_start_recover_filehist_request
{
ndmp_pval env<>;
ndmp_name nlist<>;
string butype_name<>;
};
struct ndmp_data_start_recover_filehist_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:
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.
destination_dir
Ignored.
Expires August 2001 [Page 137]
Draft Specification NDMP Version 4 Protocol February 2001
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 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 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.
Reply Arguments
error
Error code.
Expires August 2001 [Page 138]
Draft Specification NDMP Version 4 Protocol February 2001
Reply Errors
NDMP_NO_ERR
The 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 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 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 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 August 2001 [Page 139]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.5. 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.2 for a complete definition of the standard
data server variables and associated enumerations.
Message XDR definition
/* NDMP_DATA_GET_STATE */
/* 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
The data get state request does not have a message body or
message arguments.
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 NDMPCONNECT_CLIENT_AUTH request from the
DMA.
Expires August 2001 [Page 140]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.6. 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 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 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.
Message XDR definition
/* NDMP_DATA_GET_ENV */
/* no request arguments */
struct ndmp_data_get_env_reply
{
ndmp_error error;
ndmp_pval env<>;
};
Request Arguments
The data get env request does not have a message body or message
arguments.
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 data get env request was successfully processed. The data
get env reply represents the final backup environment.
Expires August 2001 [Page 141]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_ILLEGAL_STATE_ERR
The data get env request was received while the data server
state machine was in a state that prevented processing this
request. Get env requests are only valid in the ACTIVE or
HALTED 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 August 2001 [Page 142]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.7. 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.
Message XDR definition
/* NDMP_DATA_STOP */
/* no request arguments */
struct ndmp_data_stop_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error
Error code.
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 transiti
oned 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 August 2001 [Page 143]
Draft Specification NDMP Version 4 Protocol February 2001
3.5.8. 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.
Message XDR definition
/* NDMP_DATA_ABORT */
/* no request arguments */
struct ndmp_data_abort_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a request body.
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 August 2001 [Page 144]
Draft Specification NDMP Version 4 Protocol February 2001
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 meta
data on NDMP generated tapes. Data that resides outside of the mover
window is controlled by the DMA and represents meta data 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 meta data 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 meta data between the backup stream segments.
During a recover operation, the DMA is responsible for positioning
the tape over any non-backup stream meta data (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 August 2001 [Page 145]
Draft Specification NDMP Version 4 Protocol February 2001
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 meta data 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.2. 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 August 2001 [Page 146]
Draft Specification NDMP Version 4 Protocol February 2001
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_PAUSED_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 August 2001 [Page 147]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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.
Expires August 2001 [Page 148]
Draft Specification NDMP Version 4 Protocol February 2001
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 a 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 meta data processed
via the tape interface.
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.
Expires August 2001 [Page 149]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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.
Expires August 2001 [Page 150]
Draft Specification NDMP Version 4 Protocol February 2001
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 set window
request. Prior to issuing a 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
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 meta
data 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; indicating 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 a 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.
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 set window requests and transitions to the
IDLE state.
Expires August 2001 [Page 151]
Draft Specification NDMP Version 4 Protocol February 2001
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.3. 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.
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 August 2001 [Page 152]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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.
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
/* NDMP_MOVER_SET_RECORD_SIZE */
struct ndmp_mover_set_record_size_request
{
u_long len;
};
struct ndmp_mover_set_record_size_reply
{
ndmp_error error;
};
Request Arguments
len
The length of the mover record specified in bytes.
Expires August 2001 [Page 153]
Draft Specification NDMP Version 4 Protocol February 2001
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.
Expires August 2001 [Page 154]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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 set
window 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 a 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 a set window request
before causing the mover to transition out of the PAUSED state via a
mover continue request.
Prior to issuing a set window 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.
A 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 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. For recovery operations (NDMP_MOVER_MODE_WRITE) the
window offset MUST be set to zero or a multiple of the mover
record_size. These requirement MUST be enforced in the set window
processing when the mover is in the PAUSED state. Note: this
restriction MUST also be inforced 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_PAUSED_EOF reason rather than an NDMP_MOVER_PAUSE_SEEK
reason if an EOW was detected.
Expires August 2001 [Page 155]
Draft Specification NDMP Version 4 Protocol February 2001
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
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 notify mover
paused message to the DMA. This provides the DMA an opportunity to
interleave meta data 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
/* NDMP_MOVER_SET_WINDOW */
struct ndmp_mover_set_window_request
{
ndmp_u_quad offset;
ndmp_u_quad length;
};
struct ndmp_mover_set_window_reply
{
ndmp_error error;
};
Request Arguments
offset
The 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 August 2001 [Page 156]
Draft Specification NDMP Version 4 Protocol February 2001
Reply Arguments
error
Error code.
Reply Errors
NDMP_NO_ERR
The mover set window request was successfully processed. The
specified mover window is now in effect.
NDMP_PRECONDITION_ERR
The mover set window request was received prior to
establishing a valid mover record_size.
NDMP_ILLEGAL_ARGS_ERR
The mover set window 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. 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 set window request was received while the mover
state machine was in a state that prevented processing this
request. Set window requests are 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 August 2001 [Page 157]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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_MODE_READ, implying a write to tape,
the tape must be open in NDMP_TAPE_MODE_WRITE or NDMP_TAPE_MODE_RAW
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.
The 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_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 requirement MUST also
be enforced in the NDMP_MOVER_SET_WINDOW processing when the mover is
in the PAUSED state.
Message XDR definition
Expires August 2001 [Page 158]
Draft Specification NDMP Version 4 Protocol February 2001
/* NDMP_MOVER_CONNECT */
struct ndmp_mover_connect_request
{
ndmp_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 August 2001 [Page 159]
Draft Specification NDMP Version 4 Protocol February 2001
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. 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 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 August 2001 [Page 160]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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 data server 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 requirement MUST also
be enforced in the NDMP_MOVER_SET_WINDOW processing when the mover is
in the PAUSED state.
Expires August 2001 [Page 161]
Draft Specification NDMP Version 4 Protocol February 2001
Message XDR definition
/* NDMP_MOVER_LISTEN */
struct ndmp_mover_listen_request
{
ndmp_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 August 2001 [Page 162]
Draft Specification NDMP Version 4 Protocol February 2001
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. For recovery operations (NDMP_MOVER_MODE_WRITE) the
window offset was not set to a multiple of the mover
record_size or zero.
Expires August 2001 [Page 163]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 164]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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 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 August 2001 [Page 165]
Draft Specification NDMP Version 4 Protocol February 2001
Message XDR definition
/* NDMP_MOVER_READ */
struct ndmp_mover_read_request
{
ndmp_u_quad offset;
ndmp_u_quad length;
};
struct ndmp_mover_read_reply
{
ndmp_error error;
};
Request Arguments
offset
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 (new error)
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 August 2001 [Page 166]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 167]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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.3 for a complete definition of the
standard mover variables and associated enumerations.
Message XDR definition
/* NDMP_MOVER_GET_STATE */
/* no request arguments */
struct ndmp_mover_get_state_reply
{
ndmp_error error;
ndmp_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
The mover get state request does not have a message body or
message arguments.
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 NDMPCONNECT_CLIENT_AUTH request from the
DMA.
Expires August 2001 [Page 168]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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. A 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.
Message XDR definition
/* NDMP_MOVER_CONTINUE */
/* no request arguments */
struct ndmp_mover_continue_reply
{
ndmp_error error;
};
Request Arguments
The mover continue request does not have a message body or
message arguments.
Reply Arguments
error
Error code.
Reply Errors
NDMP_NO_ERR
The 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 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.
Expires August 2001 [Page 169]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_PRECONDITION_ERR
The mover continue request was received prior to establishing
a valid mover window.
Expires August 2001 [Page 170]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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 the mover has successfully
transferred all backup stream data to the tape subsystem, or 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.
Message XDR definition
/* NDMP_MOVER_CLOSE */
/* no request arguments */
struct ndmp_mover_close_reply
{
ndmp_error error;
};
Request Arguments
The mover close request does not have a message body or message
arguments.
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 NDMPCONNECT_CLIENT_AUTH request from the
DMA.
Expires August 2001 [Page 171]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.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.
Message XDR definition
/* NDMP_MOVER_ABORT */
/* no request arguments */
struct ndmp_mover_abort_reply
{
ndmp_error error;
};
Request Arguments
The mover abort request does not have a message body or message
arguments.
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 August 2001 [Page 172]
Draft Specification NDMP Version 4 Protocol February 2001
3.6.3.10. NDMP_MOVER_STOP
This request is used by the DMA to instruct the mover to release all
resources, reset all mover state variables, and transition the mover
to the IDLE state.
Message XDR definition
/* NDMP_MOVER_STOP */
/* no request arguments */
struct ndmp_mover_stop_reply
{
ndmp_error error;
};
Request Arguments
The mover close request does not have a message body or message
arguments.
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 August 2001 [Page 173]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 174]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 175]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 176]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 177]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 178]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 179]
Draft Specification NDMP Version 4 Protocol February 2001
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. In response to this message, the NMDP client MUST send an
NDMP_MOVER_READ message to the remote tape 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 August 2001 [Page 180]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 181]
Draft Specification NDMP Version 4 Protocol February 2001
4.2.1. NDMP_LOG_MESSAGE
This request 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.
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:
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:
Expires August 2001 [Page 182]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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 August 2001 [Page 183]
Draft Specification NDMP Version 4 Protocol February 2001
4.2.2. NDMP_LOG_FILE
This request 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.
Post Message
struct ndmp_log_file_post
{
string name<>;
ndmp_recovery_status recovery_status;
};
Post Message Arguments
name
File name.
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_FILE_RECOVERY_FAILED_UNDEFINED_ERROR
Error encountered during recovery other than one of those
listed above.
Expires August 2001 [Page 184]
Draft Specification NDMP Version 4 Protocol February 2001
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Ýs 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.
Expires August 2001 [Page 185]
Draft Specification NDMP Version 4 Protocol February 2001
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 can be either
the absolute pathname or the pathname relative to the backup root
directory. An absolute pathname is denoted by the presence of a
leading path separation character ('/' for UNIX; '\' for NT and DOS).
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
/* NDMP_FH_ADD_FILE */
struct ndmp_fh_add_file_post
{
ndmp_file files<>;
};
/* no reply */
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. MAY be either the
absolute path name or the path name relative to the
backup root directory. The first character of an
absolute path name MUST be a '/'. The first character
of a relative path name MUST NOT be a '/'. The path
separation character is '/'.
Expires August 2001 [Page 186]
Draft Specification NDMP Version 4 Protocol February 2001
nt_name
NT path name of backed up file. MAY be either the
absolute path name or the path name relative to the
backup root directory. The first character of an
absolute path name MUST be a '\'. The first character
of a relative path name MUST NOT be a '\'. The path
separation character is '\'.
other_name
Path name of backed up file. MAY be either the
absolute path name or the path name relative to the
backup root directory. The first character of an
absolute path name MUST be a path separation
character. The first character of a relative path name
MUST NOT be a path separation character. The path
separation character is file system dependent. 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.
Expires August 2001 [Page 187]
Draft Specification NDMP Version 4 Protocol February 2001
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.
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.
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 August 2001 [Page 188]
Draft Specification NDMP Version 4 Protocol February 2001
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 add directory 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, add directory 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 "." add directory entry and a ".." add
directory entry MUST immediately precede all add directory
entries for files contained in the directory. A "." add directory
entry MUST contain "." as one of the names in the name array. The
node and parent values MUST be equivalent. A ".." add directory
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 directory entries for files/directories contained in a
directory MUST immediately follow the ".." add directory entry
for that directory. All add directory entries for a directory
must be sent prior to any add directory entry for another
directory.
Expires August 2001 [Page 189]
Draft Specification NDMP Version 4 Protocol February 2001
5. For any given node, an add directory entry for the node MUST
be sent prior to the add node entry for the node. In the event
that multiple hard links exist for a node, one add directory
entry MUST be sent for each link but only one 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 add directory entries before sending the add node
entry.
6. For an incremental backup, add directory entries MAY be sent
for which no associated 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. 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
/* NDMP_FH_ADD_DIR */
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.
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 August 2001 [Page 190]
Draft Specification NDMP Version 4 Protocol February 2001
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
/* NDMP_FH_ADD_NODE */
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.
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.
5. References
[1] RFC 1832, "XDR: External Data Representation Standard", R.
Srinivasan, Sun Microsystems, August 1995
[2] RFC 1321, "The MD5 Message-Digest Algorithm", R. Rivest, MIT
Laboratory for Computer Science and RSA Data Security, Inc.,
April 1992
[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.
Expires August 2001 [Page 191]
Draft Specification NDMP Version 4 Protocol February 2001
[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
6. 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.
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.
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.
Expires August 2001 [Page 192]
Draft Specification NDMP Version 4 Protocol February 2001
Version 4 of the NDMP specification is largely a cleanup effort from
version 2 and version 3 of the NDMP specification. Very few aspects
have changed between the two versions, and the architecture of NDMP
from versions 2 and 3 of the protocol is preserved.
8. Authors and Contributors
8.1. Document Editor
Harald Skardal
Network Appliance, Inc.
495 East Java Drive
Sunnyvale, CA 94089, USA
Tel: 603.882.3881
Email: Harald.Skardal@netapp.com
8.2. Authors' Addresses
[Companies, email addresses, phone numbers etc will be added.]
Expires August 2001 [Page 193]
Draft Specification NDMP Version 4 Protocol February 2001
James Bunnell
Spectra Logic Inc.
Email: jamesb@spectralogic.com
Sudakar V. Chellam,
IBM,
Email: svelkant@us.ibm.com
Tim Gardner
Chewcoba Inc.
Email: tim@chewcoba.com
Clive Hendrie
Synaxia Networks
Email: clive.hendrie@synaxia.com
Kiyoshi Komatsu
Network Appliance, Inc.
Email: Kiyoshi.Komatsu@netapp.com
Greg Linn
Network Appliance Inc.
Email: Greg.Linn@netapp.com
Dave Manley
Network Appliance
Email: David.Manley@netapp.com
Jim Ward
Workstation Solutions Inc.
Email: jimw@worksta.com
Gordon Waidhofer
Traakan Inc.
Email: gww@traakan.com
8.3. Contributors
In addition to the authors, the following people have helped the
effort by participating in the reviews:
Steve Kappel
Veritas Software
Email: steve.kappel@veritas.com
Expires August 2001 [Page 194]
Draft Specification NDMP Version 4 Protocol February 2001
Paul Lockwood,
Legato Software,
plock@legato.com
Expires: August 2001
Expires August 2001 [Page 195]
Draft Specification NDMP Version 4 Protocol February 2001
Appendixes:
Appendix A: MD5 Based Authentication:
This appendix describes the typical process of authenticating the DMA
to an NDMP server host.
The requirement for authentication is a shared secret between the DMA
and the NDMP server host where the data or tape servers are running.
The typical implementation is to use a user account on the host such
as ååndmpÝÝ, with a password that is the shared secret. This user
account (ååndmp_userÝÝ) has the right privileges to run the necessary
backup programs such as tar, cpio, dump etc., or to use the tape
devices.
The DMA uses the command NDMP_CONFIG_GET_AUTH_ATTR to get the 64 byte
challenge from the remote host. The client combines the challenge,
the åndmp_userÝ password and null byte padding as follows:
The input string to the MD5 algorithm is 128 bytes, or 1024 bits.
Notice that this string is the ååmessageÝÝ part in the MD5 input
string, as defined by RFC 1321. The MD5 routine will add its own
padding and the length of the input message before the digest is
computed.
The challenge part is 64 bytes. This is the string returned from the
NDMP server host using the NDMP_CONFIG_GET_AUTH_ATTR request.
The password is up to 32 bytes. Notice that it is the same password
that is repeated. If the password is longer than 32 bytes, it is
truncated to 32 bytes.
The padding is a sequence of null bytes (0x00) that pads the
remainder of the MD5 input string such that it becomes 128 bytes.
This resulting string is the input to the MD5 digest algorithm, as
specified in RFC 1321.
The MD5 algorithm takes this input and produces the digest, a 128 bit
(=16 byte) quantity. The digest goes into the
NDMP_CONNECT_CLIENT_AUTH command as the ååauth_digestÝÝ value, together
with the ndmp_user id.
The host receives the ndmp_user ID and the MD5 digest. The host
computes its own digest based on the stored password for the
ndmp_user, the challenge it sent to the client, and padding,
according to the NDMP convention for generating an MD5 message.
The resulting digest is compared to the digest received from the
client. If the computed and the received digests are equal, the
client is authenticated.
Expires August 2001 [Page 196]
Draft Specification NDMP Version 4 Protocol February 2001
Appendix B: 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.
Official Extensions:
The layout and management of the official extensions space is
tbd. It may be deferred and specified as a separate
specification.
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: 2030.0000 - 2033.FFFF
Legato: 2040.0000 - 2043.FFFF
NetApp: 2050.0000 - 2053.FFFF
Procom: 2060.0000 - 2063.FFFF
Spectralogic: 2070.0000 - 2073.FFFF
Synaxia: 2080.0000 - 2083.FFFF
Syncsort: 2090.0000 - 2093.FFFF
Traakan: 20A0.0000 - 20A3.FFFF
Veritas: 20B0.0000 - 20B3.FFFF
Expires August 2001 [Page 197]
Draft Specification NDMP Version 4 Protocol February 2001
Workstation Solutions: 20C0.FFFF - 20C3.FFFF
EMC: 20D0.0000 - 20D3.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.
Extension Standardization Process
The process for how to conduct this standardization of extensions
should be discussed with the IETF area director, and also we
should review if similar extensibility has been developed in the
IETF before.
The layout and management of the standard extensions code space
is tbd.
Expires August 2001 [Page 198]
Draft Specification NDMP Version 4 Protocol February 2001
Appendix C: NDMP Extensions Test Message
The extension class 0xfff0, interface 00, message 00 will be used as
a test message that all NDMP server implementation SHOULD implement.
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 0xfff0 class with different
message definitions will be defined.
NDMP Extension Test Message Numbers:
The following messages is defined:
enum ndmp_test_ext_message {
/* ECHO INTERFACE */
NDMP_TEST_ECHO = 0xfff00000;
};
Class 0xfff0 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
/* NDMP_TEST_ECHO */
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 you expect to be echoed back from the
server.
Expires August 2001 [Page 199]
Draft Specification NDMP Version 4 Protocol February 2001
Reply Arguments
error
Error code.
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 0xfff0 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
/* NDMP_TEST_ECHO */
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 you expect to be echoed back from the
server.
Expires August 2001 [Page 200]
Draft Specification NDMP Version 4 Protocol February 2001
echo_short
This is any u_short that you expect to be echoed back from
the server.
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 August 2001 [Page 201]
Draft Specification NDMP Version 4 Protocol February 2001
Appendix D: 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 August 2001 [Page 202]
Draft Specification NDMP Version 4 Protocol February 2001
enum 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;
};
/* 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,
Expires August 2001 [Page 203]
Draft Specification NDMP Version 4 Protocol February 2001
NDMP_PRECONDITION_ERR = 26,
NDMP_CLASS_NOT_SUPPORTED = 27,
NDMP_VERSION_NOT_SUPPORTED = 28,
NDMP_EXT_DUPL_CLASSES = 29,
NDMP_EXT_DN_ILLEGAL = 30
};
Expires August 2001 [Page 204]
Draft Specification NDMP Version 4 Protocol February 2001
/* Note: Because of extensibility, this */
/* is not a complete list of messages */
enum ndmp_message {
/* CONNECT INTERFACE */
NDMP_CONNECT_OPEN = 0x900,
NDMP_CONNECT_CLIENT_AUTH = 0x901,
NDMP_CONNECT_CLOSE = 0x902,
NDMP_CONNECT_SERVER_AUTH = 0x903,
/* CONFIG INTERFACE */
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,
/* SCSI INTERFACE */
NDMP_SCSI_OPEN = 0x200,
NDMP_SCSI_CLOSE = 0x201,
NDMP_SCSI_GET_STATE = 0x202,
NDMP_SCSI_RESET_DEVICE = 0x204,
NDMP_SCSI_EXECUTE_CDB = 0x206,
/* TAPE INTERFACE */
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,
/* DATA INTERFACE */
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,
Expires August 2001 [Page 205]
Draft Specification NDMP Version 4 Protocol February 2001
/* NOTIFY INTERFACE */
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,
/* LOGGING INTERFACE */
NDMP_LOG_FILE = 0x602,
NDMP_LOG_MESSAGE = 0x603,
/* FILE HISTORY INTERFACE */
NDMP_FH_ADD_FILE = 0x703,
NDMP_FH_ADD_DIR = 0x704,
NDMP_FH_ADD_NODE = 0x705,
/* MOVER INTERFACE */
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,
/* EXTENSIBILITY */
/* Reserved for Standard extensions */
NDMP_EXT_STANDARD_BASE = 0x10000,
/* Reserved for Proprietary extensions */
NDMP_EXT_PROPRIETARY_BASE = 0x20000000,
};
/* Connect messages */
struct ndmp_connect_open_request
{
u_short protocol_version;
};
struct ndmp_connect_open_reply
{
ndmp_error error;
};
enum ndmp_auth_type
{
Expires August 2001 [Page 206]
Draft Specification NDMP Version 4 Protocol February 2001
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;
};
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
{
ndmp_error error;
ndmp_auth_data server_result;
};
struct ndmp_config_get_host_info_reply
Expires August 2001 [Page 207]
Draft Specification NDMP Version 4 Protocol February 2001
{
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<>;
};
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_config_get_auth_attr_request
{
ndmp_auth_type auth_type;
};
struct ndmp_config_get_auth_attr_reply
Expires August 2001 [Page 208]
Draft Specification NDMP Version 4 Protocol February 2001
{
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;
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;
Expires August 2001 [Page 209]
Draft Specification NDMP Version 4 Protocol February 2001
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;
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_pval
{
string name<>;
string value<>;
};
struct ndmp_device_capability
{
string device<>;
u_long attr;
ndmp_pval capability<>;
};
struct ndmp_device_info
{
string model<>;
ndmp_device_capability caplist<>;
Expires August 2001 [Page 210]
Draft Specification NDMP Version 4 Protocol February 2001
};
struct ndmp_config_get_scsi_info_reply
{
ndmp_error error;
ndmp_device_info scsi_info <>;
};
struct ndmp_class_list
{
u_short class_id;
u_short version<>;
};
struct ndmp_class_version
{
u_short class_id;
u_short version;
};
struct ndmp_config_get_ext_list_reply
{
ndmp_error error;
ndmp_class_listclass_list<>;
};
struct ndmp_config_set_ext_list_reply
{
ndmp_error error;
ndmp_class_list ndmp_accepted_ext<>;
};
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
Expires August 2001 [Page 211]
Draft Specification NDMP Version 4 Protocol February 2001
{
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_scsi_execute_cdb_request
{
u_long flags;
u_long timeout;
u_long datain_len;
opaque cdb<>;
opaque dataout<>;
};
struct ndmp_scsi_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_tape_open_request {
string device<>;
ndmp_tape_open_mode mode;
};
struct ndmp_tape_open_reply {
ndmp_error error;
};
Expires August 2001 [Page 212]
Draft Specification NDMP Version 4 Protocol February 2001
struct ndmp_tape_close_reply
{
ndmp_error error;
};
struct ndmp_u_quad
{
u_long high;
u_long low;
};
/* flags */
const NDMP_TAPE_STATE_NOREWIND = 0x0008; /* non-rewind device */
const NDMP_TAPE_STATE_WR_PROT = 0x0010; /* write-protected */
const NDMP_TAPE_STATE_ERROR = 0x0020; /* media error */
const NDMP_TAPE_STATE_UNLOAD = 0x0040; /* tape unloaded upon
close */
/* unsupported bits */
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;
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_quadtotal_space;
ndmp_u_quadspace_remain;
};
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,
Expires August 2001 [Page 213]
Draft Specification NDMP Version 4 Protocol February 2001
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_scsi_execute_cdb_request
ndmp_tape_execute_cdb_request;
typedef ndmp_scsi_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 August 2001 [Page 214]
Draft Specification NDMP Version 4 Protocol February 2001
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,
};
/* ndmp_addr */
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;
};
/* unsupported bitmask bits */
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;
Expires August 2001 [Page 215]
Draft Specification NDMP Version 4 Protocol February 2001
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;
};
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<>;
Expires August 2001 [Page 216]
Draft Specification NDMP Version 4 Protocol February 2001
string destination_dir<>;
string name<>;
string other_name<>;
ndmp_u_quad node;
ndmp_u_quad fh_info;
};
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<>;
};
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
{
Expires August 2001 [Page 217]
Draft Specification NDMP Version 4 Protocol February 2001
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
{
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;
};
Expires August 2001 [Page 218]
Draft Specification NDMP Version 4 Protocol February 2001
enum ndmp_mover_mode
{
NDMP_MOVER_MODE_READ = 0,
NDMP_MOVER_MODE_WRITE = 1,
NDMP_MOVER_MODE_NOACTION = 2
};
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;
};
struct ndmp_notify_data_halted_post
{
ndmp_data_halt_reason reason;
Expires August 2001 [Page 219]
Draft Specification NDMP Version 4 Protocol February 2001
};
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
};
Expires August 2001 [Page 220]
Draft Specification NDMP Version 4 Protocol February 2001
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;
};
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
};
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;
Expires August 2001 [Page 221]
Draft Specification NDMP Version 4 Protocol February 2001
};
/* file type */
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
};
/* file stat */
/* unsupported bitmask */
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
Expires August 2001 [Page 222]
Draft Specification NDMP Version 4 Protocol February 2001
{
ndmp_file_name name<>;
ndmp_u_quad node;
ndmp_u_quad parent;
};
struct ndmp_fh_add_dir_post
{
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 August 2001 [Page 223]
Draft Specification NDMP Version 4 Protocol February 2001
Appendix E: Workflow
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 Server with TAPE service and that the data to
be backed up is on the host running NDMP Server with DATA service.
(1) DMA will open a communication channel to the NDMP server with
Tape Service, 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 server with tape service 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 server with tape service to instruct it to open a
tape drive for writing. The NDMP server with Tape
Service 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 server with TAPE
service to properly position the tape for writing the
backup data. This may include:
Rewinding and optionally writing a new tape label
and header files.
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 Tape library what
record size to use when writing to the tape.
(3) Connection to the NDMP Server with DATA service
Expires August 2001 [Page 224]
Draft Specification NDMP Version 4 Protocol February 2001
(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 server with
Data service can be replaced by NDMP server with Tape
service 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 server with Data Service.
(4) The DMA will send NDMP_CONFIG_GET_BUTYPE_INFO message to
query the capability of NDMP Server with DATA service. For
example, is file history is supported or not
(5) Get a mover address from the NDMP Server with TAPE service
(a) The DMA will send an NDMP_CONFIG_GET_CONNECTION_TYPE
message to the NDMP server with DATA service and the NDMP
server with Tape service 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 choose the type of connection to be used
between the NDMP Server with DATA service and the NDMP
server with TAPE service and include it in the
NDMP_MOVER_LISTEN message.
(d) The DMA will send NDMP_MOVER_LISTEN message to the NDMP
server with TAPE service.
(e) The mover running on the NDMP server with TAPE service
will create a connection point and begin listening for a
connection. The NDMP server with TAPE service will return
the mover address to the DMA.
(f) THE DMA will send NDMP_DATA_CONNECT message to the NDMP
server with data service, with the address of the NDMP
server with tape service
(6) The DMA will initiate a backup.
Expires August 2001 [Page 225]
Draft Specification NDMP Version 4 Protocol February 2001
(a) The DMA will send an NDMP_DATA_START_BACKUP message to
the NDMP server with DATA service 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 the dumplevel, compression etc. The
NDMP server with Data service will then attempt to open a
data connection to the mover on the NDMP server with Tape
service. If the NDMP server with Data service 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 with TAPE service to tell it to stop listening
for a connection.
(b) The NDMP Server with DATA service 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 server with Data service and
the NDMP server with Tape service
(a) As individual files are backed up, the NDMP server with
Data service 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 server with Tape service and the NDMP server
with Data service may send NDMP_LOG_MESSAGE messages to
the DMA to indicate progress.
(c) If an event occurs that requires attention, the NDMP
server with DATA service or NDMP server with TAPE service
will use the NDMP NOTIFY interface to let the DMA know
that attention is required.
(8) Successful backup completion.
(a) On completion of successful backup the NDMP server with
DATA service 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.
Expires August 2001 [Page 226]
Draft Specification NDMP Version 4 Protocol February 2001
(b) The DMA will issue an NDMP_DATA_GET_STATE and
NDMP_DATA_GET_ENV to the NDMP server with DATA service
and savethe information returned to be used during the
recovery process. Note, that the backup method initiated
by the NDMP server with Data service is free to modify
and/or add NDMP environment variables
(c) The DMA will send an NDMP_DATA_STOP message to the NDMP
server with DATA service.
(d) Once the NDMP server with DATA service has released the
resources, it will return the status to the DMA.
(e) Since the mover on the NDMP server with TAPE service
detects the disconnection from the NDMP server with DATA
service, 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.
(f) The DMA will issue an NDMP_MOVER_GET_STATE message to the
NDMP server with TAPE service and note the total number of
bytes generated.
(g) The DMA will send an NDMP_MOVER_STOP message to the NDMP
server with Tape service.
(h) The DMA will use the NDMP server with TAPE interface to
write a file mark to tape.
(i) The DMA can optionally use the NDMP server with TAPE
interface 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 server with DATA service and then
open a new connection with the new NDMP server with DATA
service.
(b) The DMA can optionally use the NDMP server with TAPE
interface 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 August 2001 [Page 227]
Draft Specification NDMP Version 4 Protocol February 2001
(a) The DMA will send an NDMP_CONNECT_CLOSE message to close
the connection to the NDMP server with DATA service,
unless the NDMP server with DATA service and NDMP server
with TAPE service are running on the same host.
(b) The DMA optionally use the NDMP server with TAPE interface
on the NDMP server with TAPE service to rewind the tape.
(c) The DMA may choose to use the NDMP server with TAPE
interface to eject the tape.
(d) The DMA will send NDMP_CONNECT_CLOSE message to close the
connection to the NDMP server with TAPE service.
Recover
This section describes the recover process. It assumes that the data
to be recoverd is already in a tape drive.
(1) DMA will open a communication channel to the NDMP server with
TAPE service, 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 server with TAPE service to open, read and
position the tape drive in preparation for recover.
(b) The DMA will send an NDMP_TAPE_OPEN message to the NDMP
server with Tape service to instruct it to open a tape
drive for reading. The NDMP server with Tape Service
SHALL , to extent possible exclude other entities from
accessing any device opened by the DMA.
(c) 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).
(d) The DMA can optionally position and validate any header
files surrounding the data that is to be recoverd. If
the header is incorrect or cannot be read, the DMA can
rewind and eject the tape.
(e) 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 server with Data service
Expires August 2001 [Page 228]
Draft Specification NDMP Version 4 Protocol February 2001
(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 server with
Data service can be replaced by NDMP server with Tape
service and the remainder of this step (3) should be
skipped.
(b) If the data to be recoverd 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 server with Data service.
(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 server with Data service. For example, is
individual file recover supported or not?
(5) Begin recover process on the NDMP server with Data service.
(a) The DMA will send an NDMP_CONFIG_GET_CONNECTION_TYPE
message to the NDMP server with Data service and the NDMP
server with Tape service to query the type of connections
supported.
(b) The DMA will choose the type of connection to be used
between the NDMP server with Data service and the NDMP
server with Tape service and include it in the
NDMP_DATA_LISTEN message.
(c) The DMA will send an NDMP_DATA_LISTEN message to the NDMP
server with data service. The NDMP server with data
service will return the address on which it will begin to
listen.
(d) THE DMA will send NDMP_MOVER_CONNECT message to the NDMP
server with tape service, with the address of the NDMP
server with data service
(e) The DMA will send an NDMP_DATA_START_RECOVER message to
the NDMP server with Data service. The message will
include the mover address, a list of NDMP environment
variables, the list of files to be recoverd and the
destination.
(f) If the recover involves a remote NDMP server, i.e. not a
local retrieval.
(g) The NDMP server with Data service will send an
NDMP_NOTIFY_DATA_READ message to the DMA to initiate the
recover.
Expires August 2001 [Page 229]
Draft Specification NDMP Version 4 Protocol February 2001
(h) The DMA should send an NDMP_MOVER_READ message to the NDMP
server with Tape service to inform the mover to start
sending the requested data.
(i) The DMA MUST be prepared to accept NDMP LOG_MESSAGE
message.
(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
which 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_PAUSED_SEEK.
(7) Successful recover
(a) The NDMP server with Data service will send an
NDMP_LOG_FILE message to report if the files are recoverd.
(b) Once all of the files have been recovered, the NDMP server
with Data service 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 server with Tape service and send
an NDMP_NOTIFY_DATA_HALTED message to the DMA.
(c) The DMA will send an NDMP_DATA_STOP message to the NDMP
server with Data service.
(d) Once the resources have been released the NDMP server with
Data service 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
server with Tape service
(f) The DMA will send an NDMP_MOVER_STOP message to the NDMP
server with Tape service.
(g) If there are more recovers to be processed from the tape,
the DMA will position the tape as above.
(h) If there are no more recovers to be processed for this
tape, the DMA will use the NDMP TAPE interface to rewind
and eject the tape.
(i) The DMA will close the tape device.
Expires August 2001 [Page 230]
Draft Specification NDMP Version 4 Protocol February 2001
(j) The DMA will close the connection.
Restore Exceptions
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 recover has been read. This section describes
how that condition should be handled.
(1) Detect end-of-file
(a) The mover on the NDMP server with Tape service 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 server with Tape service 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 server with Data service.
Expires August 2001 [Page 231]
Draft Specification NDMP Version 4 Protocol February 2001
(f) If a continuation tape cannot be located, then the DMA
will send an NDMP_DATA_ABORT message to the NDMP server
with Data service and the recover will be aborted. The
NDMP server with Data service 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
server with Data service will close the data connection to
the NDMP server with Tape service.
(g) The DMA will send an NDMP_DATA_STOP message to return the
NDMP server with Data service to an idle state.
(h) Once the resources have been released the NDMP server with
Data service will return the status to the DMA.
(i) The NDMP server with Tape service will detect the closed
data connection and change itÝs mover state to
NDMP_MOVER_STATE_HALTED. The NDMP server with Tape
service 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
server with Tape service.
(3) No more tape file:
(a) The DMA will send an NDMP_MOVER_CLOSE message to the NDMP
server with Tape service.
(b) The mover will close the connection to the NDMP server
with Data service.
(c) The mover will change itÝs mover state to
NDMP_MOVER_STATE_HALTED. The NDMP server with Tape
service will send an NDMP_NOTIFY_MOVER_HALTED message
with an NDMP_MOVER_CONNECT_CLOSED reason message to
the DMA.
(d) The NDMP server with Data service 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 server with Data service 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 server with Data service to an idle state.
Expires August 2001 [Page 232]
Draft Specification NDMP Version 4 Protocol February 2001
(g) Once the resources have been released the NDMP server with
Data service will return the status to the DMA.
(h) The DMA will send an NDMP_MOVER_STOP message to the NDMP
server with Tape service.
Media error
It is possible for the tape drive to detect a media error while
reading.
(1) Detecting a media error
(a) The NDMP server with Tape service somehow detects a media
error. This is usually detected by the tape drive and
returned by the device driver.
(b) The NDMP server with Tape service will change its mover
status to NDMP_MOVER_STATE_PAUSED and the
mover_paused_reason to NDMP_MOVER_PAUSE_MEDIA_ERROR.
No further processing of data will occur.
(c) The NDMP server with Tape service will send an
NDMP_NOTIFY_MOVER_PAUSED message with an
NDMP_MOVER_PAUSE_MEDIA_ERROR reason to the DMA.
(d) The DMA will send an NDMP_DATA_ABORT message to the NDMP
server with Data service. The NDMP server with Data
service will close the connection to the mover on the NDMP
server with Tape service 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
server with Data service.
(f) Once the resources have been released the NDMP server with
Data service will return the status to the DMA.
(g) The DMA will send an NDMP_MOVER_ABORT message to NDMP
server with Tape service .
(h) The NDMP server with Tape service will change its mover
state to NDMP_MOVER_STATE_HALTED and the reason to
NDMP_MOVER_HALT_ABORTED.
(i) The NDMP server with Tape service will send an
NDMP_NOTIFY_MOVER_HALTED message to the DMA with an
NDMP_MOVER_HALT_ABORTED reason .
(j) The DMA will send an NDMP_MOVER_STOP message to the mover
on the NMDP sever.
Expires August 2001 [Page 233]
Draft Specification NDMP Version 4 Protocol February 2001
(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.
User aborted
It is possible for the user to abort an in progress recover. 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 server with Data
service.
(b) The NDMP server with Tape service 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 server
with Tape service will be closed.
(c) The NDMP server with Tape service will send an
NDMP_NOTIFY_DATA_HALTED message with an
NDMP_DATA_HALT_ABORTED reason to the DMA.
(2) Handling the abort
(a) The DMA host will send an NDMP_DATA_STOP message to the
NDMP server with Data service.
(b) When the NDMP server with Data service 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 server with Tape service with the reason set
to NDMP_MOVER_CONNECT_CLOSED.
(d) The DMA will send an NDMP_MOVER_STOP message to the NDMP
server with Tape service.
(3) Continuing
(a) The DMA may or may not continue with the next recover
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 close the connection to the NDMP server with
Tape service.
Expires August 2001 [Page 234]
Draft Specification NDMP Version 4 Protocol February 2001
Direct access recovers
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 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
server with Tape service 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 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.
(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 server with Tape service.
(7) The NDMP server with Tape service 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.
(8) The NDMP server with Tape service will read the next tape
record, skip the correct number of bytes and continue reading
the data and passing it to the NDMP server with Data service.
Loss of data connection
The loss of data connection can be detected from the NDMP server with
Data service or from the NDMP server with Tape service.
(1) Detected from the NDMP server with Data service:
(a) The NDMP server with Data service gets an error while
reading from the data connection.
Expires August 2001 [Page 235]
Draft Specification NDMP Version 4 Protocol February 2001
(b) The NDMP server with Data service 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 server with Data service will close the
connection to the mover on NDMP server with Tape service.
(d) The NDMP server with Data service 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
server with Data service.
(f) The DMA will send an NDMP_MOVER_ABORT message to the NDMP
server with Tape service.
(g) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
from the NDMP server with Tape service 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 server with Data
service first or receive an NDMP_MOVER_ABORT message.
(2) Detected from the NDMP server with Tape service:
(a) The NDMP server with Tape service gets an error while
writing to the data connection.
(b) The NDMP server with Tape service 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 server with Data
service.
(d) The NDMP server with Data service 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 server with Data service will close the
connection to the mover on NDMP server with Tape service.
(f) The NDMP server with Data service will send an
NDMP_NOTIFY_DATA_HALTED message with an
NDMP_DATA_HALT_ABORTED reason to the DMA.
Expires August 2001 [Page 236]
Draft Specification NDMP Version 4 Protocol February 2001
(g) The DMA will send an NDMP_DATA_STOP message to the NDMP
server with Data service.
(h) Once the resources have been released the NDMP server with
Data service will return the status to the DMA.
(i) The DMA will send an NDMP_MOVER_STOP message to the NDMP
server with Tape service.
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.
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 cdbÝs 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.
(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 cdbÝs to
determine if the jukebox inventory has changed.
(b) The jukebox manager will form and send a SCSI MOVE MEDIUM
cdb to move the tape from the tape drive to its original
location. If this succeeds the jukebox manager continues
as described in the local workflow sections.
Expires August 2001 [Page 237]
Draft Specification NDMP Version 4 Protocol February 2001
(c) 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.
(d) The jukebox manager will form and send a SCSI MOVE MEDIUM
cdb to move the tape from the tape drive to its original
location.
Initializing a jukebox
When The jukebox manager first contacts the jukebox it will form and
send SCSI cdbÝs 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.
(4) The jukebox manager may form and send other SCSI cdbÝs
depending on the product id returned by the SCSI INQUIRY.
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 itÝs physical
inventory, The jukebox manager will form and send a SCSI
INITIALIZE ELEMENT STATUS cdb to cause the jukebox to scan
its physical inventory.
Expires August 2001 [Page 238]
Draft Specification NDMP Version 4 Protocol February 2001
If any SCSI cdb fails the jukebox manager may form and send
additional SCSI cdbÝs to correct the problem.
Tape Duplication
Two TAPE servers can be connected together to copy the contents of a
tape.
(1) DMA will open a communication channel to both NDMP server
with Tape services, 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
server with Tape service 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 server with Tape services to properly position
the tapes for reading/writing.
(c) The DMA will send an NDMP_MOVER_SET_RECORD_SIZE message to
each NDMP server with Tape service to tell them what
record size to use when reading/writing tape.
(3) Connect NDMP server with Tape services.
(a) The DMA will send an NDMP_CONFIG_GET_CONNECTION_TYPE
message to both of the NDMP server with Tape services to
query the type of connections supported.
(b) The DMA will choose the type of connection to be used
between the two NDMP server with Tape services and include
it in the NDMP_MOVER_LISTEN message.
(c) The DMA will send an NDMP_MOVER_LISTEN message to the
destination NDMP server with Tape service.
(d) The DMA will send an NDMP_MOVER_CONNECT message to source
NDMP server with Tape service.
(4) The DMA will initiate a tape copy.
(a) The DMA will send an NDMP_MOVER_READ message to the source
NDMP server with Tape service with the desired offset and
length.
(b) The source NDMP server with Tape service will begin to
read data from the tape drive and write it to the data
connection.
Expires August 2001 [Page 239]
Draft Specification NDMP Version 4 Protocol February 2001
(c) The destination NDMP server with Tape service 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 server with Tape
services.
(a) Both NDMP server with Tape services may send
NDMP_LOG_MESSAGE messages to the DMA to indicate progress.
(b) If an event occurs that requires attention, either of the
NDMP server with Tape services will use an
NDMP_NOTIFY_MOVER_PAUSED message to let the DMA know that
attention is required.
(6) Successful tape duplication completion.
(a) On completion of a successful tape copy the source NDMP
server with tape service will close the connection to the
mover and then send an NDMP_NOTIFY_MOVER_PAUSED message
with NDMP_MOVER_PAUSE_EOM reason to the DMA.
(b) The DMA will issue an NDMP_MOVER_GET_STATE to the source
NDMP server with tape service and save any prudent
information returned for use during the recover process.
(c) The DMA will send an NDMP_MOVER_STOP message to the source
NDMP server with tape service.
(d) Once the source NDMP server with tape service has release
the resources, it will return the status to the DMA.
(e) Since the mover on the destination NDMP server with tape
service detects the disconnection from the source NDMP
server with tape service, destination NDMP server with
tape service sends an NDMP_NOTIFY_MOVER_HALTED message
with NDMP_MOVER_CONNECTION_CLOSED reason to the DMA.
(f) The DMA will issue an NDMP_MOVER_GET_STATE message to the
destination NDMP server with Tape service and note the
total number of bytes generated.
(g) The DMA will send an NDMP_MOVER_STOP message to the
destination NDMP server with Tape service.
(7) If the DMA has no more backups to process
(a) The DMA will use the NDMP TAPE interface on the NDMP
server with Tape service to rewind the tape.
Expires August 2001 [Page 240]
Draft Specification NDMP Version 4 Protocol February 2001
(b) The DMA may choose to use the NDMP TAPE interface to eject
the tape.
(c) The DMA will send NDMP_CONNECT_CLOSE message to close the
connection to both the NDMP server with Tape service.
Exceptions
The previous workflow assumes that there were no problems writing to
tape and that everything fits on a single tape. In this section we
examine some of the exceptions that can occur and how they are
handled.
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 server with Tape
service 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 server with Tape service
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 server with Tape service 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
server with tape service.
(b) The source NDMP server with tape service will discard any
unwritten data and close the connection to the mover on
the destination NDMP server with Tape service
Expires August 2001 [Page 241]
Draft Specification NDMP Version 4 Protocol February 2001
(c) The source NDMP server with tape service 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 server with tape service.
(e) Once the resources have been released the source NDMP
server with tape service 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 server with tape service.
(g) The DMA will send an NDMP_MOVER_STOP message to the
destination NDMP server with tape service.
(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 server
with tape service.
Expires August 2001 [Page 242]
Draft Specification NDMP Version 4 Protocol February 2001
(c) The mover on the destination NDMP server with tape service
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.
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 server with tape service
somehow detects a media error. This is usually detected
by the tape drive and returned by the device driver.
(b) The destination NDMP server with tape service will change
its mover state to NDMP_MOVER_STATE_PAUSED and the
reason to NDMP_MOVER_PAUSE_MEDIA_ERROR.
(c) The destination NDMP server with tape service will send an
NDMP_NOTIFY_MOVER_PAUSED message to the DMA with an
NDMP_MOVER_PAUSE_MEDIA_ERROR reason .
(d) The DMA will send an NDMP_MOVER_ABORT message to the
source NDMP server with tape service. The source NDMP
server with tape service will close the connection to the
mover on the destination NDMP server with tape service and
will change its state to NDMP_MOVER_STATE_HALTED and
the reason to NDMP_MOVER_HALT_ABORTED.
(e) The DMA will send an NDMP_MOVER_STOP message to the source
NDMP server with tape service.
(f) Once the resources have been released the source NDMP
server with tape service will return the status to the
DMA.
(g) The DMA will send an NDMP_MOVER_ABORT message to the
destination NDMP server with tape service .
(h) The destination NDMP server with tape service will change
its mover state to NDMP_MOVER_STATE_HALTED and the
reason to NDMP_MOVER_HALT_ABORTED.
(i) The destination NDMP server with tape service will send an
NDMP_NOTIFY_MOVER_HALTED message to the DMA with an
NDMP_MOVER_HALT_ABORTED reason .
Expires August 2001 [Page 243]
Draft Specification NDMP Version 4 Protocol February 2001
(j) The DMA will send an NDMP_MOVER_STOP message to the mover
on the destination NMDP server with tape service.
(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.
(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.
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 server with
tape service.
(b) The source NDMP server with tape service 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 server with tape service will close the
connection to the mover on the destination NDMP server
with Tape service.
(d) The source NDMP server with tape service 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 server with Data service.
(f) Once the resources have been released the source NDMP
server with tape service will return the status to the
DMA.
(g) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
from the destination NDMP server with Tape service with
the reason set to NDMP_MOVER_CONNECT_CLOSED.
Expires August 2001 [Page 244]
Draft Specification NDMP Version 4 Protocol February 2001
(h) The DMA will send an NDMP_MOVER_STOP message to the
destination NDMP server with Tape service.
(2) Handling the abort
(a) The DMA host will use the NDMP TAPE interface on the NDMP
server with Tape service 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.
(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
server with Tape service to close the connection.
Loss of data connection
The loss of data connection can be detected from the source NDMP
server with tape service or from the destination NDMP server with
tape service.
(1) Detected from the source NDMP server with tape service:
(a) The source NDMP server with tape service gets an error
while writing to the data connection.
(b) The source NDMP server with tape service 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 server with tape service will close the
connection to the mover on destination NDMP server with
tape service.
(d) The source NDMP server with tape service 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 server with tape service.
Expires August 2001 [Page 245]
Draft Specification NDMP Version 4 Protocol February 2001
(f) The DMA will send an NDMP_MOVER_ABORT message to the
destination NDMP server with tape service.
(g) The DMA will receive an NDMP_NOTIFY_MOVER_HALTED message
from the destination NDMP server with tape service 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 server with
tape service first or receive an NDMP_MOVER_ABORT message.
(2) Detected from the destination NDMP server with Tape service:
(a) The destination NDMP server with tape service gets an
error while reading from the data connection.
(b) The destination NDMP server with tape service 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 server with
tape service.
(d) The source NDMP server with tape service 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 server with tape service will close the
connection to the mover on destination NDMP server with
tape service.
(f) The source NDMP server with tape service 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 server with tape service.
(h) Once the resources have been released the source NDMP
server with tape service will return the status to the
DMA.
(i) The DMA will send an NDMP_MOVER_STOP message to the
destination NDMP server with tape service.
Network Copy
Two DATA servers can be connected together to copy a file system.
Expires August 2001 [Page 246]
Draft Specification NDMP Version 4 Protocol February 2001
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 August 2001 [Page 247]