# Uploading and Managing Files * [Uploading and Managing Files](#uploading-and-managing-files) * [Upload a file to dStorage](#uploading-a-file-to-dstorage) * [Uploading an Encrypted File to dStorage](#uploading-an-encrypted-file-to-dstorage) * [Create directory on dStorage](#create-directory) * [Updating the contents of a file on dStorage](#updating-the-contents-of-a-file-on-dstorage) * [Sharing a file on dStorage](#sharing-a-file-on-dstorage) * [Downloading the file from dStorage](#downloading-the-file-from-dstorage) * [Copy uploaded files to another folder path on dStorage](#copy-file-to-another-existing-folder-in-dstorage) * [Move uploaded files to another folder path on dStorage](#moving-files-between-directories-in-dstorage) * [Renaming Files on dStorage](#renaming-files-in-dstorage) * [List files from Blobbers](#list-files-from-blobbers) * [Get Stats for file in dStorage](#get-stats-for-file-in-dstorage) * [Get metadata for stored file on dStorage](#get-metadata-for-stored-file) * [Get Download Cost for a file on dStorage](#download-cost) * [Get Cost for Uploading a file on dStorage](#upload-cost) * [Sync](#sync) * [Batch Upload Files to dStorage](#batch-upload-files-to-dstorage) * [Private File Sharing](#private-file-sharing) * [Cancel Sharing of File for a Particular User](#cancel-sharing-of-file-for-a-particular-user) * [Private Directory Sharing](#private-directory-sharing) * [Repair a file on dStorage](#repair-a-file-on-dstorage) * [Rollback](#rollback) * [Total Stored Data](#total-stored-data) * [Asking the receiver to pay for download](#asking-the-receiver-to-pay-for-download-rx_pay) * [Video Streaming](#video-streaming) * [Feed](#feed) ### Uploading a file to dStorage `./zbox upload` command is used to upload a file on dStorage. Parameters for uploading a file to dStorage can be viewed by using the `./zbox upload --help command.` Here are the Parameters : | Parameter | Required | Description | Default | Valid values | | ------------- | -------- | ------------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id, sender must be allocation owner | | string | | commit | no | save metadata to blockchain | false | boolean | | encrypt | no | encrypt file before upload | false | boolean | | localpath | yes | local path of the file to upload | | file path | | remotepath | yes | remote path to upload file to, use to access file later | | string | | thumbnailpath | no | local path of thumbnail | | file path | Example : Let's upload an info.txt file to allocation, the local path for the file is mapped to a `local` variable and the remote directory is mapped to a `remote` variable which is `myfiles/info.txt.` Sample Command: ``` ./zbox upload --localpath $local --remotepath $remote --allocation $ALLOC ``` Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-1b4221939fcfa0944e32742c534f853021e88118%2Fzbox%20fileupload.gif?alt=media) Verify whether the uploaded file is available on dStorage using list command required parameters are allocation ID and remote path ``` ./zbox list --remotepath $remote --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS |LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+----------+-------------------+------+------------+----------------------------------------------- f | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c4322 69eeb7def555f1f8b9b9a28bd9611362c | NO | owner ​ ``` The response yields a lookuphash which works as a unique identifier for the uploaded file. Since you uploaded the file, the download payer section will show it as `owner`. Copy and mark your lookup hash to a variable as it will be used for performing other file operations\ `export LOOKUPHASH=f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c` ### Uploading an Encrypted File to dStorage Parameters for encrypting and uploading a file to dStorage are almost the same as [uploading a file on dStorage ](#uploading-a-file-to-dstorage)and only requires an additional `--encrypt` flag with the command. For instance if we want to encrypt and upload a sample `info.txt` file the command would be: Command: ``` ./zbox upload --encrypt --localpath $local --remotepath $remote --allocation $ALLOC ``` Response: ``` 24 / 24 [================================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = info.txt ``` To verify whether the file is encrypted and uploaded to dstorage use the list command : ``` ./zbox list --allocation $ALLOC --remotepath $remote ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS |LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+----------+-------------------+------+------------+----------------------------------------------- f | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c432269 eeb7def555f1f8b9b9a28bd9611362c | YES | owner ``` Scroll right in the response and check the `IS ENCRYPTED` section, it will say `YES` if the file is encrypted. ### Updating the contents of a file on dStorage Use `./zbox update` command to update the content of an existing file in the remote path. Like upload command. Only the owner of the allocation or a collaborator can update a file. To add collaborators to an allocation, check [File Collaboration.](#file-collaboration) Parameters for updating the contents of the file on dStorage can be seen by typing `./zbox update --help` Here are the parameters: | Parameter | Required | Description | Default | Valid values | | ------------- | -------- | ----------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | encrypt | no | encrypt file before upload | false | boolean | | localpath | yes | local file to upload | | file path | | remotepath | yes | remote file to upload | | string | | thumbnailpath | no | local fumbnail file to upload | | file path | | commit | no | save meta data to blockchain | false | boolean | Sample Command: ``` ./zbox update --localpath $local --remotepath $remote --allocation $ALLOC ``` Verify the contents of updated file on dStorage using the list command. ``` ./zbox list --remotepath $remote --allocation $ALLOC ``` Sample Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER ​ f | info.txt | /myfiles/info.txt | 76 | 4 | f15383a1130bd2fae1e52a7a15c432 269eeb7def555f1f8b9b9a28bd9611362c | NO | owner ​ ``` ### **Create Directory** `./zbox createdir` command is used to create directory on allocation for storing files. | Parameter | Description | Valid Values | | ------------ | ------------------------------------------ | ------------ | | --allocation | Provide Allocation ID | string | | --dirname | Provide Directory Name and absolute path . | string | | --h,--help | help for createdir | int | Sample Command: ``` ./zbox createdir --allocation $ALLOCATION_ID --dirname /photos ``` Sample Response: ``` /photos directory created ``` **Note:** To verify whether directory is created successfully run [List all files](https://github.com/0chain/zboxcli/tree/hm90121-patch-1#list-all-files) command. ### Sharing a File on dStorage Zbox supports sharing of files using auth tokens. Sharing can be encrypted or not encrypted for this section we will describe the non-encrypted share functionality. For encrypted shared functionality have a look at [Private Sharing](#private-data-sharing) . `./zbox share` command is used to generate an authtoken that provides authorization to the holder to the specified file on the remotepath. Parameters for sharing the file can be viewed using the `./zbox share --help` The parameters are: | Parameter | Required | Description | Valid values | | ------------------- | -------- | ----------------------------------------------------------------- | ------------ | | allocation | yes | allocation id | string | | clientid | no | id of user to share file with, leave blank for public share | string | | encryptionpublickey | no | public key of the client to share file with, required if clientId | string | | expiration-seconds | no | seconds before `auth ticket` expires | int | | remotepath | yes | remote path of file to share | string | | revoke | no | revoke share for remote path | flag | Command: ``` ./zbox share --remotepath $remote --allocation $ALLOC ``` The response will yield an Auth token which can be shared publicly to users for downloading the file. Sample Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-9c4abc0f45b29da1d4322734d5319a8660df4b95%2Fzbox%20share.gif?alt=media) Note: Use an export command and mark your Auth token to a variable to use with more commands ``` export AUTH= eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3NTNkMjlkODE5ODkyNmZhYzJlZDQzYWNj MzcwNDhhNzFmZmYzNDg2YTQ4N2ZjNmVlZDU0ZWFkNDY5YWQxNTkiLCJhbGxvY2F0aW9uX2lkIjoiNTJmYjl iNTkyNmMwNmU0M2E5MjkwZTlkN2FkMzIxN2E0YWVlNTFjOTQ2ODRiYWYwZmMxNzRhYTQxYWJlNjA1OSIsIm ZpbGVfcGF0aF9oYXNoIjoiZjE1MzgzYTExMzBiZDJmYWUxZTUyYTdhMTVjNDMyMjY5ZWViN2RlZjU1NWYxZ jhiOWI5YTI4YmQ5NjExMzYyYyIsImZpbGVfbmFtZSI6ImluZm8udHh0IiwicmVmZXJlbmNlX3R5cGUiOiJmIi wiZXhwaXJhdGlvbiI6MTYyNjIwNDM5NSwidGltZXN0YW1wIjoxNjE4NDI4Mzk1LCJyZV9lbmNyeXB0aW9uX2tle SI6IiIsInNpZ25hdHVyZSI6ImM1ZDViYzY3M2Q1NTNmZmM3M2FhNTg2MDkwNDgwODVlMjZhN2UyZmUzNTQ2MjA5O TlhNTk3NDdhNDFlNmNiMWQifQ== ``` ## Downloading the file from dStorage The `./zbox download` can be used to download the file in two ways from dStorage. Using the Allocation ID or Authticket. ### Download using Allocation ID and Remotepath Parameters for downloading the contents of file from dStorage can be viewed using the`./zbox download --help` Here are the parameters: | Parameter | Required | Description | Default | Valid values | | --------------- | -------- | ----------------------------------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | authticket | no | auth ticked if not owner of the allocation, use share to get auth ticket | | string | | blockspermarker | no | download multiple blocks per marker | 10 | int | | commit | no | save metadata to blockchain | false | boolean | | endblock | no | download until specified block number | | int | | localpath | yes | local path to which to download the file to | | file path | | remotepath | yes | remote path to which the file was uploaded | | string | | rx\_pay | no | `authticket` must be valid, true = sender pays, false = allocation owner pays | false | boolean | | startblock | no | start download from specified block | | int | | thumbail | no | only download the thumbnail | false | boolean | Command: ``` ./zbox download --localpath $local --remotepath $remote --allocation $ALLOC ``` Sample Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-491dc312ade27facbccba5854dad7f70b75638c7%2Fzbox%20download.gif?alt=media) If you are not able to download files and getting **Error in file operation: File content didn't match with uploaded file** response check [Error 2 in Tips and Troubleshooting Section](#error-2-error-in-file-operation-file-content-didnt-match-with-uploaded-file). ### Download using Authticket The necessary flags for downloading the file using the Authticket is auth ticket and local path. Get the AuthToken for the file on dstorage from another user and mark it to a variable. We will use auth token created and marked to `AUTH` variable for the file we shared in [sharing a file on dStorage section](#sharing-a-file-on-dstorage) . Command: ``` ./zbox download --authticket $AUTH --localpath $local ``` Response: ``` 28 / 28 [==========================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = info.txt ``` As you can see Zbox has identified the file(info.txt) based on the auth token and didn't require any remote path and allocation id. ## Deleting a File from dStorage Deleting the file on dStorage can be done using the `./zbox delete` command. Parameters for deleting the contents of the file on dStorage can be seen by typing `./zbox delete --help` Here are the parameters: | Parameter | Required | Description | Default | Valid values | | ---------- | -------- | ----------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | remotepath | yes | remote path of file to delete | | string | | commit | no | save meta data to blockchain | false | boolean | Command: ``` ./zbox delete --remotepath $remote --allocation $ALLOC ``` Sample Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-0b6e3f8063b7e239ecfe29cb3128997c2910e19c%2Fzbox%20delete.gif?alt=media) Verify whether the updated txt file is available on dstorage using the list command ``` ./zbox list --remotepath $remote --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+------+------+------+------------+-------------+--------------+-----------------+ ​ ​ ``` As you can see the file is not showing in remote directory which means the file has been successfully deleted. ## **Copy File to Another Existing Folder in dStorage** Use `./zbox copy`command to copy file to another folder path in dStorage. Only the owner of the allocation can copy an object. By using `./zbox copy --help` .You can have a look at the parameters: | Parameter | Required | Description | default | Valid values | | ---------- | -------- | ------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | commit | no | save metadata to blockchain | false | boolean | | remotepath | yes | remote path of object to copy | | string | | destpath | yes | destination, an existing directory to copy object | | string | Required Flags for copying the file to another folder are Allocation ID, the remote path to the existing file on dstorage, and the new destination path/folder path to copy a file to. Steps : 1. Verify whether the sync.txt file is available in the remote path using list command. ``` ./zbox list --remotepath / --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+----------+-----------+------+------------+------------------------------------------------------------------+--------------+-----------------+ d | myfiles | /myfiles | | 4 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a | | owner f | sync.txt | /sync.txt | 68 | 4 | 1fe7228abacc12a28277ff2fb5f97c7b7288942b8bbd7c5a96f80a1a65a0367e | NO | owner ``` 2\. Use the `./zbox copy` command to copy files. ``` ./zbox copy --remotepath /sync.txt --destpath /myfiles --allocation $ALLOC ``` Successful Response: ``` /sync.txt copied ``` 3\. Verify whether the file has copied using: ``` ./zbox list --remotepath /myfiles --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+----------+-------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+ f | info.txt | /myfiles/info.txt | 76 | 4 | f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c | NO | owner f | sync.txt | /myfiles/sync.txt | 68 | 4 | 4a5669bef007b8f3b8a93e34fb9c43ab1f868701379777c2580b8196029e9923 | NO | owner ``` ## **Moving Files Between Directories in dStorage** The `./zbox move` command can be used to move files between folder paths in dStorage. The parameters required for the move command can be viewed using `./zbox move --help` | Parameter | Required | Description | default | Valid values | | ---------- | -------- | ------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | commit | no | save metadata to blockchain | false | boolean | | remotepath | yes | remote path of object to copy | | string | | destpath | yes | destination, an existing directory to copy object | | string | The required parameters are Allocation ID , dest path and remote path of the moving file .\ Steps: 1. Verify whether the directories are available in the remote path using the list command. ``` ./zbox list --remotepath / --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+----------+-----------+------+------------+------------------------------------------------------------------+--------------+-----------------+ d | myfiles | /myfiles | | 8 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a | | owner f | sync.txt | /sync.txt | 68 | 4 | 1fe7228abacc12a28277ff2fb5f97c7b7288942b8bbd7c5a96f80a1a65a0367e | NO | owner d | myfiles1 | /myfiles1 | | 4 | d541b2190c7527967ae10a8f991f34ebf9d474c10ba02832d224093110f1fcfc | | owner ``` As you can see there are two directory paths available `/myfiles` and `myfiles1`.We will move the info.txt file available remotepath `/myfiles` to the `destpath` `/myfiles1` . 2\. Use the `./zbox move` command ``` ./zbox move --remotepath /myfiles/info.txt --destpath /myfiles1 --allocation $ALLOC ``` Successful Response: ``` /myfiles/info.txt moved ``` 3\. Verify whether the file has moved by listing the directory path using: ``` ./zbox list --remotepath /myfiles1 --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+-----------+---------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+ f | info1.txt | /myfiles1/info1.txt | 112 | 4 | 675fab6ebfd03539848e224c2f758af33f5c8f34fb1471c9ede1fa387e389d52 | NO | owner f | info.txt | /myfiles1/info.txt | 76 | 4 | c369ce1609ca141142ab3146b7c436d945bfa4f1dd6dda1f19820dbd71c3dfe1 | NO | owner ``` ## **Renaming Files in dStorage** `./zbox rename` command can be used to rename files already existing in dStorage.Only the allocation's owner can rename a file. Parameters for the command can be viewed using `./zbox rename --help` | Parameter | Required | Description | default | Valid values | | ---------- | -------- | ------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | commit | no | save metadata to blockchain | false | boolean | | destname | yes | new neame of the object | | string | | remotepath | yes | remote path of object, do not use with authticket | | string | Command: ``` ./zbox rename --remotepath /sync.txt --destname $DEST_PATH --allocation $ALLOC ``` Response: ``` /sync.txt renamed ``` Verify by listing the remote path using ``` ./zbox list --remotepath / --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+-------------------+-------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+ d | myfiles | /myfiles | | 4 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a | | owner d | myfiles1 | /myfiles1 | | 8 | d541b2190c7527967ae10a8f991f34ebf9d474c10ba02832d224093110f1fcfc | | owner f | /myfiles/info.txt | /myfiles/info.txt | 68 | 4 | f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c | NO | owner ``` ### List files from Blobbers `./zbox list`command is used to list all the files from a specified directory on dStorage. Use `./zbox list --help` to know the possible parameters. | Parameter | Required | Description | Valid Values | | ---------- | -------- | ------------------------------------ | ------------ | | allocation | yes | allocation id | string | | lookuphash | | adjust storage expiration time | string | | remotepath | yes | Remote Path of directory on dStorage | string | Command : ``` ./zbox list --remotepath $remote --allocation $ALLOC ``` Sample Response : ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-8a8fade32eaa1c18005a86655d5716fd9ee753fc%2Fzbox%20list%20files%20in%20directory.gif?alt=media) ### **Get Stats for file in dStorage** `./zbox stats` command can be used to get upload, download and challenge information for a file. Parameters for the command can be viewed using `./zbox stats --help` | Parameter | Required | Description | default | Valid values | | ---------- | -------- | --------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | json | no | print result in json format | false | boolean | | remotepath | yes | file of which to get stats | | string | Steps: 1. Verify whether the file exists at the remote path using ``` ./zbox list --remotepath $remote --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+-----------+---------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+ f | info1.txt | /myfiles1/info1.txt | 112 | 4 | 675fab6ebfd03539848e224c2f758af33f5c8f34fb1471c9ede1fa387e389d52 | NO | owner f | info.txt | /myfiles1/info.txt | 76 | 4 | c369ce1609ca141142ab3146b7c436d945bfa4f1dd6dda1f19820dbd71c3dfe1 | NO | owner ``` 2\. Run the stats command using ``` ./zbox stats --remotepath $remote --allocation $ALLOC ``` Sample Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-fc6193f058dd9649d49f144bb2852be5c64ebde0%2Fzbox%20stats.gif?alt=media) ### Get metadata for stored file `./zbox meta` command is used to get meta data for the given file in dStorage . Use `./zbox meta --help` to know more about possible flags. | Parameter | Required | Description | default | Valid values | | ---------- | -------- | ------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | authticket | no | auth ticked if not owner of the allocation | | string | | json | no | print result in json format | false | boolean | | lookuphash | no | hash of object, use with auth ticket | | string | | remotepath | no | remote path of object, do not use with authticket | | string | Command: ``` ./zbox meta --remotepath $remote --allocation $ALLOC ``` Sample Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-ec49b7bcba305e03c556c735c1ba607aea1392d1%2Fzbox%20meta.gif?alt=media) ### **Get** Download cost `./zbox get-download-cost` determines the cost for downloading the remote file from dStorage. The client must either be the owner, a collaborator or be using an auth ticket. | Parameter | Required | Description | default | Valid values | | ---------- | -------- | ----------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | authticket | no | auth ticket to use if not the owner | | string | | lookuphash | no | hash of remote file, use with auth ticket | | string | | remotepath | yes | file of which to get stats, use if owner | | string | Command: ``` ./zbox get-download-cost --allocation $ALLOC --remotepath $remote ``` Sample Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-bf50dec9b5bc51324027d0191979138fc884acb5%2Fzbox%20download%20cost.gif?alt=media) ### Get Upload cost `./zbox get-upload-cost` determines the cost for uploading a local file on dStorage. `--duration` Ignored if `--end` true, in which case the cost of upload calculated until the allocation expires. | Parameter | Required | Description | default | Valid values | | ---------- | -------- | ------------------------------------ | ------- | ------------ | | allocation | yes | allocation id | | string | | duration | no | duration for which to upload file | | duration | | end | no | upload file until allocation expires | false | boolean | | localpath | yes | local of path to calculate upload | | file path | Command: ``` ./zbox get-upload-cost --allocation $ALLOC --localpath $local ``` Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-408b6e37be43751605542e6e6a618c5f5d21ec63%2Fzbox%20upload%20cost.gif?alt=media) ### Get Differences `./zbox get-diff` command returns the differences between the local files specified by `localpath` and the files stored on the root remotepath of the allocation.`localcache` flag can also be specified to use the local cache of remote snapshot created during[ Sync](https://docs-old.zus.network/guides/zbox-cli/broken-reference) for file comparison. | Parameter | Required | Description | default | Valid values | | ----------- | -------- | --------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | excludepath | no | remote folder paths to exclude during syncing | | string array | | localcache | no | local cache of remote snapshot | | string | | localpath | yes | local directory to sync | | string | Command: ``` ./zbox get-diff --allocation $ALLOC --localpath $local ``` Response :
Formatted Shortened Response : ``` [{"operation":"Upload","path":"/file1.txt","type":"f","attributes":{}}, {"operation":"Upload","path":"/file2.txt","type":"f","attributes":{}}, {"operation":"Upload","path":"/file3.txt","type":"f","attributes":{}}, {"operation":"Download","path":"/myfiles/file1.txt","type":"f","attributes":{}}, {"operation":"Download","path":"/myfiles/file2.txt","type":"f","attributes":{}}] ``` ### Sync `./zbox sync` command is used to sync all files in the local folder. Creation, deletion and updation will be done automatically. Parameter details can be viewed using the `./zbox sync --help command.` Here are the Parameters: | Parameter | Required | Description | default | Valid values | | ----------- | -------- | -------------------------------------------------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | commit | no | commet metadata to blockchain | false | boolean | | encryptpath | no | local directory path to be uploaded as encrypted | false | boolean | | excludepath | no | paths to exclude from sync | | string array | | localcache | no | local cache of remote snapshot. Used for comparsion with remote. After sync will be updated. | | string | | localpath | yes | local directory to which to sync | | file path | | uploadonly | no | only upload and update files | false | boolean | Example: Let's sync files stored in the local directory .The local directory for sync in the command below is mapped to `local` variable. Variable `cache` is marked to local cache text file located inside the local directory.`.` Command: ``` ./zbox sync --localpath $local --localcache $cache --allocation $ALLOC ``` Response: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-84dd52f3ec8cadbf6b7a7111937f18240d407662%2Fzbox%20sync.gif?alt=media) Verify whether all the files located in the local directory are synced to dStorage using ``` ./zbox list --remotepath / --allocation $ALLOC ``` ### Batch upload files to dStorage `./zbox sync` command with `--uploadonly` flag can be used to upload all the files in local folder to dStorage. Parameter details can be viewed using the `./zbox sync --help` Here are the Parameters: | Parameter | Required | Description | default | Valid values | | ----------- | -------- | -------------------------------------------------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | commit | no | commet metadata to blockchain | false | boolean | | encryptpath | no | local directory path to be uploaded as encrypted | false | boolean | | excludepath | no | paths to exclude from sync | | string array | | localcache | no | local cache of remote snapshot. Used for comparsion with remote. After sync will be updated. | | string | | localpath | yes | local directory to which to sync | | file path | | uploadonly | no | only upload and update files | false | boolean | Example:\ We will create three txt files and move them into a directory to specify it as a local path for the `./zbox sync` command. Here is the list of contents of the directory: ``` file1.txt file2.txt file3.txt​ ``` Now by using the `./zbox sync` command with `--uploadonly`flag we will batch upload these files to the dStorage .Variable `local` is marked to local directory containing all the files for upload. Variable `cache` is marked to local cache text file located inside the local directory. Command: ``` ./zbox sync --uploadonly --localpath $local --localcache $cache ``` Response ``` OPERATION | PATH +-----------+------------+ Upload | /file1.txt Upload | /file2.txt Upload | /file3.txt ​ 12 / 12 [=======================================================================================================================================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = file1.txt 24 / 24 [=======================================================================================================================================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = file2.txt 28 / 28 [=======================================================================================================================================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = file3.txt ​ Sync Complete ​ ``` Verify whether the files are uploaded using ``` ./zbox list --remotepath / --allocation $ALLOC ``` Response: All the files located in the local directory should be listed in the remotepath. ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+-----------+------------+------+------------+------------------------------------------------------------------+--------------+-----------------+ d | myfiles | /myfiles | | 4 | e8129c2bc551226f0043b17c218f27bfaababd3e6340c60590e4edbbd9cb2517 | | owner f | file1.txt | /file1.txt | 12 | 4 | 899454ceec5d3791f15743dfd91ce22eb9b365f1563c5e389bf3b0ca2e92f85f | NO | owner f | file2.txt | /file2.txt | 24 | 4 | 585d0cc1fcffbf5d2c13697489eb3d49247deaebda380c60afd759b4ca15dad6 | NO | owner f | file3.txt | /file3.txt | 28 | 4 | 63c8f593b9341873f4b5f478c49da1b6d9c58a3aefc4f483a017b86840ba0e7d | NO | owner ``` ### Private File Sharing Private sharing of files can be implemented using the `./zbox share command`.Parameters can be viewed using`./zbox share --help`are shown below: | Parameter | Required | Description | Valid values | | ------------------- | -------- | ----------------------------------------------------------------- | ------------ | | allocation | yes | allocation id | string | | clientid | no | id of user to share file with, leave blank for public share | string | | encryptionpublickey | no | public key of the client to share file with, required if clientId | string | | expiration-seconds | no | seconds before `auth ticket` expires | int | | remotepath | yes | remote path of file to share | string | | revoke | no | revoke share for remote path | flag | #### **Note: Private File Sharing only works with encrypted files.** Let's consider two users (User A and B) and User A wants to privately share the `info.txt` file located in `myfiles/info.txt` directory in dStorage with User B. 1.User A will upload the encrypted `info.txt` file. For instructions on how to upload an encrypted file check[ Uploading an Encrypted file on dStorage](#uploading-an-encrypted-file-file-to-dstorage). 2\. User B has to share his client id and encryption public key which can be retrieved using the`getwallet`command. Here we are showing the output of the UserB `getwallet` command Command: ``` ./zbox getwallet ``` Response: ``` PUBLIC KEY | CLIENTID | ENCRYPTION PUBLIC KEY 9bdb7137eab401bf715d49479fd7790a35b270ac08b23b5778fea005c81f2f19a66785bb7917830d2d 513afffc4061bc578fa9af09eb2cf17fd8a6fdb877ef8e | 8e4e5ad06a7fef3e3810074f0f6b2d203170d0e386a84936ea5fc94428ce18c9 | qpV7bqX77UEzNj722qIrxgpHBVR5i8sR6UDdQ70ZSys= ​ ``` 3.Let's export the User B clientid and public encryption key to a variable named `UserB` and `PUBLIC_KEY_UserB` ``` export UserB=8e4e5ad06a7fef3e3810074f0f6b2d203170d0e386a84936ea5fc94428ce18c9 export PUBLIC_KEY_UserB=qpV7bqX77UEzNj722qIrxgpHBVR5i8sR6UDdQ70ZSys= ``` 4.Now use the `./zbox share` command with above exported variables .Also specify the allocation and remote path for the file shared by User A which is `myfiles/info.txt` . So the sample command for the UserA is: ``` ./zbox share --clientid $UserB --encryptionpublickey $PUBLIC_KEY_UserB --allocation $ALLOC --remotepath /myfiles/info.txt ``` Response: ``` Auth token:eyJjbGllbnRfaWQiOiIyNmU1YjcwZmNiYTNmNzJhNDc1ZWYxZGJjNjZlNDU0ZDNiNDU4Yjk1MGQ2MmM2ZWMyMThjYzM0MjVlM2I2MjFmIiwib3duZXJfaWQiOiJlZmE1MDVhOGFiMzBkNGE3ZTAzNTM4OGE1YzA5OTg1YWY5YTNhMDQyYmFkYzBkODY4YjYyYWRkMjQyMzlkNWExIiwiYWxsb2NhdGlvbl9pZCI6IjFkYTBmYzhmNTgwZTZmZTI3M2QwN2MyZTU0NGEyNjA4MDRlMmVmNTBiMjM4OTAwZGYzMzAwNDIzYzI0YjYwYmQiLCJmaWxlX3BhdGhfaGFzaCI6IjNjNDRkNWRhNDM2ODdhMjJkMmUxMDM1NTQ3NDQ1YjA4NDFlMzQ0YWVmMzk1NGU1MWM3MzAwYTU3NDgwNzVkMWUiLCJmaWxlX25hbWUiOiJpbmZvLnR4dCIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2Mjg1MzM5NzUsInRpbWVzdGFtcCI6MTYyMDc1Nzk3NSwicmVfZW5jcnlwdGlvbl9rZXkiOiJ7XCJyMVwiOlwiRHY3WTNQTFEyNXJ3VEFuZjdQRlI5TWw1cHRlTDFSeXpvQ1VJbjJZMXU3Zz1cIixcInIyXCI6XCJSV0tKSzNLUnE3SHBHQ1BUd2M5YUc4NE8xaXdjSkFWQitXQTdsTEg2UmFjPVwiLFwicjNcIjpcIjArRG5QU0ZOQzZuMWpwSlduS2R4M3dqRlYwcjFzTnduNHBOUEhtNUJmQUE9XCJ9Iiwic2lnbmF0dXJlIjoiYjA0YmFiYTM4NTk0MDg0ZTBjZjI4ZjlmMjg5MDc5ZGJkODg3YWM2MWYwMDEyYjdhOTc3ZjY2YmM3MzQ1ODgwZCJ9 ​ ``` The Response provides an encrypted auth token string that only UserB can use for private download. Any other user using this AuthToken will not be able to download the file. 5.Let's use `./zbox download` using Authtoken provided on UserB computer to privately download the file. Necessary Flags are Authtoken and local path to save the file. Make sure to point encrypted auth token using the `export AUTH=` before running the download command. ``` ./zbox download --authticket $AUTH --localpath /root/ ``` Response: ``` 23 / 23 [=======================================================================================================================================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = info.txt• ``` 6.To check sharing details and verify whether the file is encrypted. You can also base decode the Authtoken using: ``` echo 'eyJjbGllbnRfaWQiOiIyNmU1YjcwZmNiYTNmNzJhNDc1ZWYxZGJjNjZlNDU0ZDNiNDU4Yjk1MGQ2MmM2ZWMyMThjYzM0MjVlM2I2MjFmIiwib3duZXJfaWQiOiJlZmE1MDVhOGFiMzBkNGE3ZTAzNTM4OGE1YzA5OTg1YWY5YTNhMDQyYmFkYzBkODY4YjYyYWRkMjQyMzlkNWExIiwiYWxsb2NhdGlvbl9pZCI6IjFkYTBmYzhmNTgwZTZmZTI3M2QwN2MyZTU0NGEyNjA4MDRlMmVmNTBiMjM4OTAwZGYzMzAwNDIzYzI0YjYwYmQiLCJmaWxlX3BhdGhfaGFzaCI6IjNjNDRkNWRhNDM2ODdhMjJkMmUxMDM1NTQ3NDQ1YjA4NDFlMzQ0YWVmMzk1NGU1MWM3MzAwYTU3NDgwNzVkMWUiLCJmaWxlX25hbWUiOiJpbmZvLnR4dCIsInJlZmVyZW5jZV90eXBlIjoiZiIsImV4cGlyYXRpb24iOjE2Mjg1MzM5NzUsInRpbWVzdGFtcCI6MTYyMDc1Nzk3NSwicmVfZW5jcnlwdGlvbl9rZXkiOiJ7XCJyMVwiOlwiRHY3WTNQTFEyNXJ3VEFuZjdQRlI5TWw1cHRlTDFSeXpvQ1VJbjJZMXU3Zz1cIixcInIyXCI6XCJSV0tKSzNLUnE3SHBHQ1BUd2M5YUc4NE8xaXdjSkFWQitXQTdsTEg2UmFjPVwiLFwicjNcIjpcIjArRG5QU0ZOQzZuMWpwSlduS2R4M3dqRlYwcjFzTnduNHBOUEhtNUJmQUE9XCJ9Iiwic2lnbmF0dXJlIjoiYjA0YmFiYTM4NTk0MDg0ZTBjZjI4ZjlmMjg5MDc5ZGJkODg3YWM2MWYwMDEyYjdhOTc3ZjY2YmM3MzQ1ODgwZCJ9' | base64 --decode ``` Response:\ The response will provide all the private sharing details and encryption key for the shared file under `re_encryption_key` field. ``` {"client_id":"26e5b70fcba3f72a475ef1dbc66e454d3b458b950d62c6ec218cc3425e3b621f", "owner_id":"efa505a8ab30d4a7e035388a5c09985af9a3a042badc0d868b62add24239d5a1", "allocation_id":"1da0fc8f580e6fe273d07c2e544a260804e2ef50b238900df3300423c24b60bd", "file_path_hash":"3c44d5da43687a22d2e1035547445b0841e344aef3954e51c7300a5748075d1e", "file_name":"info.txt","reference_type":"f","expiration":1628533975,"timestamp":1620757975, "re_encryption_key":"{\"r1\":\"Dv7Y3PLQ25rwTAnf7PFR9Ml5pteL1RyzoCUIn2Y1u7g=\",\"r2\ ":\"RWKJK3KRq7HpGCPTwc9aG84O1iwcJAVB+WA7lLH6Rac=\",\"r3\":\"0+DnPSFNC6n1jpJWnKdx3wjFV0r1sNwn4pNPHm5BfAA=\"}", "signature":"b04baba38594084e0cf28f9f289079dbd887ac61f0012b7a977f66bc734" ``` ### Cancel Sharing of File for a Particular User `./zbox share --revoke` is used to cancel the share for particular buyer that performed by the seller through Private File Sharing. Note : `./zbox share --revoke`only works for encrypted files on dStorage. Required Parameters for Cancel Share are : | Parameter | Required | Description | Valid Values | | ---------- | -------- | ---------------------------------------------------------------------- | ------------ | | allocation | yes | allocation id | string | | remotepath | yes | remote path of an encrypted file that was earlier shared with the user | duration | | clientid | yes | Wallet Client ID of the user whose share access has to be revoked | string | Command : ``` ./zbox share --revoke --remotepath $remote --clientid User_CLIENT_ID --allocation $ALLOC ``` Response : ``` Share revoked for client User_CLIENT_ID ``` ### **Private Directory Sharing** Private sharing of directories can be implemented using the `./zbox share command`.Parameters can be viewed using`./zbox share --help`are shown below: | Parameter | Required | Description | Valid values | | ------------------- | -------- | ----------------------------------------------------------------- | ------------ | | allocation | yes | allocation id | string | | clientid | no | id of user to share file with, leave blank for public share | string | | encryptionpublickey | no | public key of the client to share file with, required if clientId | string | | expiration-seconds | no | seconds before `auth ticket` expires | int | | remotepath | yes | remote path of file to share | string | | revoke | no | revoke share for remote path | flag | **Note: Private Directory Sharing works for both encrypted and non-encrypted files** Let's consider two users (User A and B) and User A wants to privately share the `docs` directory in dStorage with User B. 1.User A should check whether the `docs`directory exists on dStorage using the list command. Command : ``` ./zbox list --remotepath /docs --allocation c6507f3f6470972a928576a2f0cb00019fcc4ca8e60c8c9e085a8a905da6d838 ``` Response : ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER -------+-----------+-----------------+------+------------+------------------------------------------------------------------+--------------+------------------ f | info.txt | /docs/info.txt | 48 | 4 | 3b256a3b8fbf1f497eea5b7d149228fc23e39c98c7f06b960949690070157d3b | NO f | hello.txt | /docs/hello.txt | 30 | 3 | 4f2515f95d35c7d6641197cc024608b4dc2af1b4c8fb9af0f2637e0c89c3c5cc | NO ​ ``` 2\. Now User B has to share his client id and encryption public key which can be retrieved using the`getwallet`command. Here we are showing the output of the UserB `getwallet` command Command: ``` ./zbox getwallet ``` Response: ``` PUBLIC KEY | CLIENTID | ENCRYPTION PUBLIC KEY -----------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------------------------------------------- 9332ca57e335f286f1d3edc2dd7589594dbb4b30fae19766b5f67712520fde09f8eac6a979f3574ccd89e5680a6b47dcdc88ae0544dc30633cce2a7831ce0014 | 9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b | bKodfMsHfUNXr/rr8msPe4Rv2nLP34aUIasK44p7tRs= ​ ``` 3.Let's export the User B clientid and public encryption key to a variable named `UserB` and `PUBLIC_KEY_UserB` ``` export UserB=9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b export PUBLIC_KEY_UserB=bKodfMsHfUNXr/rr8msPe4Rv2nLP34aUIasK44p7tRs= ``` 4.Now use the `./zbox share` command with above exported variables .Also specify the allocation and remote path for the directory . ``` ./zbox share --clientid $UserB --encryptionpublickey $PUBLIC_KEY_UserB --allocation $ALLOC --remotepath /docs ``` Response: The Response provides an encrypted auth token string that only UserB can use for private download. Any other user using this AuthToken will not be able to download the file. ``` Auth token :eyJjbGllbnRfaWQiOiI5NDYwZDY0YWI2MzM0MGEwYjQzMDVkMjBhMDMyNjkwYTQ5NWVkNTB kNmRjOTJkMjM4YTQyYjI1ZmRmNzkyNThiIiwib3duZXJfaWQiOiJjZTk1ZGM4YWM5MzMyNDlhMjE4NTM3NT FkMzk5OWMzMWFhNjlmNmRiMDBjMDFmMTY2YTg3ODI4MzJmZWE3ZmQ4IiwiYWxsb2NhdGlvbl9pZCI6ImM2 NTA3ZjNmNjQ3MDk3MmE5Mjg1NzZhMmYwY2IwMDAxOWZjYzRjYThlNjBjOGM5ZTA4NWE4YTkwNWRhNmQ4Mzg iLCJmaWxlX3BhdGhfaGFzaCI6IjE0OGY3YjAyNWE2ZTA1ZWZlZWQ5N2YxMTA5ZmJjYzg1ZGIyMTU4MTRjZj JhODJmNjYyOTdjZjI3NWRjMjYyMDciLCJhY3R1YWxfZmlsZV9oYXNoIjoiYTU5MTc1NGM3MTY1Yzk0NzcwN GU4ZTM3OGY4ZmI2NTI4NjdhNjFjMSIsImZpbGVfbmFtZSI6ImRvY3MiLCJyZWZlcmVuY2VfdHlwZSI6ImYi LCJleHBpcmF0aW9uIjoxNjM3NTMxNTIzLCJ0aW1lc3RhbXAiOjE2Mjk3NTU1MjMsInJlX2VuY3J5cHRpb25 fa2V5IjoiIiwiZW5jcnlwdGVkIjp0cnVlLCJzaWduYXR1cmUiOiJmNThhNDViZGVkOGQzNDMwMzcyMzU3ZWQ 1MmEzODFmZmI5ZDk4MWNjMzc0NzQ4OTk3M2QzMDFmOGZjMDVjMzFkIn0= ``` 5\. The string is encoded , to know the sharing details of the string UserB can decode it using the command : ``` echo 'eyJjbGllbnRfaWQiOiI5NDYwZDY0YWI2MzM0MGEwYjQzMDVkMjBhMDMyNjkwYTQ5NWVkNTBkNmRjOT JkMjM4YTQyYjI1ZmRmNzkyNThiIiwib3duZXJfaWQiOiJjZTk1ZGM4YWM5MzMyNDlhMjE4NTM3NTFkMzk5O WMzMWFhNjlmNmRiMDBjMDFmMTY2YTg3ODI4MzJmZWE3ZmQ4IiwiYWxsb2NhdGlvbl9pZCI6ImM2NTA3ZjNm NjQ3MDk3MmE5Mjg1NzZhMmYwY2IwMDAxOWZjYzRjYThlNjBjOGM5ZTA4NWE4YTkwNWRhNmQ4MzgiLCJmaWx lX3BhdGhfaGFzaCI6IjE0OGY3YjAyNWE2ZTA1ZWZlZWQ5N2YxMTA5ZmJjYzg1ZGIyMTU4MTRjZjJhODJmNj YyOTdjZjI3NWRjMjYyMDciLCJhY3R1YWxfZmlsZV9oYXNoIjoiYTU5MTc1NGM3MTY1Yzk0NzcwNGU4ZTM3O GY4ZmI2NTI4NjdhNjFjMSIsImZpbGVfbmFtZSI6ImRvY3MiLCJyZWZlcmVuY2VfdHlwZSI6ImYiLCJleHBpc mF0aW9uIjoxNjM3NTMxNTIzLCJ0aW1lc3RhbXAiOjE2Mjk3NTU1MjMsInJlX2VuY3J5cHRpb25fa2V5Ijoi IiwiZW5jcnlwdGVkIjp0cnVlLCJzaWduYXR1cmUiOiJmNThhNDViZGVkOGQzNDMwMzcyMzU3ZWQ1MmEzODFm ZmI5ZDk4MWNjMzc0NzQ4OTk3M2QzMDFmOGZjMDVjMzFkIn0=' | base64 --decode ``` Response : ``` {"client_id":"9460d64ab63340a0b4305d20a032690a495ed50d6dc92d238a42b25fdf79258b", "owner_id":"ce95dc8ac933249a21853751d3999c31aa69f6db00c01f166a8782832fea7fd8", "allocation_id":"c6507f3f6470972a928576a2f0cb00019fcc4ca8e60c8c9e085a8a905da6d838", "file_path_hash":"148f7b025a6e05efeed97f1109fbcc85db215814cf2a82f66297cf275dc26207" ,"actual_file_hash":"a591754c7165c947704e8e378f8fb652867a61c1","file_name":"docs", "reference_type":"f","expiration":1637531523,"timestamp":1629755523,"re_encryption_key":"", "encrypted":true,"signature":"f58a45bded8d3430372357ed52a381ffb9d981cc3747489973d301f8fc05c31d"} ``` 6\. Now UserB can download files inside the shared directory with the AUTH token. First point the encrypted auth token to a variable using the `export` command. ``` export AUTH = eyJjbGllbnRfaWQiOiI5NDYwZDY0YWI2MzM0MGEwYjQzMDVkMjBhMDMyNjkwYTQ5NWVkNTBkNmRjOTJkMjM4YTQyYjI1ZmRmNzkyNThiIiwib3duZXJfaWQiOiJjZTk1ZGM4YWM5MzMyNDlhMjE4NTM3NTFkMzk5OWMzMWFhNjlmNmRiMDBjMDFmMTY2YTg3ODI4MzJmZWE3ZmQ4IiwiYWxsb2NhdGlvbl9pZCI6ImM2NTA3ZjNmNjQ3MDk3MmE5Mjg1NzZhMmYwY2IwMDAxOWZjYzRjYThlNjBjOGM5ZTA4NWE4YTkwNWRhNmQ4MzgiLCJmaWxlX3BhdGhfaGFzaCI6IjE0OGY3YjAyNWE2ZTA1ZWZlZWQ5N2YxMTA5ZmJjYzg1ZGIyMTU4MTRjZjJhODJmNjYyOTdjZjI3NWRjMjYyMDciLCJhY3R1YWxfZmlsZV9oYXNoIjoiYTU5MTc1NGM3MTY1Yzk0NzcwNGU4ZTM3OGY4ZmI2NTI4NjdhNjFjMSIsImZpbGVfbmFtZSI6ImRvY3MiLCJyZWZlcmVuY2VfdHlwZSI6ImYiLCJleHBpcmF0aW9uIjoxNjM3NTMxNTIzLCJ0aW1lc3RhbXAiOjE2Mjk3NTU1MjMsInJlX2VuY3J5cHRpb25fa2V5IjoiIiwiZW5jcnlwdGVkIjp0cnVlLCJzaWduYXR1cmUiOiJmNThhNDViZGVkOGQzNDMwMzcyMzU3ZWQ1MmEzODFmZmI5ZDk4MWNjMzc0NzQ4OTk3M2QzMDFmOGZjMDVjMzFkIn0= ``` 7\. Download the files inside the directory by using the following command ``` zbox download --localpath $local --authticket $AUTH --remotepath $remote --allocation $ALLOC ``` Response: ``` 19 / 19 [=====================================================================================================================================================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = docs ​ ``` Note : The allocation ID required in the command above can be retrieved from decoding the AUTH string. For remote path the actual path for the shared directory should be specified. If you are not able to download files and getting **Error in file operation: File content didn't match with uploaded file** response check [Error 2 in Tips and Troubleshooting Section](#error-2-error-in-file-operation-file-content-didnt-match-with-uploaded-file). ### Repair a file on dStorage Use `./zbox start-repair` command to repair a file on dStorage. Parameters can be viewed using the `--help` flag. | Parameter | Required | Description | default | Valid values | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | repairpath | yes | remote path of files on dStorage to repair | | string | | rootpath | yes | File path for local files. Files from rootpath will be compared with files on dStorage for data blocks error. | | string | ​Sample Command: ``` ./zbox start-repair --repairpath /myfiles --rootpath $root --allocation $ALLOC ``` Response: ``` Repair file completed, Total files repaired: 0 ``` In the above response the total number of files repaired were 0 which means all the data blocks for the files are not altered or damaged. ### **Rollback** Use `./zbox rollback` to rollback to a previous state of allocation. This is helpful when you want to rollback to previous version of files you updated on allocation using [Update allocation.](https://github.com/0chain/zboxcli/tree/hm90121-patch-1#update-allocation) | Parameter | Description | Valid Values | | ------------ | ----------------------------------- | ------------ | | --allocation | Provide Allocation ID for rollback. | string | | --h,--help | help for rollback | int | Sample Command: ``` ./zbox rollback --allocation $ALLOCATION_ID ``` Sample Response: ``` Rollback successful ``` ### Total Stored Data `./zbox total-stored-data` returns the summation of all the Size fields in all the files stored across blobbers.\ Sample Command: ``` ./zbox total-stored-data ``` Sample Response: ``` total stored data: 673504 ``` ### Asking the receiver to pay for download (RX\_pay) RX pay is a specified boolean flag in `./zbox download` command which asks the file receiver to pay for their file download. Parameters for `--rx_pay` flag can be viewed using the `zbox download --help`​. | Parameter | Required | Description | Default | Valid values | | --------------- | -------- | ----------------------------------------------------------------------------- | ------- | ------------ | | allocation | yes | allocation id | | string | | authticket | no | auth ticked if not owner of the allocation, use share to get auth ticket | | string | | blockspermarker | no | download multiple blocks per marker | 10 | int | | commit | no | save metadata to blockchain | false | boolean | | endblock | no | download until specified block number | | int | | localpath | yes | local path to which to download the file to | | file path | | remotepath | yes | remote path to which the file was uploaded | | string | | rx\_pay | no | `authticket` must be valid, true = sender pays, false = allocation owner pays | false | boolean | | startblock | no | start download from specified block | | int | | thumbail | no | only download the thumbnail | false | boolean | As we can see that RX pay requires download by auth ticket and a `rx_pay` boolean set to `true .` Example: Let's take two users (User A and User B). User A is the seller of the file downloaded by User B (receiver). 1.User A will upload a file on dstorage and share an authtoken for the file. For example we are uploading `info1.txt` file located on `myfiles` directory of dStorage which User B will download and pay for himself using --rxpay. 2.To make the file available for pay User A has to set the`--attr-who-pays-for-reads` for upload command to 3rd\_party (by default it is set to "owner") Sample Command: ``` ./zbox upload --attr-who-pays-for-reads 3rd_party --remotepath $remote --allocation $ALLOC ``` 3.To verify whether downloads payer are properly configured use: ``` ./zbox list --remotepath $remote --allocation $ALLOC ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER ​ f | info1.txt | /myfiles/info1.txt | 44 | 4 | bf58c1b39eb26ae8762822623 e38f919358338017f8b2144e5cf6ccab23fd2af | NO | 3rd_party ​ ``` In the response, you will notice that the downloads payers section for `info1.txt` are successfully set to 3rd-party. 4.To know how to share a file on dStorage and get an AuthToken for a file have a look at the [sharing a file on dStorage ](#sharing-a-file-on-dstorage). 5.Once the auth token is created and marked to a variable, share it with the receiver(UserB) who will run the `.zbox download` command to download the file with `--rx_pay` flag. Command for User B: ``` ./zbox download --authticket $AUTH --localpath /root/ --rx_pay true ``` Response: ``` 23 / 23 [=======================================================================================================================================================================] 100.00% 0s Status completed callback. Type = application/octet-stream. Name = info1.txt ​ ``` To verify whether (UserB) has paid successfully for the download check the wallet and read pool balance for change using `./zwallet getbalance` and `/zbox rp-info`. Note: Do unlock read tokens using `rp-unlock` before using `./zwallet getbalance`to let the download money reflect in wallet. ### Video Streaming Video streaming with Zboxcli can be implemented with players for different operating platforms(iOS, Android, Mac). Zbox CLI does not have a player itself and uses the following helping functions : **downloadFileByBlocks - properly returns file-chunks with correct byte range,.** **getFileMeta - returns actuaBlockNumbers and actualFileSize (exclude thumbnail size)** **getFileMetaByAuth - same updates as getFileMeta** **listAllocation - returns actuaBlockNumbers and actualFileSize (exclude thumbnail size)** For all the Platforms streaming implementation using ZboxCLi has the following flow: ![](https://979598987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNrAZJ0KGiwEbKkbVRYPu%2Fuploads%2Fgit-blob-f1002d9409c3c25dbe06e2192f123e532b9899e8%2Fstreaming-android.png?alt=media) When the user starts the video player (ExoPlayer for Android or AVPlayer for iOS), A ZChainDataSource starts chunked download and requests chunks of video from the buffer(a Middleman between streaming player and Zbox). After the arrival of the first chunk, the player starts requesting more chunks from the buffer which request the Zbox SDK .Zbox SDK which is built using GO makes use of the downloadFileByBlocks method to reliably download large files by chunking them into a sequence of parts that can be downloaded individually. Once the blocks are downloaded they are read into input streams and added to the media source of the streaming player. The task of downloading files and writing them to buffer using ZboxSDK happens constantly and If player request random bits of video they are delivered instantly by the buffer. In a case, if the player didn't receive chunks (for example it's still not downloaded), then the player switches to STALE state and the video stream will pause. During the STALE state, player tries to make multiple requests for chunks, if didn't receive a response the video stream stops. To understand how Zbox CLI provides downloading of files by blocks check the below demonstration: For instance, Let's consider an allocation which has a `audio.mp3`file stored on dStorage. Make sure the file has a large size(more than 64 kB(64000 bytes) ) to download the file by blocks. The size and other attributes of the sample`audio.mp3`file can be viewed using ``` ./zbox list --allocation $ALLOC --remotepath /myfiles ``` Response: ``` TYPE | NAME | PATH | SIZE | NUM BLOCKS |LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER +------+-----------+--------------------+---------+------------+---------------- f | audio.mp3 | /myfiles/audio.mp3 | 5992396 | 92 | 3cea39505cc30fb9f6fc5c6045284188feb14eac8ff3a19577701c4f6d973239 | NO | owner​ ``` Here we can see `audio.mp3` file has size (5993286) bytes and has 92 blocks. If we want to download a certain number of blocks for the info.txt file we can use `--endblock` or `--startblock` flag with `./zbox download` command. Other flags for download can be viewed using `./zbox download --help` | Parameter | Required | Description | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | --allocation | yes | Allocation ID | | --authticket | no | Auth ticket for the file to download if you dont own it | | -b, --blockspermarker | no | Pass this option to download multiple blocks per marker (by default 10) | | --delay | no | Pass segment duration to generate media playlist(m3u8). only works with --live. default duration is 5s. (default 5) | | -e,--endblock | yes | Pass this option to download till specific block number | | -h, --help | no | help for download | | --live | no | Start m3u8 downloader,and automatically generate media playlist(m3u8) on --localpath | | --localpath | yes | Local path of file to download | | --lookuphash | no | The remote lookuphash of the object retrieved from the list | | --remotepath | yes | Remote path to download | | -s, --startblock | yes | Pass this option to download from specific block number | | -t,--thumbnail | no | Pass this option to download only the thumbnail | To download only 3 blocks of `audio.mp3` file we specify `--startblock` and`--endblock` with an integer value of 1 and 3. `--blockspermarker`flag can also be specified to download multiple blocks at a time(default is 10). The whole download command for downloading till 3rd block of `audio.mp3` file would be: ``` ./zbox download --localpath /root --remotepath /myfiles/audio.mp3 --allocation $ALLOC --startblock 1 --endblock 3 ``` Response: ``` 393216 / 2996198 [====================>-----------------------------------------------------------------------------------------------------------------------------------------] 13.12% 1s Status completed callback. Type = audio/mpeg. Name = audio.mp3 ​ ``` As we can see, the downloaded file size(393216) is quite less than the original(2996198) which means zbox has downloaded some blocks of the file. ### **Feed** Use `feed` command to automatically download segment files from remote live feed with `--downloader-args "-q -f best"` * encode them into new segment files with `--delay` and `--ffmpeg-args`, and upload. * please use `youtube-dl -F https://www.youtube.com/watch?v=pC5mGB5enkw` to list formats of video (see below). ``` [youtube] pC5mGB5enkw: Downloading webpage [info] Available formats for pC5mGB5enkw: format code extension resolution note 249 webm audio only tiny 44k , webm_dash container, opus @ 44k (48000Hz), 95.21MiB 250 webm audio only tiny 59k , webm_dash container, opus @ 59k (48000Hz), 127.05MiB 251 webm audio only tiny 123k , webm_dash container, opus @123k (48000Hz), 264.98MiB 140 m4a audio only tiny 129k , m4a_dash container, mp4a.40.2@129k (44100Hz), 277.82MiB 278 webm 256x136 144p 87k , webm_dash container, vp9@ 87k, 30fps, video only, 188.78MiB 160 mp4 256x136 144p 118k , mp4_dash container, avc1.4d400c@ 118k, 30fps, video only, 253.62MiB 242 webm 426x224 240p 190k , webm_dash container, vp9@ 190k, 30fps, video only, 409.20MiB 133 mp4 426x224 240p 252k , mp4_dash container, avc1.4d400d@ 252k, 30fps, video only, 541.15MiB 243 webm 640x338 360p 326k , webm_dash container, vp9@ 326k, 30fps, video only, 701.53MiB 134 mp4 640x338 360p 576k , mp4_dash container, avc1.4d401e@ 576k, 30fps, video only, 1.21GiB 244 webm 854x450 480p 649k , webm_dash container, vp9@ 649k, 30fps, video only, 1.36GiB 135 mp4 854x450 480p 1028k , mp4_dash container, avc1.4d401f@1028k, 30fps, video only, 2.16GiB 247 webm 1280x676 720p 1320k , webm_dash container, vp9@1320k, 30fps, video only, 2.77GiB 136 mp4 1280x676 720p 1988k , mp4_dash container, avc1.64001f@1988k, 30fps, video only, 4.17GiB 248 webm 1920x1012 1080p 2527k , webm_dash container, vp9@2527k, 30fps, video only, 5.30GiB 137 mp4 1920x1012 1080p 4125k , mp4_dash container, avc1.640028@4125k, 30fps, video only, 8.64GiB 271 webm 2560x1350 1440p 7083k , webm_dash container, vp9@7083k, 30fps, video only, 14.84GiB 313 webm 3840x2026 2160p 13670k , webm_dash container, vp9@13670k, 30fps, video only, 28.65GiB 18 mp4 640x338 360p 738k , avc1.42001E, 30fps, mp4a.40.2 (44100Hz), 1.55GiB 22 mp4 1280x676 720p 2117k , avc1.64001F, 30fps, mp4a.40.2 (44100Hz) (best) ``` `--downloader-args "-f 22"` dowloads video with `22 mp4 1280x676 720p 2117k , avc1.64001F, 30fps, mp4a.40.2 (44100Hz) (best)` The user must be the owner of the allocation.You can request the file be encrypted before upload, and can send thumbnails with the file. | Parameter | Required | Description | Default | Valid values | | --------------- | -------- | ------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------- | | allocation | yes | allocation id, sender must be allocation owner | | string | | encrypt | no | encrypt file before upload | false | boolean | | localpath | yes | local path of segment files to download, generate and upload | | file path | | remotepath | yes | remote path to upload file to, use to access file later | | string | | thumbnailpath | no | local path of thumbnaSil | | file path | | chunknumber | no | how many chunks should be uploaded in a http request | 1 | int | | delay | no | set segment duration to seconds. | 5 | int | | feed | no | set remote live feed to url. | false | url | | downloader-args | no | pass args to youtube-dl to download video. default is "-q -f best". | -q -f best | [youtube-dl](https://github.com/ytdl-org/youtube-dl/blob/master/README.md#options) | | ffmpeg-args | no | pass args to ffmpeg to build segments. | -loglevel warning | [ffmpeg](https://www.ffmpeg.org/ffmpeg.html) | Sample Command: ``` ./zbox feed --localpath /tvshow.m3u8 --remotepath /videos/tvsho --allocation $ALLOC --delay 10 --downloader-args "-f 22" --feed https://www.youtube.com/watch?v=pC5mGB5enkw ```