Driver-Taper protocol: Difference between revisions

From wiki.zmanda.com
Jump to navigation Jump to search
No edit summary
No edit summary
Line 4: Line 4:
==Command sequence during backup operation==
==Command sequence during backup operation==


* driver initialises taper with: START-TAPER <datestamp> to which taper replies with: TAPER-OK or, for fatal errors, with: TAPER-ERROR [<message>]
* driver initialises taper with: START-TAPER <datestamp> to which taper replies with: TAPE-OK or, for fatal errors, with: TAPE-ERROR [<message>]


* driver can ask taper to to copy a file from the holding disk to tape: FILE-WRITE <handle> <filename> <host> <disk> <level> or directly from a dumper: PORT-WRITE <handle> <host> <disk> <level> or exit at the end of the run: QUIT
* driver will ask the taper to start a new tape with the NEW-TAPE command.
 
* driver can ask taper to copy a file from the holding disk to tape: FILE-WRITE <handle> <filename> <host> <disk> <level> or directly from a dumper: PORT-WRITE <handle> <host> <disk> <level> or exit at the end of the run: QUIT


* taper responds to the PORT-WRITE command with: PORT <port> which driver should then hand on to dumper in a PORT-DUMP command.
* taper responds to the PORT-WRITE command with: PORT <port> which driver should then hand on to dumper in a PORT-DUMP command.
Line 12: Line 14:
* If the copy to tape finishes correctly taper replies with: DONE <handle> [<message>]
* If the copy to tape finishes correctly taper replies with: DONE <handle> [<message>]


* If something goes wrong with the tape, taper can request that the dump be retried at a later time with: TRY-AGAIN <handle> [<message>] or, for fatal errors, be abandoned with: TAPE-ERROR <handle> [<message>]
* If something goes wrong with the tape, taper can ask to continue on a new tape SPLIT-NEEDNEXT (for splited dump only) or it can abort that dump with PARTIAL or FAILED reply


==Other commands==
==Other commands==
Line 46: Line 48:
{|border=1
{|border=1
!Reply!!Description
!Reply!!Description
|-
|TAPE-OK||taper is setup correctly
|-
|TAPE-ERROR||Error in setup of the driver
|-
|PORT||Reply sent in response to PORT-WRITE command
|-
|-
|DONE||Full dump is on the media
|DONE||Full dump is on the media
|-
|-
|PARTIAL||Dump was partially written to the media. PARTIAL responses also contain
|PARTIAL||Dump was partially written to the media.
* TRYAGAIN - The dump should retried
* NOTRYAGAIN - Should not retry (Example: If there is missing chunk in the holding disk)
|-
|-
|FAILED||Nothing was written to the media
|FAILED||Nothing was written to the media
|-
|-
|SAME-TAPE||This tape can be use for another dump
|SPLIT-CONTINUE||A complete part is written to tape
|-
|-
|TAPE-ERROR|| No more space in the current tape
|SPLIT-NEEDNEXT||Ask driver if it should continue on a new tape
|-
|-
|PORT||Reply sent in response to PORT-WRITE command
|NEW-TAPE||Will continue on a new found tape
|-
|NO-NEW-TAPE||Will not continue on a new tape
|}
|}


===Driver/Taper Requests/Replies===


