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: 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