[Box Backup] Box Backup protocol description, for the record
Chris Wilson
chris at qwirx.com
Mon Jan 24 23:04:09 GMT 2011
Application for User Registered Port Number
Name :
Chris Wilson
E-mail :
chris+iana at qwirx.com
Protocol Number :
TCP
Message Formats :
Handshake message:
char mIdent[32];
The ident used by both sides is currently "Box-Backup:v=C"
Object header:
u_int32_t mObjSize;
u_int32_t mObjType;
(followed by mObjSize bytes of data)
Error message (mObjType = 0):
int32 Type
int32 SubType
where Type is always 1000 and SubType is one of:
CONSTANT ErrorType 1000
CONSTANT Err_WrongVersion 1
CONSTANT Err_NotInRightProtocolPhase 2
CONSTANT Err_BadLogin 3
CONSTANT Err_CannotLockStoreForWriting 4
CONSTANT Err_SessionReadOnly 5
CONSTANT Err_FileDoesNotVerify 6
CONSTANT Err_DoesNotExist 7
CONSTANT Err_DirectoryAlreadyExists 8
CONSTANT Err_CannotDeleteRoot 9
CONSTANT Err_TargetNameExists 10
CONSTANT Err_StorageLimitExceeded 11
CONSTANT Err_DiffFromFileDoesNotExist 12
CONSTANT Err_DoesNotExistInDirectory 13
CONSTANT Err_PatchConsistencyError 14
Version message (mObjType = 1):
int32 Version
Login Message mObjType = 2):
int32 ClientID
int32 Flags
CONSTANT Flags_ReadOnly 1
LoginConfirmed message (mObjType = 3):
int64 ClientStoreMarker
int64 BlocksUsed
int64 BlocksSoftLimit
int64 BlocksHardLimit
Finished message (mObjType = 4):
no data fields
Success message (mObjType = 5):
int64 ObjectID
SetClientStoreMarker message (mObjType = 6):
int64 ClientStoreMarker
GetObject (mObjType = 10)
int64 ObjectID
CONSTANT NoObject 0
# reply has stream following, if ObjectID != NoObject
MoveObject (11):
int64 ObjectID
int64 MoveFromDirectory
int64 MoveToDirectory
int32 Flags
Filename NewFilename
CONSTANT Flags_MoveAllWithSameName 1
CONSTANT Flags_AllowMoveOverDeletedObject 2
GetObjectName (12)
int64 ObjectID
int64 ContainingDirectoryID
CONSTANT ObjectID_DirectoryOnly 0
# set ObjectID to ObjectID_DirectoryOnly to only get info on the directory
ObjectName (13)
int32 NumNameElements
int64 ModificationTime
int64 AttributesHash
int16 Flags
# NumNameElements is zero if the object doesn't exist
CONSTANT NumNameElements_ObjectDoesntExist 0
# a stream of Filename objects follows, if and only if NumNameElements > 0
CreateDirectory (20)
int64 ContainingDirectoryID
int64 AttributesModTime
Filename DirectoryName
# stream following containing attributes
ListDirectory (21)
int64 ObjectID
int16 FlagsMustBeSet
int16 FlagsNotToBeSet
bool SendAttributes
CONSTANT Flags_INCLUDE_EVERYTHING -1
CONSTANT Flags_EXCLUDE_NOTHING 0
CONSTANT Flags_EXCLUDE_EVERYTHING 15
CONSTANT Flags_File 1
CONSTANT Flags_Dir 2
CONSTANT Flags_Deleted 4
CONSTANT Flags_OldVersion 8
CONSTANT RootDirectory 1
ChangeDirAttributes (22)
int64 ObjectID
int64 AttributesModTime
# stream following containing attributes
DeleteDirectory (23)
int64 ObjectID
UndeleteDirectory (24)
int64 ObjectID
StoreFile (30)
int64 DirectoryObjectID
int64 ModificationTime
int64 AttributesHash
int64 DiffFromFileID # 0 if the file is not a diff
Filename Filename
# then send a stream containing the encoded file
GetFile (31)
int64 InDirectory
int64 ObjectID
# error returned if not a file, or does not exist
# reply has stream following, containing an encoded file IN STREAM ORDER
# (use GetObject to get it in file order)
SetReplacementFileAttributes (32)
int64 InDirectory
int64 AttributesHash
Filename Filename
# stream follows containing attributes
DeleteFile (33)
int64 InDirectory
Filename Filename
# will return 0 if the object couldn't be found in the specified directory
GetBlockIndexByID (34)
int64 ObjectID
GetBlockIndexByName (35)
int64 InDirectory
Filename Filename
GetAccountUsage (40)
# no data members
AccountUsage (41)
int64 BlocksUsed
int64 BlocksInOldFiles
int64 BlocksInDeletedFiles
int64 BlocksInDirectories
int64 BlocksSoftLimit
int64 BlocksHardLimit
int32 BlockSize
GetIsAlive (42)
# no data members
IsAlive (43)
# no data members
Message Types :
handshake, command, reply, error, stream.
Since each command has its own sequence of parameters, given above, you could regard each command as a message type.
Message opcodes :
Operation codes are given in brackets after each message description above.
Message Sequences :
After handshake, the client sends Command messages to the server, and receives Reply messages (one of which is Error).
Any command (except Handshake) may receive an Error reply.
client message -> expected response from server
Handshake -> Handshake
Version -> Version
Login -> LoginConfirmed
Finished -> Finished
SetClientStoreMarker -> Success
GetObject -> Success (followed by stream)
MoveObject -> Success
GetObjectName -> ObjectName
CreateDirectory -> Success
ListDirectory -> Success + stream
ChangeDirAttributes -> Success
DeleteDirectory -> Success
UndeleteDirectory -> Success
StoreFile + stream -> Success
GetFile -> Success + stream
SetReplacementFileAttributes + stream -> Success
DeleteFile -> Success
GetBlockIndexByID -> Success + stream
GetBlockIndexByName -> Success + stream
GetAccountUsage -> AccountUsage
GetIsAlive -> IsAlive
Protocol functions :
Management of encrypted files, directories and block indexes (checksums) on an untrusted remote backup server.
Broadcast or Multicast used ?
no
How and what for Broadcast or Multicast is used (if used):
Description :
An open source, completely automatic on-line backup system for UNIX and Windows.
All backed up data is stored on the server in files on a filesystem -- no tape or archive devices are used. The server is trusted only to make files available when they are required -- all data is encrypted.
A backup daemon runs on systems to be backed up, and copies encrypted data to the server when it notices changes.
We need a port number for the server to listen on for requests from backup daemons.
Name of the port :
Box Backup Store Service
Short name of the port :
boxbackupstore
More information about the Boxbackup
mailing list