wiki:BoxBackupStoreProtocol

Version 1 (modified by chris, 8 months ago) (diff)

initial protocol docs: dumped from email

Application for User Registered Port Number Name : Chris Wilson E-mail : [email protected]… 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?

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