spec.v1.txt

网络数据管理协议的开发

Internet Draft     Network Data Management Protocol       October 1996





2.3 State Description

The following state diagram defines the DATA interface















































Stager,Hitz                                                    Page 11





Internet Draft     Network Data Management Protocol       October 1996




   _____________________________________
  |                                     |
  |                                     |
  |                               ******V******
  |                               *   Idle    *
  |                               *           *
  |                               *************
  |                                |         |
  |                                |         |
  |                  DATA_start-restore    DATA_start_backup
  |                                |         |
  |                                 \       /
  |                                  \     /
  |                                   \   /
  |                                    \ /
  |                                     |______________________________
  |                                     |                              |
  |                               ******V******                        |
  |            ___________________*  Active   *___Detect EOM___        |
  |           |                   *           *___Detect EOF___|       |
  |           |         __________*           *                |       |
DATA-stop     |        |          *************                |       |
  |           |        |            |        |                 |       |
  |           |        |            |        |                 |       |
  |           |        |       Successful  Detect              | DATA_ |
  |      Internal  DATA-abort   Completion  Media              |continue
  |      Error         |            |      Error        *******V****** |
  |           |        |            |        |          *  Paused    * |
  |             \      |            |      /            *            * |
  |               \    |            |    /              ************** |
  |                 \  |            |  /                       |       |
  |                   \              /                         |       |
  |                     \          /                           |_______|
  |                       \      /                                 |
  |                    ****V****V****                              |
  |                    *   Halted   *                              |
  |____________________*            *<_____________________________|
                       **************





Figure 4 - Backup state diagram

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




Stager,Hitz                                                    Page 12





Internet Draft     Network Data Management Protocol       October 1996


2.3.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.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.


     Transition to paused state upon detection of EOM.


     Transition to paused state upon detection of EOF.


2.3.3 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_data_continue
     message.


     Transition to halted state upon receipt of ndmp_data_abort message.


2.3.4 Halted State

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



Stager,Hitz                                                    Page 13





Internet Draft     Network Data Management Protocol       October 1996


     Transition to idle state upon receipt of ndmp_data_stop message.


2.4 Protocol interfaces

Messages are grouped together by functionality into several _interfaces_.


2.4.1 NDMP Server Interfaces

The NDMP server must implement the following interfaces


.  CONNECT interface

This interface will be used when a client opens the communication to a
NDMP server. This interface allows the NDMP server to authenticate the
client and negotiate the version of protocol used.


.  CONFIG interface

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


.  SCSI interface

This interface simply passes SCSI CDBs through to the SCSI device and
returns the SCSI status. The NDMP client will use this interface to
control a locally attached jukebox. 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 tape drives.


.  TAPE interface

The TAPE interface will support both tape positioning and tape read/write
operations. The NDMP client will use this interface to control the
labeling and format of the tape. The NDMP client will also use this
interface for positioning of 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 should
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.


Stager,Hitz                                                    Page 14





Internet Draft     Network Data Management Protocol       October 1996





2.4.2 NDMP Client Interfaces

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 NDMP client that the
NDMP server requires attention.


.  FILE HISTORY interface

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


.  LOGGING interface

These messages allows the NDMP server to make entries in the backup log.
This is used by the operator to monitor the progress and successful
completion 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.


The NDMP uses asynchronous messages and a message does not require a
reply, however, many of the messages may result in a reply message. A
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.







Stager,Hitz                                                    Page 15





Internet Draft     Network Data Management Protocol       October 1996


2.6 Header

Each message will be preceded by a message header.  The header will be
used to identify the message, how to de-serialize the arguments.









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




 


The message headers are defined by the following XDR block



   enum ndmp_message_type
   {
       NDMP_REQUEST,
       NDMP_REPLY
   };

   struct ndmp_header
   {
       u_long                  sequence;
       u_long                  time_stamp;
       ndmp_message_type       message_type;
       ndmp_message            message;
       u_long                  reply_sequence;
       ndmp_error              error;
   };






   sequence              The sequence number is a connection local counter
                         that starts at 1 and increases by 1 for every


Stager,Hitz                                                    Page 16





Internet Draft     Network Data Management Protocol       October 1996


                         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 request
                         message.In reply messages, the reply_sequence is
                         the sequence number from the request message to
                         which the reply is associated.


   error                 The error field is 0 in request messages. In
                         reply messages, the error field identifies any
                         problem that was incurred receiving or decoding
                         the message.  If the error value is non-zero, no
                         message body will  follow the message header.


























Stager,Hitz                                                    Page 17





Internet Draft     Network Data Management Protocol       October 1996


2.7 Error

The following errors 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


     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




Stager,Hitz                                                    Page 18





Internet Draft     Network Data Management Protocol       October 1996


     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 used.


NDMP_DEVICE_OPENED_ERR


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


Document Version:   1.8.0





     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


     Device I/O error.


NDMP_TIMEOUT_ERR


     Command timeout error.


NDMP_ILLEGAL_ARGS_ERR


Stager,Hitz                                                    Page 19





Internet Draft     Network Data Management Protocol       October 1996


     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 because end of file was encountered.


NDMP_EOM_ERR


     The tape command 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


     Error due to invalid file descriptor.


NDMP_NO_DEVICE_ERR


     Specified device device does not exist.