path: root/src/fuse/cowDoc/readme.md

Fuse Copy on Write (CoW)
Table of Contents

Introduction
Usage
Implementation Details
REST Api

Introduction
This extension to the fuse dnbd3 client allows it to mount images writable. The changes to an writeable mounted image will be stored in a separate files (also called Copy on Write (Cow)) on the client computer. These changes are uploaded in the background to the cow server. Once the user unmounts the images all remaining changes will be uploaded. Then the image will be merged on the server (if set so in the startup parameters).
Usage
New Parameters

-c <path> Enables the cow functionality, the argument sets the path for the temporary .meta and .data file in which the writes are stored
-C <address> sets the address of the cow server. The cow server is responsible for merging the original image with the changes from the client.
-L <path> Similar to -c <path> but instead of creating a new session it loads an existing from the given path.
-m if set, the client will request a merge after the image is unmounted and all change are uploaded.

Example parameters for creating a new cow session:
./dnbd3-fuse "/home/user/VMs/mount" -f -h localhost -i test -c "/home/user/temp" -C "192.168.178.20:5000"


Implementation Details
Files
If a new CoW session is started, a new meta, data and status.txt file is created.
status.txt
While the cow session ist active the file contains:
uuid: <uuid>
state: active



The uuid is the session uuid, which the cow server uses to identify the session.

Once the user unmounts the image the file contains:
uid: <uuid>
state: uploading
uploaded: <number>
totalBlocks: <number>




uploaded is the number of Blocks which are already uploaded.


totalBlocks is the total Number of Blocks which need to be uploaded.


Once all blocks are uploaded the state will be set to done.
meta.dat
The meta file contains the following header:
// cowfile.h
typedef struct __attribute__( ( packed ) ) cowfile_metadata_header
{
    uint64_t magicValue;            // 8byte
    atomic_uint_fast64_t imageSize; // 8byte
    int32_t version;                // 4byte
    int32_t blocksize;              // 4byte
    uint64_t originalImageSize;     // 8byte
    uint64_t metaDataStart;         // 8byte
    int32_t bitfieldSize;           // 4byte
    int32_t nextL2;                 // 4byte
    atomic_size_t metadataFileSize; // 8byte
    atomic_size_t dataFileSize;     // 8byte
    uint64_t maxImageSize;          // 8byte
    uint64_t creationTime;          // 8byte
    uuid_t uuid;                    // 16byte
    char imageName[200];            // 200byte
} cowfile_metadata_header_t;


data
The data files contains
magic values in the file headers
The magic values in both files are used to ensure that a suitable file is read and that the machine has the correct endianness.
//config.h
#define COW_FILE_META_MAGIC_VALUE ((uint64_t)0xEBE44D6E72F7825E) // Magic Value to recognize a Cow meta file
#define COW_FILE_DATA_MAGIC_VALUE ((uint64_t)0xEBE44D6E72F7825F) // Magic Value to recognize a Cow data file


Data strucure

REST Api
To transfer the data to the cow server, the following rest api is used:
/api/File/Create
POST
Responses



Code
Description




200
Success



/api/File/Update
POST
Parameters



Name
Located in
Description
Required
Schema




guid
query

Yes
string (uuid)


blockNumber
query

Yes
integer



Responses



Code
Description




200
Success



/api/File/StartMerge
GET
Parameters



Name
Located in
Description
Required
Schema




guid
query

Yes
string (uuid)


fileSize
query

Yes
long



Responses



Code
Description




200
Success



/api/File/Satus
GET
Parameters



Name
Located in
Description
Required
Schema




guid
query

Yes
string (uuid)



Responses



Code
Description




200
Success



Models
SessionState



Name
Type
Description
Required




SessionState
string

Yes



SessionStatus



Name
Type
Description
Required




state
string
Enum: "Copying", "Active", "Merging", "Done"
Yes


imageName
string

Yes


originalImageVersion
integer

Yes


newImageVersion
integer

Yes


mergedBlocks
integer

Yes


totalBlocks
integer

Yes