Uploading and Managing Files

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
​
Sharing a File on dStorage
Zbox supports sharing of files using Authorization 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
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":{}}]
​

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	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

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

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

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

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

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

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

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

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

Parameter	Required	Description	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

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

Parameter	Required	Description	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

Creating and Managing Allocations

Advanced Zbox Commands

Last modified 8d ago