DONE/PARTIAL and FAILED reply also contains an INPUT-* an TAPE-* message to denote any error:
{|border=1
{|border=1
!Driver request!!Taper reply!!Description
!Reply!!Description
|-
|-
|START-TAPER||TAPE-OK||normal taper setup (a tape is available, nothing is written on it)
|INPUT-GOOD||There was no error with the input.
|-
|-
|START-TAPER||TAPE-ERROR||failed taper setup (no tape are available or something else is broken)
|INPUT-ERROR||There was error with the input.
|}
 
{|border=1
!Reply!!Description
|-
|-
|NEW-TAPE||NEW-TAPE||The driver tell the taper to use a new tape, the taper found one
|TAPE-GOOD||This tape can be use to write another dump.
|-
|-
|NEW-TAPE||NO-NEW-TAPE||The driver tell the taper to use a new tape, no tape are available
|TAPE-ERROR||Nothing more can fit on that tape.
|}
 
A result for a successful dump should be: DONE INPUT-GOOD TAPE-GOOD
 
===Driver/Taper Requests/Replies===
{|border=1
!Driver request!! !!Taper reply!!Description
|-
|-
|FILE-WRITE||DONE||normal protocol for a success
|initail setup
|-
|-
|||SAME-TAPE||Continue using the same tape
|START-TAPER||--->|| ||  
|-
|-
|FILE-WRITE||FAILED||protocol for error in setup (before something is written to tape)
|||<---||TAPE-OK||normal taper setup (a tape is available, nothing is written on it)
|-
|-
|||TRYAGAIN or NOTRYAGAIN||Information on whether the command should be retried
|||<---||TAPE-ERROR||failed taper setup (no tape are available or something else is broken)
|-
|-
|||SAMETAPE or TAPE-ERROR||Continue using the same tape for next dump or not
|ask for new tape
|-
|-
|FILE-WRITE||PARTIAL or FAILED||protocol for error in data phase
|NEW-TAPE||--->||||driver tell the taper to use a new tape
|-
|-
|||TRYAGAIN or NOTRYAGAIN||Information on whether the command should be retried
|||<---||GOT-NEW-TAPE||taper found one
|-
|-
|||SAMETAPE or TAPE-ERROR||Continue using the same tape for next dump or not
|||<---||NO-NEW-TAPE||no tape are available
|-
|-
|PORT-WRITE||PORT||Normal port establishment protocol and dumper status
|file-write setup
|-
|-
|DONE||DONE or PARTIAL||Dumper can send DONE reply to driver but, dumper can fail to write everything to the tape (PARTIAL)
|FILE-WRITE||--->||||
|-
|-
|||TRYAGAIN or NOTRYAGAIN||
|||||||Will get one part-result for each part written and one global result
|-
|-
|||SAME-TAPE or TAPE-ERROR||
|port-write setup
|-
|-
|PORT-WRITE||FAILED||Protocol error in port setup
|PORT-WRITE||--->|| ||
|-
|-
|||TRYAGAIN or NOTRYAGAIN||
|||<---||PORT||
|-
|-
|||SAME-TAPE or TAPE-ERROR||
|||||||WIll continue with one part-result for each part written and one global result
|-
|-
|PORT-WRITE||PORT||Protocol for error in data phase (dumper errors)
|global-result
|-
|-
|FAILED||PARTIAL or FAILED||result of the dumper
|||<---||DONE INPUT-GOOD TAPE-GOOD||normal protocol for a success
|-
|-
|||TRYAGAIN or NOTRYAGAIN||
|||<---||PARTIAL INPUT-* TAPE-*||protocol for error in data phase (something written to tape)
|-
|-
|||SAME-TAPE or TAPE-ERROR||
|||<---||FAILED INPUT-* TAPE-*||protocol for error in setup (before something is written to tape)
|-
|-
|<Split dump handling>||SPLIT_CONTINUE||if it's a split dump, then taper send this after each chunk is written
|part-result
to tape.
|-
|-
|||SPLIT_NEED_NEXT||it it hit end of tape
|||<---||SPLIT-CONTINUE||successfully part written to tape
|-
|-
|NEW-TAPE||NEW-TAPE||driver tells the taper to use a new tape, taper found one
|||<---||SPLIT-NEEDNEXT||failed PART (only for tape-error) (driver will send a NEW-TAPE or NO-NEW-TAPE command)
|-
|-
|||NO-NEW-TAPE||driver tell the taper to use a new, no tape are available. Continues with a PARTIAL result
|no new tape
|-
|-
|NO-NEW-TAPE||||Taper continues with PARTIAL result
|NO-NEW-TAPE||--->||||driver doesn't want the taper to use a new tape (continue with global-result)
|-
|-
|}
|}

