Network Working Group R. Stager, PDC
Internet Draft D. Hitz, Network Appliance
Category: Informational August 1997
PDC/NetApp Backup Protocol
Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups 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.''
To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet-Drafts
Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net
(Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East
Coast), or ftp.isi.edu (US West Coast).
Abstract
The Network Data Management Protocol ('NDMP') is an open protocol
for enterprise-wide network based backup. The NDMP architecture
allows network-attached file servers to ship with a 'universal
agent,' which can be used by any NDMP-compliant backup
administration application. This same universal agent architecture
is also used for network-attached backup devices, such as a tape
drives and tape libraries.
Filename: <draft-stager-pdc-netapp-backup-03.txt >
2
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Expires: March 1998
3
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
1.OVERVIEW ................................................7
1.1 MOTIVATION ...........................................7
1.2 AUDIENCE .............................................7
1.3 TERMINOLOGY ..........................................7
2.ARCHITECTURE ............................................9
2.1 ARCHITECTURAL MODEL ..................................9
2.2 COMPARISON ARCHITECTURES ............................19
2.3 STATE DESCRIPTION ...................................20
2.3.1 The Data state ...................................20
2.3.1.1 ......................................Idle State 22
2.3.1.2 ....................................Active State 22
2.3.1.3 ....................................Halted State 22
2.3.2 The Mover state diagram ..........................23
2.3.2.1 ......................................Idle State 26
2.3.2.2 ....................................Listen State 26
2.3.2.3 ....................................Active State 26
2.3.2.4 ....................................Halted State 27
2.3.2.5 ....................................Paused State 27
2.4 PROTOCOL INTERFACES .................................27
2.4.1 Messages from NDMP Client to NDMP Server .........27
2.4.2 Messages from NDMP Server to NDMP Client .........29
2.5 MESSAGING PROTOCOL ..................................29
2.6 HEADER ..............................................30
2.7 ERROR CODES .........................................33
2.8 MESSAGE NUMBERS .....................................36
2.9 MESSAGE DEFINITIONS .................................38
3.NDMP SERVER INTERFACES .................................39
3.1 CONNECT INTERFACE ...................................39
3.1.1 Open Connection ..................................40
3.1.2 Authorization ....................................40
3.1.3 Close Connection .................................43
3.2 CONFIG INTERFACE ....................................44
3.2.1 Get Host Info ....................................44
3.2.2 Get backup Type Attribute ........................45
3.2.3 Get Mover Type ...................................47
3.2.4 Get authentication Type Attribute ................48
3.3 SCSI INTERFACE ......................................50
3.3.1 Open SCSI Device .................................50
3.3.2 Close Device .....................................52
3.3.3 Get SCSI State ...................................53
3.3.4 Set SCSI Target ..................................54
3.3.5 Reset Device .....................................56
3.3.6 Reset Bus ........................................57
3.3.7 Execute CDB ......................................58
3.4 TAPE INTERFACE ......................................61
3.4.1 Open Tape Device .................................61
4
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
3.4.2 Close Device .....................................63
3.4.3 Get Tape State ...................................64
3.4.4 MTIO .............................................67
3.4.5 Write ............................................70
3.4.6 Read .............................................71
3.4.7 Execute CDB ......................................73
3.5 DATA INTERFACE ......................................73
3.5.1 Get Data State ...................................73
3.5.2 Backup ...........................................76
3.5.3 Recover ..........................................80
3.5.4 Abort ............................................82
3.5.5 Stop .............................................83
3.5.6 Get ENV ..........................................84
3.6 MOVER INTERFACE .....................................85
3.6.1 Get Mover State ..................................85
3.6.2 Listen ...........................................89
3.6.3 Set Record Size ..................................91
3.6.4 Set Window .......................................92
3.6.5 Continue .........................................94
3.6.6 Abort ............................................95
3.6.7 Stop .............................................96
3.6.8 Read .............................................96
3.6.9 Close ............................................98
4.NDMP CLIENT INTERFACES .................................99
4.1 NOTIFY INTERFACE ....................................99
4.1.1 Notify Halted ....................................99
4.1.2 Notify Connected ................................100
4.1.3 Notify Mover Halted .............................101
4.1.4 Notify Mover Paused .............................103
4.1.5 Notify DATA Read ................................104
4.2 LOGGING INTERFACE ..................................104
4.2.1 Log .............................................105
4.2.2 Debug ...........................................105
4.2.3 File Recovered ..................................107
4.3 FILE HISTORY INTERFACE .............................108
4.3.1 Add Unix Path ...................................108
4.3.2 Add Unix Dir ....................................111
4.3.3 Add Unix Node ...................................112
5.REFERENCES ............................................114
6.SECURITY ..............................................114
7.AUTHORS ...............................................114
5
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
FIGURE 1. SIMPLE CONFIGURATION............................11
FIGURE 2. TWO DRIVE CONFIGURATION.........................14
FIGURE 3. JUKEBOX CONFIGURATION...........................16
FIGURE 4. BACKING UP NDMP HOST THROUGH THE NETWORK TO ANOTHER NDMP HOST
.......................................................19
FIGURE 5 - DATA STATE DIAGRAM.............................22
FIGURE 6 - MOVER STATE DIAGRAM............................26
6
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
1. Overview
1.1 Motivation
The purpose of this protocol is to allow a network backup application to
control the backup of an NDMP compliant server using a universal agent
without installing special software on the server.
This separation of control and data 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.
This protocol is specifically intended to support tape drives. This
protocol is targeted towards backup software and there are extensive
references to the tasks of backup and restore. However, the protocol may
be used for other applications in the future.
1.2 Audience
This document is intended for use by software developers to implement
Network Data Management Protocol. The reader is assumed to be familiar
with network protocol specifications and with the general operation of
backup software. The user is not expected to have knowledge of internal
backup software behavior.
1.3 Terminology
NDMP client
The application that controls the NDMP server.
NDMP host
The host that executes the NDMP server application. Data is backed
up from the NDMP host to either a local tape drive or to a backup
device on a remote NDMP host.
NDMP server
7
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
The virtual state machine on the NDMP host that is controlled using
the NDMP protocol. There is one of these for each connection to
the NDMP host. This term is used independent of implementation.
8
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
2. Architecture
2.1 Architectural Model
The architecture is a client server model and backup software is
considered a client to the NDMP server. For every connection between the
client on the backup software host and the NDMP host there is a virtual
state machine on the NDMP host that is controlled using NDMP. This
virtual state machine is referred to as the NDMP server. Each state
machine controls at most one device used to perform backups. The
protocol is a set of XDR encoded messages that are exchanged over a bi-
directional TCP/IP connection and are used to control and monitor the
state of the NDMP server and to collect detailed information about the
data that is backed up.
In the most simple configuration, backup software will backup the data
from the NDMP host to a backup device connected to the NDMP host.
9
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Network Boundary
*
BACKUP HOST * NDMP HOST
*
*
____________________ * ____________________
| NDMP Client | * | NDMP Server |
| |<--NDMP Connection-->| |
|____________________| * |____________________|
* ^ |
* Backup Data | Backup data |
* _______|__ _____V___
* | | | Tape |
* | Disk | | Drive |
* | | | |
* | | |_________|
* |__________|
*
*
Network Boundary
10
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Figure 1. Simple configuration
11
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
It is also possible to use NDMP to simultaneously backup to two backup
devices physically attached to the NDMP host. In this configuration
there are two instances of the NDMP server on the NDMP host.
12
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Network Boundary
*
BACKUP HOST * NDMP HOST
*
*
__________ * ____________
| NDMP | * |NDMP Server |
| Client |<--NDMP Connection-->|____________| ___________
| |<--NDMP Connection--------------------->| NDMP |
|__________| * ^ | | Server |
* Backup| Backup| |__________|
* Data | Data | Backup ^ Backup|
* _____|_ ___V___ Data | Data |
* | | | | | |
* | | |Tape | | |
* | Disk | |Drive | ____|_ ___V__
* | | | | | | | |
* |_______| |______| | | |Tape |
* |Disk | |Drive |
* | | | |
* |______| |______|
*
*
Network Boundary
13
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Figure 2. Two drive configuration
NDMP can be used to backup data to a backup device in a jukebox that is
physically attached to the NDMP host. In this configuration, there is a
separate instance of the NDMP server to control the robotic arm in the
jukebox.
14
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Network Boundary
*
BACKUP HOST * NDMP HOST
*
*
__________ * ____________ ____________
| NDMP | * |NDMP Server | | |
| Client |<--NDMP Connection-->|____________|----|-> Robotics |
| | * ____________ | Control |
| |<--NDMP Connection-->| NDMP Server | | |
|__________| * |_____________|---|-> Tape |
* ^ | Drive |
* Backup| | |
* Data | |Tape Jukebox|
* _____|___ |____________|
* | |
* | |
* | Disk |
* | |
* |_________|
*
*
Network Boundary
15
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Figure 3. Jukebox configuration
16
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
It is possible to backup a host that supports NDMP but does not have a
locally attached backup device by sending the data through a raw TCP/IP
connection to another NDMP host.
17
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Network Boundary
*
BACKUP HOST * NDMP HOST
*
*
__________ * ____________
| NDMP | * |NDMP Server |
| Client |<--NDMP Connection-->|____________|
| | * ^ |
|____^_____| * | |
| * Backup| |
| * Data | |
| * _____|_ |
| * | | |
| * | | |
| * | Disk | |
| * | | | Backup Data Only
| * |_______| |
| * |
****************************************|************ Network Boundary
| * |
| * _____v____
--NDMP Connection----------->| NDMP |
^ | Server |
* ----------
* Backup|
* Data |
* ___V___
* | |
* |Tape |
* |Drive |
* | |
* |______|
*
Network Boundary
18
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Figure 4. Backing up NDMP host through the network to another NDMP host
2.2 Comparison Architectures
It is useful to compare the NDMP architecture to other architectures and
note the similarities and differences.
rmt
The architecture is similar to the rmt architecture in that connection
is made to a generic server and the server is instructed to open a
specific tape drive device. NDMP differs in that it uses a TCP/IP
connection to a dedicated port whereas rmt uses the rsh demon to
launch a server.
X11
The architecture is similar to the X11 architecture in that it uses a
single connection to a TCP/IP port, however it differs in that the NDMP
server is not assigned to a device until the client opens a device and
that there is only one client per NDMP server, whereas X11 is assigned
to a display device before the first client connects and accepts
connections from many clients.
RPC
The NDMP architecture is similar to RPC in that it uses XDR encoding.
NDMP differs in that it is only defined for a TCP/IP connection and that
it is not a call-return model, but rather a bi-directional asynchronous
messaging model.
19
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
2.3 State Description
Two interfaces have states associated with them. The Data interface and
the Mover interface.
2.3.1 The Data state
The following defines the DATA state diagram
20
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
_____________________________________
| |
| |
| ******V******
| * Idle *
| * *
| *************
| | |
| | |
| DATA_start_restore DATA_start_backup
| | |
| \ /
| \ /
| \ /
| \ /
| |
| |
| ******V******
| ___________________* Active *
| | * *
| | __________* *
DATA_stop | | *************
| | | | |
| | | | |
| | | Successful Connection
| Internal DATA_abort Completion Error
| Error | | |
| | | | |
| \ | | /
| \ | | /
| \ | | /
| \ /
| \ /
| \ /
| ****V****V****
| * Halted *
|____________________* *
**************
21
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Figure 5 - data state diagram
The following defines the state machine for the data interface and the
rules for transitions between states.
2.3.1.1 Idle State
This is the start state of the state machine.
Transition to active state upon receipt of ndmp_data_start_backup
message.
Transition to active state upon receipt of ndmp_data_start_restore
message.
2.3.1.2 Active State
The NDMP server remains in this state while a backup or restore is
active.
Transition to halted state upon detection of a backup/restore
error.
Transition to halted state upon receipt of ndmp_data_abort message.
Transition to halted state upon completion of backup/restore.
2.3.1.3 Halted State
The NDMP server enters this state after a backup/restore has either
completed or been aborted.
Transition to idle state upon receipt of ndmp_data_stop message.
22
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
2.3.2 The Mover state diagram
23
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
The following defines the state diagram for the Mover interface
_____________________________________
| |
| |
| ******V******
| * Idle *
| * *
| *************
| |MOVER_listen
MOVER_stop |
| ******V******
| ____________________________* Listening *
| | * *
| | *************
| | |______________________________
| | | |
| |Mover_abort ******V******__ Media Error _| |
| | ___________________* Active *___Detect EOM__ | |
| | | * *___Detect EOF___| |
| | | __________* *___Seek ________| |
| | | | ************* | |
| | | | | | | |
| | | | | | | |
| | | | Connection Connection | MOVER_|
| | Internal MOVER_abort Closed Error |continue
| | Error | | | *******V****** |
| | | | | | * Paused *_|
| | \ | | / * *
| \ \ | | / **************
| \ \ | | / | |
| \ \ / Mover_abort | Mover_close
| \ \ / v_______v
| \ \ / |
| \ ****V****V**** |
| \--------> Halted * |
|___________________* *<----------------------------
**************
24
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
25
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Figure 6 - Mover state diagram
2.3.2.1 Idle State
This is the start state of the state machine.
Transition to listen state upon receipt of ndmp_mover_listen
message.
2.3.2.2 Listen State
The NDMP server remains in this state while waiting for a connection
from either a local or remote NDMP data server.
Transition to active state upon establishment of connection with
NDMP data server.
Transition to halted state upon receipt of ndmp_mover_abort
message.
2.3.2.3 Active State
The NDMP server remains in this state while a backup or restore is
active.
Transition to halted state upon detection of an internal error.
Transition to halted state upon receipt of ndmp_mover_abort
message.
Transition to halted state upon detection of a connection error.
Transition to halted state upon detection of connection close.
Transition to paused state upon detection of EOM.
Transition to paused state upon detection of EOF.
26
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Transition to paused state upon detection of media error.
Transition to paused state upon reaching end of data window.
2.3.2.4 Halted State
The NDMP server enters this state after a backup/restore has either
completed or been aborted.
Transition to idle state upon receipt of ndmp_mover_stop message.
2.3.2.5 Paused State
The NDMP server remains in this state while awaiting for a tape volume
to be changed.
Transition to active state upon receipt of ndmp_mover_continue
message.
Transition to halted state upon receipt of ndmp_mover_abort
message.
Transition to halted state upon receipt of ndmp_mover_close
message.
2.4 Protocol Interfaces
Messages are grouped together by functionality into several
_interfaces_.
2.4.1 Messages from NDMP Client to NDMP Server
The NDMP server must implement the following interfaces
. CONNECT interface
This interface will be used after a client first establishes a
connection to an NDMP server. This interface allows the NDMP server to
authenticate the client and negotiate the version of protocol used.
27
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
. CONFIG interface
This interface allows NDMP client to discover the configuration of the
NDMP server. It can be used to discover NDMP server configuration and
attributes.
. SCSI interface
This interface is used to pass SCSI CDBs through to a SCSI device and
retrieve the resulting SCSI status. The NDMP client will use this
interface to control a locally attached jukebox. Software on the NDMP
client will construct SCSI CDBs and will interpret the returned status
and data. This interface can also be used to exploit special features
of SCSI backup devices.
. TAPE interface
The TAPE interface will support both tape positioning and tape
read/write operations. The NDMP client will typically use this interface
to write tape volume header and trailer files. The NDMP client will also
use this interface for positioning the tape during backups and restores.
. DATA interface
This is the interface that actually deals with the format of the backup
data. The NDMP client will initiate backups and restores using this
interface. The NDMP client provides all of the parameters that may
affect the backup or restore using this interface. The NDMP client does
not place any constraints on the format of the backup data other than it
must be a stream of data that can be written to the tape device.
. MOVER interface
This interface is used to control the reading/writing of backup data
from/to a tape device. During a backup the mover reads data from the
data connection, buffers the data into tape records, and writes the data
to the tape device. During a restore the mover reads data from the tape
device and writes the data to the data connection. The mover is
responsible for handling tape exceptions and notifying the NDMP client.
28
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
2.4.2 Messages from NDMP Server to NDMP Client
The NDMP server's implementation may send the following messages to the
NDMP client. All of the messages that the NDMP client accepts are
asynchronous. None of these messages will generate a reply message.
. NOTIFY interface
This message is used by the NDMP server to notify the NDMP client that
the NDMP server requires attention.
. FILE HISTORY interface
These messages allow the NDMP server to make entries in the file history
for the current backup. The file history will be used by the NDMP client
to select files for retrieval.
. LOGGING interface
These messages allow the NDMP server to make entries in the backup log.
This is used by the operator to monitor the progress and completion
status of the backup. It is also used to diagnose problems.
2.5 Messaging Protocol
The NDMP protocol is based on XDR encoded messages transmitted over a
TCP/IP connection.
NDMP messages are asynchronous. Not all request messages have an
associated reply message. An NDMP message consists of a message header
optionally followed by a message body. Each message is identified by a
message number that is sent as part of the message header. Each message
(message header plus message body) will be XDR encoded and sent within a
single XDR record.
Messages that cannot be parsed or have invalid sequence information may
be logged on the receiving host but no response is returned to the
sender.
29
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
2.6 Header
Each message is preceded by a message header. The header is used to
identify the message and defines how to de-serialize the arguments and
dispatch the message.
30
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
31
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
The message headers are defined by the following XDR block
enum ndmp_header_message_type
{
NDMP_MESSAGE_REQUEST,
NDMP_MESSAGE_REPLY
};
struct ndmp_header
{
u_long sequence;
u_long time_stamp;
ndmp_header_message_type message_type;
enum ndmp_message message;
u_long reply_sequence;
ndmp_error error;
};
Message header data definitions:
sequence The sequence number is a connection local
counter that starts at 1 and increases by 1 for
every message sent. The client and the server
both start with 1 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 whether the
message is a request or a reply message.
message The message field identifies the message.
reply_sequence The reply_sequence field is 0 in a request
message. In reply messages, the reply_sequence
is the sequence number from the request message
to which the reply is associated.
32
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
error The error field is 0 in request messages. In
reply messages, the error field identifies any
problem that was incurred receiving or decoding
the message. If the error value is non-zero,
no message body will follow the message
header. The complete list of error codes is
provided in the next section.
2.7 Error Codes
The following error codes are defined:
enum ndmp_error
{
NDMP_NO_ERR,
NDMP_NOT_SUPPORTED_ERR,
NDMP_DEVICE_BUSY_ERR,
NDMP_DEVICE_OPENED_ERR,
NDMP_NOT_AUTHORIZED_ERR,
NDMP_PERMISSION_ERR,
NDMP_DEV_NOT_OPEN_ERR,
NDMP_IO_ERR,
NDMP_TIMEOUT_ERR,
NDMP_ILLEGAL_ARGS_ERR,
NDMP_NO_TAPE_LOADED_ERR,
NDMP_WRITE_PROTECT_ERR,
NDMP_EOF_ERR,
NDMP_EOM_ERR,
NDMP_FILE_NOT_FOUND_ERR,
NDMP_BAD_FILE_ERR,
NDMP_NO_DEVICE_ERR,
NDMP_NO_BUS_ERR,
NDMP_XDR_DECODE_ERR,
NDMP_ILLEGAL_STATE_ERR,
NDMP_UNDEFINED_ERR,
NDMP_XDR_ENCODE_ERR,
NDMP_NO_MEM_ERR
};
NDMP_NO_ERR
33
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
No error.
NDMP_NOT_SUPPORTED_ERR
Specified message not supported. Some NDMP implementations may
only support a subset of the NDMP protocol.
NDMP_DEVICE_BUSY_ERR
Specified device is in use. This error will be returned if an
attempt is made to open a tape or SCSI device that is already in
use.
NDMP_DEVICE_OPENED_ERR
A device is already open. NDMP connections are limited to having a
single device opened at a time.
NDMP_NOT_AUTHORIZED_ERR
NDMP connection not yet authenticated. Prior to issuing most
requests, the NDMP connection must first be authenticated via the
connect_auth message. This error is returned if a message requiring
connection authentication is received when the connection has not
yet been authenticated.
NDMP_PERMISSION_ERR
The user that was used to authenticate the connection does not have
the access permissions to execute this message.
NDMP_DEV_NOT_OPEN_ERR
Device not open. An attempt was made to access a device that was
not open.
NDMP_IO_ERR
34
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Device I/O error.
NDMP_TIMEOUT_ERR
Command timeout error.
NDMP_ILLEGAL_ARGS_ERR
Message received containing one or more invalid arguments.
NDMP_NO_TAPE_LOADED_ERR
Tape device could not be opened because no tape was loaded.
NDMP_WRITE_PROTECT_ERR
Tape device could not be opened in write mode because the tape is
write protected.
NDMP_EOF_ERR
The tape command failed because end of file was encountered.
NDMP_EOM_ERR
The tape command failed because the end of media mark was
encountered.
NDMP_FILE_NOT_FOUND_ERR
During a recover operation, a specified file was not found.
NDMP_BAD_FILE_ERR
35
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Error due to invalid file descriptor.
NDMP_NO_DEVICE_ERR
Specified device does not exist.
NDMP_NO_BUS_ERR
Specified SCSI controller does not exist.
NDMP_XDR_DECODE_ERR
Error decoding message.
NDMP_ILLEGAL_STATE_ERR
Message cannot be processed in the current state.
NDMP_UNDEFINED_ERR
Undefined error.
NDMP_XDR_ENCODE_ERR
Error encoding reply message.
NDMP_NO_MEM_ERR
Memory allocation error.
2.8 Message Numbers
The following messages are defined:
36
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
enum ndmp_message
{
/* Config Interface */
NDMP_CONFIG_GET_HOST_INFO = 0x100,
NDMP_CONFIG_GET_BUTYPE_ATTR,
NDMP_CONFIG_GET_MOVER_TYPE,
NDMP_CONFIG_GET_AUTH_TYPE_ATTR,
/* SCSI Interface */
NDMP_SCSI_OPEN = 0x200,
NDMP_SCSI_CLOSE,
NDMP_SCSI_GET_STATE,
NDMP_SCSI_SET_TARGET,
NDMP_SCSI_RESET_DEVICE,
NDMP_SCSI_RESET_BUS,
NDMP_SCSI_EXECUTE_CDB,
/* Tape Interface */
NDMP_TAPE_OPEN = 0x300,
NDMP_TAPE_CLOSE,
NDMP_TAPE_GET_STATE,
NDMP_TAPE_MTIO,
NDMP_TAPE_WRITE,
NDMP_TAPE_READ,
NDMP_TAPE_RESVD1,
NDMP_TAPE_EXECUTE_CDB,
/* Data Interface */
NDMP_DATA_GET_STATE = 0x400,
NDMP_DATA_START_BACKUP,
NDMP_DATA_START_RECOVER,
NDMP_DATA_ABORT,
NDMP_DATA_GET_ENV,
NDMP_DATA_RESVD1,
NDMP_DATA_RESVD2,
NDMP_DATA_STOP,
/* Notify Interface */
NDMP_NOTIFY_RESVD1 = 0x500,
NDMP_NOTIFY_HALTED,
NDMP_NOTIFY_CONNECTED,
NDMP_NOTIFY_MOVER_HALTED,
NDMP_NOTIFY_MOVER_PAUSED,
NDMP_NOTIFY_DATA_READ,
37
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* Log Interface */
NDMP_LOG_LOG = 0x600,
NDMP_LOG_DEBUG,
NDMP_LOG_FILE,
/* File History Interface */
NDMP_FH_ADD_UNIX_PATH = 0x700,
NDMP_FH_ADD_UNIX_DIR,
NDMP_FH_ADD_UNIX_NODE,
/* Connect Interface */
NDMP_CONNECT_OPEN = 0x900,
NDMP_CONNECT_AUTH,
NDMP_CONNECT_CLOSE,
/* Mover Interface */
NDMP_MOVER_GET_STATE = 0xA00,
NDMP_MOVER_LISTEN,
NDMP_MOVER_CONTINUE,
NDMP_MOVER_ABORT,
NDMP_MOVER_STOP,
NDMP_MOVER_SET_WINDOW,
NDMP_MOVER_READ,
NDMP_MOVER_CLOSE,
NDMP_MOVER_SET_RECORD_SIZE,
/* Reserved for prototyping */
NDMP_RESERVED = 0xF00
};
2.9 Message Definitions
Each message is described using a block of XDR specification in the
following format:
38
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
struct message_name_request
{
type request_argument1;
...
type request_argumentN;
};
struct message_name_reply
{
enum ndmp_error error;
type reply_argument1;
...
type reply_argumentN;
};
Each XDR specification conforms to rpcgen format. No XDR specification
is provided for the request message if the request message does not
contain any arguments. No XDR specification is provided for the reply
message if the reply message does not contain any argument or if no
reply message is defined. Not all request messages have an associated
reply message. Following the XDR specification is a description of each
request and reply argument. Each reply message contains an error code.
If an error code is returned that is not equal to NDMP_NO_ERR, some of
the reply arguments 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_MEMORY are not listed.
3. NDMP Server Interfaces
This section defines the protocol interfaces implemented by the NDMP
server.
3.1 CONNECT Interface
This interface is used to authenticate the client and negotiate the
version of protocol which will be used.
The NDMP client first connects to a well known port (10,000). The NDMP
server accepts the connection and sends a NOTIFY_CONNECT message. The
NDMP client then sends a CONNECT_OPEN message, usually followed by a
CONNECT_AUTH message.
39
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
3.1.1 Open Connection
Used to negotiate the protocol version to be used between the NDMP
client and server.
Message XDR definition
/* NDMP_CONNECT_OPEN */
struct ndmp_connect_open_request
{
u_short protocol_version;
};
struct ndmp_connect_open_reply
{
ndmp_error error;
};
Request Arguments
protocol_version Protocol version suggested by the NDMP client.
Reply Errors
NDMP_NO_ERR Protocol version suggested by the client is
supported by the server.
NDMP_ILLEGAL_ARGS_ERR Protocol version suggested by the client is not
supported by the server. The client should
retry the request with a lower protocol version
number.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
3.1.2 Authorization
Used to authenticate the NDMP connection. Only request messages within
the config interface may be processed on a connection that has not yet
been authenticated. A reply message containing an
40
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_NOT_AUTHORIZED_ERR error will be returned in response to any other
request message received when the connection has not yet been
authenticated.
NDMP servers must support at least one of the following authentication
methods.
1. NONE: no authentication required.
2. TEXT: connection is authenticated using a user name and non-
encrypted password.
3. MD5: connection is authenticated using a MD5 digest
Message XDR definition
41
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_CONNECT_AUTH */
enum ndmp_auth_type
{
NDMP_AUTH_NONE,
NDMP_AUTH_TEXT,
NDMP_AUTH_MD5
};
struct ndmp_auth_text
{
string user <>;
string password<>;
};
struct ndmp_auth_md5
{
string user <>;
opaque 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_auth_request
{
ndmp_auth_data auth_data;
};
struct ndmp_connect_auth_reply
{
ndmp_error error;
};
Request Arguments
42
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
auth_data Authentication data. NDMP servers must support
at least one of the following authentication
methods:
NONE: no authentication required.
TEXT: connection is authenticated using a user
name and non-encrypted password.
MD5: connection is authenticated using user
name and MD5 digest of the user password and
the per session challenge from the
NDMP_CONFIG_GET_AUTH_TYPE_ATTR message.
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.
3.1.3 Close Connection
This message is used when client wants to close the NDMP connection.
This message should be sent by the NDMP client before shutting down the
TCP/IP connection.
Message XDR definition
/* NDMP_CONNECT_CLOSE */
/* no request arguments */
/* no reply message */
43
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
3.2 CONFIG Interface
This interface allows the NDMP client to discover the configuration of
the NDMP server.
3.2.1 Get Host Info
This request is used to get information about the NDMP server.
Message XDR definition
/* NDMP_CONFIG_GET_HOST_INFO */
/* no request arguments */
struct ndmp_config_get_host_info_reply
{
ndmp_error error;
string hostname<>;
string os_type<>;
string os_vers<>;
string hostid<>;
ndmp_auth_type auth_type<>;
};
Request Arguments
This request does not have a message body.
Reply Arguments
error Error code.
hostname Host name of the NDMP server
os_type Name of NDMP server operating system (i.e.
Solaris).
44
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
os_vers Version of NDMP server operating system (i.e.
2.5).
hostid NDMP server host identifier.
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.2 Get backup Type Attribute
This message is used to query the capability of the supported backup
type.
Message XDR definition
/* NDMP_CONFIG_GET_BUTYPE_ATTR */
const NDMP_NO_BACKUP_FILELIST = 0x0001;
const NDMP_NO_BACKUP_FHINFO = 0x0002;
const NDMP_NO_RECOVER_FILELIST = 0x0004;
const NDMP_NO_RECOVER_FHINFO = 0x0008;
const NDMP_NO_RECOVER_RESVD = 0x0010;
const NDMP_NO_RECOVER_INC_ONLY = 0x0020;
struct ndmp_config_get_butype_attr_request
{
string name <>;
};
struct ndmp_config_get_butype_attr_reply
{
ndmp_error error;
u_long attrs;
};
45
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Request Arguments
name Name of backup type for which attributes are
being requested (e.g. dump, tar, cpio). Backup
types are NDMP server implementation dependent.
Reply Arguments
error Error code.
attrs Backup attributes bit mask. The following
attribute bits are defined:
NDMP_NO_BACKUP_FILELIST NDMP server doesn't support
archiving of selective files as specified
by a file list. (i.e. only supports
dumping the entire specified
filesystem/directory.)
NDMP_NO_BACKUP_FILEINFO NDMP server doesn't support the file
history.
NDMP_NO_RECOVER_FILELIST NDMP server doesn't support
restoration of individual files.
NDMP_NO_RECOVER_FHINFO NDMP server doesn't support the
direct access restore (i.e. positioning to
the offset of a backup image and restoring
the specified file).
NDMP_NO_RECOVER_RESVD This value is reserved.
NDMP_NO_RECOVER_INC_ONLY NDMP server doesn't support
incremental only restoration (i.e. a full
46
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
restore must be performed prior to an
incremental restore).
Reply Errors
NDMP_NO_ERR Attributes for specified backup type
successfully returned.
NDMP_ILLEGAL_ARGS_ERR Specified backup type not supported.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
3.2.3 Get Mover Type
This request returns a list of the connection methods which NDMP server
supports. LOCAL and TCP are the only types supported in the current
version of the protocol.
Message XDR definition
/* NDMP_CONFIG_GET_MOVER_TYPE */
/* no request arguments */
enum ndmp_mover_addr_type
{
NDMP_ADDR_LOCAL,
NDMP_ADDR_TCP
};
struct ndmp_config_get_mover_type_reply
{
ndmp_error error;
ndmp_mover_addr_type methods<>;
};
Request Arguments
This request does not have a message body.
47
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Arguments
error Error code.
methods Array of supported mover methods.
Reply Errors
NDMP_NO_ERR Return the supported mover type successfully.
NDMP_NOT_SUPPORTED_ERR The request sequence is not supported for this
implementation.
3.2.4 Get authentication Type Attribute
This message is used to query the attributes of the supported
authentication methods.
Message XDR definition
48
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_CONFIG_GET_AUTH_ATTR */
union ndmp_auth_attr_request
switch (enum ndmp_auth_type auth_type){
case NDMP_AUTH_NONE:
void;
case NDMP_AUTH_TEXT:
void;
case NDMP_AUTH_MD5:
void;
};
union ndmp_auth_attr_reply
switch (enum ndmp_auth_type auth_type){
case NDMP_AUTH_NONE:
void;
case NDMP_AUTH_TEXT:
void;
case NDMP_AUTH_MD5:
opaque challenge<>;
};
struct ndmp_config_get_auth_attr_request
{
union ndmp_auth_attr_request attr;
};
struct ndmp_config_get_auth_attr_reply
{
ndmp_error error;
union ndmp_auth_attr_reply attr;
};
Request Arguments
none None of the currently define authentication
schemes require arguments.
Reply Arguments
error Error code.
49
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
attrs Return the attributes required for a specific
authentication scheme:
The following attributes are defined:
challenge For NDMP_AUTH_MD5 the NDMP server will return
a per session challenge.
3.3 SCSI Interface
The SCSI interface allows low level control of SCSI jukebox devices.
3.3.1 Open SCSI Device
Opens the specified SCSI device. This operation is required before any
other SCSI requests can be executed. The open must be an exclusive open.
Only one NDMP server can open a SCSI device at a time. The NDMP server
can only open one SCSI or tape device at a time. An NDMP_DEVICE_BUSY_ERR
is returned if the NDMP server already has a tape or SCSI device opened.
For security reasons, NDMP_SCSI_OPEN should only be supported for tape
and jukebox devices.
Message XDR definition
50
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_SCSI_OPEN */
struct ndmp_scsi_device
{
string name<>;
};
struct ndmp_scsi_open_request
{
ndmp_scsi_device device;
};
struct ndmp_scsi_open_reply
{
ndmp_error error;
};
Request Arguments
name Name of SCSI interface device to open. The
usage of this argument is NDMP server
implementation dependent. This argument may be
used to specify the name of an actual SCSI
device but more typically will be used to
specify the name of a SCSI pass-through driver
pseudo device. The specific device to be
controlled is selected via the set SCSI target
request.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR SCSI interface device successfully opened.
51
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_DEVICE_OPENED_ERR The connection already has a tape device or
SCSI device open.
NDMP_DEVICE_BUSY_ERR Another NDMP connection currently has the
specified device open.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized or device is not
a tape or jukebox.
NDMP_NO_DEVICE_ERR Invalid device specified.
NDMP_IO_ERR IO error while opening SCSI device.
3.3.2 Close Device
Closes the currently open SCSI interface device. No further requests
may 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
52
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
This request does not have a message body.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Device successfully closed.
NDMP_DEV_NOT_OPEN_ERR No device currently open by the connection.
NDMP_NOT_SUPPORTED_ERR The request sequence is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.3.3 Get SCSI State
Return the current state of the SCSI interface. The target information
provides information about which SCSI device is controlled by this
interface.
Message XDR definition
/* NDMP_SCSI_GET_STATE */
/* no request arguments */
struct ndmp_scsi_get_state_reply
{
ndmp_error error;
short target_controller;
short target_id;
short target_lun;
};
53
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Request Arguments
This request does not have a message body.
Reply Arguments
error Error code.
target_controller Identifier of the SCSI controller to which the
currently targeted SCSI device is attached. -1
if no device currently targeted.
target_id SCSI target identifier. Specifies the SCSI bus
address of the targeted device. -1 if no device
currently targeted.
target_lun Logic unit number of the targeted device. -1 if
no device currently targeted.
Reply Errors
NDMP_NO_ERR Target device information successfully
returned.
NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the
connection.
NDMP_NOT_SUPPORTED_ERR The request sequence is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.3.4 Set SCSI Target
Selects or changes the SCSI target. When the SCSI interface is opened,
it is not known if the NDMP server has opened a device file that can
pass commands to a single SCSI target or to multiple SCSI targets. This
request is used to pass the information describing the SCSI target to
which to send commands. Additionally, if the target can talk to multiple
54
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
targets, this allows _scanning_ the SCSI bus on the NDMP host for
diagnostics or for jukebox discovery.
For security reasons this message should only be supported for tape or
jukebox devices.
Message XDR definition
/* NDMP_SCSI_SET_TARGET */
struct ndmp_scsi_set_target_request
{
ndmp_scsi_device device;
u_short target_controller;
u_short target_id;
u_short target_lun;
};
struct ndmp_scsi_set_target_reply
{
ndmp_error error;
};
Request Arguments
device SCSI device name. This argument is NDMP server
implementation dependent. Some implementations
may support the targeting of a device via a
logical device name. If this argument is used,
the following arguments may be ignored. If
this argument is not specified or supported,
then the following arguments must be specified.
target_controller Identifier of the SCSI controller to which the
targeted SCSI device is attached.
target_id SCSI target identifier. Specifies the SCSI bus
address of the targeted device.
target_lun Logic unit number of the targeted device.
55
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Specified SCSI device successfully targeted.
NDMP_NO_BUS_ERR No SCSI device currently open by the
connection.
NDMP_NO_DEVICE_ERR No device at this specified target.
NDMP_NOT_SUPPORTED_ERR The request sequence is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized or device is not
a tape or jukebox.
3.3.5 Reset Device
Send a SCSI device reset message to the currently targeted SCSI device.
Message XDR definition
/* NDMP_SCSI_RESET_DEVICE */
/* no request arguments */
struct ndmp_scsi_reset_device_reply
{
ndmp_error error;
};
Request Arguments
This request does not have a message body.
56
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
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 for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.3.6 Reset Bus
Assert a SCSI bus reset on the SCSI bus to which the SCSI device is
attached.
Message XDR definition
/* NDMP_SCSI_RESET_BUS */
/* no request arguments */
struct ndmp_scsi_reset_bus_reply
{
ndmp_error error;
};
Request Arguments
This request does not have a message body.
57
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
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 sequence is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.3.7 Execute CDB
Send a SCSI Control Data Block to a SCSI device. If a check condition is
generated, then the extended sense data is also retrieved. Data can be
transferred to or from the SCSI device as part of the command.
The server selects the SCSI target. The cdb is sent to the SCSI device
in command mode. If DATA_OUT is set in the flags, then the dataout is
sent to the SCSI device in data mode. Sometimes the host will disconnect
from the target and wait for a re-select. If timeout is zero, the host
will wait indefinitely for the target to re-select. If timeout is non-
zero, the host will wait timeout milliseconds for the target to
reselect. If the reselect does not occur, an NDMP_TIMEOUT_ERR is
returned. If the target re-selects and the status is CHECK CONDITION,
then the server executes a REQUEST SENSE cdb. If the DATA_IN flag is
set, the server reads data from the target in data mode. The SCSI
status, the datain and the extended sense data are returned.
Message XDR definition
58
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_SCSI_EXECUTE_CDB */
const NDMP_SCSI_DATA_IN = 0x00000001;
const NDMP_SCSI_DATA_OUT = 0x00000002;
struct ndmp_execute_cdb_request
{
u_long flags;
u_long timeout;
u_long datain_len;
opaque cdb<>;
opaque dataout<>;
};
struct ndmp_execute_cdb_reply
{
ndmp_error error;
u_char status;
u_long dataout_len;
opaque datain<>;
opaque ext_sense<>;
};
Request Arguments
flags Specifies the data transfer (if any) direction.
DATA_IN and DATA_OUT are with reference to the
host. They refer to data from the SCSI device
into the host and data out of the host to the
SCSI device.
timeout Number of milliseconds to wait if a re-select
occurs. If timeout is zero then the host will
wait indefinitely for the target to reselect.
datain_len If the data transfer direction is DATA_IN, the
expected number of data bytes to read.
cdb The SCSI command data block.
59
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
dataout If the data transfer direction is DATA_OUT, the
data to be transfered to the SCSI device.
Reply Arguments
error Error code.
status SCSI status byte.
dataout If the data transfer direction is DATA_OUT, the
number of data bytes transfered to the device.
datain If the data transfer direction is DATA_IN, the
data transfered from the SCSI device.
ext_sense Extended SCSI sense data.
Reply Errors
NDMP_NO_ERR Message successfully processed. Does not
necessarily indicate that the SCSI command was
successfully executed. The returned SCSI status
byte must be used to determine if the command
was successful.
NDMP_DEV_NOT_OPEN_ERR No SCSI device currently open by the
connection.
NDMP_IO_ERR I/O error.
NDMP_ILLEGAL_ARGS Invalid argument in request message.
NDMP_TIMEOUT_ERR The SCSI command timed out.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
60
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.4 TAPE Interface
Provide complete control of a tape drive. If the tape drive is a SCSI
tape drive, then this interface also provides low level CDB access to
the tape drive. This interface is analogous to the rmt protocol. The
physical device is assigned when the server is started.
3.4.1 Open Tape Device
Opens the tape device in the specified mode. This operation is required
before any other tape requests can be executed. The device is opened
exclusively; no other NDMP server may concurrently open the device.
Each tape device may only be opened by one NDMP server at a time. Each
NDMP server may only have one tape or SCSI device open at a time. If the
drive does not have a tape loaded, an error is returned. If the loaded
media is write protected, then the device may only be opened in read
only mode.
Message XDR definition
61
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_TAPE_OPEN */
struct ndmp_tape_device
{
string name<>;
};
enum ndmp_tape_open_mode
{
NDMP_TAPE_READ_MODE,
NDMP_TAPE_WRITE_MODE
};
struct ndmp_tape_open_request
{
ndmp_tape_device device;
ndmp_tape_open_mode mode;
};
struct ndmp_tape_open_reply
{
ndmp_error error;
};
Request Arguments
device Name of tape device to open.
mode Tape open mode.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Tape device successfully opened.
NDMP_DEVICE_OPENED_ERR The NDMP server already has a SCSI device or
tape device open.
62
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_NO_DEVICE_ERR The specified device does not exist.
NDMP_DEVICE_BUSY_ERR The device is already open by another NDMP
server or system process.
NDMP_IO_ERR Device I/O error.
NDMP_WRITE_PROTECT_ERR Device can not 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.
3.4.2 Close Device
Close the tape drive. No further tape requests can be processed until
another tape open request is successfully executed.
Message XDR definition
/* NDMP_TAPE_CLOSE */
/* no request arguments */
struct ndmp_tape_close_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
63
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Tape device successfully closed.
NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
connection.
NDMP_IO_ERR Device I/O error.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.4.3 Get Tape State
Return the state of the tape drive interface.
Message XDR definition
64
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_TAPE_GET_STATE */
/* no request arguments */
struct ndmp_u_quad
{
u_long high;
u_long low;
};
const NDMP_TAPE_NOREWIND = 0x0008;
const NDMP_TAPE_WR_PROT = 0x0010;
const NDMP_TAPE_ERROR = 0x0020;
const NDMP_TAPE_UNLOAD = 0x0040;
struct ndmp_tape_get_state_reply
{
ndmp_error error;
u_long flags;
u_long file_num;
u_long soft_errors;
u_long block_size;
u_long blockno;
ndmp_u_quad total_space;
ndmp_u_quad space_remain;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error Error code.
flags Bitmask of the following tape device mode
flags:
65
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_TAPE_NOREWIND Upon device close, the tape will not be
rewound.
NDMP_TAPE_WR_PROT The loaded tape is write-protected.
NDMP_TAPE_ERROR A media error was detected during the previous
tape operation. This bit is cleared at the
start of each tape operation.
NDMP_TAPE_UNLOAD The currently loaded tape will automatically be
unloaded when the device is closed. Only
applies to media changer devices such as tape
stackers and jukeboxes.
file_num Current file position. First file on the tape
is file number 0.
soft_errors Total number of soft media errors detected
since the device was opened.
block_size Tape block size in bytes. 0 if the device is in
variable block size mode.
blockno Current tape block number. First tape block is
block number 0.
total_space Total tape capacity in bytes. 0 if this feature
not supported by the NDMP server
implementation.
space_remain Total remaining tape capacity in bytes. 0 if
this feature not supported by the NDMP server
implementation.
Reply Errors
NDMP_NO_ERR Tape state successfully returned.
66
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
connection.
NDMP_NOT_SUPPORTED_ERR The request sequence is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
NDMP_IO_ERR Device I/O error.
3.4.4 MTIO
Provides access to the standard magnetic tape I/O operations. When
spacing forward over a record, the tape head is positioned in the tape
gap between the record just skipped and the next record. When spacing
forward over file marks, the tape head is positioned in the tape gap
between the next file mark and the record that follows it. When spacing
backward over a record data, the tape head is positioned in the tape gap
immediately preceding the tape record where the tape head is currently
positioned. When spacing backward over file marks, the tape head is
positioned in the tape gap preceding the file mark the next read would
fetch the EOF.
Message XDR definition
67
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_TAPE_MTIO */
enum ndmp_tape_mtio_op
{
NDMP_MTIO_FSF,
NDMP_MTIO_BSF,
NDMP_MTIO_FSR,
NDMP_MTIO_BSR,
NDMP_MTIO_REW,
NDMP_MTIO_EOF,
NDMP_MTIO_OFF
};
struct ndmp_tape_mtio_request
{
ndmp_tape_mtio_op tape_op;
u_long count;
};
struct ndmp_tape_mtio_reply
{
ndmp_error error;
u_long resid_count;
};
Request Arguments
tape_op One of the following tape operations:
NDMP_MTIO_FSF Forward space over file marks. The tape head is
positioned in the tape gap between the file
mark and the record that follows it.
NDMP_MTIO_BSF Backward space over file marks. The tape head
is positioned in the tape gap preceding the
file mark such that the next read encounters
EOF.
NDMP_MTIO_FSR Forward space over tape records. The tape head
is positioned in the tape gap between the
record just skipped and the next record.
68
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_MTIO_BSR Backward space over tape records. The tape head
is positioned in the tape gap preceding the
tape record just skipped.
NDMP_MTIO_REW Rewind the tape.
NDMP_MTIO_EOF Write end of file marks.
NDMP_MTIO_OFF Eject the tape from the device.
count Number of operations to perform.
Reply Arguments
error Error code.
resid_count Residual operation count. Represents the number
of operations that were not able to be
performed 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 sequence is not supported for this
implementation.
69
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
NDMP_WRITE_PROTECT_ERR Tape is write protected.
3.4.5 Write
Writes data to the tape device. The NDMP server writes the specified
data as a single record. It is the responsibility of the NDMP client to
ensure that the length of the data is a multiple of the tape device
block size if the device is a fixed block device. The NDMP server
performs no buffering or padding of the data. . This request is
typically used by the NDMP client to write tape header and trailer file
data.
Message XDR definition
/* NDMP_TAPE_WRITE */
struct ndmp_tape_write_request
{
opaque data_out<>;
};
struct ndmp_tape_write_reply
{
ndmp_error error;
u_long count;
};
Request Arguments
data_out The data to be written to the tape device.
Reply Arguments
error Error code.
count Number of data bytes written.
70
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
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.
NDMP_EOM_ERR End of tape was encountered while writing.
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.
3.4.6 Read
Reads the requested amount of data from the tape drive. The NDMP server
always reads a complete record. If the specified number of bytes to read
is not a multiple of the tape record size, then the NDMP server discards
the bytes from the end of the record. The next read will return bytes
starting from the beginning of the next record. To perform contiguous
reads, the number of bytes read must be a multiple of the tape record
size. The client is responsible for ensuring that the data length is a
multiple of the tape record size if the tape device is in fixed block
size mode.
Message XDR definition
71
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_TAPE_READ */
struct ndmp_tape_read_request
{
u_long count;
};
struct ndmp_tape_read_reply
{
ndmp_error error;
opaque data_in<>;
};
Request Arguments
count Number of bytes to read.
Reply Arguments
error Error code.
data_in The data read from the tape drive.
Reply Errors
NDMP_NO_ERR Requested number of bytes successfully read
from the tape device.
NDMP_DEV_NOT_OPEN_ERR No tape device currently open by the
connection.
NDMP_IO_ERR Device I/O error during read.
NDMP_EOF_ERR End of file was encountered while reading. The
number of returned data bytes may be less than
the number of bytes requested.
72
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_NOT_SUPPORTED_ERR The request sequence is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.4.7 Execute CDB
This message behaves in exactly the same way as the SCSI_EXECUTE_CDB
request except that it sends the cdb to the tape device. This request
should not be used to change the state of the tape device (e.g. tape
positioning).
Message XDR definition
/* NDMP_TAPE_EXECUTE_CDB */
typedef ndmp_scsi_execute_cdb_request ndmp_tape_execute_cdb_request;
typedef ndmp_scsi_execute_cdb_reply ndmp_tape_execute_cdb_reply;
3.5 DATA Interface
Controls backup and recover operations.
3.5.1 Get Data State
Returns data state information that may be used for monitoring the
progress of the current data operation.
Message XDR definition
73
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_DATA_GET_STATE */
/* no request arguments */
enum ndmp_data_operation
{
NDMP_DATA_OP_NOACTION,
NDMP_DATA_OP_BACKUP,
NDMP_DATA_OP_RESTORE
};
enum ndmp_data_state
{
NDMP_DATA_STATE_IDLE,
NDMP_DATA_STATE_ACTIVE,
NDMP_DATA_STATE_HALTED,
};
enum ndmp_data_halt_reason
{
NDMP_HALT_NA,
NDMP_HALT_SUCCESSFUL,
NDMP_HALT_ABORTED,
NDMP_HALT_INTERNAL_ERROR,
NDMP_HALT_CONNECT_ERROR,
};
struct ndmp_data_get_state_reply
{
ndmp_error error;
ndmp_data_operation operation;
ndmp_data_state state;
ndmp_data_halt_reason halt_reason;
ndmp_u_quad bytes_processed;
ndmp_u_quad est_bytes_remain;
u_long est_time_remain;
ndmp_mover_addr mover;
ndmp_u_quad read_offset;
ndmp_u_quad read_length;
};
Request Arguments
This message does not have a message body.
74
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Arguments
error Error code.
operation Data operation currently in progress.
NDMP_DATA_OP_NOACTION No data operation currently in progress.
NDMP_DATA_OP_BACKUP Backup operation currently in progress.
NDMP_DATA_OP_RESTORE Restore operation currently in progress.
state Current state of the NDMP server.
NDMP_DATA_STATE_IDLE No active data operation.
NDMP_DATA_STATE_ACTIVEData operation in progress.
NDMP_DATA_STATE_HALTEDData operation completed.
halt_reason Reason the data operation is halted.
NDMP_DATA_HALT_NA Data operation not in progress or not in the
halt state.
NDMP_DATA_HALT_SUCCESSFUL Data operation completed successfully.
NDMP_DATA_HALT_ABORTED Data operation aborted by the NDMP client.
NDMP_DATA_HALT_CONNECT_ERROR
Error establishing connection to tape server.
75
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_DATA_HALT_INTERNAL_ERROR
Data operation halted due to unrecoverable
error incurred by the NDMP server data
backup/recover software.
bytes_processed Total number of bytes processed by the data
operation.
est_bytes_remain Estimated number of bytes processed remaining
to be processed by the data operation. May be
set to 0 to indicate that this feature is not
supported by the NDMP server.
est_time_remain Estimated number of seconds until the data
operation to completes. May be set to 0 to
indicate that this feature is not supported by
the NDMP server.
read_offset Offset value specified in last
ndmp_notify_data_read request.
read_len Length value specified in last
ndmp_notify_data_read request.
Reply Errors
NDMP_NO_ERR Data state successfully returned.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.5.2 Backup
Begins a backup. The id identifies the object to be backed up. The
meaning of id is implementation dependent. The type of backup is also
implementation dependent. The env is a list of parameters that may
76
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
affect the behavior of the backup. The env returned by the DATA_GET_ENV
will be saved and made available to the retrieval process.
Message XDR definition
/* NDMP_DATA_START_BACKUP */
struct ndmp_data_start_backup_request
{
ndmp_mover_addr mover;
string bu_type<>;
ndmp_pval env<>;
};
struct ndmp_data_start_backup_reply
{
ndmp_error error;
};
Request Arguments
bu_type The name of the backup method. Backup methods
are NDMP server implementation dependent.
env List of parameter names and values for
configuring the backup method. Backup method
parameters are NDMP server implementation
dependent. See below for example parameters.
mover The mover to receive data.
Reply Arguments
error Error code.
77
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Errors
NDMP_NO_ERR Backup operation successfully started.
NDMP_ILLEGAL_STATE_ERR A data operation is already in progress. Only
one data operation per connection is allowed to
be executing at a time.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_ILLEGAL_ARGS_ERR Invalid backup method, invalid backup method
parameter, or invalid backup method parameter
value specified.
NDMP_ NOT_AUTHORIZED _ERR Connection not authorized.
The following are examples of generic environment variables that may be
defined by the NDMP client.
Variable Name Meaning Value
PREFIX prefix path for path name
the request
TYPE the data type (i.e.
dump,tar,cpio)
USER user id to user name
perform backup
HIST a flag to y/n
maintain file
history
78
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
The following are examples of environment variables that may be defined
by dump type.
Variable Name Meaning Value
FILESYSTEM device or file file system or
system name to be device name (e.g.
backed up /dev/rsd0a)
LEVEL dump level 0 - 9
The following are examples of environment variables that may be defined
by tar type.
Variable Name Meaning Value
FILES list of files to e.g. ./* ./*.c ./*h
be backed up
The following are examples of environment variables that may be defined
by cpio type.
Variable Name Meaning Value
CMD command to e.g. find . -print
generate the file
list for cpio.
79
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
3.5.3 Recover
Recover the files specified in nlist from the backup. The env is the
list of parameters and values saved at the end of the backup.
Message XDR definition
/* NDMP_DATA_START_RECOVER */
struct ndmp_name
{
string name<>;
string dest<>;
u_short resvd;
ndmp_u_quad fh_info;
};
struct ndmp_data_start_recover_request
{
ndmp_mover_addr mover;
ndmp_pval env<>;
ndmp_name nlist<>;
string bu_type<>;
};
struct ndmp_data_start_recover_reply
{
ndmp_error error;
};
80
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Request Arguments
mover The mover from which to receive data
env The backup environment that was returned from a
data get environment request made prior to
notifying the NDMP server that the backup was
complete via a data stop message.
nlist List of files to be recovered and the location
each file is to be recovered to. Definition of
list entry:
name Name of a file/directory to be recovered. The
name is the original backed up path name and is
relative to the backup root directory.
dest Full destination pathname to be used when
recovering the file.
resvd reserved
fh_info File history tape positioning data recorded
when the file was backed up. This data may be
used by the restore method to perform tape
positioning for direct access data retrieval.
The positioning data is NDMP server dependent.
Typically it will be the byte or record offset
from the beginning of the tape of the file to
be recovered. This field is ignored by data
method implementations that do not support
this feature.
bu_type Name of the recover method. Recover methods are
NDMP server implementation dependent.
Reply Arguments
81
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
error Error code.
Reply Errors
NDMP_NO_ERR Recover operation successfully started.
NDMP_ILLEGAL_STATE_ERR A data operation is already in progress. Only
one data operation per connection is allowed to
be executing at a time.
NDMP_ILLEGAL_ARGS_ERR Invalid recover method, invalid recover method
parameter, invalid recover method parameter
value, or invalid name list entry specified.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_ NOT_AUTHORIZED _ERR Connection not authorized.
3.5.4 Abort
Send a message to abort the current backup or restore operation. The
operation should be terminated as soon as possible.
Message XDR definition
/* NDMP_DATA_ABORT */
/* no request arguments */
struct ndmp_data_abort_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a request body.
82
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Data operation successfully terminated.
NDMP_ILLEGAL_STATE_ERR No data operation in progress.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.5.5 Stop
Send a message to inform NDMP server that the current backup is
complete. NDMP server will change to idle state and be ready to process
another request.
Message XDR definition
/* NDMP_DATA_STOP */
/* no request arguments */
struct ndmp_data_stop_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error Error code.
83
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Errors
NDMP_NO_ERR Message successfully processed.
NDMP_ILLEGAL_STATE_ERR The request can not be performed in the current
state.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.5.6 Get ENV
Get the backup environment. Returns the environment included in the
data_start_backup request along with any additional parameters added or
modified by the backup method. The returned environment should be saved
and passed in the data_start_recover request whenever data from the
backup is to be recovered.
Message XDR definition
/* NDMP_DATA_GET_ENV */
/* no request arguments */
struct ndmp_data_get_env_reply
{
ndmp_error error;
ndmp_pval env<>;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error Error code.
env The backup method environment parameters and
values.
84
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Errors
NDMP_NO_ERR Environment successfully returned.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_ILLEGAL_STATE_ERR Illegal state. A data operation is not
currently in progress.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.6 MOVER Interface
During a backup, the mover accepts data from the data connection and
writes the data to tape using fixed size records. During restores, the
mover accepts requests to read portions of the data from tape. If the
requested data is not a multiple of the record size, the mover will
perform a full record read and only return the requested amount of data.
If the mover encounters end of file (EOF), media error, or reaches the
end of the data window while reading, it halts and notifies the NDMP
client.
3.6.1 Get Mover State
Return the state of the mover.
Message XDR definition
85
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_MOVER_GET_STATE */
enum ndmp_mover_state
{
NDMP_MOVER_STATE_IDLE,
NDMP_MOVER_STATE_LISTEN,
NDMP_MOVER_STATE_ACTIVE,
NDMP_MOVER_STATE_PAUSED,
NDMP_MOVER_STATE_HALTED
};
enum ndmp_mover_pause_reason
{
NDMP_MOVER_PAUSE_NA,
NDMP_MOVER_PAUSE_EOM,
NDMP_MOVER_PAUSE_EOF,
NDMP_MOVER_PAUSE_SEEK,
NDMP_MOVER_PAUSE_MEDIA_ERROR
};
enum ndmp_mover_halt_reason
{
NDMP_MOVER_HALT_NA,
NDMP_MOVER_HALT_CONNECT_CLOSED,
NDMP_MOVER_HALT_ABORTED,
NDMP_MOVER_HALT_INTERNAL_ERROR,
NDMP_MOVER_HALT_CONNECT_ERROR
};
/* no request arguments */
struct ndmp_mover_get_state_reply
{
ndmp_error error;
ndmp_mover_state state;
ndmp_mover_pause_reason pause_reason;
ndmp_mover_halt_reason halt_reason;
u_long record_size;
u_long record_num;
ndmp_u_quad data_written;
ndmp_u_quad seek_position;
ndmp_u_quad bytes_left_to_read;
ndmp_u_quad window_offset;
ndmp_u_quad window_length;
};
Request Arguments
86
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
This message does not have a message body.
Reply Arguments
error Error code.
state Current state of the NDMP server.
NDMP_MOVER_STATE_IDLE No active mover operation.
NDMP_MOVER_STATE_LISTEN Awaiting connection from the data server.
NDMP_MOVER_STATE_ACTIVE Mover operation in progress.
NDMP_MOVER_STATE_PAUSED Operation paused awaiting operator
attention.
NDMP_MOVER_STATE_HALTED Operation completed.
pause_reason Reason the operation is paused.
NDMP_MOVER_PAUSE_NA Operation not in progress or not in the pause
state.
NDMP_MOVER_PAUSE_EOM Operation encountered end of media. NDMP
client attention required.
NDMP_MOVER_PAUSE_EOF Operation encountered end of file. NDMP
client attention required.
NDMP_MOVER_PAUSE_SEEK Data operation requested a seek that
requires NDMP client intervention.
NDMP_MOVER_PAUSE_MEDIA_ERROR Error while reading/writing tape.
87
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
halt_reason Reason the operation is halted.
NDMP_MOVER_HALT_NA Operation not in progress or not in the halt
state.
NDMP_MOVER_HALT_CONNECTION_CLOSED Connection to data server
close detected.
NDMP_MOVER_HALT_ABORTED Operation aborted by the NDMP client.
NDMP_MOVER_HALT_INTERNAL_ERROR Operation halted due to
unrecoverable error incurred by the mover.
NDMP_MOVER_HALT_CONNECT_ERROR Error establishing connection to data
server.
record_size Size of tape data record.
record_num Current tape record number.
data_written Total number of bytes written to tape.
seek_position Offset value from last ndmp_mover_read request.
bytes_left_to_read Number of bytes remaining to be read to satisfy
the last ndmp_mover_read request.
window_offset Offset value from last ndmp_mover_set_window
request.
window_length Length value from last ndmp_mover_set_window
request.
Reply Errors
NDMP_NO_ERR Data state successfully returned.
88
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_ NOT_AUTHORIZED _ERR Connection not authorized.
3.6.2 Listen
The mover should begin listening for a data connection from a data
server. The mover returns an address that may be used by a data server
to connect to the mover.
Message XDR definition
/* NDMP_MOVER_LISTEN */
enum ndmp_mover_mode
{
NDMP_MOVER_MODE_READ,
NDMP_MOVER_MODE_WRITE
};
struct ndmp_mover_tcp_addr
{
u_long ip_addr;
u_short port;
};
union ndmp_mover_addr switch (ndmp_mover_addr_type addr_type)
{
case NDMP_ADDR_LOCAL:
void;
case NDMP_ADDR_TCP:
ndmp_mover_tcp_addr addr;
};
struct ndmp_mover_listen_request
{
ndmp_mover_mode mode;
ndmp_mover_addr_type addr_type;
};
struct ndmp_mover_listen_reply
{
ndmp_error error;
ndmp_mover_addr mover;
};
89
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Request Arguments
mode One of the following:
NDMP_MOVER_MODE_READ The mover should read data from the data
connection and write the data to tape. This
mode is used for backup operations.
NDMP_MOVER_MODE_WRITE The mover should read data from tape and write
the data to the data connection. This mode is
used for restore operations.
addr_type One of the following:
NDMP_ADDR_LOCAL Mover should listen for a connection from a
data server that is co-located with the mover.
This means that the data server and mover are
controlled via the same NDMP client connection.
The communication mechanism is implementation
dependent.
NDMP_ADDR_TCP Mover should listen for a connection from a
remote data server using a TCP/IP port.
Reply Arguments
error Error code.
mover Address on which the mover is listening for a
connection. If the address type is TCP, then
the returned address contains the IP address
and port number that the mover is listening on.
Reply Errors
90
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_NO_ERR Listen successful.
NDMP_ILLEGAL_STATE_ERR Mover not currently in idle state.
NDMP_ILLEGAL_ARGS_ERR Invalid mode or address type specified.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_ NOT_AUTHORIZED _ERR Connection not authorized.
3.6.3 Set Record Size
This request sets the record size used by the mover for all tape reads
and writes. When writing to tape, the mover will buffer data until a
full record has been buffered before writing the record to tape. The
client is responsible for setting the record size to a multiple of the
tape block size if the tape device being used is a fixed block size
device.
Message XDR definition
/* NDMP_MOVER_SET_RECORD_SIZE */
struct ndmp_mover_set_record_size_request
{
u_long length;
};
struct ndmp_mover_set_record_size_reply
{
ndmp_error error;
};
Request Arguments
length Record size in bytes.
91
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Record size successfully set.
NDMP_ILLEGAL_ARGS_ERR Invalid record size specified. The maximum
record size is implementation dependent
NDMP_ILLEGAL_STATE_ERR Illegal state. The record size may only be set
when in the idle state.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
NDMP_ NOT_AUTHORIZED _ERR Connection not authorized.
3.6.4 Set Window
Defines the valid data window. The window begins at the first record of
the current tape file and extends for the specified number of bytes.
After reading all data specified by the window, the mover will notify
the NDMP client that a tape change/seek is required.
92
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Message XDR definition
/* NDMP_MOVER_SET_WINDOW */
struct ndmp_mover_set_window_request
{
ndmp_u_quad offset;
ndmp_u_quad length;
};
struct ndmp_mover_set_window_reply
{
ndmp_error error;
};
Request Arguments
offset The data stream byte offset of the first byte
in the window.
length Number of bytes in the window.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Window successfully set.
NDMP_ILLEGAL_ARGS_ERR Invalid window specified.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
93
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_ILLEGAL_STATE_ERR Illegal state. A window may only be set when in
the listen or paused state.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.6.5 Continue
Notifies the mover to continue reading/writing tape data. This request
is sent after the NDMP client has completed a tape change or tape
positioning.
Message XDR definition
/* NDMP_MOVER_CONTINUE */
/* no request arguments */
struct ndmp_mover_continue_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Mover successfully continued.
NDMP_NOT_SUPPORTED_ERR The request is not supported for this
implementation.
94
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_ILLEGAL_STATE_ERR Illegal state. Mover not currently in the
paused state.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.6.6 Abort
Aborts the mover. The mover stops reading or writing data from/to tape
and closes the data connection.
Message XDR definition
/* NDMP_MOVER_ABORT */
/* no request arguments */
struct ndmp_mover_abort_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Mover successfully aborted.
NDMP_ILLEGAL_STATE_ERR Illegal state. Mover not currently in the
listen, active, or paused state.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
95
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
3.6.7 Stop
Frees any resources associated with the mover and returns the mover to
the idle state.
Message XDR definition
/* NDMP_MOVER_STOP */
/* no request arguments */
struct ndmp_mover_stop_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Mover successfully stopped.
NDMP_ILLEGAL_STATE_ERR Illegal state. Mover not currently in the
halted state.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.6.8 Read
This request notifies the mover to begin reading backup data from the
tape drive and write the data to the data connection. The mover will
continue to write data to the data connection until the requested number
of bytes have been read from tape and written to the data connection.
If EOF or the end of the data window is encountered, the mover will
notify the NDMP client and then enter the paused state. While
fulfilling this request, the mover should continue to accept messages
96
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
from the NDMP client. It is invalid to issue another read request while
the current request is in progress.
Message XDR definition
/* NDMP_MOVER_READ */
struct ndmp_mover_read_request
{
ndmp_u_quad offset;
ndmp_u_quad length;
};
struct ndmp_mover_read_reply
{
ndmp_error error;
};
Request Arguments
offset Offset within the data stream of the first byte
to be sent to the data connection. The mover
should seek the tape to the record containing
the requested offset and then read and discard
data until the offset has been reached. If the
offset is outside of the currently set data
window, the mover should notify the NDMP client
that a seek is required.
length Number of data bytes to be read and send to the
data connection.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Read successfully started.
97
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_ILLEGAL_STATE_ERR Illegal state. Mover not currently in the
paused state.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
3.6.9 Close
Notifies the mover to close the data connection. The NDMP client will
send this request after a backup operation has completed or after all
data for a restore operation has been read.
Message XDR definition
/* NDMP_MOVER_CLOSE */
/* no request arguments */
struct ndmp_mover_close_reply
{
ndmp_error error;
};
Request Arguments
This message does not have a message body.
Reply Arguments
error Error code.
Reply Errors
NDMP_NO_ERR Data connection successfully closed.
NDMP_ILLEGAL_STATE_ERR Illegal state. Data connection not open.
NDMP_NOT_AUTHORIZED_ERR Connection not authorized.
98
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
4. NDMP Client Interfaces
This section defines the protocol interfaces implemented by the NDMP
client.
4.1 NOTIFY Interface
This interface is used by the NDMP server to let the NDMP client know
that the NDMP server requires attention.
4.1.1 Notify Halted
This message is used to notify NDMP client that the NDMP data server has
halted
Message XDR definition
/* NDMP_NOTIFY_DATA_HALTED */
struct ndmp_notify_data_halted_request
{
ndmp_data_halt_reason reason;
string text_reason<>;
};
Request Arguments
reason Reason the data operation halted.
NDMP_HALT_NA Data operation not in progress or not in the
halt state.
NDMP_HALT_SUCCESSFUL Data operation completed successfully.
NDMP_HALT_ABORTED Data operation aborted by the NDMP client.
99
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
NDMP_HALT_MEDIA_ERROR Data operation halted due to unrecoverable
media error.
NDMP_HALT_INTERNAL_ERROR Data operation halted due to unrecoverable
error incurred by the NDMP server or the data
backup/recover method.
NDMP_HALT_RESVD1 Reserved.
text_reason Diagnostic error message. NDMP server
implementation dependent.
Reply Arguments
This message does not have a message body.
4.1.2 Notify Connected
This message is sent in response to a connection establishment attempt.
This message is always the first message sent on a new connection. It is
also used prior to NDMP server shutdown to inform the client that the
server is shutting down.
Message XDR definition
/* NDMP_NOTIFY_CONNECTED */
enum ndmp_connect_reason
{
NDMP_CONNECTED, /* Connect sucessfully */
NDMP_SHUTDOWN, /* Connection shutdown */
NDMP_REFUSED /* reach the maximum number of connections */
};
struct ndmp_notify_connected_request
{
ndmp_connect_reason reason;
u_short protocol_version;
string text_reason<>;
};
100
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Request Arguments
reason Reason code describing the current connection
state.
NDMP_CONNECTED NDMP connection successfully established. This
code will be returned in a message sent
immediately after successful connection
establishment.
NDMP_SHUTDOWN The NDMP server is shutting down the NDMP
connection. Will typically used when shutting
down the NDMP host to gracefully close down the
NDMP connection.
NDMP_REFUSED NDMP connection refused by the NDMP server.
This code will be returned in a message sent
immediately after a connection establishment
attempt to notify the NDMP client that the NDMP
server is not able to accept the connection at
the current time. This will typically be used
if the NDMP server implementation limits the
total number of concurrent NDMP connections,
when NDMP services on the NDMP host are
disabled, or when the NDMP host is in the
process of shutting down.
protocol_version Version of protocol being used.
text_reason NDMP server implementation dependent message
indicating why the connection is being shutdown
or refused.
Reply Arguments
This message does not have a message body.
4.1.3 Notify Mover Halted
This message is used to notify the NDMP client that the NDMP mover has
entered the halted state.
101
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
Message XDR definition
/* NDMP_NOTIFY_MOVER_HALTED */
struct ndmp_notify_mover_halted_request
{
ndmp_mover_halt_reason reason;
string text_reason<>;
};
Request Arguments
reason Reason the mover halted.
NDMP_MOVER_HALT_NA Operation not in progress or not in
the halt state.
NDMP_MOVER_HALT_CONNECTION_CLOSED Connection to data server close
detected.
NDMP_MOVER_HALT_ABORTED Operation aborted by the NDMP client.
NDMP_MOVER_HALT_INTERNAL_ERROR Operation halted due to
unrecoverable error incurred by the
mover.
NDMP_MOVER_HALT_CONNECT_ERROR Error establishing connection to data
server.
text reason Message providing additional diagnostic
information. NDMP server implementation
dependent.
Reply Arguments
This message does not have a message body.
102
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
4.1.4 Notify Mover Paused
This message is used to notify the NDMP client that the NDMP mover has
paused.
Message XDR definition
/* NDMP_NOTIFY_MOVER_PAUSED */
struct ndmp_notify_mover_paused_request
{
ndmp_mover_pause_reason reason;
ndmp_u_quad seek_position;
};
Request Arguments
reason Reason the mover paused.
NDMP_MOVER_PAUSE_NA Operation not in progress or not in the pause
state.
NDMP_MOVER_PAUSE_EOM Operation encountered end of media. NDMP
client attention required.
NDMP_MOVER_PAUSE_EOF Operation encountered end of file. NDMP
client attention required.
NDMP_MOVER_PAUSE_SEEK Data operation requested a seek that is
outside of the current data window. NDMP client
attention required.
NDMP_MOVER_PAUSE_MEDIA_ERROR Error while reading/writing tape.
seek_position If reason is NDMP_MOVER_PAUSE_SEEK, indicates
the desired data stream seek position. The NDMP
client should load the tape containing the
requested seek_position, position the tape
103
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
appropriately, set a new data window, and then
continue the mover.
Reply Arguments
This message does not have a message body.
4.1.5 Notify DATA Read
This message is used to notify the NDMP client that the NDMP server
wants to read data from a remote mover. The NDMP server must send at
least one NOTIFY_DATA_READ message to the NDMP client if the mover is
remote. In response to this message, the NMDP client will sent an
NDMP_MOVER_READ message to the remote mover.
Message XDR definition
/* NDMP_NOTIFY_DATA_READ */
struct ndmp_notify_data_read_request
{
ndmp_u_quad offset;
ndmp_u_quad length;
};
Request Arguments
offset Data stream offset of first byte that should be
sent to the data connection
length Number of data bytes the mover should read from
tape and sent to the data connection.
Reply Arguments
This message does not have a message body.
4.2 LOGGING Interface
104
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
This interface is used by the NDMP server to send informational and
diagnostic data to the NDMP client. This data is used by the client to
monitor the progress of the currently running data operation and to
diagnose problems.
4.2.1 Log
Send an informational message to the NDMP client. Typically used to send
log messages generated by the backup or recover method.
Message XDR definition
/* NDMP_LOG_LOG */
struct ndmp_log_log_request
{
string entry<>;
};
Request Arguments
entry Text message.
Reply Arguments
This message does not have a message body.
4.2.2 Debug
Send a diagnostic message to the NDMP client. This message is typically
used to diagnose NDMP server problems. The mechanism used to
enable/disable diagnostic messages is NDMP server dependent. This
feature is primarily intended to be used during software development and
when troubleshooting.
Message XDR definition
105
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_LOG_DEBUG */
enum ndmp_debug_level
{
NDMP_DBG_USER_INFO,
NDMP_DBG_USER_SUMMARY,
NDMP_DBG_USER_DETAIL,
NDMP_DBG_DIAG_INFO,
NDMP_DBG_DIAG_SUMMARY,
NDMP_DBG_DIAG_DETAIL,
NDMP_DBG_PROG_INFO,
NDMP_DBG_PROG_SUMMARY,
NDMP_DBG_PROG_DETAIL
};
struct ndmp_log_debug_request
{
ndmp_debug_level level;
string message<>;
};
Request Arguments
level The level is divided into two components. The
first component is the intended audience. The
audience can be the end user (user), the
technical support personnel (diag), or the
development engineer (prog). The second
component is the level of detail requested.
The level of detail is specified as info,
summary, and detail. There are no specific
guidelines on the use of level of detail, but
a message that typically is encountered less
that 10 times during a backup should be an
info level; a message that is encountered more
than 100 times should be at a detail level.
message Diagnostic text message
Reply Arguments
This message does not have a message body.
106
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
4.2.3 File Recovered
Send a file recover message to the NDMP client. Used during recovery to
notify the NDMP client that a file from the recovery list sent in the
ndmp_data_start_recover request has or has not been recovered. This
message should not be sent for every recovered (or failed) file, just
files having a name that matches a name in the recovery list.
Message XDR definition
/* NDMP_LOG_FILE */
struct ndmp_log_file_request
{
string name<>;
u_short ssid;
ndmp_error error;
};
Request Arguments
name File name.
ssid Selection set identifier. Only used by recover
methods that support ssid.
error Error code.
NDMP_NO_ERR File successfully recovered.
NDMP_PERMISSION_ERR Some sort of permission problem.
NDMP_FILE_NOT_FOUND_ERR File not found during restore.
Reply Arguments
This message does not have a message body.
107
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
4.3 FILE HISTORY Interface
The NDMP server uses this interface to send file history entries to the
NDMP client. The file history entries provide a file by file record of
every file backed up by the backup method. The file history data is
defined using a UNIX filesystem compatible format. There are two sets
of messages for sending file history data. The first set consisting of
just the add path message is for use by filename based backup methods
(such as the UNIX tar and cpio commands) for which the full pathname
and file attributes are available at the time each file is backed up.
The second set consisting of the add directory and add node messages is
for use by inode based backup methods (such as the UNIX dump command)
for which the full pathname is not necessarily available at the time
each file is backed up. Some backup methods may not support the sending
of file history data.
4.3.1 Add Unix Path
Message XDR definition
108
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
/* NDMP_FH_ADD_UNIX_PATH */
typedef string ndmp_unix_path<>;
enum ndmp_unix_file_type
{
NDMP_FILE_DIR,
NDMP_FILE_FIFO,
NDMP_FILE_CSPEC,
NDMP_FILE_BSPEC,
NDMP_FILE_REG,
NDMP_FILE_SLINK,
NDMP_FILE_SOCK
};
struct ndmp_unix_file_stat
{
ndmp_unix_file_type ftype;
u_long mtime;
u_long atime;
u_long ctime;
u_long uid;
u_long gid;
u_long mode;
ndmp_u_quad size;
ndmp_u_quad fh_info;
};
struct ndmp_fh_unix_path
{
ndmp_unix_path name;
ndmp_unix_file_stat fstat;
};
struct ndmp_fh_add_unix_path_request
{
ndmp_fh_unix_path paths<>;
};
Request Arguments
paths Array of file history path entries. Each entry
contains:
name The full pathname of the backed up file
relative to the backup root directory.
109
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
fstat File attribute data consisting of:
ftype File type.
mtime Time the file was last modified (in seconds
since 00:00:00 GMT, Jan 1, 1970).
atime Time the file was last accessed (in seconds
since 00:00:00 GMT, Jan 1, 1970).
ctime Time the file status was last modified (in
seconds since 00:00:00 GMT, Jan 1, 1970).
Indicates the last time that either the file
data or the file attributes were modified.
uid File owner identifier.
gid File group identifier.
mode File mode flags.
size File size.
fh_info File history tape positioning data representing
the tape position at the time the file was
written to tape. This data may be used by the
restore method to perform tape positioning for
direct access file retrieval. The positioning
data is NDMP server dependent. Typically it
will be the byte or record offset from the
beginning of the tape of the file to be
recovered. This field is ignored by data method
implementations that do not support this
feature.
Reply Arguments
This message does not have a message body.
110
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
4.3.2 Add Unix Dir
This message is used to support directory/inode types of backup
formats. The node number can be any unique number that matches a
corresponding fh_add_unix_node message.
Message XDR definition
/* NDMP_FH_ADD_UNIX_DIR */
struct ndmp_fh_unix_dir
{
ndmp_unix_path name;
u_long node;
u_long parent;
};
struct ndmp_fh_add_unix_dir_request
{
ndmp_fh_unix_dir dirs<>;
};
Request Arguments
dirs Array of directory entries. Each entry
contains:
name Node file name. This is not a full pathname;
just the basename relative to the node's parent
directory.
node Node identifier that matches a node in a
corresponding add node message. NDMP server
implementation dependent but will typically be
the inode number of the file.
parent Node identifier of the node's parent directory.
NDMP server implementation dependent but will
typically be the inode number of the file.
Reply Arguments
111
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
This message does not have a message body.
4.3.3 Add Unix Node
Add a list of file attribute entries to the file history. These entries
must match a corresponding node number from a previous add directory
message. For each file, this message must be sent after the
corresponding ndmp_fh_add_unix_dir message.
Message XDR definition
/* NDMP_FH_ADD_UNIX_NODE */
struct ndmp_fh_unix_node
{
ndmp_unix_file_stat fstat;
u_long node;
};
struct ndmp_fh_add_unix_node_request
{
ndmp_fh_unix_node nodes<>;
};
Request Arguments
nodes Array of file history node entries. Each entry
contains:
fstat File attribute data.
node Node identifier that matches a node in a
corresponding add directory message. NDMP
server implementation dependent but will
typically be the inode number of the file.
Reply Arguments
112
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
This message does not have a message body.
113
Stager,Hitz
Internet Draft PDC/NetApp Backup Protocol 08/25/97
5. References
[1] RFC 1832 , _XDR: External Data Representation Standard_, R.
Srinivasan, Sun Microsystems, August 1995
6. Security
The NDMP client is normally authenticated by the NDMP server using a
secure MD5 digest. However the NDMP server can optionally authenticate
using a clear text password or even permit access without
authentication. Once authenticated, privileges are not specified by the
NDMP protocol, but it is expected that NDMP server implementations will
permit data to be transferred to and from tape using the protocol.
The NDMP_SCSI_OPEN permits low level access to SCSI tape and jukebox
devices. The NDMP server should prevent access to other SCSI devices
(such as disk drives) to prevent the NDMP client from bypassing
filesystem security.
File history information is transferred to the NDMP client through a
TCP/IP connection.
7. Authors
D. Hitz R. Stager
Network Appliance PDC
2770 San Tomas Expressway. 111C Lindbergh Ave
Santa Clara, CA 95051 Livermore, CA 94550
USA USA
Tel: 408-367-3106 Tel: 510-449-6881
Fax: 408-367-3151 Fax: 415-428-5151
email: hitz@netapp.com email: rstager@pdc.com
http://www.netapp.com http://www.pdc.com
Expires: March 1998
114
Stager,Hitz