Comment on page
Uploading and Managing Files

​Uploading and Managing Files​
​Upload a file to dStorage​
​Uploading an Encrypted File to dStorage​
​Create directory on dStorage​
​Updating the contents of a file on dStorage​
​Sharing a file on dStorage​
​Downloading the file from dStorage​
​Copy uploaded files to another folder path on dStorage​
​Move uploaded files to another folder path on dStorage​
​Renaming Files on dStorage​
​List files from Blobbers​
​Get Stats for file in dStorage​
​Get metadata for stored file on dStorage​
​Get Download Cost for a file on dStorage​
​Get Cost for Uploading a file on dStorage​
​Sync​
​Batch Upload Files to dStorage​
​Private File Sharing​
​Cancel Sharing of File for a Particular User​
​Private Directory Sharing​
​Repair a file on dStorage​
​Rollback​
​Total Stored Data​
​Asking the receiver to pay for download​
​Video Streaming​
​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:
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 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.​
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 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 .
./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:
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:
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.
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 .
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:
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 copycommand 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 listcommand 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 :
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:
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:
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:
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:
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 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
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
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
Parameter	Description	Valid Values
--allocation	Provide Allocation ID	string
--dirname	Provide Directory Name and absolute path .	string
--h,--help	help for createdir	int