Revision as of 16:06, 16 October 2006

Communication method

driver talks via two pipes connected to taper's stdin and stdout. The commands and responses are plain text.

Command sequence during backup operation

  • driver initialises taper with: START-TAPER <datestamp> to which taper replies with: TAPE-OK or, for fatal errors, with: TAPE-ERROR [<message>]
  • driver will ask the taper to start a new tape with the NEW-TAPE command.
  • driver can ask taper to copy a file from the holding disk to tape: FILE-WRITE <handle> <filename> <host> <disk> <level> or directly from a dumper: PORT-WRITE <handle> <host> <disk> <level> or exit at the end of the run: QUIT
  • taper responds to the PORT-WRITE command with: PORT <port> which driver should then hand on to dumper in a PORT-DUMP command.
  • If the copy to tape finishes correctly taper replies with: DONE <handle> [<message>]
  • If something goes wrong with the tape, taper can ask to continue on a new tape SPLIT-NEEDNEXT (for splited dump only) or it can abort that dump with PARTIAL or FAILED reply

Other commands

  • If driver says something that taper doesn't recognise it responds with: BAD-COMMAND <message>
  • taper responds to the QUIT command with: QUITING

Protocol data

data description
<datestamp> Date as "yymmdd"
<handle> Request ID
<filename> Name of file on the holding disk where backup will be written to
<port> Taper port to send the backup data to
<host> Hostname of the client
<disk> Disk on the client being backed up
<level> Dump level being used for backup
<message> Error or Status message

Protocol command reference

Taper command reply

Reply Description
TAPE-OK taper is setup correctly
TAPE-ERROR Error in setup of the driver
PORT Reply sent in response to PORT-WRITE command
DONE Full dump is on the media
PARTIAL Dump was partially written to the media.
FAILED Nothing was written to the media
SPLIT-CONTINUE A complete part is written to tape
SPLIT-NEEDNEXT Ask driver if it should continue on a new tape
NEW-TAPE Will continue on a new found tape
NO-NEW-TAPE Will not continue on a new tape


DONE/PARTIAL and FAILED reply also contains an INPUT-* an TAPE-* message to denote any error:

Reply Description
INPUT-GOOD There was no error with the input.
INPUT-ERROR There was error with the input.
Reply Description
TAPE-GOOD This tape can be use to write another dump.
TAPE-ERROR Nothing more can fit on that tape.

A result for a successful dump should be: DONE INPUT-GOOD TAPE-GOOD

Driver/Taper Requests/Replies

Driver request Taper reply Description
initail setup
START-TAPER --->
<--- TAPE-OK normal taper setup (a tape is available, nothing is written on it)
<--- TAPE-ERROR failed taper setup (no tape are available or something else is broken)
ask for new tape
NEW-TAPE ---> driver tell the taper to use a new tape
<--- GOT-NEW-TAPE taper found one
<--- NO-NEW-TAPE no tape are available
file-write setup
FILE-WRITE --->
Will get one part-result for each part written and one global result
port-write setup
PORT-WRITE --->
<--- PORT
WIll continue with one part-result for each part written and one global result
global-result
<--- DONE INPUT-GOOD TAPE-GOOD normal protocol for a success
<--- PARTIAL INPUT-* TAPE-* protocol for error in data phase (something written to tape)
<--- FAILED INPUT-* TAPE-* protocol for error in setup (before something is written to tape)
part-result
<--- SPLIT-CONTINUE successfully part written to tape
<--- SPLIT-NEEDNEXT failed PART (only for tape-error) (driver will send a NEW-TAPE or NO-NEW-TAPE command)
no new tape
NO-NEW-TAPE ---> driver doesn't want the taper to use a new tape (continue with global-result)
Retrieved from ‘http://wiki.zmanda.com/index.php?title=Driver-Taper_protocol&oldid=3536’