Uploading and Managing Files

0Chain
Search…
Explorer
ZWallet CLI
Zbox CLI
Get Started
Zbox Commands
Uploading and Managing Files
Advanced Zbox Commands
Tips & Troubleshooting
Setup a 0Chain Testnet
Blobber
0miner
0Chain Diagnostics Glossary
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:
1
./zbox upload --localpath $local --remotepath $remote --allocation $ALLOC
Copied!
Response:
Verify whether the uploaded file is available on dStorage using list command required parameters are allocation ID and remote path
1
./zbox list --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
  TYPE |   NAME   |       PATH        | SIZE | NUM BLOCKS |LOOKUP HASH | 
2
  IS ENCRYPTED | DOWNLOADS PAYER
3
+------+----------+-------------------+------+------------+-----------------------------------------------
4
  f    | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c4322
5
  69eeb7def555f1f8b9b9a28bd9611362c | NO | owner
6
​
Copied!
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:
1
./zbox upload --encrypt --localpath $local --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
24 / 24 [================================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = info.txt
Copied!
To verify whether the file is encrypted and uploaded to dstorage use the list command :
1
./zbox list --allocation $ALLOC --remotepath $remote
Copied!
Response:
1
 TYPE |   NAME   |       PATH        | SIZE | NUM BLOCKS |LOOKUP HASH 
2
 | IS ENCRYPTED | DOWNLOADS PAYER
3
+------+----------+-------------------+------+------------+-----------------------------------------------
4
  f    | info.txt | /myfiles/info.txt | 24 | 4 | f15383a1130bd2fae1e52a7a15c432269
5
  eeb7def555f1f8b9b9a28bd9611362c | YES | owner
Copied!
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:
1
./zbox update --localpath $local --remotepath $remote --allocation $ALLOC  
Copied!
Verify the contents of updated file on dStorage using the list command.
1
./zbox list --remotepath $remote --allocation $ALLOC
Copied!
Sample Response:
1
  TYPE |   NAME   |       PATH    | SIZE | NUM BLOCKS | LOOKUP HASH 
2
  | IS ENCRYPTED | DOWNLOADS PAYER
3
​
4
  f    | info.txt | /myfiles/info.txt | 76 |  4 | f15383a1130bd2fae1e52a7a15c432
5
  269eeb7def555f1f8b9b9a28bd9611362c | NO | owner
6
​
Copied!
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:
1
./zbox share --remotepath $remote --allocation $ALLOC
Copied!
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
1
export AUTH= eyJjbGllbnRfaWQiOiIiLCJvd25lcl9pZCI6IjE3NTNkMjlkODE5ODkyNmZhYzJlZDQzYWNj
2
MzcwNDhhNzFmZmYzNDg2YTQ4N2ZjNmVlZDU0ZWFkNDY5YWQxNTkiLCJhbGxvY2F0aW9uX2lkIjoiNTJmYjl
3
iNTkyNmMwNmU0M2E5MjkwZTlkN2FkMzIxN2E0YWVlNTFjOTQ2ODRiYWYwZmMxNzRhYTQxYWJlNjA1OSIsIm
4
ZpbGVfcGF0aF9oYXNoIjoiZjE1MzgzYTExMzBiZDJmYWUxZTUyYTdhMTVjNDMyMjY5ZWViN2RlZjU1NWYxZ
5
jhiOWI5YTI4YmQ5NjExMzYyYyIsImZpbGVfbmFtZSI6ImluZm8udHh0IiwicmVmZXJlbmNlX3R5cGUiOiJmIi
6
wiZXhwaXJhdGlvbiI6MTYyNjIwNDM5NSwidGltZXN0YW1wIjoxNjE4NDI4Mzk1LCJyZV9lbmNyeXB0aW9uX2tle
7
SI6IiIsInNpZ25hdHVyZSI6ImM1ZDViYzY3M2Q1NTNmZmM3M2FhNTg2MDkwNDgwODVlMjZhN2UyZmUzNTQ2MjA5O
8
TlhNTk3NDdhNDFlNmNiMWQifQ==
Copied!
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:
1
./zbox download --localpath $local --remotepath $remote --allocation $ALLOC 
Copied!
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:
1
./zbox download --authticket $AUTH --localpath $local 
Copied!
Response:
1
 28 / 28 [==========================================================] 100.00% 0s
2
Status completed callback. Type = application/octet-stream. Name = info.txt
Copied!
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:
1
./zbox delete --remotepath $remote --allocation $ALLOC
Copied!
Sample Response:
Verify whether the updated txt file is available on dstorage using the list command
1
./zbox list --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
  TYPE | NAME | PATH | SIZE | NUM BLOCKS | LOOKUP HASH | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+------+------+------+------------+-------------+--------------+-----------------+
3
​
4
​
Copied!
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.
1
./zbox list --remotepath / --allocation $ALLOC 
Copied!
Response:
1
  TYPE |   NAME   |   PATH    | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+----------+-----------+------+------------+------------------------------------------------------------------+--------------+-----------------+
3
  d    | myfiles  | /myfiles  |      |          4 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a |              | owner
4
  f    | sync.txt | /sync.txt |   68 |          4 | 1fe7228abacc12a28277ff2fb5f97c7b7288942b8bbd7c5a96f80a1a65a0367e | NO           | owner
Copied!
2. Use the ./zbox copy command to copy files.
1
./zbox copy --remotepath /sync.txt --destpath /myfiles --allocation $ALLOC
Copied!
Successful Response:
1
/sync.txt copied
Copied!
3. Verify whether the file has copied using:
1
./zbox list --remotepath /myfiles --allocation $ALLOC
Copied!
Response:
1
  TYPE |   NAME   |       PATH        | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+----------+-------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
3
  f    | info.txt | /myfiles/info.txt |   76 |          4 | f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c | NO           | owner
4
  f    | sync.txt | /myfiles/sync.txt |   68 |          4 | 4a5669bef007b8f3b8a93e34fb9c43ab1f868701379777c2580b8196029e9923 | NO           | owner
Copied!
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.
1
./zbox list --remotepath / --allocation $ALLOC 
Copied!
Response:
1
    TYPE |   NAME   |   PATH    | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+----------+-----------+------+------------+------------------------------------------------------------------+--------------+-----------------+
3
  d    | myfiles  | /myfiles  |      |          8 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a |              | owner
4
  f    | sync.txt | /sync.txt |   68 |          4 | 1fe7228abacc12a28277ff2fb5f97c7b7288942b8bbd7c5a96f80a1a65a0367e | NO           | owner
5
  d    | myfiles1 | /myfiles1 |      |          4 | d541b2190c7527967ae10a8f991f34ebf9d474c10ba02832d224093110f1fcfc |              | owner
Copied!
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
1
./zbox move --remotepath /myfiles/info.txt --destpath /myfiles1 --allocation $ALLOC 
Copied!
Successful Response:
1
/myfiles/info.txt moved
Copied!
3. Verify whether the file has moved by listing the directory path using:
1
./zbox list --remotepath /myfiles1 --allocation $ALLOC 
Copied!
Response:
1
  TYPE |   NAME    |        PATH         | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+-----------+---------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
3
  f    | info1.txt | /myfiles1/info1.txt |  112 |          4 | 675fab6ebfd03539848e224c2f758af33f5c8f34fb1471c9ede1fa387e389d52 | NO           | owner
4
  f    | info.txt  | /myfiles1/info.txt  |   76 |          4 | c369ce1609ca141142ab3146b7c436d945bfa4f1dd6dda1f19820dbd71c3dfe1 | NO           | owner
Copied!
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:
1
./zbox rename --remotepath /sync.txt --destname $DEST_PATH --allocation $ALLOC
Copied!
Response:
1
/sync.txt renamed
Copied!
Verify by listing the remote path using
1
./zbox list --remotepath / --allocation $ALLOC 
Copied!
Response:
1
  TYPE |       NAME        |       PATH        | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+-------------------+-------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
3
  d    | myfiles           | /myfiles          |      |          4 | 0343cabc0c987686344be0b30055df76994888ce9159f97a9c76de035225fc9a |              | owner
4
  d    | myfiles1          | /myfiles1         |      |          8 | d541b2190c7527967ae10a8f991f34ebf9d474c10ba02832d224093110f1fcfc |              | owner
5
  f    | /myfiles/info.txt | /myfiles/info.txt |   68 |          4 | f15383a1130bd2fae1e52a7a15c432269eeb7def555f1f8b9b9a28bd9611362c | NO           | owner
Copied!
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 :
1
./zbox list --remotepath $remote --allocation $ALLOC 
Copied!
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
1
./zbox list --remotepath $remote --allocation $ALLOC 
Copied!
Response:
1
  TYPE |   NAME    |        PATH         | SIZE | NUM BLOCKS |                           LOOKUP HASH                            | IS ENCRYPTED | DOWNLOADS PAYER
2
+------+-----------+---------------------+------+------------+------------------------------------------------------------------+--------------+-----------------+
3
  f    | info1.txt | /myfiles1/info1.txt |  112 |          4 | 675fab6ebfd03539848e224c2f758af33f5c8f34fb1471c9ede1fa387e389d52 | NO           | owner
4
  f    | info.txt  | /myfiles1/info.txt  |   76 |          4 | c369ce1609ca141142ab3146b7c436d945bfa4f1dd6dda1f19820dbd71c3dfe1 | NO           | owner
Copied!
2. Run the stats command using
1
./zbox stats --remotepath $remote --allocation $ALLOC 
Copied!
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:
1
./zbox meta --remotepath $remote --allocation $ALLOC
Copied!
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:
1
./zbox get-download-cost --allocation $ALLOC --remotepath $remote
Copied!
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:
1
./zbox get-upload-cost --allocation $ALLOC --localpath $local
Copied!
Response:
​